+# A MIPS version of the GCC dg.exp driver.
+#
+# There are many MIPS features that we want to test, and many of those
+# features are specific to certain architectures, certain ABIs and so on.
+# There are therefore many cases in which we want to test something that
+# is incompatible with the user's chosen test options.
+#
+# In most dg testsuites, the options added by dg-options have a lower
+# priority than the options chosen by the user. For example, if a test
+# specifies:
+#
+# { dg-options "-mips1" }
+#
+# and the user passes the following option to runtest:
+#
+# --target_board unix/-mips3
+#
+# the test would be compiled as MIPS III rather than MIPS I. If the
+# test really wouldn't work with -mips3, normal practice would be to
+# have something like:
+#
+# { dg-do compile { target can_force_mips1 } }
+#
+# so that the test is skipped when an option like -mips3 is passed.
+#
+# Sticking to the same approach here would cause us to skip many tests,
+# even though the toolchain can generate the required code. For example,
+# there are 6 MIPS ABIs, plus variants. Some configurations support
+# more than one ABI, so it is natural to use something like:
+#
+# --target_board unix{-mabi=n32,-mabi=32,-mabi=64}
+#
+# when testing them. But these -mabi=* options would normally prevent any
+# EABI and o64 tests from running.
+#
+# This testsuite therefore defines a local version of dg-options that
+# overrides any user options that are incompatible with the test options.
+# It tries to keep the other user options intact.
+#
+#
+# Most of the tests in this testsuite are scan-assembler tests, but
+# sometimes we need a link test instead. In these cases, we must not
+# try to link code with options that are incompatible with the current
+# multilib, because xgcc is passed -L and -B options that are specific
+# to that multilib.
+#
+# Normal GCC practice would be to skip incompatible link tests as
+# unsupported, but in this particular case, it seems better to downgrade
+# them to an assemble test instead. At least that way we get some
+# test-for-ICE and code-sanity coverage.
+#
+# The same problem applies to run tests. If a test requires runtime
+# support for a particular feature, and if the current target does not
+# provide that support, normal practice would be to skip the test.
+# But in this case it seems better to downgrade it to a link test instead.
+# (We might then have to downgrade it to an assembler test according to
+# the constraints just mentioned.)
+#
+# The local dg-options therefore checks whether the new options are
+# link-compatiable with the user's options. If not, it automatically
+# downgrades link tests to assemble tests. It does the same for run
+# tests, but in addition, it downgrades run tests to link tests if the
+# target does not provide runtime support for a required feature or ASE.
+#
+#
+# Another problem is that many of the options we want to test require
+# certain other features. For example, -mips3d requires both 64-bit
+# FPRs and a MIPS32 or MIPS64 target; -mfix-r10000 requires branch-
+# likely instructions; and so on. We could handle this by specifying
+# a set of options that are guaranteed to give us what we want, such as:
+#
+# dg-options "-mips3d -mpaired-single -mhard-float -mgp64 -mfp64 -mabi=n32 -march=mips64 -mips64"
+#
+# With the new dg-options semantics, this would override any troublesome
+# user options like -mips3, -march=vr4100, -mfp32, -mgp32, -msoft-float,
+# -mno-paired-single and so on. But there are three major problems with
+# this:
+#
+# - It is easy to forget options.
+#
+# - If a new option is added, all tests that are incompatible with that
+# option must be updated.
+#
+# - We want to be able to test MIPS-3D with things like -march=mips32,
+# -march=mips64r2, -march=sb1, and so on.
+#
+# The local version of dg-options therefore works out the requirements
+# of each test option. As with the test options themselves, the local
+# dg-options overrides any user options that incompatible with these
+# requirements, but it keeps the other user options the same.
+#
+# For example, if the user passes -mips3, a MIPS-3D test will choose
+# a different architecture like -mips64 instead. But if the user
+# passes -march=sb1, MIPS-3D tests will be run with that option.
+#
+#
+# Sometimes it is useful to say "I want an environment that is compatible
+# with option X, but I don't want to pass option X itself". The main example
+# of this is -mips16: we want to be able to test __attribute__((mips16))
+# without requiring the test itself to be compiled as -mips16. The local
+# version of dg-options lets you do this by putting X in parentheses.
+# For example:
+#
+# { dg-options "(-mips16)" }
+#
+# selects a MIPS16-compatible target without passing -mips16 itself.
+#
+# It is also useful to say "any architecture within this ISA range is fine".
+# This can be done using special pseudo-options of the form:
+#
+# PROP=VALUE PROP<=VALUE PROP>=VALUE
+#
+# where PROP can be:
+#
+# isa:
+# the value of the __mips macro.
+#
+# isa_rev:
+# the value of the __mips_isa_rev macro, or 0 if it isn't defined.
+#
+# For example, "isa_rev>=1" selects a MIPS32 or MIPS64 processor,
+# "isa=4" selects a MIPS IV processor, and so on.
+#
+# There are also the following special pseudo-options:
+#
+# isa=loongson
+# select a Loongson processor
+#
+# addressing=absolute
+# force absolute addresses to be used
+#
+# forbid_cpu=REGEXP
+# forbid processors that match the given regexp; choose a
+# generic ISA instead.
+#
+#
+# In summary:
+#
+# (1) Try to avoid { target ... } requirements wherever possible.
+# Specify the requirements as dg-options instead.
+#
+# (2) Don't worry about the consequences of (1) for link and run tests.
+# If the test uses { dg-do link } or { dg-do run }, and its
+# dg-options are incompatible with the current target, the
+# testsuite will downgrade them where necessary.
+#
+# (3) Try to use the bare minimum of options and leave dg-options
+# to work out the dependencies. For example, if you want
+# a MIPS-3D test, you should generally just specify -mips3d.
+# Don't specify an architecture option like -mips64 unless
+# the test really doesn't work with -mips32r2, -mips64r2,
+# -march=sb1, etc.
+#
+# (4) If you want something compatible with a particular option,
+# but don't want to pass the option itself, wrap that option
+# in parentheses. In particular, pass '(-mips16)' if you
+# want to use "mips16" attributes.
+#
+# (5) When testing a feature of a generic ISA (as opposed to a
+# processor-specific extension), try to use the "isa" and
+# "isa_rev" pseudo-options instead of specific architecture
+# options. For example, if the feature is present on revision 2
+# processors and above, try to use "isa_rev>=2" instead of
+# "-mips32r2" or "-mips64r2".
+#
+# (6) If you need to disable processor-specific extensions use
+# forbid_cpu=REGEXP instead of forcing a generic ISA.
+#
+#
+# Terminology
+#
+# Option group or just group:
+# See comment before mips_option_groups.
+#
+# Test options:
+# The options specified in dg-options.
+#
+# Explicit options:
+# The options that were either passed to runtest as "multilib" options
+# (e.g. -mips4 in --target_board=mips-sim-idt/-mips4) or specified as
+# test options. Note that options in parenthesis (i.e. (-mips16)) are
+# not explicit and can be omitted depending on the base options.
+#
+# Base options:
+# Options that are on by default without being specified in dg-options,
+# e.g. -march=mips64r2 for mipsisa64r2-elf or because they've been
+# passed to runtest as "multilib" options.
+#
+# Option array:
+# Many functions in this file work with option arrays. These are
+# two-dimensional Tcl arrays where the first dimension can have three
+# values: option, explicit_p or test_option_p. The second dimension is
+# the name of the option group. "option" contains the name of the
+# option that is in effect from this group. If no option is active it
+# contains the empty string. The flags "explicit_p" and "test_option_p"
+# are set for explicit and test options.