<html lang="en">
<head>
<title>Literal Directive - Using as</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Using as">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Xtensa-Directives.html#Xtensa-Directives" title="Xtensa Directives">
<link rel="prev" href="Transform-Directive.html#Transform-Directive" title="Transform Directive">
<link rel="next" href="Literal-Position-Directive.html#Literal-Position-Directive" title="Literal Position Directive">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU Assembler "as".

Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000, 2001, 2002, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts.  A copy of the license is included in the
section entitled ``GNU Free Documentation License''.

-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Literal-Directive"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Literal-Position-Directive.html#Literal-Position-Directive">Literal Position Directive</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Transform-Directive.html#Transform-Directive">Transform Directive</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Xtensa-Directives.html#Xtensa-Directives">Xtensa Directives</a>
<hr>
</div>

<h5 class="subsubsection">9.42.5.4 literal</h5>

<p><a name="index-g_t_0040code_007bliteral_007d-directive-2051"></a>
The <code>.literal</code> directive is used to define literal pool data, i.e.,
read-only 32-bit data accessed via <code>L32R</code> instructions.

<pre class="smallexample">         .literal <var>label</var>, <var>value</var>[, <var>value</var>...]
</pre>
   <p>This directive is similar to the standard <code>.word</code> directive, except
that the actual location of the literal data is determined by the
assembler and linker, not by the position of the <code>.literal</code>
directive.  Using this directive gives the assembler freedom to locate
the literal data in the most appropriate place and possibly to combine
identical literals.  For example, the code:

<pre class="smallexample">         entry sp, 40
         .literal .L1, sym
         l32r    a4, .L1
</pre>
   <p>can be used to load a pointer to the symbol <code>sym</code> into register
<code>a4</code>.  The value of <code>sym</code> will not be placed between the
<code>ENTRY</code> and <code>L32R</code> instructions; instead, the assembler puts
the data in a literal pool.

   <p>Literal pools are placed by default in separate literal sections;
however, when using the &lsquo;<samp><span class="samp">--text-section-literals</span></samp>&rsquo;
option (see <a href="Xtensa-Options.html#Xtensa-Options">Command Line Options</a>), the literal
pools for PC-relative mode <code>L32R</code> instructions
are placed in the current section.<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a>
These text section literal
pools are created automatically before <code>ENTRY</code> instructions and
manually after &lsquo;<samp><span class="samp">.literal_position</span></samp>&rsquo; directives (see <a href="Literal-Position-Directive.html#Literal-Position-Directive">literal_position</a>).  If there are no preceding
<code>ENTRY</code> instructions, explicit <code>.literal_position</code> directives
must be used to place the text section literal pools; otherwise,
<samp><span class="command">as</span></samp> will report an error.

   <p>When literals are placed in separate sections, the literal section names
are derived from the names of the sections where the literals are
defined.  The base literal section names are <code>.literal</code> for
PC-relative mode <code>L32R</code> instructions and <code>.lit4</code> for absolute
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
the default <code>.text</code> section.  For literals defined in other
sections or within the scope of a <code>literal_prefix</code> directive
(see <a href="Literal-Prefix-Directive.html#Literal-Prefix-Directive">literal_prefix</a>), the following rules
determine the literal section name:

     <ol type=1 start=1>
<li>If the current section is a member of a section group, the literal
section name includes the group name as a suffix to the base
<code>.literal</code> or <code>.lit4</code> name, with a period to separate the base
name and group name.  The literal section is also made a member of the
group.

     <li>If the current section name (or <code>literal_prefix</code> value) begins with
&ldquo;<code>.gnu.linkonce.</code><var>kind</var><code>.</code>&rdquo;, the literal section name is formed
by replacing &ldquo;<code>.</code><var>kind</var>&rdquo; with the base <code>.literal</code> or
<code>.lit4</code> name.  For example, for literals defined in a section named
<code>.gnu.linkonce.t.func</code>, the literal section will be
<code>.gnu.linkonce.literal.func</code> or <code>.gnu.linkonce.lit4.func</code>.

     <li>If the current section name (or <code>literal_prefix</code> value) ends with
<code>.text</code>, the literal section name is formed by replacing that
suffix with the base <code>.literal</code> or <code>.lit4</code> name.  For example,
for literals defined in a section named <code>.iram0.text</code>, the literal
section will be <code>.iram0.literal</code> or <code>.iram0.lit4</code>.

     <li>If none of the preceding conditions apply, the literal section name is
formed by adding the base <code>.literal</code> or <code>.lit4</code> name as a
suffix to the current section name (or <code>literal_prefix</code> value).
        </ol>

   <div class="footnote">
<hr>
<h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> Literals for the
<code>.init</code> and <code>.fini</code> sections are always placed in separate
sections, even when &lsquo;<samp><span class="samp">--text-section-literals</span></samp>&rsquo; is enabled.</p>

   <hr></div>

   </body></html>