gas/doc/c-nios2.texi

   1 @c Copyright (C) 2012-2023 Free Software Foundation, Inc.
   2 @c This is part of the GAS manual.
   3 @c For copying conditions, see the file as.texinfo.
   4 @c man end
   5 @ifset GENERIC
   6 @page
   7 @node NiosII-Dependent
   8 @chapter Nios II Dependent Features
   9 @end ifset
  10 @ifclear GENERIC
  11 @node Machine Dependencies
  12 @chapter Nios II Dependent Features
  13 @end ifclear
  14
  15 @cindex Altera Nios II support
  16 @cindex Nios support
  17 @cindex Nios II support
  18 @menu
  19 * Nios II Options::              Options
  20 * Nios II Syntax::               Syntax
  21 * Nios II Relocations::          Relocations
  22 * Nios II Directives::           Nios II Machine Directives
  23 * Nios II Opcodes::              Opcodes
  24 @end menu
  25
  26 @node Nios II Options
  27 @section Options
  28 @cindex Nios II options
  29 @cindex options for Nios II
  30
  31 @c man begin OPTIONS
  32 @table @gcctabopt
  33
  34 @cindex @code{relax-section} command-line option, Nios II
  35 @item -relax-section
  36 Replace identified out-of-range branches with PC-relative @code{jmp}
  37 sequences when possible.  The generated code sequences are suitable
  38 for use in position-independent code, but there is a practical limit
  39 on the extended branch range because of the length of the sequences.
  40 This option is the default.
  41
  42 @cindex @code{relax-all} command-line option, Nios II
  43 @item -relax-all
  44 Replace branch instructions not determinable to be in range
  45 and all call instructions with @code{jmp} and @code{callr} sequences
  46 (respectively).  This option generates absolute relocations against the
  47 target symbols and is not appropriate for position-independent code.
  48
  49 @cindex @code{no-relax} command-line option, Nios II
  50 @item -no-relax
  51 Do not replace any branches or calls.
  52
  53 @cindex @code{EB} command-line option, Nios II
  54 @item -EB
  55 Generate big-endian output.
  56
  57 @cindex @code{EL} command-line option, Nios II
  58 @item -EL
  59 Generate little-endian output.  This is the default.
  60
  61 @cindex @code{march} command-line option, Nios II
  62 @item -march=@var{architecture}
  63 This option specifies the target architecture.  The assembler issues
  64 an error message if an attempt is made to assemble an instruction which
  65 will not execute on the target architecture.  The following architecture
  66 names are recognized:
  67 @code{r1},
  68 @code{r2}.
  69 The default is @code{r1}.
  70
  71 @end table
  72 @c man end
  73
  74 @node Nios II Syntax
  75 @section Syntax
  76 @menu
  77 * Nios II Chars::                Special Characters
  78 @end menu
  79
  80
  81 @node Nios II Chars
  82 @subsection Special Characters
  83
  84 @cindex line comment character, Nios II
  85 @cindex Nios II line comment character
  86 @cindex line separator character, Nios II
  87 @cindex Nios II line separator character
  88 @samp{#} is the line comment character.
  89 @samp{;} is the line separator character.
  90
  91
  92 @node Nios II Relocations
  93 @section Nios II Machine Relocations
  94
  95 @cindex machine relocations, Nios II
  96 @cindex Nios II machine relocations
  97
  98 @table @code
  99 @cindex @code{hiadj} directive, Nios II
 100 @item %hiadj(@var{expression})
 101 Extract the upper 16 bits of @var{expression} and add
 102 one if the 15th bit is set.
 103
 104 The value of @code{%hiadj(@var{expression})} is:
 105 @smallexample
 106 ((@var{expression} >> 16) & 0xffff) + ((@var{expression} >> 15) & 0x01)
 107 @end smallexample
 108
 109 The @code{%hiadj} relocation is intended to be used with
 110 the @code{addi}, @code{ld} or @code{st} instructions
 111 along with a @code{%lo}, in order to load a 32-bit constant.
 112
 113 @smallexample
 114 movhi r2, %hiadj(symbol)
 115 addi r2, r2, %lo(symbol)
 116 @end smallexample
 117
 118 @cindex @code{hi} directive, Nios II
 119 @item %hi(@var{expression})
 120 Extract the upper 16 bits of @var{expression}.
 121
 122 @cindex @code{lo} directive, Nios II
 123 @item %lo(@var{expression})
 124 Extract the lower 16 bits of @var{expression}.
 125
 126 @cindex @code{gprel} directive, Nios II
 127 @item %gprel(@var{expression})
 128 Subtract the value of the symbol @code{_gp} from
 129 @var{expression}.
 130
 131 The intention of the @code{%gprel} relocation is
 132 to have a fast small area of memory which only
 133 takes a 16-bit immediate to access.
 134
 135 @smallexample
 136         .section .sdata
 137 fastint:
 138         .int 123
 139         .section .text
 140         ldw r4, %gprel(fastint)(gp)
 141 @end smallexample
 142
 143 @cindex @code{call} directive, Nios II
 144 @cindex @code{call_lo} directive, Nios II
 145 @cindex @code{call_hiadj} directive, Nios II
 146 @cindex @code{got} directive, Nios II
 147 @cindex @code{got_lo} directive, Nios II
 148 @cindex @code{got_hiadj} directive, Nios II
 149 @cindex @code{gotoff} directive, Nios II
 150 @cindex @code{gotoff_lo} directive, Nios II
 151 @cindex @code{gotoff_hiadj} directive, Nios II
 152 @cindex @code{tls_gd} directive, Nios II
 153 @cindex @code{tls_ie} directive, Nios II
 154 @cindex @code{tls_le} directive, Nios II
 155 @cindex @code{tls_ldm} directive, Nios II
 156 @cindex @code{tls_ldo} directive, Nios II
 157 @item %call(@var{expression})
 158 @item %call_lo(@var{expression})
 159 @item %call_hiadj(@var{expression})
 160 @itemx %got(@var{expression})
 161 @itemx %got_lo(@var{expression})
 162 @itemx %got_hiadj(@var{expression})
 163 @itemx %gotoff(@var{expression})
 164 @itemx %gotoff_lo(@var{expression})
 165 @itemx %gotoff_hiadj(@var{expression})
 166 @itemx %tls_gd(@var{expression})
 167 @itemx %tls_ie(@var{expression})
 168 @itemx %tls_le(@var{expression})
 169 @itemx %tls_ldm(@var{expression})
 170 @itemx %tls_ldo(@var{expression})
 171
 172 These relocations support the ABI for Linux Systems documented in the
 173 @cite{Nios II Processor Reference Handbook}.
 174 @end table
 175
 176
 177 @node Nios II Directives
 178 @section Nios II Machine Directives
 179
 180 @cindex machine directives, Nios II
 181 @cindex Nios II machine directives
 182
 183 @table @code
 184
 185 @cindex @code{align} directive, Nios II
 186 @item .align @var{expression} [, @var{expression}]
 187 This is the generic @code{.align} directive, however
 188 this aligns to a power of two.
 189
 190 @cindex @code{half} directive, Nios II
 191 @item .half @var{expression}
 192 Create an aligned constant 2 bytes in size.
 193
 194 @cindex @code{word} directive, Nios II
 195 @item .word @var{expression}
 196 Create an aligned constant 4 bytes in size.
 197
 198 @cindex @code{dword} directive, Nios II
 199 @item .dword @var{expression}
 200 Create an aligned constant 8 bytes in size.
 201
 202 @cindex @code{2byte} directive, Nios II
 203 @item .2byte @var{expression}
 204 Create an unaligned constant 2 bytes in size.
 205
 206 @cindex @code{4byte} directive, Nios II
 207 @item .4byte @var{expression}
 208 Create an unaligned constant 4 bytes in size.
 209
 210 @cindex @code{8byte} directive, Nios II
 211 @item .8byte @var{expression}
 212 Create an unaligned constant 8 bytes in size.
 213
 214 @cindex @code{16byte} directive, Nios II
 215 @item .16byte @var{expression}
 216 Create an unaligned constant 16 bytes in size.
 217
 218 @cindex @code{set noat} directive, Nios II
 219 @item .set noat
 220 Allows assembly code to use @code{at} register without
 221 warning.  Macro or relaxation expansions
 222 generate warnings.
 223
 224 @cindex @code{set at} directive, Nios II
 225 @item .set at
 226 Assembly code using @code{at} register generates
 227 warnings, and macro expansion and relaxation are
 228 enabled.
 229
 230 @cindex @code{set nobreak} directive, Nios II
 231 @item .set nobreak
 232 Allows assembly code to use @code{ba} and @code{bt}
 233 registers without warning.
 234
 235 @cindex @code{set break} directive, Nios II
 236 @item .set break
 237 Turns warnings back on for using @code{ba} and @code{bt}
 238 registers.
 239
 240 @cindex @code{set norelax} directive, Nios II
 241 @item .set norelax
 242 Do not replace any branches or calls.
 243
 244 @cindex @code{set relaxsection} directive, Nios II
 245 @item .set relaxsection
 246 Replace identified out-of-range branches with
 247 @code{jmp} sequences (default).
 248
 249 @cindex @code{set relaxall} directive, Nios II
 250 @item .set relaxsection
 251 Replace all branch and call instructions with
 252 @code{jmp} and @code{callr} sequences.
 253
 254 @cindex @code{set} directive, Nios II
 255 @item .set @dots{}
 256 All other @code{.set} are the normal use.
 257
 258 @end table
 259
 260 @node Nios II Opcodes
 261 @section Opcodes
 262
 263 @cindex Nios II opcodes
 264 @cindex opcodes for Nios II
 265 @code{@value{AS}} implements all the standard Nios II opcodes documented in the
 266 @cite{Nios II Processor Reference Handbook}, including the assembler
 267 pseudo-instructions.