<html lang="en">
<head>
<title>File Framework - GNU Compiler Collection (GCC) Internals</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="GNU Compiler Collection (GCC) Internals">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Assembler-Format.html#Assembler-Format" title="Assembler Format">
<link rel="next" href="Data-Output.html#Data-Output" title="Data Output">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1988-2015 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 the
Invariant Sections being ``Funding Free Software'', the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below). A copy of the license is included in the section entitled
``GNU Free Documentation License''.
(a) The FSF's Front-Cover Text is:
A GNU Manual
(b) The FSF's Back-Cover Text is:
You have freedom to copy and modify this GNU Manual, like GNU
software. Copies published by the Free Software Foundation raise
funds for GNU development.-->
<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>
</head>
<body>
<div class="node">
<a name="File-Framework"></a>
<p>
Next: <a rel="next" accesskey="n" href="Data-Output.html#Data-Output">Data Output</a>,
Up: <a rel="up" accesskey="u" href="Assembler-Format.html#Assembler-Format">Assembler Format</a>
<hr>
</div>
<h4 class="subsection">17.20.1 The Overall Framework of an Assembler File</h4>
<p><a name="index-assembler-format-4555"></a><a name="index-output-of-assembler-code-4556"></a>
<!-- prevent bad page break with this line -->
This describes the overall framework of an assembly file.
<p><a name="index-default_005ffile_005fstart-4557"></a>
<div class="defun">
— Target Hook: void <b>TARGET_ASM_FILE_START</b> (<var>void</var>)<var><a name="index-TARGET_005fASM_005fFILE_005fSTART-4558"></a></var><br>
<blockquote><p>Output to <code>asm_out_file</code> any text which the assembler expects to
find at the beginning of a file. The default behavior is controlled
by two flags, documented below. Unless your target's assembler is
quite unusual, if you override the default, you should call
<code>default_file_start</code> at some point in your target hook. This
lets other target files rely on these variables.
</p></blockquote></div>
<div class="defun">
— Target Hook: bool <b>TARGET_ASM_FILE_START_APP_OFF</b><var><a name="index-TARGET_005fASM_005fFILE_005fSTART_005fAPP_005fOFF-4559"></a></var><br>
<blockquote><p>If this flag is true, the text of the macro <code>ASM_APP_OFF</code> will be
printed as the very first line in the assembly file, unless
<samp><span class="option">-fverbose-asm</span></samp> is in effect. (If that macro has been defined
to the empty string, this variable has no effect.) With the normal
definition of <code>ASM_APP_OFF</code>, the effect is to notify the GNU
assembler that it need not bother stripping comments or extra
whitespace from its input. This allows it to work a bit faster.
<p>The default is false. You should not set it to true unless you have
verified that your port does not generate any extra whitespace or
comments that will cause GAS to issue errors in NO_APP mode.
</p></blockquote></div>
<div class="defun">
— Target Hook: bool <b>TARGET_ASM_FILE_START_FILE_DIRECTIVE</b><var><a name="index-TARGET_005fASM_005fFILE_005fSTART_005fFILE_005fDIRECTIVE-4560"></a></var><br>
<blockquote><p>If this flag is true, <code>output_file_directive</code> will be called
for the primary source file, immediately after printing
<code>ASM_APP_OFF</code> (if that is enabled). Most ELF assemblers expect
this to be done. The default is false.
</p></blockquote></div>
<div class="defun">
— Target Hook: void <b>TARGET_ASM_FILE_END</b> (<var>void</var>)<var><a name="index-TARGET_005fASM_005fFILE_005fEND-4561"></a></var><br>
<blockquote><p>Output to <code>asm_out_file</code> any text which the assembler expects
to find at the end of a file. The default is to output nothing.
</p></blockquote></div>
<div class="defun">
— Function: void <b>file_end_indicate_exec_stack</b> ()<var><a name="index-file_005fend_005findicate_005fexec_005fstack-4562"></a></var><br>
<blockquote><p>Some systems use a common convention, the ‘<samp><span class="samp">.note.GNU-stack</span></samp>’
special section, to indicate whether or not an object file relies on
the stack being executable. If your system uses this convention, you
should define <code>TARGET_ASM_FILE_END</code> to this function. If you
need to do other things in that hook, have your hook function call
this function.
</p></blockquote></div>
<div class="defun">
— Target Hook: void <b>TARGET_ASM_LTO_START</b> (<var>void</var>)<var><a name="index-TARGET_005fASM_005fLTO_005fSTART-4563"></a></var><br>
<blockquote><p>Output to <code>asm_out_file</code> any text which the assembler expects
to find at the start of an LTO section. The default is to output
nothing.
</p></blockquote></div>
<div class="defun">
— Target Hook: void <b>TARGET_ASM_LTO_END</b> (<var>void</var>)<var><a name="index-TARGET_005fASM_005fLTO_005fEND-4564"></a></var><br>
<blockquote><p>Output to <code>asm_out_file</code> any text which the assembler expects
to find at the end of an LTO section. The default is to output
nothing.
</p></blockquote></div>
<div class="defun">
— Target Hook: void <b>TARGET_ASM_CODE_END</b> (<var>void</var>)<var><a name="index-TARGET_005fASM_005fCODE_005fEND-4565"></a></var><br>
<blockquote><p>Output to <code>asm_out_file</code> any text which is needed before emitting
unwind info and debug info at the end of a file. Some targets emit
here PIC setup thunks that cannot be emitted at the end of file,
because they couldn't have unwind info then. The default is to output
nothing.
</p></blockquote></div>
<div class="defun">
— Macro: <b>ASM_COMMENT_START</b><var><a name="index-ASM_005fCOMMENT_005fSTART-4566"></a></var><br>
<blockquote><p>A C string constant describing how to begin a comment in the target
assembler language. The compiler assumes that the comment will end at
the end of the line.
</p></blockquote></div>
<div class="defun">
— Macro: <b>ASM_APP_ON</b><var><a name="index-ASM_005fAPP_005fON-4567"></a></var><br>
<blockquote><p>A C string constant for text to be output before each <code>asm</code>
statement or group of consecutive ones. Normally this is
<code>"#APP"</code>, which is a comment that has no effect on most
assemblers but tells the GNU assembler that it must check the lines
that follow for all valid assembler constructs.
</p></blockquote></div>
<div class="defun">
— Macro: <b>ASM_APP_OFF</b><var><a name="index-ASM_005fAPP_005fOFF-4568"></a></var><br>
<blockquote><p>A C string constant for text to be output after each <code>asm</code>
statement or group of consecutive ones. Normally this is
<code>"#NO_APP"</code>, which tells the GNU assembler to resume making the
time-saving assumptions that are valid for ordinary compiler output.
</p></blockquote></div>
<div class="defun">
— Macro: <b>ASM_OUTPUT_SOURCE_FILENAME</b> (<var>stream, name</var>)<var><a name="index-ASM_005fOUTPUT_005fSOURCE_005fFILENAME-4569"></a></var><br>
<blockquote><p>A C statement to output COFF information or DWARF debugging information
which indicates that filename <var>name</var> is the current source file to
the stdio stream <var>stream</var>.
<p>This macro need not be defined if the standard form of output
for the file format in use is appropriate.
</p></blockquote></div>
<div class="defun">
— Target Hook: void <b>TARGET_ASM_OUTPUT_SOURCE_FILENAME</b> (<var>FILE *file, const char *name</var>)<var><a name="index-TARGET_005fASM_005fOUTPUT_005fSOURCE_005fFILENAME-4570"></a></var><br>
<blockquote><p>Output COFF information or DWARF debugging information which indicates that filename <var>name</var> is the current source file to the stdio stream <var>file</var>.
<p>This target hook need not be defined if the standard form of output for the file format in use is appropriate.
</p></blockquote></div>
<div class="defun">
— Target Hook: void <b>TARGET_ASM_OUTPUT_IDENT</b> (<var>const char *name</var>)<var><a name="index-TARGET_005fASM_005fOUTPUT_005fIDENT-4571"></a></var><br>
<blockquote><p>Output a string based on <var>name</var>, suitable for the ‘<samp><span class="samp">#ident</span></samp>’ directive, or the equivalent directive or pragma in non-C-family languages. If this hook is not defined, nothing is output for the ‘<samp><span class="samp">#ident</span></samp>’ directive.
</p></blockquote></div>
<div class="defun">
— Macro: <b>OUTPUT_QUOTED_STRING</b> (<var>stream, string</var>)<var><a name="index-OUTPUT_005fQUOTED_005fSTRING-4572"></a></var><br>
<blockquote><p>A C statement to output the string <var>string</var> to the stdio stream
<var>stream</var>. If you do not call the function <code>output_quoted_string</code>
in your config files, GCC will only call it to output filenames to
the assembler source. So you can use it to canonicalize the format
of the filename using this macro.
</p></blockquote></div>
<div class="defun">
— Target Hook: void <b>TARGET_ASM_NAMED_SECTION</b> (<var>const char *name, unsigned int flags, tree decl</var>)<var><a name="index-TARGET_005fASM_005fNAMED_005fSECTION-4573"></a></var><br>
<blockquote><p>Output assembly directives to switch to section <var>name</var>. The section
should have attributes as specified by <var>flags</var>, which is a bit mask
of the <code>SECTION_*</code> flags defined in <samp><span class="file">output.h</span></samp>. If <var>decl</var>
is non-NULL, it is the <code>VAR_DECL</code> or <code>FUNCTION_DECL</code> with which
this section is associated.
</p></blockquote></div>
<div class="defun">
— Target Hook: section * <b>TARGET_ASM_FUNCTION_SECTION</b> (<var>tree decl, enum node_frequency freq, bool startup, bool exit</var>)<var><a name="index-TARGET_005fASM_005fFUNCTION_005fSECTION-4574"></a></var><br>
<blockquote><p>Return preferred text (sub)section for function <var>decl</var>.
Main purpose of this function is to separate cold, normal and hot
functions. <var>startup</var> is true when function is known to be used only
at startup (from static constructors or it is <code>main()</code>).
<var>exit</var> is true when function is known to be used only at exit
(from static destructors).
Return NULL if function should go to default text section.
</p></blockquote></div>
<div class="defun">
— Target Hook: void <b>TARGET_ASM_FUNCTION_SWITCHED_TEXT_SECTIONS</b> (<var>FILE *file, tree decl, bool new_is_cold</var>)<var><a name="index-TARGET_005fASM_005fFUNCTION_005fSWITCHED_005fTEXT_005fSECTIONS-4575"></a></var><br>
<blockquote><p>Used by the target to emit any assembler directives or additional labels needed when a function is partitioned between different sections. Output should be written to <var>file</var>. The function decl is available as <var>decl</var> and the new section is `cold' if <var>new_is_cold</var> is <code>true</code>.
</p></blockquote></div>
<div class="defun">
— Common Target Hook: bool <b>TARGET_HAVE_NAMED_SECTIONS</b><var><a name="index-TARGET_005fHAVE_005fNAMED_005fSECTIONS-4576"></a></var><br>
<blockquote><p>This flag is true if the target supports <code>TARGET_ASM_NAMED_SECTION</code>.
It must not be modified by command-line option processing.
</p></blockquote></div>
<p><a name="TARGET_005fHAVE_005fSWITCHABLE_005fBSS_005fSECTIONS"></a>
<div class="defun">
— Target Hook: bool <b>TARGET_HAVE_SWITCHABLE_BSS_SECTIONS</b><var><a name="index-TARGET_005fHAVE_005fSWITCHABLE_005fBSS_005fSECTIONS-4577"></a></var><br>
<blockquote><p>This flag is true if we can create zeroed data by switching to a BSS
section and then using <code>ASM_OUTPUT_SKIP</code> to allocate the space.
This is true on most ELF targets.
</p></blockquote></div>
<div class="defun">
— Target Hook: unsigned int <b>TARGET_SECTION_TYPE_FLAGS</b> (<var>tree decl, const char *name, int reloc</var>)<var><a name="index-TARGET_005fSECTION_005fTYPE_005fFLAGS-4578"></a></var><br>
<blockquote><p>Choose a set of section attributes for use by <code>TARGET_ASM_NAMED_SECTION</code>
based on a variable or function decl, a section name, and whether or not the
declaration's initializer may contain runtime relocations. <var>decl</var> may be
null, in which case read-write data should be assumed.
<p>The default version of this function handles choosing code vs data,
read-only vs read-write data, and <code>flag_pic</code>. You should only
need to override this if your target has special flags that might be
set via <code>__attribute__</code>.
</p></blockquote></div>
<div class="defun">
— Target Hook: int <b>TARGET_ASM_RECORD_GCC_SWITCHES</b> (<var>print_switch_type type, const char *text</var>)<var><a name="index-TARGET_005fASM_005fRECORD_005fGCC_005fSWITCHES-4579"></a></var><br>
<blockquote><p>Provides the target with the ability to record the gcc command line
switches that have been passed to the compiler, and options that are
enabled. The <var>type</var> argument specifies what is being recorded.
It can take the following values:
<dl>
<dt><code>SWITCH_TYPE_PASSED</code><dd><var>text</var> is a command line switch that has been set by the user.
<br><dt><code>SWITCH_TYPE_ENABLED</code><dd><var>text</var> is an option which has been enabled. This might be as a
direct result of a command line switch, or because it is enabled by
default or because it has been enabled as a side effect of a different
command line switch. For example, the <samp><span class="option">-O2</span></samp> switch enables
various different individual optimization passes.
<br><dt><code>SWITCH_TYPE_DESCRIPTIVE</code><dd><var>text</var> is either NULL or some descriptive text which should be
ignored. If <var>text</var> is NULL then it is being used to warn the
target hook that either recording is starting or ending. The first
time <var>type</var> is SWITCH_TYPE_DESCRIPTIVE and <var>text</var> is NULL, the
warning is for start up and the second time the warning is for
wind down. This feature is to allow the target hook to make any
necessary preparations before it starts to record switches and to
perform any necessary tidying up after it has finished recording
switches.
<br><dt><code>SWITCH_TYPE_LINE_START</code><dd>This option can be ignored by this target hook.
<br><dt><code>SWITCH_TYPE_LINE_END</code><dd>This option can be ignored by this target hook.
</dl>
<p>The hook's return value must be zero. Other return values may be
supported in the future.
<p>By default this hook is set to NULL, but an example implementation is
provided for ELF based targets. Called <var>elf_record_gcc_switches</var>,
it records the switches as ASCII text inside a new, string mergeable
section in the assembler output file. The name of the new section is
provided by the <code>TARGET_ASM_RECORD_GCC_SWITCHES_SECTION</code> target
hook.
</p></blockquote></div>
<div class="defun">
— Target Hook: const char * <b>TARGET_ASM_RECORD_GCC_SWITCHES_SECTION</b><var><a name="index-TARGET_005fASM_005fRECORD_005fGCC_005fSWITCHES_005fSECTION-4580"></a></var><br>
<blockquote><p>This is the name of the section that will be created by the example
ELF implementation of the <code>TARGET_ASM_RECORD_GCC_SWITCHES</code> target
hook.
</p></blockquote></div>
</body></html>