Target-Attributes.html 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2. <html>
  3. <!-- Copyright (C) 1988-2017 Free Software Foundation, Inc.
  4. Permission is granted to copy, distribute and/or modify this document
  5. under the terms of the GNU Free Documentation License, Version 1.3 or
  6. any later version published by the Free Software Foundation; with the
  7. Invariant Sections being "Funding Free Software", the Front-Cover
  8. Texts being (a) (see below), and with the Back-Cover Texts being (b)
  9. (see below). A copy of the license is included in the section entitled
  10. "GNU Free Documentation License".
  11. (a) The FSF's Front-Cover Text is:
  12. A GNU Manual
  13. (b) The FSF's Back-Cover Text is:
  14. You have freedom to copy and modify this GNU Manual, like GNU
  15. software. Copies published by the Free Software Foundation raise
  16. funds for GNU development. -->
  17. <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
  18. <head>
  19. <title>GNU Compiler Collection (GCC) Internals: Target Attributes</title>
  20. <meta name="description" content="GNU Compiler Collection (GCC) Internals: Target Attributes">
  21. <meta name="keywords" content="GNU Compiler Collection (GCC) Internals: Target Attributes">
  22. <meta name="resource-type" content="document">
  23. <meta name="distribution" content="global">
  24. <meta name="Generator" content="makeinfo">
  25. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  26. <link href="index.html#Top" rel="start" title="Top">
  27. <link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
  28. <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
  29. <link href="Target-Macros.html#Target-Macros" rel="up" title="Target Macros">
  30. <link href="Emulated-TLS.html#Emulated-TLS" rel="next" title="Emulated TLS">
  31. <link href="Mode-Switching.html#Mode-Switching" rel="prev" title="Mode Switching">
  32. <style type="text/css">
  33. <!--
  34. a.summary-letter {text-decoration: none}
  35. blockquote.smallquotation {font-size: smaller}
  36. div.display {margin-left: 3.2em}
  37. div.example {margin-left: 3.2em}
  38. div.indentedblock {margin-left: 3.2em}
  39. div.lisp {margin-left: 3.2em}
  40. div.smalldisplay {margin-left: 3.2em}
  41. div.smallexample {margin-left: 3.2em}
  42. div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
  43. div.smalllisp {margin-left: 3.2em}
  44. kbd {font-style:oblique}
  45. pre.display {font-family: inherit}
  46. pre.format {font-family: inherit}
  47. pre.menu-comment {font-family: serif}
  48. pre.menu-preformatted {font-family: serif}
  49. pre.smalldisplay {font-family: inherit; font-size: smaller}
  50. pre.smallexample {font-size: smaller}
  51. pre.smallformat {font-family: inherit; font-size: smaller}
  52. pre.smalllisp {font-size: smaller}
  53. span.nocodebreak {white-space:nowrap}
  54. span.nolinebreak {white-space:nowrap}
  55. span.roman {font-family:serif; font-weight:normal}
  56. span.sansserif {font-family:sans-serif; font-weight:normal}
  57. ul.no-bullet {list-style: none}
  58. -->
  59. </style>
  60. </head>
  61. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  62. <a name="Target-Attributes"></a>
  63. <div class="header">
  64. <p>
  65. Next: <a href="Emulated-TLS.html#Emulated-TLS" accesskey="n" rel="next">Emulated TLS</a>, Previous: <a href="Mode-Switching.html#Mode-Switching" accesskey="p" rel="prev">Mode Switching</a>, Up: <a href="Target-Macros.html#Target-Macros" accesskey="u" rel="up">Target Macros</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
  66. </div>
  67. <hr>
  68. <a name="Defining-target_002dspecific-uses-of-_005f_005fattribute_005f_005f"></a>
  69. <h3 class="section">17.24 Defining target-specific uses of <code>__attribute__</code></h3>
  70. <a name="index-target-attributes"></a>
  71. <a name="index-machine-attributes"></a>
  72. <a name="index-attributes_002c-target_002dspecific"></a>
  73. <p>Target-specific attributes may be defined for functions, data and types.
  74. These are described using the following target hooks; they also need to
  75. be documented in <samp>extend.texi</samp>.
  76. </p>
  77. <dl>
  78. <dt><a name="index-TARGET_005fATTRIBUTE_005fTABLE"></a>Target Hook: <em>const struct attribute_spec *</em> <strong>TARGET_ATTRIBUTE_TABLE</strong></dt>
  79. <dd><p>If defined, this target hook points to an array of &lsquo;<samp>struct
  80. attribute_spec</samp>&rsquo; (defined in <samp>tree-core.h</samp>) specifying the machine
  81. specific attributes for this target and some of the restrictions on the
  82. entities to which these attributes are applied and the arguments they
  83. take.
  84. </p></dd></dl>
  85. <dl>
  86. <dt><a name="index-TARGET_005fATTRIBUTE_005fTAKES_005fIDENTIFIER_005fP"></a>Target Hook: <em>bool</em> <strong>TARGET_ATTRIBUTE_TAKES_IDENTIFIER_P</strong> <em>(const_tree <var>name</var>)</em></dt>
  87. <dd><p>If defined, this target hook is a function which returns true if the
  88. machine-specific attribute named <var>name</var> expects an identifier
  89. given as its first argument to be passed on as a plain identifier, not
  90. subjected to name lookup. If this is not defined, the default is
  91. false for all machine-specific attributes.
  92. </p></dd></dl>
  93. <dl>
  94. <dt><a name="index-TARGET_005fCOMP_005fTYPE_005fATTRIBUTES"></a>Target Hook: <em>int</em> <strong>TARGET_COMP_TYPE_ATTRIBUTES</strong> <em>(const_tree <var>type1</var>, const_tree <var>type2</var>)</em></dt>
  95. <dd><p>If defined, this target hook is a function which returns zero if the attributes on
  96. <var>type1</var> and <var>type2</var> are incompatible, one if they are compatible,
  97. and two if they are nearly compatible (which causes a warning to be
  98. generated). If this is not defined, machine-specific attributes are
  99. supposed always to be compatible.
  100. </p></dd></dl>
  101. <dl>
  102. <dt><a name="index-TARGET_005fSET_005fDEFAULT_005fTYPE_005fATTRIBUTES"></a>Target Hook: <em>void</em> <strong>TARGET_SET_DEFAULT_TYPE_ATTRIBUTES</strong> <em>(tree <var>type</var>)</em></dt>
  103. <dd><p>If defined, this target hook is a function which assigns default attributes to
  104. the newly defined <var>type</var>.
  105. </p></dd></dl>
  106. <dl>
  107. <dt><a name="index-TARGET_005fMERGE_005fTYPE_005fATTRIBUTES"></a>Target Hook: <em>tree</em> <strong>TARGET_MERGE_TYPE_ATTRIBUTES</strong> <em>(tree <var>type1</var>, tree <var>type2</var>)</em></dt>
  108. <dd><p>Define this target hook if the merging of type attributes needs special
  109. handling. If defined, the result is a list of the combined
  110. <code>TYPE_ATTRIBUTES</code> of <var>type1</var> and <var>type2</var>. It is assumed
  111. that <code>comptypes</code> has already been called and returned 1. This
  112. function may call <code>merge_attributes</code> to handle machine-independent
  113. merging.
  114. </p></dd></dl>
  115. <dl>
  116. <dt><a name="index-TARGET_005fMERGE_005fDECL_005fATTRIBUTES"></a>Target Hook: <em>tree</em> <strong>TARGET_MERGE_DECL_ATTRIBUTES</strong> <em>(tree <var>olddecl</var>, tree <var>newdecl</var>)</em></dt>
  117. <dd><p>Define this target hook if the merging of decl attributes needs special
  118. handling. If defined, the result is a list of the combined
  119. <code>DECL_ATTRIBUTES</code> of <var>olddecl</var> and <var>newdecl</var>.
  120. <var>newdecl</var> is a duplicate declaration of <var>olddecl</var>. Examples of
  121. when this is needed are when one attribute overrides another, or when an
  122. attribute is nullified by a subsequent definition. This function may
  123. call <code>merge_attributes</code> to handle machine-independent merging.
  124. </p>
  125. <a name="index-TARGET_005fDLLIMPORT_005fDECL_005fATTRIBUTES"></a>
  126. <p>If the only target-specific handling you require is &lsquo;<samp>dllimport</samp>&rsquo;
  127. for Microsoft Windows targets, you should define the macro
  128. <code>TARGET_DLLIMPORT_DECL_ATTRIBUTES</code> to <code>1</code>. The compiler
  129. will then define a function called
  130. <code>merge_dllimport_decl_attributes</code> which can then be defined as
  131. the expansion of <code>TARGET_MERGE_DECL_ATTRIBUTES</code>. You can also
  132. add <code>handle_dll_attribute</code> in the attribute table for your port
  133. to perform initial processing of the &lsquo;<samp>dllimport</samp>&rsquo; and
  134. &lsquo;<samp>dllexport</samp>&rsquo; attributes. This is done in <samp>i386/cygwin.h</samp> and
  135. <samp>i386/i386.c</samp>, for example.
  136. </p></dd></dl>
  137. <dl>
  138. <dt><a name="index-TARGET_005fVALID_005fDLLIMPORT_005fATTRIBUTE_005fP"></a>Target Hook: <em>bool</em> <strong>TARGET_VALID_DLLIMPORT_ATTRIBUTE_P</strong> <em>(const_tree <var>decl</var>)</em></dt>
  139. <dd><p><var>decl</var> is a variable or function with <code>__attribute__((dllimport))</code> specified. Use this hook if the target needs to add extra validation checks to <code>handle_dll_attribute</code>.
  140. </p></dd></dl>
  141. <dl>
  142. <dt><a name="index-TARGET_005fDECLSPEC"></a>Macro: <strong>TARGET_DECLSPEC</strong></dt>
  143. <dd><p>Define this macro to a nonzero value if you want to treat
  144. <code>__declspec(X)</code> as equivalent to <code>__attribute((X))</code>. By
  145. default, this behavior is enabled only for targets that define
  146. <code>TARGET_DLLIMPORT_DECL_ATTRIBUTES</code>. The current implementation
  147. of <code>__declspec</code> is via a built-in macro, but you should not rely
  148. on this implementation detail.
  149. </p></dd></dl>
  150. <dl>
  151. <dt><a name="index-TARGET_005fINSERT_005fATTRIBUTES"></a>Target Hook: <em>void</em> <strong>TARGET_INSERT_ATTRIBUTES</strong> <em>(tree <var>node</var>, tree *<var>attr_ptr</var>)</em></dt>
  152. <dd><p>Define this target hook if you want to be able to add attributes to a decl
  153. when it is being created. This is normally useful for back ends which
  154. wish to implement a pragma by using the attributes which correspond to
  155. the pragma&rsquo;s effect. The <var>node</var> argument is the decl which is being
  156. created. The <var>attr_ptr</var> argument is a pointer to the attribute list
  157. for this decl. The list itself should not be modified, since it may be
  158. shared with other decls, but attributes may be chained on the head of
  159. the list and <code>*<var>attr_ptr</var></code> modified to point to the new
  160. attributes, or a copy of the list may be made if further changes are
  161. needed.
  162. </p></dd></dl>
  163. <dl>
  164. <dt><a name="index-TARGET_005fFUNCTION_005fATTRIBUTE_005fINLINABLE_005fP"></a>Target Hook: <em>bool</em> <strong>TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P</strong> <em>(const_tree <var>fndecl</var>)</em></dt>
  165. <dd><a name="index-inlining"></a>
  166. <p>This target hook returns <code>true</code> if it is OK to inline <var>fndecl</var>
  167. into the current function, despite its having target-specific
  168. attributes, <code>false</code> otherwise. By default, if a function has a
  169. target specific attribute attached to it, it will not be inlined.
  170. </p></dd></dl>
  171. <dl>
  172. <dt><a name="index-TARGET_005fOPTION_005fVALID_005fATTRIBUTE_005fP"></a>Target Hook: <em>bool</em> <strong>TARGET_OPTION_VALID_ATTRIBUTE_P</strong> <em>(tree <var>fndecl</var>, tree <var>name</var>, tree <var>args</var>, int <var>flags</var>)</em></dt>
  173. <dd><p>This hook is called to parse <code>attribute(target(&quot;...&quot;))</code>, which
  174. allows setting target-specific options on individual functions.
  175. These function-specific options may differ
  176. from the options specified on the command line. The hook should return
  177. <code>true</code> if the options are valid.
  178. </p>
  179. <p>The hook should set the <code>DECL_FUNCTION_SPECIFIC_TARGET</code> field in
  180. the function declaration to hold a pointer to a target-specific
  181. <code>struct cl_target_option</code> structure.
  182. </p></dd></dl>
  183. <dl>
  184. <dt><a name="index-TARGET_005fOPTION_005fSAVE"></a>Target Hook: <em>void</em> <strong>TARGET_OPTION_SAVE</strong> <em>(struct cl_target_option *<var>ptr</var>, struct gcc_options *<var>opts</var>)</em></dt>
  185. <dd><p>This hook is called to save any additional target-specific information
  186. in the <code>struct cl_target_option</code> structure for function-specific
  187. options from the <code>struct gcc_options</code> structure.
  188. See <a href="Option-file-format.html#Option-file-format">Option file format</a>.
  189. </p></dd></dl>
  190. <dl>
  191. <dt><a name="index-TARGET_005fOPTION_005fRESTORE"></a>Target Hook: <em>void</em> <strong>TARGET_OPTION_RESTORE</strong> <em>(struct gcc_options *<var>opts</var>, struct cl_target_option *<var>ptr</var>)</em></dt>
  192. <dd><p>This hook is called to restore any additional target-specific
  193. information in the <code>struct cl_target_option</code> structure for
  194. function-specific options to the <code>struct gcc_options</code> structure.
  195. </p></dd></dl>
  196. <dl>
  197. <dt><a name="index-TARGET_005fOPTION_005fPOST_005fSTREAM_005fIN"></a>Target Hook: <em>void</em> <strong>TARGET_OPTION_POST_STREAM_IN</strong> <em>(struct cl_target_option *<var>ptr</var>)</em></dt>
  198. <dd><p>This hook is called to update target-specific information in the
  199. <code>struct cl_target_option</code> structure after it is streamed in from
  200. LTO bytecode.
  201. </p></dd></dl>
  202. <dl>
  203. <dt><a name="index-TARGET_005fOPTION_005fPRINT"></a>Target Hook: <em>void</em> <strong>TARGET_OPTION_PRINT</strong> <em>(FILE *<var>file</var>, int <var>indent</var>, struct cl_target_option *<var>ptr</var>)</em></dt>
  204. <dd><p>This hook is called to print any additional target-specific
  205. information in the <code>struct cl_target_option</code> structure for
  206. function-specific options.
  207. </p></dd></dl>
  208. <dl>
  209. <dt><a name="index-TARGET_005fOPTION_005fPRAGMA_005fPARSE"></a>Target Hook: <em>bool</em> <strong>TARGET_OPTION_PRAGMA_PARSE</strong> <em>(tree <var>args</var>, tree <var>pop_target</var>)</em></dt>
  210. <dd><p>This target hook parses the options for <code>#pragma GCC target</code>, which
  211. sets the target-specific options for functions that occur later in the
  212. input stream. The options accepted should be the same as those handled by the
  213. <code>TARGET_OPTION_VALID_ATTRIBUTE_P</code> hook.
  214. </p></dd></dl>
  215. <dl>
  216. <dt><a name="index-TARGET_005fOPTION_005fOVERRIDE"></a>Target Hook: <em>void</em> <strong>TARGET_OPTION_OVERRIDE</strong> <em>(void)</em></dt>
  217. <dd><p>Sometimes certain combinations of command options do not make sense on
  218. a particular target machine. You can override the hook
  219. <code>TARGET_OPTION_OVERRIDE</code> to take account of this. This hooks is called
  220. once just after all the command options have been parsed.
  221. </p>
  222. <p>Don&rsquo;t use this hook to turn on various extra optimizations for
  223. <samp>-O</samp>. That is what <code>TARGET_OPTION_OPTIMIZATION</code> is for.
  224. </p>
  225. <p>If you need to do something whenever the optimization level is
  226. changed via the optimize attribute or pragma, see
  227. <code>TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE</code>
  228. </p></dd></dl>
  229. <dl>
  230. <dt><a name="index-TARGET_005fOPTION_005fFUNCTION_005fVERSIONS"></a>Target Hook: <em>bool</em> <strong>TARGET_OPTION_FUNCTION_VERSIONS</strong> <em>(tree <var>decl1</var>, tree <var>decl2</var>)</em></dt>
  231. <dd><p>This target hook returns <code>true</code> if <var>DECL1</var> and <var>DECL2</var> are
  232. versions of the same function. <var>DECL1</var> and <var>DECL2</var> are function
  233. versions if and only if they have the same function signature and
  234. different target specific attributes, that is, they are compiled for
  235. different target machines.
  236. </p></dd></dl>
  237. <dl>
  238. <dt><a name="index-TARGET_005fCAN_005fINLINE_005fP"></a>Target Hook: <em>bool</em> <strong>TARGET_CAN_INLINE_P</strong> <em>(tree <var>caller</var>, tree <var>callee</var>)</em></dt>
  239. <dd><p>This target hook returns <code>false</code> if the <var>caller</var> function
  240. cannot inline <var>callee</var>, based on target specific information. By
  241. default, inlining is not allowed if the callee function has function
  242. specific target options and the caller does not use the same options.
  243. </p></dd></dl>
  244. <dl>
  245. <dt><a name="index-TARGET_005fRELAYOUT_005fFUNCTION"></a>Target Hook: <em>void</em> <strong>TARGET_RELAYOUT_FUNCTION</strong> <em>(tree <var>fndecl</var>)</em></dt>
  246. <dd><p>This target hook fixes function <var>fndecl</var> after attributes are processed. Default does nothing. On ARM, the default function&rsquo;s alignment is updated with the attribute target.
  247. </p></dd></dl>
  248. <hr>
  249. <div class="header">
  250. <p>
  251. Next: <a href="Emulated-TLS.html#Emulated-TLS" accesskey="n" rel="next">Emulated TLS</a>, Previous: <a href="Mode-Switching.html#Mode-Switching" accesskey="p" rel="prev">Mode Switching</a>, Up: <a href="Target-Macros.html#Target-Macros" accesskey="u" rel="up">Target Macros</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
  252. </div>
  253. </body>
  254. </html>