gcc/doc/gcc/extensions-to-the-c-language-family/target-builtins/fr-v-built-in-functions.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _fr-v-built-in-functions:
   7
   8 FR-V Built-in Functions
   9 ^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 GCC provides many FR-V-specific built-in functions.  In general,
  12 these functions are intended to be compatible with those described
  13 by FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
  14 Semiconductor.  The two exceptions are ``__MDUNPACKH`` and
  15 ``__MBTOHE``, the GCC forms of which pass 128-bit values by
  16 pointer rather than by value.
  17
  18 Most of the functions are named after specific FR-V instructions.
  19 Such functions are said to be 'directly mapped' and are summarized
  20 here in tabular form.
  21
  22 .. toctree::
  23   :maxdepth: 2
  24
  25
  26 .. _argument-types:
  27
  28 Argument Types
  29 ~~~~~~~~~~~~~~
  30
  31 The arguments to the built-in functions can be divided into three groups:
  32 register numbers, compile-time constants and run-time values.  In order
  33 to make this classification clear at a glance, the arguments and return
  34 values are given the following pseudo types:
  35
  36 .. list-table::
  37    :header-rows: 1
  38
  39    * - Pseudo type
  40      - Real C type
  41      - Constant?
  42      - Description
  43
  44    * - ``uh``
  45      - ``unsigned short``
  46      - No
  47      - an unsigned halfword
  48    * - ``uw1``
  49      - ``unsigned int``
  50      - No
  51      - an unsigned word
  52    * - ``sw1``
  53      - ``int``
  54      - No
  55      - a signed word
  56    * - ``uw2``
  57      - ``unsigned long long``
  58      - No
  59      - an unsigned doubleword
  60    * - ``sw2``
  61      - ``long long``
  62      - No
  63      - a signed doubleword
  64    * - ``const``
  65      - ``int``
  66      - Yes
  67      - an integer constant
  68    * - ``acc``
  69      - ``int``
  70      - Yes
  71      - an ACC register number
  72    * - ``iacc``
  73      - ``int``
  74      - Yes
  75      - an IACC register number
  76
  77 These pseudo types are not defined by GCC, they are simply a notational
  78 convenience used in this manual.
  79
  80 Arguments of type ``uh``, ``uw1``, ``sw1``, ``uw2``
  81 and ``sw2`` are evaluated at run time.  They correspond to
  82 register operands in the underlying FR-V instructions.
  83
  84 ``const`` arguments represent immediate operands in the underlying
  85 FR-V instructions.  They must be compile-time constants.
  86
  87 ``acc`` arguments are evaluated at compile time and specify the number
  88 of an accumulator register.  For example, an ``acc`` argument of 2
  89 selects the ACC2 register.
  90
  91 ``iacc`` arguments are similar to ``acc`` arguments but specify the
  92 number of an IACC register.  See see :ref:`other-builtins`
  93 for more details.
  94
  95 .. _directly-mapped-integer-functions:
  96
  97 Directly-Mapped Integer Functions
  98 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  99
 100 The functions listed below map directly to FR-V I-type instructions.
 101
 102 .. list-table::
 103    :header-rows: 1
 104
 105    * - Function prototype
 106      - Example usage
 107      - Assembly output
 108
 109    * - ``sw1 __ADDSS (sw1, sw1)``
 110      - ``c = __ADDSS (a, b)``
 111      - ``ADDSS a,b,c``
 112    * - ``sw1 __SCAN (sw1, sw1)``
 113      - ``c = __SCAN (a, b)``
 114      - ``SCAN a,b,c``
 115    * - ``sw1 __SCUTSS (sw1)``
 116      - ``b = __SCUTSS (a)``
 117      - ``SCUTSS a,b``
 118    * - ``sw1 __SLASS (sw1, sw1)``
 119      - ``c = __SLASS (a, b)``
 120      - ``SLASS a,b,c``
 121    * - ``void __SMASS (sw1, sw1)``
 122      - ``__SMASS (a, b)``
 123      - ``SMASS a,b``
 124    * - ``void __SMSSS (sw1, sw1)``
 125      - ``__SMSSS (a, b)``
 126      - ``SMSSS a,b``
 127    * - ``void __SMU (sw1, sw1)``
 128      - ``__SMU (a, b)``
 129      - ``SMU a,b``
 130    * - ``sw2 __SMUL (sw1, sw1)``
 131      - ``c = __SMUL (a, b)``
 132      - ``SMUL a,b,c``
 133    * - ``sw1 __SUBSS (sw1, sw1)``
 134      - ``c = __SUBSS (a, b)``
 135      - ``SUBSS a,b,c``
 136    * - ``uw2 __UMUL (uw1, uw1)``
 137      - ``c = __UMUL (a, b)``
 138      - ``UMUL a,b,c``
 139
 140 .. _directly-mapped-media-functions:
 141
 142 Directly-Mapped Media Functions
 143 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 144
 145 The functions listed below map directly to FR-V M-type instructions.
 146
 147 .. list-table::
 148    :header-rows: 1
 149
 150    * - Function prototype
 151      - Example usage
 152      - Assembly output
 153
 154    * - ``uw1 __MABSHS (sw1)``
 155      - ``b = __MABSHS (a)``
 156      - ``MABSHS a,b``
 157    * - ``void __MADDACCS (acc, acc)``
 158      - ``__MADDACCS (b, a)``
 159      - ``MADDACCS a,b``
 160    * - ``sw1 __MADDHSS (sw1, sw1)``
 161      - ``c = __MADDHSS (a, b)``
 162      - ``MADDHSS a,b,c``
 163    * - ``uw1 __MADDHUS (uw1, uw1)``
 164      - ``c = __MADDHUS (a, b)``
 165      - ``MADDHUS a,b,c``
 166    * - ``uw1 __MAND (uw1, uw1)``
 167      - ``c = __MAND (a, b)``
 168      - ``MAND a,b,c``
 169    * - ``void __MASACCS (acc, acc)``
 170      - ``__MASACCS (b, a)``
 171      - ``MASACCS a,b``
 172    * - ``uw1 __MAVEH (uw1, uw1)``
 173      - ``c = __MAVEH (a, b)``
 174      - ``MAVEH a,b,c``
 175    * - ``uw2 __MBTOH (uw1)``
 176      - ``b = __MBTOH (a)``
 177      - ``MBTOH a,b``
 178    * - ``void __MBTOHE (uw1 *, uw1)``
 179      - ``__MBTOHE (&b, a)``
 180      - ``MBTOHE a,b``
 181    * - ``void __MCLRACC (acc)``
 182      - ``__MCLRACC (a)``
 183      - ``MCLRACC a``
 184    * - ``void __MCLRACCA (void)``
 185      - ``__MCLRACCA ()``
 186      - ``MCLRACCA``
 187    * - ``uw1 __Mcop1 (uw1, uw1)``
 188      - ``c = __Mcop1 (a, b)``
 189      - ``Mcop1 a,b,c``
 190    * - ``uw1 __Mcop2 (uw1, uw1)``
 191      - ``c = __Mcop2 (a, b)``
 192      - ``Mcop2 a,b,c``
 193    * - ``uw1 __MCPLHI (uw2, const)``
 194      - ``c = __MCPLHI (a, b)``
 195      - ``MCPLHI a,#b,c``
 196    * - ``uw1 __MCPLI (uw2, const)``
 197      - ``c = __MCPLI (a, b)``
 198      - ``MCPLI a,#b,c``
 199    * - ``void __MCPXIS (acc, sw1, sw1)``
 200      - ``__MCPXIS (c, a, b)``
 201      - ``MCPXIS a,b,c``
 202    * - ``void __MCPXIU (acc, uw1, uw1)``
 203      - ``__MCPXIU (c, a, b)``
 204      - ``MCPXIU a,b,c``
 205    * - ``void __MCPXRS (acc, sw1, sw1)``
 206      - ``__MCPXRS (c, a, b)``
 207      - ``MCPXRS a,b,c``
 208    * - ``void __MCPXRU (acc, uw1, uw1)``
 209      - ``__MCPXRU (c, a, b)``
 210      - ``MCPXRU a,b,c``
 211    * - ``uw1 __MCUT (acc, uw1)``
 212      - ``c = __MCUT (a, b)``
 213      - ``MCUT a,b,c``
 214    * - ``uw1 __MCUTSS (acc, sw1)``
 215      - ``c = __MCUTSS (a, b)``
 216      - ``MCUTSS a,b,c``
 217    * - ``void __MDADDACCS (acc, acc)``
 218      - ``__MDADDACCS (b, a)``
 219      - ``MDADDACCS a,b``
 220    * - ``void __MDASACCS (acc, acc)``
 221      - ``__MDASACCS (b, a)``
 222      - ``MDASACCS a,b``
 223    * - ``uw2 __MDCUTSSI (acc, const)``
 224      - ``c = __MDCUTSSI (a, b)``
 225      - ``MDCUTSSI a,#b,c``
 226    * - ``uw2 __MDPACKH (uw2, uw2)``
 227      - ``c = __MDPACKH (a, b)``
 228      - ``MDPACKH a,b,c``
 229    * - ``uw2 __MDROTLI (uw2, const)``
 230      - ``c = __MDROTLI (a, b)``
 231      - ``MDROTLI a,#b,c``
 232    * - ``void __MDSUBACCS (acc, acc)``
 233      - ``__MDSUBACCS (b, a)``
 234      - ``MDSUBACCS a,b``
 235    * - ``void __MDUNPACKH (uw1 *, uw2)``
 236      - ``__MDUNPACKH (&b, a)``
 237      - ``MDUNPACKH a,b``
 238    * - ``uw2 __MEXPDHD (uw1, const)``
 239      - ``c = __MEXPDHD (a, b)``
 240      - ``MEXPDHD a,#b,c``
 241    * - ``uw1 __MEXPDHW (uw1, const)``
 242      - ``c = __MEXPDHW (a, b)``
 243      - ``MEXPDHW a,#b,c``
 244    * - ``uw1 __MHDSETH (uw1, const)``
 245      - ``c = __MHDSETH (a, b)``
 246      - ``MHDSETH a,#b,c``
 247    * - ``sw1 __MHDSETS (const)``
 248      - ``b = __MHDSETS (a)``
 249      - ``MHDSETS #a,b``
 250    * - ``uw1 __MHSETHIH (uw1, const)``
 251      - ``b = __MHSETHIH (b, a)``
 252      - ``MHSETHIH #a,b``
 253    * - ``sw1 __MHSETHIS (sw1, const)``
 254      - ``b = __MHSETHIS (b, a)``
 255      - ``MHSETHIS #a,b``
 256    * - ``uw1 __MHSETLOH (uw1, const)``
 257      - ``b = __MHSETLOH (b, a)``
 258      - ``MHSETLOH #a,b``
 259    * - ``sw1 __MHSETLOS (sw1, const)``
 260      - ``b = __MHSETLOS (b, a)``
 261      - ``MHSETLOS #a,b``
 262    * - ``uw1 __MHTOB (uw2)``
 263      - ``b = __MHTOB (a)``
 264      - ``MHTOB a,b``
 265    * - ``void __MMACHS (acc, sw1, sw1)``
 266      - ``__MMACHS (c, a, b)``
 267      - ``MMACHS a,b,c``
 268    * - ``void __MMACHU (acc, uw1, uw1)``
 269      - ``__MMACHU (c, a, b)``
 270      - ``MMACHU a,b,c``
 271    * - ``void __MMRDHS (acc, sw1, sw1)``
 272      - ``__MMRDHS (c, a, b)``
 273      - ``MMRDHS a,b,c``
 274    * - ``void __MMRDHU (acc, uw1, uw1)``
 275      - ``__MMRDHU (c, a, b)``
 276      - ``MMRDHU a,b,c``
 277    * - ``void __MMULHS (acc, sw1, sw1)``
 278      - ``__MMULHS (c, a, b)``
 279      - ``MMULHS a,b,c``
 280    * - ``void __MMULHU (acc, uw1, uw1)``
 281      - ``__MMULHU (c, a, b)``
 282      - ``MMULHU a,b,c``
 283    * - ``void __MMULXHS (acc, sw1, sw1)``
 284      - ``__MMULXHS (c, a, b)``
 285      - ``MMULXHS a,b,c``
 286    * - ``void __MMULXHU (acc, uw1, uw1)``
 287      - ``__MMULXHU (c, a, b)``
 288      - ``MMULXHU a,b,c``
 289    * - ``uw1 __MNOT (uw1)``
 290      - ``b = __MNOT (a)``
 291      - ``MNOT a,b``
 292    * - ``uw1 __MOR (uw1, uw1)``
 293      - ``c = __MOR (a, b)``
 294      - ``MOR a,b,c``
 295    * - ``uw1 __MPACKH (uh, uh)``
 296      - ``c = __MPACKH (a, b)``
 297      - ``MPACKH a,b,c``
 298    * - ``sw2 __MQADDHSS (sw2, sw2)``
 299      - ``c = __MQADDHSS (a, b)``
 300      - ``MQADDHSS a,b,c``
 301    * - ``uw2 __MQADDHUS (uw2, uw2)``
 302      - ``c = __MQADDHUS (a, b)``
 303      - ``MQADDHUS a,b,c``
 304    * - ``void __MQCPXIS (acc, sw2, sw2)``
 305      - ``__MQCPXIS (c, a, b)``
 306      - ``MQCPXIS a,b,c``
 307    * - ``void __MQCPXIU (acc, uw2, uw2)``
 308      - ``__MQCPXIU (c, a, b)``
 309      - ``MQCPXIU a,b,c``
 310    * - ``void __MQCPXRS (acc, sw2, sw2)``
 311      - ``__MQCPXRS (c, a, b)``
 312      - ``MQCPXRS a,b,c``
 313    * - ``void __MQCPXRU (acc, uw2, uw2)``
 314      - ``__MQCPXRU (c, a, b)``
 315      - ``MQCPXRU a,b,c``
 316    * - ``sw2 __MQLCLRHS (sw2, sw2)``
 317      - ``c = __MQLCLRHS (a, b)``
 318      - ``MQLCLRHS a,b,c``
 319    * - ``sw2 __MQLMTHS (sw2, sw2)``
 320      - ``c = __MQLMTHS (a, b)``
 321      - ``MQLMTHS a,b,c``
 322    * - ``void __MQMACHS (acc, sw2, sw2)``
 323      - ``__MQMACHS (c, a, b)``
 324      - ``MQMACHS a,b,c``
 325    * - ``void __MQMACHU (acc, uw2, uw2)``
 326      - ``__MQMACHU (c, a, b)``
 327      - ``MQMACHU a,b,c``
 328    * - ``void __MQMACXHS (acc, sw2, sw2)``
 329      - ``__MQMACXHS (c, a, b)``
 330      - ``MQMACXHS a,b,c``
 331    * - ``void __MQMULHS (acc, sw2, sw2)``
 332      - ``__MQMULHS (c, a, b)``
 333      - ``MQMULHS a,b,c``
 334    * - ``void __MQMULHU (acc, uw2, uw2)``
 335      - ``__MQMULHU (c, a, b)``
 336      - ``MQMULHU a,b,c``
 337    * - ``void __MQMULXHS (acc, sw2, sw2)``
 338      - ``__MQMULXHS (c, a, b)``
 339      - ``MQMULXHS a,b,c``
 340    * - ``void __MQMULXHU (acc, uw2, uw2)``
 341      - ``__MQMULXHU (c, a, b)``
 342      - ``MQMULXHU a,b,c``
 343    * - ``sw2 __MQSATHS (sw2, sw2)``
 344      - ``c = __MQSATHS (a, b)``
 345      - ``MQSATHS a,b,c``
 346    * - ``uw2 __MQSLLHI (uw2, int)``
 347      - ``c = __MQSLLHI (a, b)``
 348      - ``MQSLLHI a,b,c``
 349    * - ``sw2 __MQSRAHI (sw2, int)``
 350      - ``c = __MQSRAHI (a, b)``
 351      - ``MQSRAHI a,b,c``
 352    * - ``sw2 __MQSUBHSS (sw2, sw2)``
 353      - ``c = __MQSUBHSS (a, b)``
 354      - ``MQSUBHSS a,b,c``
 355    * - ``uw2 __MQSUBHUS (uw2, uw2)``
 356      - ``c = __MQSUBHUS (a, b)``
 357      - ``MQSUBHUS a,b,c``
 358    * - ``void __MQXMACHS (acc, sw2, sw2)``
 359      - ``__MQXMACHS (c, a, b)``
 360      - ``MQXMACHS a,b,c``
 361    * - ``void __MQXMACXHS (acc, sw2, sw2)``
 362      - ``__MQXMACXHS (c, a, b)``
 363      - ``MQXMACXHS a,b,c``
 364    * - ``uw1 __MRDACC (acc)``
 365      - ``b = __MRDACC (a)``
 366      - ``MRDACC a,b``
 367    * - ``uw1 __MRDACCG (acc)``
 368      - ``b = __MRDACCG (a)``
 369      - ``MRDACCG a,b``
 370    * - ``uw1 __MROTLI (uw1, const)``
 371      - ``c = __MROTLI (a, b)``
 372      - ``MROTLI a,#b,c``
 373    * - ``uw1 __MROTRI (uw1, const)``
 374      - ``c = __MROTRI (a, b)``
 375      - ``MROTRI a,#b,c``
 376    * - ``sw1 __MSATHS (sw1, sw1)``
 377      - ``c = __MSATHS (a, b)``
 378      - ``MSATHS a,b,c``
 379    * - ``uw1 __MSATHU (uw1, uw1)``
 380      - ``c = __MSATHU (a, b)``
 381      - ``MSATHU a,b,c``
 382    * - ``uw1 __MSLLHI (uw1, const)``
 383      - ``c = __MSLLHI (a, b)``
 384      - ``MSLLHI a,#b,c``
 385    * - ``sw1 __MSRAHI (sw1, const)``
 386      - ``c = __MSRAHI (a, b)``
 387      - ``MSRAHI a,#b,c``
 388    * - ``uw1 __MSRLHI (uw1, const)``
 389      - ``c = __MSRLHI (a, b)``
 390      - ``MSRLHI a,#b,c``
 391    * - ``void __MSUBACCS (acc, acc)``
 392      - ``__MSUBACCS (b, a)``
 393      - ``MSUBACCS a,b``
 394    * - ``sw1 __MSUBHSS (sw1, sw1)``
 395      - ``c = __MSUBHSS (a, b)``
 396      - ``MSUBHSS a,b,c``
 397    * - ``uw1 __MSUBHUS (uw1, uw1)``
 398      - ``c = __MSUBHUS (a, b)``
 399      - ``MSUBHUS a,b,c``
 400    * - ``void __MTRAP (void)``
 401      - ``__MTRAP ()``
 402      - ``MTRAP``
 403    * - ``uw2 __MUNPACKH (uw1)``
 404      - ``b = __MUNPACKH (a)``
 405      - ``MUNPACKH a,b``
 406    * - ``uw1 __MWCUT (uw2, uw1)``
 407      - ``c = __MWCUT (a, b)``
 408      - ``MWCUT a,b,c``
 409    * - ``void __MWTACC (acc, uw1)``
 410      - ``__MWTACC (b, a)``
 411      - ``MWTACC a,b``
 412    * - ``void __MWTACCG (acc, uw1)``
 413      - ``__MWTACCG (b, a)``
 414      - ``MWTACCG a,b``
 415    * - ``uw1 __MXOR (uw1, uw1)``
 416      - ``c = __MXOR (a, b)``
 417      - ``MXOR a,b,c``
 418
 419 .. _raw-read-write-functions:
 420
 421 Raw Read/Write Functions
 422 ~~~~~~~~~~~~~~~~~~~~~~~~
 423
 424 This sections describes built-in functions related to read and write
 425 instructions to access memory.  These functions generate
 426 ``membar`` instructions to flush the I/O load and stores where
 427 appropriate, as described in Fujitsu's manual described above.
 428
 429 .. code-block:: c++
 430
 431   unsigned char __builtin_read8 (void *data);
 432   unsigned short __builtin_read16 (void *data);
 433   unsigned long __builtin_read32 (void *data);
 434   unsigned long long __builtin_read64 (void *data);
 435   void __builtin_write8 (void *data, unsigned char datum);
 436   void __builtin_write16 (void *data, unsigned short datum);
 437   void __builtin_write32 (void *data, unsigned long datum);
 438   void __builtin_write64 (void *data, unsigned long long datum);
 439
 440 Other Built-in Functions
 441 ~~~~~~~~~~~~~~~~~~~~~~~~
 442
 443 This section describes built-in functions that are not named after
 444 a specific FR-V instruction.
 445
 446 .. function:: sw2 __IACCreadll (iacc reg)
 447
 448   Return the full 64-bit value of IACC0.  The :samp:`{reg}` argument is reserved
 449   for future expansion and must be 0.
 450
 451 .. function:: sw1 __IACCreadl (iacc reg)
 452
 453   Return the value of IACC0H if :samp:`{reg}` is 0 and IACC0L if :samp:`{reg}` is 1.
 454   Other values of :samp:`{reg}` are rejected as invalid.
 455
 456 .. function:: void __IACCsetll (iacc reg, sw2 x)
 457
 458   Set the full 64-bit value of IACC0 to :samp:`{x}`.  The :samp:`{reg}` argument
 459   is reserved for future expansion and must be 0.
 460
 461 .. function:: void __IACCsetl (iacc reg, sw1 x)
 462
 463   Set IACC0H to :samp:`{x}` if :samp:`{reg}` is 0 and IACC0L to :samp:`{x}` if :samp:`{reg}`
 464   is 1.  Other values of :samp:`{reg}` are rejected as invalid.
 465
 466 .. function:: void __data_prefetch0 (const void *x)
 467
 468   Use the ``dcpl`` instruction to load the contents of address :samp:`{x}`
 469   into the data cache.
 470
 471 .. function:: void __data_prefetch (const void *x)
 472
 473   Use the ``nldub`` instruction to load the contents of address :samp:`{x}`
 474   into the data cache.  The instruction is issued in slot I1.