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

1.17      jym         1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
1.1       dsieger     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.11      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>
1.17      jym        19: <div id="centralHeader">
1.19      jym        20: <div id="logo">
1.21    ! jym        21: <a href="../../"><img alt="[NetBSD Logo]" src="../../images/NetBSD-smaller.png"></a><div id="name"><a href="../../">
1.19      jym        22:          The NetBSD Project
1.21    ! jym        23:        </a></div>
        !            24: <div id="slogan"><a href="../../">
1.19      jym        25:          &#8220;Of course it runs NetBSD&#8221;
1.21    ! jym        26:        </a></div>
1.19      jym        27: </div>
                     28: <div id="headerTools">
1.17      jym        29: <div id="header-cse-search-form">Google custom search</div>
1.15      spz        30: <script src="http://www.google.com/jsapi" type="text/javascript"></script><script type="text/javascript"> 
                     31:                  google.load('search', '1', {language : 'en'});
                     32:                  google.setOnLoadCallback(function() {
                     33:                    var header_customSearchControl = new google.search.CustomSearchControl('006277936787196004968:mbdhrauy1wm');
                     34:                    header_customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET);
                     35:                    var header_options = new google.search.DrawOptions();
                     36:                    header_options.enableSearchboxOnly("http://google.com/cse?cx=006277936787196004968:mbdhrauy1wm");    
                     37:                    header_customSearchControl.draw('header-cse-search-form', header_options);
                     38:                  }, true);
1.17      jym        39:                </script>
                     40: </div>
1.3       dsieger    41: </div>
1.17      jym        42: <div id="navBar" role="navigation">
1.6       dsieger    43: <span class="doNotDisplay">
                     44:          Navigation:
1.17      jym        45:        </span><ul>
                     46: <li><a href="../../">
                     47:          Home</a></li>
                     48: <li>
                     49: <a href="../../">
1.20      wiz        50:          News &amp; Media</a><ul>
1.17      jym        51: <li><a href="../../changes/">
                     52:            Recent changes</a></li>
1.18      jym        53: <li><a href="http://blog.NetBSD.org/">
1.17      jym        54:            NetBSD blog</a></li>
                     55: <li><a href="../../gallery/events.html">
                     56:            Events</a></li>
                     57: <li><a href="../../changes/rss.html">
                     58:            Feeds</a></li>
                     59: </ul>
                     60: </li>
                     61: <li>
                     62: <a href="../../about/">
                     63:          About</a><ul>
                     64: <li><a href="../../about/">
                     65:            NetBSD</a></li>
                     66: <li><a href="../../foundation/">
                     67:            The NetBSD Foundation</a></li>
                     68: <li><a href="../../gallery/">
                     69:            Advocacy</a></li>
                     70: </ul>
                     71: </li>
                     72: <li>
                     73: <a href="../../docs/">
                     74:          Documentation</a><ul>
                     75: <li><a href="../../docs/misc/index.html">
                     76:            FAQ &amp; HOWTOs</a></li>
                     77: <li><a href="../../docs/guide/en/">
                     78:            The Guide</a></li>
1.18      jym        79: <li><a href="http://man.NetBSD.org/">
1.17      jym        80:            Manual pages</a></li>
1.18      jym        81: <li><a href="http://wiki.NetBSD.org/">
1.17      jym        82:            Wiki</a></li>
                     83: </ul>
                     84: </li>
                     85: <li>
                     86: <a href="../../support/">
                     87:          Support</a><ul>
                     88: <li><a href="../../support/send-pr.html">
                     89:            Problem report guide</a></li>
                     90: <li><a href="../../cgi-bin/sendpr.cgi?gndb=netbsd">
                     91:            Report a bug</a></li>
                     92: <li><a href="../../support/query-pr.html">
                     93:            Query bug database</a></li>
                     94: <li><a href="../../support/security/">
                     95:            Security</a></li>
                     96: </ul>
                     97: </li>
                     98: <li>
                     99: <a href="../../community/">
                    100:          Community</a><ul>
                    101: <li><a href="http://onetbsd.org/">
                    102:            Blogs</a></li>
                    103: <li><a href="../../mailinglists/">
                    104:            Mailing lists</a></li>
1.18      jym       105: <li><a href="http://mail-index.NetBSD.org/">
1.17      jym       106:            List archives</a></li>
                    107: </ul>
                    108: </li>
                    109: <li>
                    110: <a href="../../developers/">
                    111:          Developers</a><ul>
1.18      jym       112: <li><a href="http://cvsweb.NetBSD.org/">
1.17      jym       113:            Browse source</a></li>
1.18      jym       114: <li><a href="http://nxr.NetBSD.org/">
1.17      jym       115:            Cross-reference</a></li>
1.18      jym       116: <li><a href="http://releng.NetBSD.org/">
1.17      jym       117:            Release engineering</a></li>
1.18      jym       118: <li><a href="http://wiki.NetBSD.org/projects/">
1.17      jym       119:            Projects list</a></li>
                    120: </ul>
                    121: </li>
                    122: <li>
                    123: <a href="../../ports/">
                    124:          Ports</a><ul>
                    125: <li><a href="../../ports/history.html">
                    126:            History</a></li>
                    127: <li><a href="../../ports/emulators.html">
                    128:            Emulators</a></li>
                    129: </ul>
                    130: </li>
                    131: <li>
                    132: <a href="http://www.pkgsrc.org/">
                    133:          Packages</a><ul>
                    134: <li><a href="http://www.pkgsrc.se/">
                    135:            Browse packages</a></li>
1.18      jym       136: <li><a href="http://releng.NetBSD.org/index-pkgsrc.html">
1.17      jym       137:            Release engineering</a></li>
                    138: </ul>
                    139: </li>
                    140: </ul>
1.3       dsieger   141: </div>
                    142: <div id="content"><div class="fullWidth"><div class="rowOfBoxes">
                    143: <h1>NetBSD Documentation: Vendor-specific ELF Note Elements</h1>
1.1       dsieger   144: <h3 class="title"><a name="introduction"></a></h3>
                    145: <ul>
                    146: <li><a href="#introduction-sub">Introduction</a></li>
                    147: <li><a href="#note-format">Format of an ELF Note Element</a></li>
                    148: <li><a href="#note-names">Known ELF Note Names</a></li>
                    149: <li><a href="#note-contents">Vendor-specific ELF Notes</a></li>
                    150: <li><a href="#note-creation">Creating ELF PT_NOTE Sections</a></li>
                    151: <li><a href="#netbsd-note">Creating a NetBSD ELF PT_NOTE Section</a></li>
                    152: </ul>
                    153: <hr>
                    154: <h3 class="title"></h3>
                    155:     <h4 class="title">
                    156: <a name="introduction-sub"></a>Introduction (<a href="#introduction">top</a>)
                    157:   </h4>
                    158:       <p>
                    159:        Various operating system vendors are shipping ELF binaries and those
                    160:        binaries expect different system call interfaces.  In order to help
                    161:        operating systems correctly determine whether or not they can run an
                    162:        ELF program, and how to run it (e.g. what OS emulation to use), some
                    163:        operating system vendors have begun marking their ELF binaries with
                    164:        vendor-specific note elements, and placing those notes in the
                    165:        binaries' <code class="constant">PT_NOTE</code> sections.
                    166:       </p>
                    167:       <p>
                    168:        This page is meant to be a repository of knowledge about vendor-specific
                    169:        note elements used in binaries <code class="constant">PT_NOTE</code> sections for operating system
                    170:        identification.
                    171:       </p>
                    172: 
                    173:       <p>
                    174:        If your operating system uses vendor-specific note elements to
                    175:        mark its binaries and is not listed here, please send mail to
1.11      dsieger   176:        <a class="ulink" href="mailto:cgd@NetBSD.org" target="_top">Chris Demetriou</a>
1.1       dsieger   177:        with information about those notes.
                    178:       </p>
                    179:     
                    180:       <h4 class="title">
                    181: <a name="note-format"></a>Format of an ELF Note Element (<a href="#introduction">top</a>)
                    182:   </h4>
                    183: 
                    184:       <p>
                    185:        All ELF Note elements have the same basic structure:
                    186:        </p>
                    187: <div class="variablelist"><dl>
                    188: <dt><span class="term"><code class="varname">Name Size</code></span></dt>
                    189: <dd>4 bytes (integer)</dd>
                    190: <dt><span class="term"><code class="varname">Desc Size</code></span></dt>
                    191: <dd>4 bytes (integer)</dd>
                    192: <dt><span class="term"><code class="varname">Type</code></span></dt>
                    193: <dd>4 bytes (usually interpreted as an integer)</dd>
                    194: <dt><span class="term"><code class="varname">Name</code></span></dt>
                    195: <dd>variable size, padded to a 4 byte boundary</dd>
                    196: <dt><span class="term"><code class="varname">Desc</code></span></dt>
                    197: <dd>variable size, padded to a 4 byte boundary</dd>
                    198: </dl></div>
                    199: <p>
                    200:       </p>
                    201:       
                    202:       <p>
                    203:        The "Name Size" and "Desc Size" fields are integers (in the byte order
                    204:        specified by the binary's ELF header) which specify the size of the
                    205:        "Name" and "Desc" fields (excluding padding).
                    206:       </p>
                    207:     
                    208:       <p>
                    209:        The "Name" field specifies the vendor who defined the format of the Note.
                    210:        Typically, vendors use names which are related to their project and/or
                    211:        company names.  For instance, the GNU Project uses "GNU" as its name.
                    212:        No two vendors should use the same ELF Note Name, lest there be confusion
                    213:        when trying to interpret the meanings of notes.
                    214:       </p>
                    215:       
                    216:       <p>
                    217:        The "Type" field is vendor specific, but it is usually treated as an
                    218:        integer which identifies the type of the note.
                    219:       </p>
                    220:       
                    221:       <p>
                    222:        The "Desc" field is vendor specific, and usually contains data which
                    223:        depends on the note type.
                    224:       </p>
                    225:     
                    226:       <h4 class="title">
                    227: <a name="note-names"></a>Known ELF Note Names (<a href="#introduction">top</a>)
                    228:   </h4>
                    229: 
                    230:       <p>
                    231:        The following are the strings known to be used as ELF Note Names, along
                    232:        with the organizations that use them.  Names with lengths that are
                    233:        not a multiples of 4 are padded in the note, but only the given length
                    234:        should be checked.
                    235:       </p>
                    236:       
                    237:       <div class="segmentedlist"><table border="0">
                    238: <thead><tr class="segtitle">
                    239: <th>Note Name String</th>
                    240: <th>Byte encoding of string</th>
                    241: <th>Length</th>
                    242: <th>Organization</th>
                    243: </tr></thead>
                    244: <tbody>
                    245: <tr class="seglistitem">
                    246:          <td class="seg"><code class="code">"NetBSD\0"</code></td>
                    247:          <td class="seg"><code class="code">0x4e 0x65 0x74 0x42 0x53 0x44 0x00</code></td>
                    248:          <td class="seg">7</td>
1.11      dsieger   249:          <td class="seg"><a class="xref" href="#note-contents-netbsd" title="The NetBSD Project">The NetBSD Project</a></td>
1.1       dsieger   250:        </tr>
                    251: <tr class="seglistitem">
                    252:          <td class="seg"><code class="code">"GNU\0"</code></td>
                    253:          <td class="seg"><code class="code">0x47 0x4e 0x55 0x00</code></td>
                    254:          <td class="seg">4</td>
1.11      dsieger   255:          <td class="seg"><a class="xref" href="#note-contents-gnu" title="The GNU Project">The GNU Project</a></td>
1.1       dsieger   256:        </tr>
                    257: </tbody>
                    258: </table></div>
                    259:     
                    260:     <h4 class="title">
                    261: <a name="note-contents"></a>Vendor-specific ELF Notes (<a href="#introduction">top</a>)
                    262:   </h4>
                    263:       
                    264:     <p>
                    265:       This section contains information about the formats of ELF notes which
                    266:       vendors use in their <code class="constant">PT_NOTE</code> sections, and is split up by vendor.
                    267:     </p>
                    268: 
1.15      spz       269:     <div class="sect4" title="The NetBSD Project">
1.1       dsieger   270: <div class="titlepage"><div><div><h5 class="title">
                    271: <a name="note-contents-netbsd"></a>The NetBSD Project</h5></div></div></div>
                    272:       
                    273:       
                    274:       <p>
                    275:        There are two vendor-specific ELF Notes for NetBSD, an OS Version note and
                    276:        an Emulation Name note.
                    277:        The former is used to indicate what OS Version
                    278:        native binaries were built with, and can be used to identify native
                    279:        binaries.
                    280:        The latter is used to mark binaries (both native an non-native) with
                    281:        a name that indicates which set of binary emulation code is to be used
                    282:        when they are run.
                    283:       </p>
                    284:       <p>
                    285:        The format of the NetBSD OS Version note is:
                    286:        
                    287:        </p>
                    288: <div class="variablelist"><dl>
                    289: <dt><span class="term"><code class="varname">Name Size</code></span></dt>
                    290: <dd>7</dd>
                    291: <dt><span class="term"><code class="varname">Desc Size</code></span></dt>
                    292: <dd>4</dd>
                    293: <dt><span class="term"><code class="varname">Type</code></span></dt>
                    294: <dd>4-byte integer containing the value <code class="code">0x01</code>
                    295: </dd>
                    296: <dt><span class="term"><code class="varname">Name</code></span></dt>
                    297: <dd>
                    298: <code class="code">"NetBSD\0"</code> (padded to 8 bytes)</dd>
                    299: <dt><span class="term"><code class="varname">Desc</code></span></dt>
                    300: <dd>4-byte integer containing the NetBSD OS version constant</dd>
                    301: </dl></div>
                    302: <p>
                    303:       </p>
                    304: 
                    305:       <p>
                    306:        The format of the NetBSD Emulation Name note is:
                    307:        </p>
                    308: <div class="variablelist"><dl>
                    309: <dt><span class="term"><code class="varname">Name Size</code></span></dt>
                    310: <dd>7</dd>
                    311: <dt><span class="term"><code class="varname">Desc Size</code></span></dt>
                    312: <dd>variable</dd>
                    313: <dt><span class="term"><code class="varname">Type</code></span></dt>
                    314: <dd>4-byte integer containing the value <code class="code">0x02</code>
                    315: </dd>
                    316: <dt><span class="term"><code class="varname">Name</code></span></dt>
                    317: <dd>
                    318: <code class="code">"NetBSD\0"</code> (padded to 8 bytes)</dd>
                    319: <dt><span class="term"><code class="varname">Desc</code></span></dt>
                    320: <dd>
                    321: <code class="code">NUL</code>-terminated string naming the
                    322:            emulation to be used to run the binary
                    323:            (padded to the next 4-byte boundary)</dd>
                    324: </dl></div>
                    325: <p>
                    326:       </p>
                    327:     </div>
                    328: 
1.15      spz       329:     <div class="sect4" title="The GNU Project">
1.1       dsieger   330: <div class="titlepage"><div><div><h5 class="title">
                    331: <a name="note-contents-gnu"></a>The GNU Project</h5></div></div></div>
                    332:       
                    333: 
                    334:       <p>
                    335:        Starting with glibc 2.1, the GNU project will be using a single ELF Note
                    336:        to indicate which GNU operating system and which version of that system
                    337:        a binary was built for.  The format of that note is:
                    338:        </p>
                    339: <div class="variablelist"><dl>
                    340: <dt><span class="term"><code class="varname">Name Size</code></span></dt>
                    341: <dd>4</dd>
                    342: <dt><span class="term"><code class="varname">Desc Size</code></span></dt>
                    343: <dd>16</dd>
                    344: <dt><span class="term"><code class="varname">Type</code></span></dt>
                    345: <dd>4-byte integer containing the value <code class="code">0x01</code>
                    346: </dd>
                    347: <dt><span class="term"><code class="varname">Name</code></span></dt>
                    348: <dd><code class="code">"GNU\0"</code></dd>
                    349: <dt><span class="term"><code class="varname">Desc</code></span></dt>
                    350: <dd>
                    351:              Four 4-byte integers containing, in order:
1.15      spz       352:              <div class="orderedlist"><ol class="orderedlist" type="1">
                    353: <li class="listitem">OS (0 = Linux, 1 = Hurd, 2 = Solaris)</li>
                    354: <li class="listitem">Major</li>
                    355: <li class="listitem">Minor</li>
                    356: <li class="listitem">Teeny</li>
1.1       dsieger   357: </ol></div>
                    358:              The major, minor and teeny versions are that of the earliest OS version that supports this ABI.
                    359:            </dd>
                    360: </dl></div>
                    361: <p>
                    362:       </p>
                    363: 
                    364:       <p>
                    365:        For more documentation on the GNU C Library's use of ELF notes,
                    366:        consult the sources:
1.11      dsieger   367:        <a class="ulink" href="http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/abi-tags?cvsroot=glibc" target="_top">abi-tags</a>
1.1       dsieger   368:        and
1.11      dsieger   369:        <a class="ulink" href="http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/csu/abi-note.S?cvsroot=glibc" target="_top">csu/abi-note.S</a>.
1.1       dsieger   370:       </p>
                    371:     </div>
                    372:   
                    373:       <h4 class="title">
                    374: <a name="note-creation"></a>Creating ELF <code class="constant">PT_NOTE</code> Sections (<a href="#introduction">top</a>)
                    375:   </h4>
                    376: 
                    377:       <p>
                    378:        If you're using the GNU binutils 2.8 or greater to create your binaries,
                    379:        you can generate <code class="constant">PT_NOTE</code> sections in your final object files.
                    380:        To create a <code class="constant">PT_NOTE</code> section, create a section in one of your object
                    381:        files (for systems which generate <code class="constant">PT_NOTE</code> entries by default, this
                    382:        is typically the runtime startup code) with a name starting
                    383:        with ".note" and having the "allocate" property set.
                    384:        Put properly formed ELF Notes entries in that section.
                    385:        When final linking is done, all sections which have names starting
                    386:        with ".note" and which are marked "allocate" will be put into <code class="constant">PT_NOTE</code>
                    387:        sections in the final object file.
                    388:       </p>
                    389:       <p>
                    390:        An example of GNU assembler input which will create a <code class="constant">PT_NOTE</code> section
                    391:        during final link is:
                    392:       </p>
                    393: <pre class="programlisting">
                    394:     .section ".note.ident", "a"
                    395:     .p2align 2
                    396:     .long 1f - 0f           # name size (not including padding)
                    397:     .long 3f - 2f           # desc size (not including padding)
                    398:     .long 0x01234567        # type
                    399: 0:  .asciz "NaMe"          # name
                    400: 1:  .p2align 2
                    401: 2:  .long 0x76543210        # desc
                    402:     .long 0x89abcdef
                    403: 3:  .p2align 2
                    404: </pre>
                    405: 
                    406: <p>
                    407:   That example will create a section called ".note.ident", marked
                    408:   "allocate" (so that it will be turned into a
                    409:   <code class="constant">PT_NOTE</code> section during final link), which
                    410:   contains a single note.  That note has a <code class="varname">type</code> of
                    411:   <code class="code">0x012345678</code>, has the <code class="varname">name</code>
                    412:   <code class="code">"NaMe\0"</code>, and has a <code class="varname">desc</code> value
                    413:   consisting of two 4-byte integers, <code class="code">0x76543210</code> and
                    414:   <code class="code">0x89abcdef</code>.
                    415: </p>
                    416:     
                    417:       <h4 class="title">
                    418: <a name="netbsd-note"></a>Creating a NetBSD ELF <code class="constant">PT_NOTE</code> Section (<a href="#introduction">top</a>)
                    419:   </h4>
                    420:       
                    421:       <p>
                    422:        The NetBSD kernel will return ENOEXEC if an ELF binary does not contain
                    423:        a recognized <code class="constant">PT_NOTE</code> section. Normally, <code class="filename">crtbegin.c</code>
                    424:        contains this section
                    425:        for native NetBSD applications. The example below creates such a section
1.10      martin    426:        on NetBSD/sparc. (Other ports may use slightly different assembler syntax,
                    427:        for example arm uses %note - since @ starts a comment,
1.1       dsieger   428:        but, except for endian variations, they all use the same bits.)
                    429:       </p>
                    430: <pre class="programlisting">
1.10      martin    431:         .section ".note.netbsd.ident", "", @note
1.1       dsieger   432:         .long   2f-1f
                    433:         .long   4f-3f
                    434:         .long   1
                    435: 1:      .asciz "NetBSD"
                    436: 2:      .p2align 2
1.10      martin    437: 3:      .long   499003600
1.1       dsieger   438: 4:      .p2align 2
                    439: </pre>
1.3       dsieger   440:     </div></div></div>
                    441: <div class="navfoot"></div>
1.13      mishka    442: <div id="footer"><div id="footerContent"><center>
1.3       dsieger   443: <span class="footfeed"><a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">
                    444:          Contact</a> |
1.9       kano      445:       </span><span class="footcopy"><a href="../../about/disclaimer.html">
1.3       dsieger   446:       Disclaimer</a> |
                    447: 
1.16      darcy     448:       <span class="copyright">Copyright © 1994-2012 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>®</sup> is a registered trademark of The NetBSD
1.3       dsieger   449:        Foundation, Inc.</span>
1.13      mishka    450: </center></div></div>
1.1       dsieger   451: </div></body>
                    452: </html>

CVSweb <webmaster@jp.NetBSD.org>