]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
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 | .. _sh-function-attributes: | |
7 | ||
8 | SH Function Attributes | |
9 | ^^^^^^^^^^^^^^^^^^^^^^ | |
10 | ||
11 | These function attributes are supported on the SH family of processors: | |
12 | ||
13 | .. index:: function_vector function attribute, SH, calling functions through the function vector on SH2A | |
14 | ||
15 | .. sh-fn-attr:: function_vector | |
16 | ||
17 | On SH2A targets, this attribute declares a function to be called using the | |
18 | TBR relative addressing mode. The argument to this attribute is the entry | |
19 | number of the same function in a vector table containing all the TBR | |
20 | relative addressable functions. For correct operation the TBR must be setup | |
21 | accordingly to point to the start of the vector table before any functions with | |
22 | this attribute are invoked. Usually a good place to do the initialization is | |
23 | the startup routine. The TBR relative vector table can have at max 256 function | |
24 | entries. The jumps to these functions are generated using a SH2A specific, | |
25 | non delayed branch instruction JSR/N @(disp8,TBR). You must use GAS and GLD | |
26 | from GNU binutils version 2.7 or later for this attribute to work correctly. | |
27 | ||
28 | In an application, for a function being called once, this attribute | |
29 | saves at least 8 bytes of code; and if other successive calls are being | |
30 | made to the same function, it saves 2 bytes of code per each of these | |
31 | calls. | |
32 | ||
33 | .. index:: interrupt_handler function attribute, SH | |
34 | ||
35 | .. sh-fn-attr:: interrupt_handler | |
36 | ||
37 | Use this attribute to | |
38 | indicate that the specified function is an interrupt handler. The compiler | |
39 | generates function entry and exit sequences suitable for use in an | |
40 | interrupt handler when this attribute is present. | |
41 | ||
42 | .. index:: nosave_low_regs function attribute, SH | |
43 | ||
44 | .. sh-fn-attr:: nosave_low_regs | |
45 | ||
46 | Use this attribute on SH targets to indicate that an :sh-fn-attr:`interrupt_handler` | |
47 | function should not save and restore registers R0..R7. This can be used on SH3\* | |
48 | and SH4\* targets that have a second R0..R7 register bank for non-reentrant | |
49 | interrupt handlers. | |
50 | ||
51 | .. index:: renesas function attribute, SH | |
52 | ||
53 | .. sh-fn-attr:: renesas | |
54 | ||
55 | On SH targets this attribute specifies that the function or struct follows the | |
56 | Renesas ABI. | |
57 | ||
58 | .. index:: resbank function attribute, SH | |
59 | ||
60 | .. sh-fn-attr:: resbank | |
61 | ||
62 | On the SH2A target, this attribute enables the high-speed register | |
63 | saving and restoration using a register bank for :sh-fn-attr:`interrupt_handler` | |
64 | routines. Saving to the bank is performed automatically after the CPU | |
65 | accepts an interrupt that uses a register bank. | |
66 | ||
67 | The nineteen 32-bit registers comprising general register R0 to R14, | |
68 | control register GBR, and system registers MACH, MACL, and PR and the | |
69 | vector table address offset are saved into a register bank. Register | |
70 | banks are stacked in first-in last-out (FILO) sequence. Restoration | |
71 | from the bank is executed by issuing a RESBANK instruction. | |
72 | ||
73 | .. index:: sp_switch function attribute, SH | |
74 | ||
75 | .. sh-fn-attr:: sp_switch | |
76 | ||
77 | Use this attribute on the SH to indicate an :sh-fn-attr:`interrupt_handler` | |
78 | function should switch to an alternate stack. It expects a string | |
79 | argument that names a global variable holding the address of the | |
80 | alternate stack. | |
81 | ||
82 | .. code-block:: c++ | |
83 | ||
84 | void *alt_stack; | |
85 | void f () __attribute__ ((interrupt_handler, | |
86 | sp_switch ("alt_stack"))); | |
87 | ||
88 | .. index:: trap_exit function attribute, SH | |
89 | ||
90 | .. sh-fn-attr:: trap_exit | |
91 | ||
92 | Use this attribute on the SH for an :sh-fn-attr:`interrupt_handler` to return using | |
93 | ``trapa`` instead of ``rte``. This attribute expects an integer | |
94 | argument specifying the trap number to be used. | |
95 | ||
96 | .. index:: trapa_handler function attribute, SH | |
97 | ||
98 | .. sh-fn-attr:: trapa_handler | |
99 | ||
100 | On SH targets this function attribute is similar to :sh-fn-attr:`interrupt_handler` | |
3ed1b4ce | 101 | but it does not save and restore all registers. |