[RFC,7/7] Add documentation for nanoMIPS

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 6d8b9856eea..5bfea4cd7b6 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -2484,6 +2484,7 @@  GCC plugins may provide their own attributes.
 * Microsoft Windows Function Attributes::
 * MIPS Function Attributes::
 * MSP430 Function Attributes::
+* nanoMIPS Function Attributes::
 * NDS32 Function Attributes::
 * Nios II Function Attributes::
 * Nvidia PTX Function Attributes::
@@ -5673,6 +5674,99 @@  options can help the packing, however, since they produce smaller,
 easier to pack regions.
 @end table
 
+@node nanoMIPS Function Attributes
+@subsection nanoMIPS Function Attributes
+
+These function attributes are supported by the nanoMIPS back end:
+
+@table @code
+@item cmodel ("@var{model}")
+@cindex @code{cmodel} function attribute, nanoMIPS
+Use this attribute to indicate what code should be generated for a particular
+code and data model for this function.  The behavior and permissible arguments
+are the same as for the command line option @option{-mcmodel=}.
+@end table
+
+@table @code
+@item interrupt
+@cindex @code{interrupt} function attribute, nanoMIPS
+Use this attribute to indicate that the specified function is an interrupt
+handler.  The compiler generates function entry and exit sequences suitable
+for use in an interrupt handler when this attribute is present.
+An optional argument is supported for the interrupt attribute which allows
+the interrupt mode to be described.  By default GCC assumes the external
+interrupt controller (EIC) mode is in use, this can be explicitly set using
+@code{eic}.  When interrupts are non-masked then the requested Interrupt
+Priority Level (IPL) is copied to the current IPL which has the effect of only
+enabling higher priority interrupts.  To use vectored interrupt mode use
+the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
+the behavior of the non-masked interrupt support and GCC will arrange to mask
+all interrupts from sw0 up to and including the specified interrupt vector.
+
+You can use the following attributes to modify the behavior
+of an interrupt handler:
+@table @code
+@item use_shadow_register_set
+@cindex @code{use_shadow_register_set} function attribute, nanoMIPS
+Assume that the handler uses a shadow register set, instead of
+the main general-purpose registers.  An optional argument @code{intstack} is
+supported to indicate that the shadow register set contains a valid stack
+pointer.
+
+@item keep_interrupts_masked
+@cindex @code{keep_interrupts_masked} function attribute, nanoMIPS
+Keep interrupts masked for the whole function.  Without this attribute,
+GCC tries to reenable interrupts for as much of the function as it can.
+
+@item use_debug_exception_return
+@cindex @code{use_debug_exception_return} function attribute, nanoMIPS
+Return using the @code{deret} instruction.  Interrupt handlers that don't
+have this attribute return using @code{eret} instead.
+@end table
+
+You can use any combination of these attributes, as shown below:
+@smallexample
+void __attribute__ ((interrupt)) v0 ();
+void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
+void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
+void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
+void __attribute__ ((interrupt, use_shadow_register_set,
+                     keep_interrupts_masked)) v4 ();
+void __attribute__ ((interrupt, use_shadow_register_set,
+                     use_debug_exception_return)) v5 ();
+void __attribute__ ((interrupt, keep_interrupts_masked,
+                     use_debug_exception_return)) v6 ();
+void __attribute__ ((interrupt, use_shadow_register_set,
+                     keep_interrupts_masked,
+                     use_debug_exception_return)) v7 ();
+void __attribute__ ((interrupt("eic"))) v8 ();
+void __attribute__ ((interrupt("vector=hw3"))) v9 ();
+@end smallexample
+
+@item long_call
+@itemx near
+@itemx far
+@cindex indirect calls, nanoMIPS
+@cindex @code{long_call} function attribute, nanoMIPS
+@cindex @code{near} function attribute, nanoMIPS
+@cindex @code{far} function attribute, nanoMIPS
+These attributes specify how a particular function is called on nanoMIPS@.
+The attributes override the @option{-mlong-calls} (@pxref{nanoMIPS Options})
+command-line switch.  The @code{long_call} and @code{far} attributes are
+synonyms, and cause the compiler to always call
+the function by first loading its address into a register, and then using
+the contents of that register.  The @code{near} attribute has the opposite
+effect; it specifies that non-PIC calls should be made using the more
+efficient @code{jal} instruction.
+
+@item use_hazard_barrier_return
+@cindex @code{use_hazard_barrier_return} function attribute, nanoMIPS
+This function attribute instructs the compiler to generate a hazard barrier
+return that clears all execution and instruction hazards while returning,
+instead of generating a normal return instruction.
+
+@end table
+
 @node NDS32 Function Attributes
 @subsection NDS32 Function Attributes
 
@@ -14495,6 +14589,8 @@  instructions, but allow the compiler to schedule those calls.
 * MIPS SIMD Architecture (MSA) Support::
 * Other MIPS Built-in Functions::
 * MSP430 Built-in Functions::
+* nanoMIPS Built-in Functions::
+* nanoMIPS DSP Built-in Functions::
 * NDS32 Built-in Functions::
 * picoChip Built-in Functions::
 * Basic PowerPC Built-in Functions::
@@ -17510,6 +17606,34 @@  optimized to a constant later.  The number of cycles delayed by this
 builtin is exact.
 @end table
 
+@node nanoMIPS Built-in Functions
+@subsection nanoMIPS Built-in Functions
+
+The following built-in functions map directly to a particular nanoMIPS
+instruction.  Please refer to the architecture specification
+for details on what each instruction does.
+
+@smallexample
+imm0_3: integer literal 0 to 3.
+typedef int i32;
+typedef unsigned int ui32;
+@end smallexample
+
+@smallexample
+i32 __builtin_mips_align (i32, i32, imm0_3)
+ui32 __builtin_mips_bitrevb (ui32)
+ui32 __builtin_mips_bitrevh (ui32)
+ui32 __builtin_mips_bitrevw (ui32)
+ui32 __builtin_mips_byterevh (ui32)
+ui32 __builtin_mips_byterevw (ui32)
+@end smallexample
+
+@node nanoMIPS DSP Built-in Functions
+@subsection nanoMIPS DSP Built-in Functions
+nanoMIPS supports DSP Rev 3 onwards. For description of the built-ins,
+Please refer to MIPS DSP and MIPS DSP Rev 2 sections in
+@pxref{MIPS DSP Built-in Functions}.
+
 @node NDS32 Built-in Functions
 @subsection NDS32 Built-in Functions
 
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index ba98eab68a5..c4ff1bff816 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -1108,6 +1108,35 @@  Objective-C and Objective-C++ Dialects}.
 -msilicon-errata=  -msilicon-errata-warn= @gol
 -mhwmult=  -minrt  -mtiny-printf  -mmax-inline-shift=}
 
+@emph{nanoMIPS Options}
+@gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
+-m32 -m64 @gol
+-mcmodel=auto -mcmodel=medium -mcmodel=large @gol
+-mbalc-stubs -mno-balc-stubs @gol
+-mpcrel -mno-pcrel @gol
+-mpid -mno-pid @gol
+-mrelax -mno-relax @gol
+-mgp32 -mgp64 -mhard-float -msoft-float @gol
+-msingle-float -mdouble-float @gol
+-mdspr3 -mno-dspr3 @gol
+-mmcu -mmno-mcu @gol
+-meva -mno-eva @gol
+-mvirt -mno-virt @gol
+-mxpa -mno-xpa @gol
+-mmsa -mno-msa @gol
+-msym32 -mno-sym32 @gol
+-G@var{num} -mlocal-sdata -mno-local-sdata @gol
+-mextern-sdata -mno-extern-sdata -mgpopt -mno-gopt @gol
+-membedded-data -mno-embedded-data @gol
+-muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
+-mcheck-zero-division -mno-check-zero-division @gol
+-mdivide-traps @gol
+-mmemcpy -mno-memcpy @gol
+-mlong-calls -mno-long-calls @gol
+-mimadd -mno-imadd @gol
+-mflush-func=@var{func} -mno-flush-func @gol
+-mbranch-cost=@var{num}}
+
 @emph{NDS32 Options}
 @gccoptlist{-mbig-endian  -mlittle-endian @gol
 -mreduced-regs  -mfull-regs @gol
@@ -18350,6 +18379,7 @@  platform.
 * MN10300 Options::
 * Moxie Options::
 * MSP430 Options::
+* nanoMIPS Options::
 * NDS32 Options::
 * Nios II Options::
 * Nvidia PTX Options::
@@ -26212,6 +26242,343 @@  Warn if @samp{devices.csv} is not found or there are problem parsing it
 
 @end table
 
+@node nanoMIPS Options
+@subsection nanoMIPS Options
+@cindex nanoMIPS options
+
+@table @gcctabopt
+
+@item -EB
+@opindex EB
+Generate big-endian code.  This is the default for @samp{nanomips*eb-*-*}
+configurations.
+
+@item -EL
+@opindex EL
+Generate little-endian code.
+
+@item -march=@var{arch}
+@opindex march
+Generate code that runs on @var{arch}, which can be the name of a
+generic nanoMIPS,  or the name of a particular processor.
+The ISA names are:
+@samp{32r6}, @samp{64r6}.
+The processor names are:
+@samp{i7200}.
+
+GCC defines two macros based on the value of this option.  The first
+is @code{_MIPS_ARCH}, which gives the name of target architecture, as
+a string.  The second has the form @code{_MIPS_ARCH_@var{foo}},
+where @var{foo} is the capitalized value of @code{_MIPS_ARCH}@.
+For example, @option{-march=32r6} sets @code{_MIPS_ARCH}
+to @code{"32r6"} and defines the macro @code{_MIPS_ARCH_32R6}.
+
+@item -mtune=@var{arch}
+@opindex mtune
+Optimize for @var{arch}.  Among other things, this option controls
+the way instructions are scheduled, and the perceived cost of arithmetic
+operations.  The list of @var{arch} values is the same as for
+@option{-march}.
+
+When this option is not used, GCC optimizes for the processor
+specified by @option{-march}.  By using @option{-march} and
+@option{-mtune} together, it is possible to generate code that
+runs on a family of processors, but optimize the code for one
+particular member of that family.
+
+@option{-mtune} defines the macros @code{_MIPS_TUNE} and
+@code{_MIPS_TUNE_@var{foo}}, which work in the same way as the
+@option{-march} ones described above.
+
+@item -m32
+@itemx -m64
+@opindex m32
+@opindex m64
+Generate code for the given ABI, either 32-bit or 64-bit variant.
+
+@item -mcmodel=auto
+@opindex mcmodel=auto
+Generate the most compressed code possible by relying on the linker to expand
+or relax code appropriately, depending on a given symbol's visibility at
+link-time.
+
+@item -mcmodel=medium
+@opindex mcmodel=medium
+Generate code which is appropriate for average-sized applications without
+relying on linker relaxations or expansions.  The GP area can not exceed 2MiB
+and direct calls have a maximum range of 32 MiB.
+
+@item -mcmodel=large
+@opindex mcmodel=large
+Generates code which is appropriate for large applications without relying on
+linker relaxations or expansions.  There are no inherent size limits when
+using this model.
+
+@item -mbalc-stubs
+@itemx -mno-balc-stubs
+@opindex mbalc-stubs
+@opindex mno-balc-stubs
+Enable (disable) the assembler's out-of-range call optimization through
+trampoline stubs.
+
+The default option is @option{-mbalc-stubs} for @option{-Os} optimization
+level and @option{-mno-balc-stubs} for any other optimization level.
+
+@item -mpcrel
+@itemx -mno-pcrel
+@opindex mpcrel
+@opindex mno-pcrel
+@option{-mpcrel} forces PC-relative addressing for non-pre-emptible symbols.
+This also effectively disables absolute addressing.
+@option{-mno-pcrel} avoids PC-relative addressing for non-pre-emptible
+symbols where alternative sequences are not larger or slower.
+
+The default option is @option{-mpcrel}.
+
+@item -mpid
+@itemx -mno-pid
+@opindex mpid
+@opindex mno-pid
+Enforce (do not enforce) position-independent data by requiring GP-relative
+addressing for all non-pre-emptible data symbols.
+
+The default is @option{mno-pid}.
+
+@item -mrelax
+@itemx -mno-relax
+@opindex mrelax
+@opindex mno-relax
+Enable (disable) linker relaxations and expansions for the compilation unit.
+The compiler emits (does not emit) a @code{.linkrelax} directive to
+the assembly file that causes an ELF header flag to be set in the object.
+
+The default option is to emit the @code{.linkrelax} directive.
+
+@item -mgp32
+@opindex mgp32
+Assume that general-purpose registers are 32 bits wide.
+
+@item -mgp64
+@opindex mgp64
+Assume that general-purpose registers are 64 bits wide.
+
+@item -mhard-float
+@opindex mhard-float
+Use floating-point coprocessor instructions.
+
+@item -msoft-float
+@opindex msoft-float
+Do not use floating-point coprocessor instructions.  Implement
+floating-point calculations using library calls instead.
+
+@item -msingle-float
+@opindex msingle-float
+Assume that the floating-point coprocessor only supports single-precision
+operations.
+
+@item -mdouble-float
+@opindex mdouble-float
+Assume that the floating-point coprocessor supports double-precision
+operations.  This is the default.
+
+@item -mdspr3
+@itemx -mno-dspr3
+@opindex mdspr3
+@opindex mno-dspr3
+Use (do not use) revision 3 of the MIPS DSP ASE@.
+@xref{MIPS DSP Built-in Functions}.  This option defines the
+preprocessor macros @code{__mips_dsp} and @code{__mips_dspr3}.
+It also defines @code{__mips_dsp_rev} to 3.
+
+@item -mmt
+@itemx -mno-mt
+@opindex mmt
+@opindex mno-mt
+Use (do not use) MT Multithreading instructions.
+
+@item -mmcu
+@itemx -mno-mcu
+@opindex mmcu
+@opindex mno-mcu
+Use (do not use) the MIPS MCU ASE instructions.
+
+@item -meva
+@itemx -mno-eva
+@opindex meva
+@opindex mno-eva
+Use (do not use) the MIPS Enhanced Virtual Addressing instructions.
+
+@item -mvirt
+@itemx -mno-virt
+@opindex mvirt
+@opindex mno-virt
+Use (do not use) the MIPS Virtualization Application Specific instructions.
+
+@item -mxpa
+@itemx -mno-xpa
+@opindex mxpa
+@opindex mno-xpa
+Use (do not use) the MIPS eXtended Physical Address (XPA) instructions.
+
+@item -msym32
+@itemx -mno-sym32
+@opindex msym32
+@opindex mno-sym32
+Assume (do not assume) that all symbols have 32-bit values, regardless
+of the selected ABI@.  This option is useful in combination with
+@option{-m64} because it allows GCC to generate shorter and faster references
+to symbolic addresses.
+
+@item -G @var{num}
+@opindex G
+Put definitions of externally-visible data in a small data section
+if that data is no bigger than @var{num} bytes.  GCC can then generate
+more efficient accesses to the data; see @option{-mgpopt} for details.
+
+The default @option{-G} option depends on the configuration.
+
+@item -mlocal-sdata
+@itemx -mno-local-sdata
+@opindex mlocal-sdata
+@opindex mno-local-sdata
+Extend (do not extend) the @option{-G} behavior to local data too,
+such as to static variables in C@.  @option{-mlocal-sdata} is the
+default for all configurations.
+
+If the linker complains that an application is using too much small data,
+you might want to try rebuilding the less performance-critical parts with
+@option{-mno-local-sdata}.  You might also want to build large
+libraries with @option{-mno-local-sdata}, so that the libraries leave
+more room for the main program.
+
+@item -mextern-sdata
+@itemx -mno-extern-sdata
+@opindex mextern-sdata
+@opindex mno-extern-sdata
+Assume (do not assume) that externally-defined data is in
+a small data section if the size of that data is within the @option{-G} limit.
+@option{-mextern-sdata} is the default for all configurations.
+
+If you compile a module @var{Mod} with @option{-mextern-sdata} @option{-G
+@var{num}} @option{-mgpopt}, and @var{Mod} references a variable @var{Var}
+that is no bigger than @var{num} bytes, you must make sure that @var{Var}
+is placed in a small data section.  If @var{Var} is defined by another
+module, you must either compile that module with a high-enough
+@option{-G} setting or attach a @code{section} attribute to @var{Var}'s
+definition.  If @var{Var} is common, you must link the application
+with a high-enough @option{-G} setting.
+
+The easiest way of satisfying these restrictions is to compile
+and link every module with the same @option{-G} option.  However,
+you may wish to build a library that supports several different
+small data limits.  You can do this by compiling the library with
+the highest supported @option{-G} setting and additionally using
+@option{-mno-extern-sdata} to stop the library from making assumptions
+about externally-defined data.
+
+@item -mgpopt
+@itemx -mno-gpopt
+@opindex mgpopt
+@opindex mno-gpopt
+Use (do not use) GP-relative accesses for symbols that are known to be
+in a small data section; see @option{-G}, @option{-mlocal-sdata} and
+@option{-mextern-sdata}.  @option{-mgpopt} is the default for all
+configurations.
+
+@option{-mno-gpopt} is useful for cases where the @code{$gp} register
+might not hold the value of @code{_gp}.  For example, if the code is
+part of a library that might be used in a boot monitor, programs that
+call boot monitor routines pass an unknown value in @code{$gp}.
+(In such situations, the boot monitor itself is usually compiled
+with @option{-G0}.)
+
+@option{-mno-gpopt} implies @option{-mno-local-sdata} and
+@option{-mno-extern-sdata}.
+
+@item -membedded-data
+@itemx -mno-embedded-data
+@opindex membedded-data
+@opindex mno-embedded-data
+Allocate variables to the read-only data section first if possible, then
+next in the small data section if possible, otherwise in data.  This gives
+slightly slower code than the default, but reduces the amount of RAM required
+when executing, and thus may be preferred for some embedded systems.
+
+@item -muninit-const-in-rodata
+@itemx -mno-uninit-const-in-rodata
+@opindex muninit-const-in-rodata
+@opindex mno-uninit-const-in-rodata
+Put uninitialized @code{const} variables in the read-only data section.
+This option is only meaningful in conjunction with @option{-membedded-data}.
+
+@item -mcheck-zero-division
+@itemx -mno-check-zero-division
+@opindex mcheck-zero-division
+@opindex mno-check-zero-division
+Trap (do not trap) on integer division by zero.
+
+The default is @option{-mno-check-zero-division} at @option{-Os} level and
+@option{-mcheck-zero-division} for any other optimization level.
+
+@item -mdivide-traps
+@opindex mdivide-traps
+nanoMIPS systems check for division by zero by generating either a
+conditional trap or a break instruction.  Using traps results in
+smaller code, but it is not supported in the nanoMIPS Subset.  Also, some
+versions of the Linux kernel have a bug that prevents trap from
+generating the proper signal (@code{SIGFPE}).  Use @option{-mdivide-traps} to
+allow conditional traps on architectures that support them and
+@option{-mno-divide-traps} to force the use of breaks.
+
+Divide-by-zero checks can be completely disabled using
+@option{-mno-check-zero-division}.
+
+@item -mmemcpy
+@itemx -mno-memcpy
+@opindex mmemcpy
+@opindex mno-memcpy
+Force (do not force) the use of @code{memcpy} for non-trivial block
+moves.  The default is @option{-mno-memcpy}, which allows GCC to inline
+most constant-sized copies.
+
+@item -mlong-calls
+@itemx -mno-long-calls
+@opindex mlong-calls
+@opindex mno-long-calls
+Disable (do not disable) use of the @code{balc} instruction.  Calling
+functions using @code{balc} is more efficient but requires the caller
+and callee to within the same 64 megabyte window.
+
+The default is @option{-mno-long-calls}.
+
+@item -mimadd
+@itemx -mno-imadd
+@opindex mimadd
+@opindex mno-imadd
+Enable (disable) use of the @code{madd} and @code{msub} integer
+instructions.  The default is @option{-mimadd} on architectures
+that support @code{madd} and @code{msub} as part of the DSP.
+
+@item -mflush-func=@var{func}
+@itemx -mno-flush-func
+@opindex mflush-func
+Specifies the function to call to flush the I and D caches, or to not
+call any such function.  If called, the function must take the same
+arguments as the common @code{_flush_func}, that is, the address of the
+memory range for which the cache is being flushed, the size of the
+memory range, and the number 3 (to flush both caches).  The default
+depends on the target GCC was configured for, but commonly is either
+@code{_flush_func} or @code{__cpu_flush}.
+
+@item mbranch-cost=@var{num}
+@opindex mbranch-cost
+Set the cost of branches to roughly @var{num} ``simple'' instructions.
+This cost is only a heuristic and is not guaranteed to produce
+consistent results across releases.  A zero cost redundantly selects
+the default, which is based on the @option{-mtune} setting.
+
+@end table
+
 @node NDS32 Options
 @subsection NDS32 Options
 @cindex NDS32 Options
diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index 2b41cb7fb7b..883ef8bdc03 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -2969,6 +2969,77 @@  Memory reference, stack only.
 
 @end table
 
+@item nanoMIPS---@file{config/mips/constraints.md}
+@table @code
+@item c
+A register suitable for use in an indirect jump.
+
+@item d
+Equivalent to @code{r}; retained for backwards compatibility.
+
+@item f
+A floating-point register (if available).
+
+@item m
+When used as a constraint in an ASM statement this is automatically
+re-interpreted as the ZR constraint.  This transformation only happens for
+simple single alternative contraints with or without modifiers @code{=},
+@code{+} and @code{&}.
+
+@item v
+Register @code{$3}.
+
+@item y
+Equivalent to @code{r}; retained for backwards compatibility.
+
+@item I
+A constant in the range @minus{}0xFFF to 0xFFFF inclusive that is suitable
+for @code{addiu[32]} or @code{addiu[neg]} instructions.
+
+@item J
+Integer zero.
+
+@item K
+An unsigned 12-bit constant (for logic instructions).
+
+@item L
+A signed 32-bit constant in which the lower 12 bits are zero.
+Such constants can be loaded using @code{lui}.
+
+@item M
+A constant that cannot be loaded using @code{lui}, @code{addiu}
+or @code{ori} and instead requires @code{li48}.
+
+@item N
+A constant in the range @minus{}65535 to @minus{}1 (inclusive).
+
+@item O
+A signed 15-bit constant.
+
+@item P
+A constant in the range 1 to 65535 (inclusive).
+
+@item G
+Floating-point zero.
+
+@item R
+An address that can be used in a non-macro load or store.  This constraint
+is deprecated as the nanoMIPS addressing modes vary between different
+forms of load and store instructions.  Use @code{ZR} to guarantee that
+an address is suitable for all possible instructions.
+
+@item ZR
+A memory operand whose address is formed from a base register alone; i.e.
+no offset or index.
+
+@item ZC
+A memory operand whose address is formed from a base register and a signed
+9-bit offset.
+
+@item ZD
+An address formed from a base register and a signed 9-bit offset.
+@end table
+
 @item NDS32---@file{config/nds32/constraints.md}
 @table @code
 @item w