Literal-Directive.html 8.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2. <html>
  3. <!-- This file documents the GNU Assembler "as".
  4. Copyright (C) 1991-2017 Free Software Foundation, Inc.
  5. Permission is granted to copy, distribute and/or modify this document
  6. under the terms of the GNU Free Documentation License, Version 1.3
  7. or any later version published by the Free Software Foundation;
  8. with no Invariant Sections, with no Front-Cover Texts, and with no
  9. Back-Cover Texts. A copy of the license is included in the
  10. section entitled "GNU Free Documentation License".
  11. -->
  12. <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
  13. <head>
  14. <title>Using as: Literal Directive</title>
  15. <meta name="description" content="Using as: Literal Directive">
  16. <meta name="keywords" content="Using as: Literal Directive">
  17. <meta name="resource-type" content="document">
  18. <meta name="distribution" content="global">
  19. <meta name="Generator" content="makeinfo">
  20. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  21. <link href="index.html#Top" rel="start" title="Top">
  22. <link href="AS-Index.html#AS-Index" rel="index" title="AS Index">
  23. <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
  24. <link href="Xtensa-Directives.html#Xtensa-Directives" rel="up" title="Xtensa Directives">
  25. <link href="Literal-Position-Directive.html#Literal-Position-Directive" rel="next" title="Literal Position Directive">
  26. <link href="Transform-Directive.html#Transform-Directive" rel="prev" title="Transform Directive">
  27. <style type="text/css">
  28. <!--
  29. a.summary-letter {text-decoration: none}
  30. blockquote.smallquotation {font-size: smaller}
  31. div.display {margin-left: 3.2em}
  32. div.example {margin-left: 3.2em}
  33. div.indentedblock {margin-left: 3.2em}
  34. div.lisp {margin-left: 3.2em}
  35. div.smalldisplay {margin-left: 3.2em}
  36. div.smallexample {margin-left: 3.2em}
  37. div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
  38. div.smalllisp {margin-left: 3.2em}
  39. kbd {font-style:oblique}
  40. pre.display {font-family: inherit}
  41. pre.format {font-family: inherit}
  42. pre.menu-comment {font-family: serif}
  43. pre.menu-preformatted {font-family: serif}
  44. pre.smalldisplay {font-family: inherit; font-size: smaller}
  45. pre.smallexample {font-size: smaller}
  46. pre.smallformat {font-family: inherit; font-size: smaller}
  47. pre.smalllisp {font-size: smaller}
  48. span.nocodebreak {white-space:nowrap}
  49. span.nolinebreak {white-space:nowrap}
  50. span.roman {font-family:serif; font-weight:normal}
  51. span.sansserif {font-family:sans-serif; font-weight:normal}
  52. ul.no-bullet {list-style: none}
  53. -->
  54. </style>
  55. </head>
  56. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  57. <a name="Literal-Directive"></a>
  58. <div class="header">
  59. <p>
  60. Next: <a href="Literal-Position-Directive.html#Literal-Position-Directive" accesskey="n" rel="next">Literal Position Directive</a>, Previous: <a href="Transform-Directive.html#Transform-Directive" accesskey="p" rel="prev">Transform Directive</a>, Up: <a href="Xtensa-Directives.html#Xtensa-Directives" accesskey="u" rel="up">Xtensa Directives</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="AS-Index.html#AS-Index" title="Index" rel="index">Index</a>]</p>
  61. </div>
  62. <hr>
  63. <a name="literal"></a>
  64. <h4 class="subsubsection">9.53.5.4 literal</h4>
  65. <a name="index-literal-directive"></a>
  66. <p>The <code>.literal</code> directive is used to define literal pool data, i.e.,
  67. read-only 32-bit data accessed via <code>L32R</code> instructions.
  68. </p>
  69. <div class="smallexample">
  70. <pre class="smallexample"> .literal <var>label</var>, <var>value</var>[, <var>value</var>&hellip;]
  71. </pre></div>
  72. <p>This directive is similar to the standard <code>.word</code> directive, except
  73. that the actual location of the literal data is determined by the
  74. assembler and linker, not by the position of the <code>.literal</code>
  75. directive. Using this directive gives the assembler freedom to locate
  76. the literal data in the most appropriate place and possibly to combine
  77. identical literals. For example, the code:
  78. </p>
  79. <div class="smallexample">
  80. <pre class="smallexample"> entry sp, 40
  81. .literal .L1, sym
  82. l32r a4, .L1
  83. </pre></div>
  84. <p>can be used to load a pointer to the symbol <code>sym</code> into register
  85. <code>a4</code>. The value of <code>sym</code> will not be placed between the
  86. <code>ENTRY</code> and <code>L32R</code> instructions; instead, the assembler puts
  87. the data in a literal pool.
  88. </p>
  89. <p>Literal pools are placed by default in separate literal sections;
  90. however, when using the &lsquo;<samp>--text-section-literals</samp>&rsquo;
  91. option (see <a href="Xtensa-Options.html#Xtensa-Options">Command Line Options</a>), the literal
  92. pools for PC-relative mode <code>L32R</code> instructions
  93. are placed in the current section.<a name="DOCF3" href="#FOOT3"><sup>3</sup></a>
  94. These text section literal
  95. pools are created automatically before <code>ENTRY</code> instructions and
  96. manually after &lsquo;<samp>.literal_position</samp>&rsquo; directives (see <a href="Literal-Position-Directive.html#Literal-Position-Directive">literal_position</a>). If there are no preceding
  97. <code>ENTRY</code> instructions, explicit <code>.literal_position</code> directives
  98. must be used to place the text section literal pools; otherwise,
  99. <code>as</code> will report an error.
  100. </p>
  101. <p>When literals are placed in separate sections, the literal section names
  102. are derived from the names of the sections where the literals are
  103. defined. The base literal section names are <code>.literal</code> for
  104. PC-relative mode <code>L32R</code> instructions and <code>.lit4</code> for absolute
  105. mode <code>L32R</code> instructions (see <a href="Absolute-Literals-Directive.html#Absolute-Literals-Directive">absolute-literals</a>). These base names are used for literals defined in
  106. the default <code>.text</code> section. For literals defined in other
  107. sections or within the scope of a <code>literal_prefix</code> directive
  108. (see <a href="Literal-Prefix-Directive.html#Literal-Prefix-Directive">literal_prefix</a>), the following rules
  109. determine the literal section name:
  110. </p>
  111. <ol>
  112. <li> If the current section is a member of a section group, the literal
  113. section name includes the group name as a suffix to the base
  114. <code>.literal</code> or <code>.lit4</code> name, with a period to separate the base
  115. name and group name. The literal section is also made a member of the
  116. group.
  117. </li><li> If the current section name (or <code>literal_prefix</code> value) begins with
  118. &ldquo;<code>.gnu.linkonce.<var>kind</var>.</code>&rdquo;, the literal section name is formed
  119. by replacing &ldquo;<code>.<var>kind</var></code>&rdquo; with the base <code>.literal</code> or
  120. <code>.lit4</code> name. For example, for literals defined in a section named
  121. <code>.gnu.linkonce.t.func</code>, the literal section will be
  122. <code>.gnu.linkonce.literal.func</code> or <code>.gnu.linkonce.lit4.func</code>.
  123. </li><li> If the current section name (or <code>literal_prefix</code> value) ends with
  124. <code>.text</code>, the literal section name is formed by replacing that
  125. suffix with the base <code>.literal</code> or <code>.lit4</code> name. For example,
  126. for literals defined in a section named <code>.iram0.text</code>, the literal
  127. section will be <code>.iram0.literal</code> or <code>.iram0.lit4</code>.
  128. </li><li> If none of the preceding conditions apply, the literal section name is
  129. formed by adding the base <code>.literal</code> or <code>.lit4</code> name as a
  130. suffix to the current section name (or <code>literal_prefix</code> value).
  131. </li></ol>
  132. <div class="footnote">
  133. <hr>
  134. <h4 class="footnotes-heading">Footnotes</h4>
  135. <h3><a name="FOOT3" href="#DOCF3">(3)</a></h3>
  136. <p>Literals for the
  137. <code>.init</code> and <code>.fini</code> sections are always placed in separate
  138. sections, even when &lsquo;<samp>--text-section-literals</samp>&rsquo; is enabled.</p>
  139. </div>
  140. <hr>
  141. <div class="header">
  142. <p>
  143. Next: <a href="Literal-Position-Directive.html#Literal-Position-Directive" accesskey="n" rel="next">Literal Position Directive</a>, Previous: <a href="Transform-Directive.html#Transform-Directive" accesskey="p" rel="prev">Transform Directive</a>, Up: <a href="Xtensa-Directives.html#Xtensa-Directives" accesskey="u" rel="up">Xtensa Directives</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="AS-Index.html#AS-Index" title="Index" rel="index">Index</a>]</p>
  144. </div>
  145. </body>
  146. </html>