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

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">
        !            11: <link rel="stylesheet" href="/NetBSD.css" type="text/css">
        !            12: 
        !            13: 
        !            14: 
        !            15: <title>NetBSD Documentation: Vendor-specific ELF Note Elements</title>
        !            16: </head>
        !            17: <body class="website"><div class="webpage">
        !            18: <a name="docs-kernel-elf-notes"></a><h1>NetBSD Documentation: Vendor-specific ELF Note Elements</h1>
        !            19: <h3 class="title"><a name="introduction"></a></h3>
        !            20: <ul>
        !            21: <li><a href="#introduction-sub">Introduction</a></li>
        !            22: <li><a href="#note-format">Format of an ELF Note Element</a></li>
        !            23: <li><a href="#note-names">Known ELF Note Names</a></li>
        !            24: <li><a href="#note-contents">Vendor-specific ELF Notes</a></li>
        !            25: <li><a href="#note-creation">Creating ELF PT_NOTE Sections</a></li>
        !            26: <li><a href="#netbsd-note">Creating a NetBSD ELF PT_NOTE Section</a></li>
        !            27: </ul>
        !            28: <hr>
        !            29: <h3 class="title"></h3>
        !            30:     <h4 class="title">
        !            31: <a name="introduction-sub"></a>Introduction (<a href="#introduction">top</a>)
        !            32:   </h4>
        !            33:       <p>
        !            34:        Various operating system vendors are shipping ELF binaries and those
        !            35:        binaries expect different system call interfaces.  In order to help
        !            36:        operating systems correctly determine whether or not they can run an
        !            37:        ELF program, and how to run it (e.g. what OS emulation to use), some
        !            38:        operating system vendors have begun marking their ELF binaries with
        !            39:        vendor-specific note elements, and placing those notes in the
        !            40:        binaries' <code class="constant">PT_NOTE</code> sections.
        !            41:       </p>
        !            42:       <p>
        !            43:        This page is meant to be a repository of knowledge about vendor-specific
        !            44:        note elements used in binaries <code class="constant">PT_NOTE</code> sections for operating system
        !            45:        identification.
        !            46:       </p>
        !            47: 
        !            48:       <p>
        !            49:        If your operating system uses vendor-specific note elements to
        !            50:        mark its binaries and is not listed here, please send mail to
        !            51:        <a href="mailto:cgd@NetBSD.org" target="_top">Chris Demetriou</a>
        !            52:        with information about those notes.
        !            53:       </p>
        !            54:     
        !            55:       <h4 class="title">
        !            56: <a name="note-format"></a>Format of an ELF Note Element (<a href="#introduction">top</a>)
        !            57:   </h4>
        !            58: 
        !            59:       <p>
        !            60:        All ELF Note elements have the same basic structure:
        !            61:        </p>
        !            62: <div class="variablelist"><dl>
        !            63: <dt><span class="term"><code class="varname">Name Size</code></span></dt>
        !            64: <dd>4 bytes (integer)</dd>
        !            65: <dt><span class="term"><code class="varname">Desc Size</code></span></dt>
        !            66: <dd>4 bytes (integer)</dd>
        !            67: <dt><span class="term"><code class="varname">Type</code></span></dt>
        !            68: <dd>4 bytes (usually interpreted as an integer)</dd>
        !            69: <dt><span class="term"><code class="varname">Name</code></span></dt>
        !            70: <dd>variable size, padded to a 4 byte boundary</dd>
        !            71: <dt><span class="term"><code class="varname">Desc</code></span></dt>
        !            72: <dd>variable size, padded to a 4 byte boundary</dd>
        !            73: </dl></div>
        !            74: <p>
        !            75:       </p>
        !            76:       
        !            77:       <p>
        !            78:        The "Name Size" and "Desc Size" fields are integers (in the byte order
        !            79:        specified by the binary's ELF header) which specify the size of the
        !            80:        "Name" and "Desc" fields (excluding padding).
        !            81:       </p>
        !            82:     
        !            83:       <p>
        !            84:        The "Name" field specifies the vendor who defined the format of the Note.
        !            85:        Typically, vendors use names which are related to their project and/or
        !            86:        company names.  For instance, the GNU Project uses "GNU" as its name.
        !            87:        No two vendors should use the same ELF Note Name, lest there be confusion
        !            88:        when trying to interpret the meanings of notes.
        !            89:       </p>
        !            90:       
        !            91:       <p>
        !            92:        The "Type" field is vendor specific, but it is usually treated as an
        !            93:        integer which identifies the type of the note.
        !            94:       </p>
        !            95:       
        !            96:       <p>
        !            97:        The "Desc" field is vendor specific, and usually contains data which
        !            98:        depends on the note type.
        !            99:       </p>
        !           100:     
        !           101:       <h4 class="title">
        !           102: <a name="note-names"></a>Known ELF Note Names (<a href="#introduction">top</a>)
        !           103:   </h4>
        !           104: 
        !           105:       <p>
        !           106:        The following are the strings known to be used as ELF Note Names, along
        !           107:        with the organizations that use them.  Names with lengths that are
        !           108:        not a multiples of 4 are padded in the note, but only the given length
        !           109:        should be checked.
        !           110:       </p>
        !           111:       
        !           112:       <div class="segmentedlist"><table border="0">
        !           113: <thead><tr class="segtitle">
        !           114: <th>Note Name String</th>
        !           115: <th>Byte encoding of string</th>
        !           116: <th>Length</th>
        !           117: <th>Organization</th>
        !           118: </tr></thead>
        !           119: <tbody>
        !           120: <tr class="seglistitem">
        !           121:          <td class="seg"><code class="code">"NetBSD\0"</code></td>
        !           122:          <td class="seg"><code class="code">0x4e 0x65 0x74 0x42 0x53 0x44 0x00</code></td>
        !           123:          <td class="seg">7</td>
        !           124:          <td class="seg"><a href="#note-contents-netbsd" title="The NetBSD Project">The NetBSD Project</a></td>
        !           125:        </tr>
        !           126: <tr class="seglistitem">
        !           127:          <td class="seg"><code class="code">"GNU\0"</code></td>
        !           128:          <td class="seg"><code class="code">0x47 0x4e 0x55 0x00</code></td>
        !           129:          <td class="seg">4</td>
        !           130:          <td class="seg"><a href="#note-contents-gnu" title="The GNU Project">The GNU Project</a></td>
        !           131:        </tr>
        !           132: </tbody>
        !           133: </table></div>
        !           134:     
        !           135:     <h4 class="title">
        !           136: <a name="note-contents"></a>Vendor-specific ELF Notes (<a href="#introduction">top</a>)
        !           137:   </h4>
        !           138:       
        !           139:     <p>
        !           140:       This section contains information about the formats of ELF notes which
        !           141:       vendors use in their <code class="constant">PT_NOTE</code> sections, and is split up by vendor.
        !           142:     </p>
        !           143: 
        !           144:     <div class="sect4" lang="en">
        !           145: <div class="titlepage"><div><div><h5 class="title">
        !           146: <a name="note-contents-netbsd"></a>The NetBSD Project</h5></div></div></div>
        !           147:       
        !           148:       
        !           149:       <p>
        !           150:        There are two vendor-specific ELF Notes for NetBSD, an OS Version note and
        !           151:        an Emulation Name note.
        !           152:        The former is used to indicate what OS Version
        !           153:        native binaries were built with, and can be used to identify native
        !           154:        binaries.
        !           155:        The latter is used to mark binaries (both native an non-native) with
        !           156:        a name that indicates which set of binary emulation code is to be used
        !           157:        when they are run.
        !           158:       </p>
        !           159:       <p>
        !           160:        The format of the NetBSD OS Version note is:
        !           161:        
        !           162:        </p>
        !           163: <div class="variablelist"><dl>
        !           164: <dt><span class="term"><code class="varname">Name Size</code></span></dt>
        !           165: <dd>7</dd>
        !           166: <dt><span class="term"><code class="varname">Desc Size</code></span></dt>
        !           167: <dd>4</dd>
        !           168: <dt><span class="term"><code class="varname">Type</code></span></dt>
        !           169: <dd>4-byte integer containing the value <code class="code">0x01</code>
        !           170: </dd>
        !           171: <dt><span class="term"><code class="varname">Name</code></span></dt>
        !           172: <dd>
        !           173: <code class="code">"NetBSD\0"</code> (padded to 8 bytes)</dd>
        !           174: <dt><span class="term"><code class="varname">Desc</code></span></dt>
        !           175: <dd>4-byte integer containing the NetBSD OS version constant</dd>
        !           176: </dl></div>
        !           177: <p>
        !           178:       </p>
        !           179: 
        !           180:       <p>
        !           181:        The format of the NetBSD Emulation Name note is:
        !           182:        </p>
        !           183: <div class="variablelist"><dl>
        !           184: <dt><span class="term"><code class="varname">Name Size</code></span></dt>
        !           185: <dd>7</dd>
        !           186: <dt><span class="term"><code class="varname">Desc Size</code></span></dt>
        !           187: <dd>variable</dd>
        !           188: <dt><span class="term"><code class="varname">Type</code></span></dt>
        !           189: <dd>4-byte integer containing the value <code class="code">0x02</code>
        !           190: </dd>
        !           191: <dt><span class="term"><code class="varname">Name</code></span></dt>
        !           192: <dd>
        !           193: <code class="code">"NetBSD\0"</code> (padded to 8 bytes)</dd>
        !           194: <dt><span class="term"><code class="varname">Desc</code></span></dt>
        !           195: <dd>
        !           196: <code class="code">NUL</code>-terminated string naming the
        !           197:            emulation to be used to run the binary
        !           198:            (padded to the next 4-byte boundary)</dd>
        !           199: </dl></div>
        !           200: <p>
        !           201:       </p>
        !           202:     </div>
        !           203: 
        !           204:     <div class="sect4" lang="en">
        !           205: <div class="titlepage"><div><div><h5 class="title">
        !           206: <a name="note-contents-gnu"></a>The GNU Project</h5></div></div></div>
        !           207:       
        !           208: 
        !           209:       <p>
        !           210:        Starting with glibc 2.1, the GNU project will be using a single ELF Note
        !           211:        to indicate which GNU operating system and which version of that system
        !           212:        a binary was built for.  The format of that note is:
        !           213:        </p>
        !           214: <div class="variablelist"><dl>
        !           215: <dt><span class="term"><code class="varname">Name Size</code></span></dt>
        !           216: <dd>4</dd>
        !           217: <dt><span class="term"><code class="varname">Desc Size</code></span></dt>
        !           218: <dd>16</dd>
        !           219: <dt><span class="term"><code class="varname">Type</code></span></dt>
        !           220: <dd>4-byte integer containing the value <code class="code">0x01</code>
        !           221: </dd>
        !           222: <dt><span class="term"><code class="varname">Name</code></span></dt>
        !           223: <dd><code class="code">"GNU\0"</code></dd>
        !           224: <dt><span class="term"><code class="varname">Desc</code></span></dt>
        !           225: <dd>
        !           226:              Four 4-byte integers containing, in order:
        !           227:              <div class="orderedlist"><ol type="1">
        !           228: <li>OS (0 = Linux, 1 = Hurd, 2 = Solaris)</li>
        !           229: <li>Major</li>
        !           230: <li>Minor</li>
        !           231: <li>Teeny</li>
        !           232: </ol></div>
        !           233:              The major, minor and teeny versions are that of the earliest OS version that supports this ABI.
        !           234:            </dd>
        !           235: </dl></div>
        !           236: <p>
        !           237:       </p>
        !           238: 
        !           239:       <p>
        !           240:        For more documentation on the GNU C Library's use of ELF notes,
        !           241:        consult the sources:
        !           242:        <a href="http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/abi-tags?cvsroot=glibc" target="_top">abi-tags</a>
        !           243:        and
        !           244:        <a href="http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/csu/abi-note.S?cvsroot=glibc" target="_top">csu/abi-note.S</a>.
        !           245:       </p>
        !           246:     </div>
        !           247:   
        !           248:       <h4 class="title">
        !           249: <a name="note-creation"></a>Creating ELF <code class="constant">PT_NOTE</code> Sections (<a href="#introduction">top</a>)
        !           250:   </h4>
        !           251: 
        !           252:       <p>
        !           253:        If you're using the GNU binutils 2.8 or greater to create your binaries,
        !           254:        you can generate <code class="constant">PT_NOTE</code> sections in your final object files.
        !           255:        To create a <code class="constant">PT_NOTE</code> section, create a section in one of your object
        !           256:        files (for systems which generate <code class="constant">PT_NOTE</code> entries by default, this
        !           257:        is typically the runtime startup code) with a name starting
        !           258:        with ".note" and having the "allocate" property set.
        !           259:        Put properly formed ELF Notes entries in that section.
        !           260:        When final linking is done, all sections which have names starting
        !           261:        with ".note" and which are marked "allocate" will be put into <code class="constant">PT_NOTE</code>
        !           262:        sections in the final object file.
        !           263:       </p>
        !           264:       <p>
        !           265:        An example of GNU assembler input which will create a <code class="constant">PT_NOTE</code> section
        !           266:        during final link is:
        !           267:       </p>
        !           268: <pre class="programlisting">
        !           269:     .section ".note.ident", "a"
        !           270:     .p2align 2
        !           271:     .long 1f - 0f           # name size (not including padding)
        !           272:     .long 3f - 2f           # desc size (not including padding)
        !           273:     .long 0x01234567        # type
        !           274: 0:  .asciz "NaMe"          # name
        !           275: 1:  .p2align 2
        !           276: 2:  .long 0x76543210        # desc
        !           277:     .long 0x89abcdef
        !           278: 3:  .p2align 2
        !           279: </pre>
        !           280: 
        !           281: <p>
        !           282:   That example will create a section called ".note.ident", marked
        !           283:   "allocate" (so that it will be turned into a
        !           284:   <code class="constant">PT_NOTE</code> section during final link), which
        !           285:   contains a single note.  That note has a <code class="varname">type</code> of
        !           286:   <code class="code">0x012345678</code>, has the <code class="varname">name</code>
        !           287:   <code class="code">"NaMe\0"</code>, and has a <code class="varname">desc</code> value
        !           288:   consisting of two 4-byte integers, <code class="code">0x76543210</code> and
        !           289:   <code class="code">0x89abcdef</code>.
        !           290: </p>
        !           291:     
        !           292:       <h4 class="title">
        !           293: <a name="netbsd-note"></a>Creating a NetBSD ELF <code class="constant">PT_NOTE</code> Section (<a href="#introduction">top</a>)
        !           294:   </h4>
        !           295:       
        !           296:       <p>
        !           297:        The NetBSD kernel will return ENOEXEC if an ELF binary does not contain
        !           298:        a recognized <code class="constant">PT_NOTE</code> section. Normally, <code class="filename">crtbegin.c</code>
        !           299:        contains this section
        !           300:        for native NetBSD applications. The example below creates such a section
        !           301:        on NetBSD/alpha. (Other ports may use slightly different assembler syntax,
        !           302:        but, except for endian variations, they all use the same bits.)
        !           303:       </p>
        !           304: <pre class="programlisting">
        !           305:         .section ".note.netbsd.ident", "a"
        !           306:         .long   2f-1f
        !           307:         .long   4f-3f
        !           308:         .long   1
        !           309: 1:      .asciz "NetBSD"
        !           310: 2:      .p2align 2
        !           311: 3:      .long   199905
        !           312: 4:      .p2align 2
        !           313: </pre>
        !           314:     <div class="navfoot">
        !           315: <hr>
        !           316: <table border="0" summary="Footer navigation"><tr>
        !           317: <td class="foothome"><span class="foothome"><a href="../../."><img src="/images/NetBSD-flag.png" alt="[NetBSD flag]" border="0" width="90" height="90"></a></span></td>
        !           318: <td class="foothome">
        !           319: <span class="foothome"><a href="../../.">Home page</a></span><br>
        !           320: </td>
        !           321: </tr></table>
        !           322: <hr>
        !           323: </div>
        !           324: <p></p>
        !           325: <span class="footfeed"><a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">(contact us)</a></span>
        !           326: 
        !           327:    
        !           328:   <span class="foottag">Generated from <em>%NetBSD: elf-notes.xml,v 1.2 2007/04/09 16:24:15 kano Exp %</em></span><br><span class="footcopy"><a href="/Misc/disclaimer.html"><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
        !           329:        Foundation, Inc.</a></span>
        !           330: </div></body>
        !           331: </html>

CVSweb <webmaster@jp.NetBSD.org>