..
  Copyright 1988-2022 Free Software Foundation, Inc.
  This is part of the GCC manual.
  For copying conditions, see the copyright.rst file.

.. program:: Nios II

.. index:: Nios II options, Altera Nios II options

.. _nios-ii-options:

Nios II Options
^^^^^^^^^^^^^^^

These are the options defined for the Altera Nios II processor.

.. index:: smaller data references

.. option:: -G {num}

  Put global and static objects less than or equal to :samp:`{num}` bytes
  into the small data or BSS sections instead of the normal data or BSS
  sections.  The default value of :samp:`{num}` is 8.

.. option:: -mgpopt={option}

  Generate (do not generate) GP-relative accesses.  The following 
  :samp:`{option}` names are recognized:

  :samp:`none`
    Do not generate GP-relative accesses.

  :samp:`local`
    Generate GP-relative accesses for small data objects that are not 
    external, weak, or uninitialized common symbols.  
    Also use GP-relative addressing for objects that
    have been explicitly placed in a small data section via a ``section``
    attribute.

  :samp:`global`
    As for :samp:`local`, but also generate GP-relative accesses for
    small data objects that are external, weak, or common.  If you use this option,
    you must ensure that all parts of your program (including libraries) are
    compiled with the same :option:`-G` setting.

  :samp:`data`
    Generate GP-relative accesses for all data objects in the program.  If you
    use this option, the entire data and BSS segments
    of your program must fit in 64K of memory and you must use an appropriate
    linker script to allocate them within the addressable range of the
    global pointer.

  :samp:`all`
    Generate GP-relative addresses for function pointers as well as data
    pointers.  If you use this option, the entire text, data, and BSS segments
    of your program must fit in 64K of memory and you must use an appropriate
    linker script to allocate them within the addressable range of the
    global pointer.

  :option:`-mgpopt` is equivalent to :option:`-mgpopt=local`, and
  :option:`-mno-gpopt` is equivalent to :option:`-mgpopt=none`.

  The default is :option:`-mgpopt` except when :option:`-fpic` or
  :option:`-fPIC` is specified to generate position-independent code.
  Note that the Nios II ABI does not permit GP-relative accesses from
  shared libraries.

  You may need to specify :option:`-mno-gpopt` explicitly when building
  programs that include large amounts of small data, including large
  GOT data sections.  In this case, the 16-bit offset for GP-relative
  addressing may not be large enough to allow access to the entire 
  small data section.

.. option:: -mgprel-sec={regexp}

  This option specifies additional section names that can be accessed via
  GP-relative addressing.  It is most useful in conjunction with 
  ``section`` attributes on variable declarations 
  (see :ref:`common-variable-attributes`) and a custom linker script.  
  The :samp:`{regexp}` is a POSIX Extended Regular Expression.

  This option does not affect the behavior of the :option:`-G` option, and 
  the specified sections are in addition to the standard ``.sdata``
  and ``.sbss`` small-data sections that are recognized by :option:`-mgpopt`.

.. option:: -mr0rel-sec={regexp}

  This option specifies names of sections that can be accessed via a 
  16-bit offset from ``r0`` ; that is, in the low 32K or high 32K 
  of the 32-bit address space.  It is most useful in conjunction with 
  ``section`` attributes on variable declarations 
  (see :ref:`common-variable-attributes`) and a custom linker script.  
  The :samp:`{regexp}` is a POSIX Extended Regular Expression.

  In contrast to the use of GP-relative addressing for small data, 
  zero-based addressing is never generated by default and there are no 
  conventional section names used in standard linker scripts for sections
  in the low or high areas of memory.

.. option:: -mel, -meb

  Generate little-endian (default) or big-endian (experimental) code,
  respectively.

.. option:: -march={arch}

  This specifies the name of the target Nios II architecture.  GCC uses this
  name to determine what kind of instructions it can emit when generating
  assembly code.  Permissible names are: :samp:`r1`, :samp:`r2`.

  The preprocessor macro ``__nios2_arch__`` is available to programs,
  with value 1 or 2, indicating the targeted ISA level.

.. option:: -mbypass-cache, -mno-bypass-cache

  Force all load and store instructions to always bypass cache by 
  using I/O variants of the instructions. The default is not to
  bypass the cache.

.. option:: -mno-cache-volatile, -mcache-volatile

  Volatile memory access bypass the cache using the I/O variants of 
  the load and store instructions. The default is not to bypass the cache.

.. option:: -mno-fast-sw-div, -mfast-sw-div

  Do not use table-based fast divide for small numbers. The default 
  is to use the fast divide at :option:`-O3` and above.

.. option:: -mno-hw-mul, -mhw-mul, -mno-hw-mulx, -mhw-mulx, -mno-hw-div, -mhw-div

  Enable or disable emitting ``mul``, ``mulx`` and ``div`` family of 
  instructions by the compiler. The default is to emit ``mul``
  and not emit ``div`` and ``mulx``.

.. option:: -mbmx, -mno-bmx, -mcdx, -mno-cdx

  Enable or disable generation of Nios II R2 BMX (bit manipulation) and
  CDX (code density) instructions.  Enabling these instructions also
  requires :option:`-march=r2`.  Since these instructions are optional
  extensions to the R2 architecture, the default is not to emit them.

.. index:: mcustom-insn, mno-custom-insn

.. option:: -mcustom-insn={N}

  Each :option:`-mcustom-insn=N` option enables use of a
  custom instruction with encoding :samp:`{N}` when generating code that uses 
  :samp:`{insn}`.  For example, :option:`-mcustom-fadds=253` generates custom
  instruction 253 for single-precision floating-point add operations instead
  of the default behavior of using a library call.

  The following values of :samp:`{insn}` are supported.  Except as otherwise
  noted, floating-point operations are expected to be implemented with
  normal IEEE 754 semantics and correspond directly to the C operators or the
  equivalent GCC built-in functions (see :ref:`other-builtins`).

  Single-precision floating point:

  :samp:`{fadds}, {fsubs}, {fdivs}, {fmuls}`
    Binary arithmetic operations.

  fnegs
    Unary negation.

  fabss
    Unary absolute value.

  :samp:`{fcmpeqs}, {fcmpges}, {fcmpgts}, {fcmples}, {fcmplts}, {fcmpnes}`
    Comparison operations.

  :samp:`{fmins}, {fmaxs}`
    Floating-point minimum and maximum.  These instructions are only
    generated if :option:`-ffinite-math-only` is specified.

  fsqrts
    Unary square root operation.

  :samp:`{fcoss}, {fsins}, {ftans}, {fatans}, {fexps}, {flogs}`
    Floating-point trigonometric and exponential functions.  These instructions
    are only generated if :option:`-funsafe-math-optimizations` is also specified.

    Double-precision floating point:

  :samp:`{faddd}, {fsubd}, {fdivd}, {fmuld}`
    Binary arithmetic operations.

  fnegd
    Unary negation.

  fabsd
    Unary absolute value.

  :samp:`{fcmpeqd}, {fcmpged}, {fcmpgtd}, {fcmpled}, {fcmpltd}, {fcmpned}`
    Comparison operations.

  :samp:`{fmind}, {fmaxd}`
    Double-precision minimum and maximum.  These instructions are only
    generated if :option:`-ffinite-math-only` is specified.

  fsqrtd
    Unary square root operation.

  :samp:`{fcosd}, {fsind}, {ftand}, {fatand}, {fexpd}, {flogd}`
    Double-precision trigonometric and exponential functions.  These instructions
    are only generated if :option:`-funsafe-math-optimizations` is also specified.

    Conversions:

  fextsd
    Conversion from single precision to double precision.

  ftruncds
    Conversion from double precision to single precision.

  :samp:`{fixsi}, {fixsu}, {fixdi}, {fixdu}`
    Conversion from floating point to signed or unsigned integer types, with
    truncation towards zero.

  round
    Conversion from single-precision floating point to signed integer,
    rounding to the nearest integer and ties away from zero.
    This corresponds to the ``__builtin_lroundf`` function when
    :option:`-fno-math-errno` is used.

  :samp:`{floatis}, {floatus}, {floatid}, {floatud}`
    Conversion from signed or unsigned integer types to floating-point types.

  In addition, all of the following transfer instructions for internal
  registers X and Y must be provided to use any of the double-precision
  floating-point instructions.  Custom instructions taking two
  double-precision source operands expect the first operand in the
  64-bit register X.  The other operand (or only operand of a unary
  operation) is given to the custom arithmetic instruction with the
  least significant half in source register :samp:`{src1}` and the most
  significant half in :samp:`{src2}`.  A custom instruction that returns a
  double-precision result returns the most significant 32 bits in the
  destination register and the other half in 32-bit register Y.  
  GCC automatically generates the necessary code sequences to write
  register X and/or read register Y when double-precision floating-point
  instructions are used.

  fwrx
    Write :samp:`{src1}` into the least significant half of X and :samp:`{src2}` into
    the most significant half of X.

  fwry
    Write :samp:`{src1}` into Y.

  :samp:`{frdxhi}, {frdxlo}`
    Read the most or least (respectively) significant half of X and store it in
    :samp:`{dest}`.

  frdy
    Read the value of Y and store it into :samp:`{dest}`.

  Note that you can gain more local control over generation of Nios II custom
  instructions by using the ``target("custom-insn=N")``
  and ``target("no-custom-insn")`` function attributes
  (see :ref:`function-attributes`)
  or pragmas (see :ref:`function-specific-option-pragmas`).

.. option:: -mcustom-fpu-cfg={name}

  This option enables a predefined, named set of custom instruction encodings
  (see :option:`-mcustom-insn` above).  
  Currently, the following sets are defined:

  :option:`-mcustom-fpu-cfg=60-1` is equivalent to:

  :option:`-mcustom-fmuls=252` |gol|
  :option:`-mcustom-fadds=253` |gol|
  :option:`-mcustom-fsubs=254` |gol|
  :option:`-fsingle-precision-constant`

  :option:`-mcustom-fpu-cfg=60-2` is equivalent to:

  :option:`-mcustom-fmuls=252` |gol|
  :option:`-mcustom-fadds=253` |gol|
  :option:`-mcustom-fsubs=254` |gol|
  :option:`-mcustom-fdivs=255` |gol|
  :option:`-fsingle-precision-constant`

  :option:`-mcustom-fpu-cfg=72-3` is equivalent to:

  :option:`-mcustom-floatus=243` |gol|
  :option:`-mcustom-fixsi=244` |gol|
  :option:`-mcustom-floatis=245` |gol|
  :option:`-mcustom-fcmpgts=246` |gol|
  :option:`-mcustom-fcmples=249` |gol|
  :option:`-mcustom-fcmpeqs=250` |gol|
  :option:`-mcustom-fcmpnes=251` |gol|
  :option:`-mcustom-fmuls=252` |gol|
  :option:`-mcustom-fadds=253` |gol|
  :option:`-mcustom-fsubs=254` |gol|
  :option:`-mcustom-fdivs=255` |gol|
  :option:`-fsingle-precision-constant`

  :option:`-mcustom-fpu-cfg=fph2` is equivalent to:

  :option:`-mcustom-fabss=224` |gol|
  :option:`-mcustom-fnegs=225` |gol|
  :option:`-mcustom-fcmpnes=226` |gol|
  :option:`-mcustom-fcmpeqs=227` |gol|
  :option:`-mcustom-fcmpges=228` |gol|
  :option:`-mcustom-fcmpgts=229` |gol|
  :option:`-mcustom-fcmples=230` |gol|
  :option:`-mcustom-fcmplts=231` |gol|
  :option:`-mcustom-fmaxs=232` |gol|
  :option:`-mcustom-fmins=233` |gol|
  :option:`-mcustom-round=248` |gol|
  :option:`-mcustom-fixsi=249` |gol|
  :option:`-mcustom-floatis=250` |gol|
  :option:`-mcustom-fsqrts=251` |gol|
  :option:`-mcustom-fmuls=252` |gol|
  :option:`-mcustom-fadds=253` |gol|
  :option:`-mcustom-fsubs=254` |gol|
  :option:`-mcustom-fdivs=255` 

  Custom instruction assignments given by individual
  :option:`-mcustom-insn=` options override those given by
  :option:`-mcustom-fpu-cfg=`, regardless of the
  order of the options on the command line.

  Note that you can gain more local control over selection of a FPU
  configuration by using the ``target("custom-fpu-cfg=name")``
  function attribute (see :ref:`function-attributes`)
  or pragma (see :ref:`function-specific-option-pragmas`).

  The name :samp:`{fph2}` is an abbreviation for *Nios II Floating Point
  Hardware 2 Component*.  Please note that the custom instructions enabled by
  :option:`-mcustom-fmins=233` and :option:`-mcustom-fmaxs=234` are only generated
  if :option:`-ffinite-math-only` is specified.  The custom instruction enabled by
  :option:`-mcustom-round=248` is only generated if :option:`-fno-math-errno` is
  specified.  In contrast to the other configurations,
  :option:`-fsingle-precision-constant` is not set.

These additional :samp:`-m` options are available for the Altera Nios II
ELF (bare-metal) target:

.. option:: -mhal

  Link with HAL BSP.  This suppresses linking with the GCC-provided C runtime
  startup and termination code, and is typically used in conjunction with
  :option:`-msys-crt0=` to specify the location of the alternate startup code
  provided by the HAL BSP.

.. option:: -msmallc

  Link with a limited version of the C library, :option:`-lsmallc`, rather than
  Newlib.

.. option:: -msys-crt0={startfile}

  :samp:`{startfile}` is the file name of the startfile (crt0) to use 
  when linking.  This option is only useful in conjunction with :option:`-mhal`.

.. option:: -msys-lib={systemlib}

  :samp:`{systemlib}` is the library name of the library that provides
  low-level system calls required by the C library,
  e.g. ``read`` and ``write``.
  This option is typically used to link with a library provided by a HAL BSP.