Annotation of htdocs/docs/kernel/elf-notes.html, revision 1.10

1.1       dsieger     1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
                      2: <html>
                      3: <head>
                      4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
                      5: <meta name="generator" content="Website XSL Stylesheet V2.6.0">
                      6: <link rel="home" href="../../." title="Welcome to The NetBSD Project: Of course it runs NetBSD.">
                      7: <link rel="up" href="../../docs/kernel/." title="NetBSD Documentation: Kernel">
                      8: <link rel="previous" href="../../docs/kernel/porting-freebsd-net.html" title="Notes on porting FreeBSD network drivers to NetBSD">
                      9: <link rel="next" href="../../docs/mirror.html" title="NetBSD Mirror FAQ">
                     10: <link rel="first" href="../../docs/kernel/lazyfpu.html" title="NetBSD Documentation: How lazy FPU context switch works">
1.3       dsieger    11: <link rel="stylesheet" href="/global.css" type="text/css">
1.1       dsieger    12: 
                     13: 
                     14: 
                     15: <title>NetBSD Documentation: Vendor-specific ELF Note Elements</title>
                     16: </head>
                     17: <body class="website"><div class="webpage">
1.3       dsieger    18: <a name="docs-kernel-elf-notes"></a><div id="top"><a href="#mainContent" class="doNotDisplay doNotPrint">Skip to main content.</a></div>
                     19: <div id="header">
                     20: <div class="topNavigation">
1.6       dsieger    21: <span>» </span><a href="../../docs/guide/en/">
                     22:          The Guide</a> |
1.3       dsieger    23:        <a href="http://man.NetBSD.org/">Manual pages</a> |
1.8       kano       24:        <a href="../../mailinglists/">
1.6       dsieger    25:          Mailing lists</a> and
1.3       dsieger    26:        <a href="http://mail-index.NetBSD.org/">Archives</a> |
                     27:        <a href="http://cvsweb.NetBSD.org/">CVS repository</a> |
1.6       dsieger    28:        <a href="http://www.NetBSD.org/cgi-bin/sendpr.cgi?gndb=netbsd">Report</a>
                     29:        or 
1.9       kano       30:        <a href="../../support/query-pr.html">
                     31:          query</a> a bug |
1.6       dsieger    32:        <a href="../../docs/software/packages.html">
                     33:          Software Packages
                     34:        </a>
1.3       dsieger    35: </div>
                     36: <div class="centralHeader">
1.6       dsieger    37: <a href="../../"><img alt="[NetBSD Logo]" width="506" height="90" src="../../images/NetBSD-headerlogo.png"></a><div class="headerTools"><div id="headerSearch"><form method="get" action="http://www.google.com/custom">
1.4       dsieger    38: <input class="whiteOnBlack" type="text" name="q" onfocus="if(this.value==this.defaultValue ) this.value='';" size="12" maxlength="255" value="Search"><input type="hidden" name="cof" value="L:http://www.NetBSD.org/images/NetBSD-smaller.png;LH:200;LW:200;AH:center;AWFID:4f6b0499f0f58d2c;"><input type="hidden" name="domains" value="NetBSD.org"><input type="hidden" name="sitesearch" value="www.NetBSD.org"><input type="submit" value="Search">
1.3       dsieger    39: </form></div></div>
                     40: </div>
                     41: <div class="navBar">
1.6       dsieger    42: <span class="doNotDisplay">
                     43:          Navigation:
                     44:        </span><a href="../../">
                     45:          Home</a> | 
                     46:        <a href="../../about/">
                     47:          About</a> | 
                     48:        <a href="../../releases/">
                     49:          Download</a> | 
                     50:        <a href="../../docs/">
                     51:          Documentation</a> | 
                     52:        <a href="../../support/">
                     53:          Support</a> | 
                     54:        <a href="../../community/">
                     55:          Community</a> | 
                     56:        <a href="../../ports/">
                     57:          Ports</a>
1.3       dsieger    58: </div>
                     59: </div>
                     60: <div id="content"><div class="fullWidth"><div class="rowOfBoxes">
                     61: <h1>NetBSD Documentation: Vendor-specific ELF Note Elements</h1>
1.1       dsieger    62: <h3 class="title"><a name="introduction"></a></h3>
                     63: <ul>
                     64: <li><a href="#introduction-sub">Introduction</a></li>
                     65: <li><a href="#note-format">Format of an ELF Note Element</a></li>
                     66: <li><a href="#note-names">Known ELF Note Names</a></li>
                     67: <li><a href="#note-contents">Vendor-specific ELF Notes</a></li>
                     68: <li><a href="#note-creation">Creating ELF PT_NOTE Sections</a></li>
                     69: <li><a href="#netbsd-note">Creating a NetBSD ELF PT_NOTE Section</a></li>
                     70: </ul>
                     71: <hr>
                     72: <h3 class="title"></h3>
                     73:     <h4 class="title">
                     74: <a name="introduction-sub"></a>Introduction (<a href="#introduction">top</a>)
                     75:   </h4>
                     76:       <p>
                     77:        Various operating system vendors are shipping ELF binaries and those
                     78:        binaries expect different system call interfaces.  In order to help
                     79:        operating systems correctly determine whether or not they can run an
                     80:        ELF program, and how to run it (e.g. what OS emulation to use), some
                     81:        operating system vendors have begun marking their ELF binaries with
                     82:        vendor-specific note elements, and placing those notes in the
                     83:        binaries' <code class="constant">PT_NOTE</code> sections.
                     84:       </p>
                     85:       <p>
                     86:        This page is meant to be a repository of knowledge about vendor-specific
                     87:        note elements used in binaries <code class="constant">PT_NOTE</code> sections for operating system
                     88:        identification.
                     89:       </p>
                     90: 
                     91:       <p>
                     92:        If your operating system uses vendor-specific note elements to
                     93:        mark its binaries and is not listed here, please send mail to
                     94:        <a href="mailto:cgd@NetBSD.org" target="_top">Chris Demetriou</a>
                     95:        with information about those notes.
                     96:       </p>
                     97:     
                     98:       <h4 class="title">
                     99: <a name="note-format"></a>Format of an ELF Note Element (<a href="#introduction">top</a>)
                    100:   </h4>
                    101: 
                    102:       <p>
                    103:        All ELF Note elements have the same basic structure:
                    104:        </p>
                    105: <div class="variablelist"><dl>
                    106: <dt><span class="term"><code class="varname">Name Size</code></span></dt>
                    107: <dd>4 bytes (integer)</dd>
                    108: <dt><span class="term"><code class="varname">Desc Size</code></span></dt>
                    109: <dd>4 bytes (integer)</dd>
                    110: <dt><span class="term"><code class="varname">Type</code></span></dt>
                    111: <dd>4 bytes (usually interpreted as an integer)</dd>
                    112: <dt><span class="term"><code class="varname">Name</code></span></dt>
                    113: <dd>variable size, padded to a 4 byte boundary</dd>
                    114: <dt><span class="term"><code class="varname">Desc</code></span></dt>
                    115: <dd>variable size, padded to a 4 byte boundary</dd>
                    116: </dl></div>
                    117: <p>
                    118:       </p>
                    119:       
                    120:       <p>
                    121:        The "Name Size" and "Desc Size" fields are integers (in the byte order
                    122:        specified by the binary's ELF header) which specify the size of the
                    123:        "Name" and "Desc" fields (excluding padding).
                    124:       </p>
                    125:     
                    126:       <p>
                    127:        The "Name" field specifies the vendor who defined the format of the Note.
                    128:        Typically, vendors use names which are related to their project and/or
                    129:        company names.  For instance, the GNU Project uses "GNU" as its name.
                    130:        No two vendors should use the same ELF Note Name, lest there be confusion
                    131:        when trying to interpret the meanings of notes.
                    132:       </p>
                    133:       
                    134:       <p>
                    135:        The "Type" field is vendor specific, but it is usually treated as an
                    136:        integer which identifies the type of the note.
                    137:       </p>
                    138:       
                    139:       <p>
                    140:        The "Desc" field is vendor specific, and usually contains data which
                    141:        depends on the note type.
                    142:       </p>
                    143:     
                    144:       <h4 class="title">
                    145: <a name="note-names"></a>Known ELF Note Names (<a href="#introduction">top</a>)
                    146:   </h4>
                    147: 
                    148:       <p>
                    149:        The following are the strings known to be used as ELF Note Names, along
                    150:        with the organizations that use them.  Names with lengths that are
                    151:        not a multiples of 4 are padded in the note, but only the given length
                    152:        should be checked.
                    153:       </p>
                    154:       
                    155:       <div class="segmentedlist"><table border="0">
                    156: <thead><tr class="segtitle">
                    157: <th>Note Name String</th>
                    158: <th>Byte encoding of string</th>
                    159: <th>Length</th>
                    160: <th>Organization</th>
                    161: </tr></thead>
                    162: <tbody>
                    163: <tr class="seglistitem">
                    164:          <td class="seg"><code class="code">"NetBSD\0"</code></td>
                    165:          <td class="seg"><code class="code">0x4e 0x65 0x74 0x42 0x53 0x44 0x00</code></td>
                    166:          <td class="seg">7</td>
1.10    ! martin    167:          <td class="seg"><a href="#note-contents-netbsd">The NetBSD Project</a></td>
1.1       dsieger   168:        </tr>
                    169: <tr class="seglistitem">
                    170:          <td class="seg"><code class="code">"GNU\0"</code></td>
                    171:          <td class="seg"><code class="code">0x47 0x4e 0x55 0x00</code></td>
                    172:          <td class="seg">4</td>
1.10    ! martin    173:          <td class="seg"><a href="#note-contents-gnu">The GNU Project</a></td>
1.1       dsieger   174:        </tr>
                    175: </tbody>
                    176: </table></div>
                    177:     
                    178:     <h4 class="title">
                    179: <a name="note-contents"></a>Vendor-specific ELF Notes (<a href="#introduction">top</a>)
                    180:   </h4>
                    181:       
                    182:     <p>
                    183:       This section contains information about the formats of ELF notes which
                    184:       vendors use in their <code class="constant">PT_NOTE</code> sections, and is split up by vendor.
                    185:     </p>
                    186: 
                    187:     <div class="sect4" lang="en">
                    188: <div class="titlepage"><div><div><h5 class="title">
                    189: <a name="note-contents-netbsd"></a>The NetBSD Project</h5></div></div></div>
                    190:       
                    191:       
                    192:       <p>
                    193:        There are two vendor-specific ELF Notes for NetBSD, an OS Version note and
                    194:        an Emulation Name note.
                    195:        The former is used to indicate what OS Version
                    196:        native binaries were built with, and can be used to identify native
                    197:        binaries.
                    198:        The latter is used to mark binaries (both native an non-native) with
                    199:        a name that indicates which set of binary emulation code is to be used
                    200:        when they are run.
                    201:       </p>
                    202:       <p>
                    203:        The format of the NetBSD OS Version note is:
                    204:        
                    205:        </p>
                    206: <div class="variablelist"><dl>
                    207: <dt><span class="term"><code class="varname">Name Size</code></span></dt>
                    208: <dd>7</dd>
                    209: <dt><span class="term"><code class="varname">Desc Size</code></span></dt>
                    210: <dd>4</dd>
                    211: <dt><span class="term"><code class="varname">Type</code></span></dt>
                    212: <dd>4-byte integer containing the value <code class="code">0x01</code>
                    213: </dd>
                    214: <dt><span class="term"><code class="varname">Name</code></span></dt>
                    215: <dd>
                    216: <code class="code">"NetBSD\0"</code> (padded to 8 bytes)</dd>
                    217: <dt><span class="term"><code class="varname">Desc</code></span></dt>
                    218: <dd>4-byte integer containing the NetBSD OS version constant</dd>
                    219: </dl></div>
                    220: <p>
                    221:       </p>
                    222: 
                    223:       <p>
                    224:        The format of the NetBSD Emulation Name note is:
                    225:        </p>
                    226: <div class="variablelist"><dl>
                    227: <dt><span class="term"><code class="varname">Name Size</code></span></dt>
                    228: <dd>7</dd>
                    229: <dt><span class="term"><code class="varname">Desc Size</code></span></dt>
                    230: <dd>variable</dd>
                    231: <dt><span class="term"><code class="varname">Type</code></span></dt>
                    232: <dd>4-byte integer containing the value <code class="code">0x02</code>
                    233: </dd>
                    234: <dt><span class="term"><code class="varname">Name</code></span></dt>
                    235: <dd>
                    236: <code class="code">"NetBSD\0"</code> (padded to 8 bytes)</dd>
                    237: <dt><span class="term"><code class="varname">Desc</code></span></dt>
                    238: <dd>
                    239: <code class="code">NUL</code>-terminated string naming the
                    240:            emulation to be used to run the binary
                    241:            (padded to the next 4-byte boundary)</dd>
                    242: </dl></div>
                    243: <p>
                    244:       </p>
                    245:     </div>
                    246: 
                    247:     <div class="sect4" lang="en">
                    248: <div class="titlepage"><div><div><h5 class="title">
                    249: <a name="note-contents-gnu"></a>The GNU Project</h5></div></div></div>
                    250:       
                    251: 
                    252:       <p>
                    253:        Starting with glibc 2.1, the GNU project will be using a single ELF Note
                    254:        to indicate which GNU operating system and which version of that system
                    255:        a binary was built for.  The format of that note is:
                    256:        </p>
                    257: <div class="variablelist"><dl>
                    258: <dt><span class="term"><code class="varname">Name Size</code></span></dt>
                    259: <dd>4</dd>
                    260: <dt><span class="term"><code class="varname">Desc Size</code></span></dt>
                    261: <dd>16</dd>
                    262: <dt><span class="term"><code class="varname">Type</code></span></dt>
                    263: <dd>4-byte integer containing the value <code class="code">0x01</code>
                    264: </dd>
                    265: <dt><span class="term"><code class="varname">Name</code></span></dt>
                    266: <dd><code class="code">"GNU\0"</code></dd>
                    267: <dt><span class="term"><code class="varname">Desc</code></span></dt>
                    268: <dd>
                    269:              Four 4-byte integers containing, in order:
                    270:              <div class="orderedlist"><ol type="1">
                    271: <li>OS (0 = Linux, 1 = Hurd, 2 = Solaris)</li>
                    272: <li>Major</li>
                    273: <li>Minor</li>
                    274: <li>Teeny</li>
                    275: </ol></div>
                    276:              The major, minor and teeny versions are that of the earliest OS version that supports this ABI.
                    277:            </dd>
                    278: </dl></div>
                    279: <p>
                    280:       </p>
                    281: 
                    282:       <p>
                    283:        For more documentation on the GNU C Library's use of ELF notes,
                    284:        consult the sources:
                    285:        <a href="http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/abi-tags?cvsroot=glibc" target="_top">abi-tags</a>
                    286:        and
                    287:        <a href="http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/csu/abi-note.S?cvsroot=glibc" target="_top">csu/abi-note.S</a>.
                    288:       </p>
                    289:     </div>
                    290:   
                    291:       <h4 class="title">
                    292: <a name="note-creation"></a>Creating ELF <code class="constant">PT_NOTE</code> Sections (<a href="#introduction">top</a>)
                    293:   </h4>
                    294: 
                    295:       <p>
                    296:        If you're using the GNU binutils 2.8 or greater to create your binaries,
                    297:        you can generate <code class="constant">PT_NOTE</code> sections in your final object files.
                    298:        To create a <code class="constant">PT_NOTE</code> section, create a section in one of your object
                    299:        files (for systems which generate <code class="constant">PT_NOTE</code> entries by default, this
                    300:        is typically the runtime startup code) with a name starting
                    301:        with ".note" and having the "allocate" property set.
                    302:        Put properly formed ELF Notes entries in that section.
                    303:        When final linking is done, all sections which have names starting
                    304:        with ".note" and which are marked "allocate" will be put into <code class="constant">PT_NOTE</code>
                    305:        sections in the final object file.
                    306:       </p>
                    307:       <p>
                    308:        An example of GNU assembler input which will create a <code class="constant">PT_NOTE</code> section
                    309:        during final link is:
                    310:       </p>
                    311: <pre class="programlisting">
                    312:     .section ".note.ident", "a"
                    313:     .p2align 2
                    314:     .long 1f - 0f           # name size (not including padding)
                    315:     .long 3f - 2f           # desc size (not including padding)
                    316:     .long 0x01234567        # type
                    317: 0:  .asciz "NaMe"          # name
                    318: 1:  .p2align 2
                    319: 2:  .long 0x76543210        # desc
                    320:     .long 0x89abcdef
                    321: 3:  .p2align 2
                    322: </pre>
                    323: 
                    324: <p>
                    325:   That example will create a section called ".note.ident", marked
                    326:   "allocate" (so that it will be turned into a
                    327:   <code class="constant">PT_NOTE</code> section during final link), which
                    328:   contains a single note.  That note has a <code class="varname">type</code> of
                    329:   <code class="code">0x012345678</code>, has the <code class="varname">name</code>
                    330:   <code class="code">"NaMe\0"</code>, and has a <code class="varname">desc</code> value
                    331:   consisting of two 4-byte integers, <code class="code">0x76543210</code> and
                    332:   <code class="code">0x89abcdef</code>.
                    333: </p>
                    334:     
                    335:       <h4 class="title">
                    336: <a name="netbsd-note"></a>Creating a NetBSD ELF <code class="constant">PT_NOTE</code> Section (<a href="#introduction">top</a>)
                    337:   </h4>
                    338:       
                    339:       <p>
                    340:        The NetBSD kernel will return ENOEXEC if an ELF binary does not contain
                    341:        a recognized <code class="constant">PT_NOTE</code> section. Normally, <code class="filename">crtbegin.c</code>
                    342:        contains this section
                    343:        for native NetBSD applications. The example below creates such a section
1.10    ! martin    344:        on NetBSD/sparc. (Other ports may use slightly different assembler syntax,
        !           345:        for example arm uses %note - since @ starts a comment,
1.1       dsieger   346:        but, except for endian variations, they all use the same bits.)
                    347:       </p>
                    348: <pre class="programlisting">
1.10    ! martin    349:         .section ".note.netbsd.ident", "", @note
1.1       dsieger   350:         .long   2f-1f
                    351:         .long   4f-3f
                    352:         .long   1
                    353: 1:      .asciz "NetBSD"
                    354: 2:      .p2align 2
1.10    ! martin    355: 3:      .long   499003600
1.1       dsieger   356: 4:      .p2align 2
                    357: </pre>
1.3       dsieger   358:     </div></div></div>
                    359: <div class="navfoot"></div>
                    360: <div id="footer"><center>
                    361: <span class="footfeed"><a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">
                    362:          Contact</a> |
1.9       kano      363:       </span><span class="footcopy"><a href="../../about/disclaimer.html">
1.3       dsieger   364:       Disclaimer</a> |
                    365: 
                    366:       <span class="copyright">Copyright © 1994-2007 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>®</sup> is a registered trademark of The NetBSD
                    367:        Foundation, Inc.</span>
                    368: </center></div>
1.1       dsieger   369: </div></body>
                    370: </html>

CVSweb <webmaster@jp.NetBSD.org>