Annotation of htdocs/docs/kernel/elf-notes.xml, revision 1.6

1.1       dsieger     1: <?xml version="1.0"?>
                      2: <!DOCTYPE webpage
                      3:  PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
                      4:         "http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">
                      5: 
                      6: <webpage id="docs-kernel-elf-notes">
                      7: <config param="desc" value="Vendor-specific ELF Notes"/>
1.6     ! martin      8: <config param="cvstag" value="$NetBSD: elf-notes.xml,v 1.5 2013/11/06 14:13:01 martin Exp $"/>
        !             9: <config param="rcsdate" value="$Date: 2013/11/06 14:13:01 $"/>
1.1       dsieger    10: <head>
                     11: 
1.3       martin     12: <!-- Copyright (c) 1994-2013
1.1       dsieger    13:        The NetBSD Foundation, Inc.  ALL RIGHTS RESERVED. -->
                     14: 
                     15: <title>NetBSD Documentation: Vendor-specific ELF Note Elements</title>
                     16: </head>
                     17: 
                     18: <sect1 role="toc">
                     19:   <sect2 id="introduction">
                     20:     <sect3 id="introduction-sub">
                     21:     <title>Introduction</title>
                     22:       <para>
                     23:        Various operating system vendors are shipping ELF binaries and those
                     24:        binaries expect different system call interfaces.  In order to help
                     25:        operating systems correctly determine whether or not they can run an
                     26:        ELF program, and how to run it (e.g. what OS emulation to use), some
                     27:        operating system vendors have begun marking their ELF binaries with
                     28:        vendor-specific note elements, and placing those notes in the
                     29:        binaries' <constant>PT_NOTE</constant> sections.
                     30:       </para>
                     31:       <para>
                     32:        This page is meant to be a repository of knowledge about vendor-specific
                     33:        note elements used in binaries <constant>PT_NOTE</constant> sections for operating system
                     34:        identification.
                     35:       </para>
                     36: 
                     37:       <para>
                     38:        If your operating system uses vendor-specific note elements to
                     39:        mark its binaries and is not listed here, please send mail to
1.3       martin     40:        <ulink url="mailto:netbsd-docs@NetBSD.org">NetBSD documentation list</ulink>
1.1       dsieger    41:        with information about those notes.
                     42:       </para>
                     43:     </sect3>
                     44:     <sect3 id="note-format">
                     45:       <title>Format of an ELF Note Element</title>
                     46: 
                     47:       <para>
                     48:        All ELF Note elements have the same basic structure:
                     49:        <variablelist class="elf-note">
                     50:          <varlistentry>
                     51:            <term><varname>Name Size</varname></term>
                     52:            <listitem>4 bytes (integer)</listitem>
                     53:          </varlistentry>
                     54:          <varlistentry>
                     55:            <term><varname>Desc Size</varname></term>
                     56:            <listitem>4 bytes (integer)</listitem>
                     57:          </varlistentry>
                     58:          <varlistentry>
                     59:            <term><varname>Type</varname></term>
                     60:            <listitem>4 bytes (usually interpreted as an integer)</listitem>
                     61:          </varlistentry>
                     62:          <varlistentry>
                     63:            <term><varname>Name</varname></term>
                     64:            <listitem>variable size, padded to a 4 byte boundary</listitem>
                     65:          </varlistentry>
                     66:          <varlistentry>
                     67:            <term><varname>Desc</varname></term>
                     68:            <listitem>variable size, padded to a 4 byte boundary</listitem>
                     69:          </varlistentry>
                     70:        </variablelist>
                     71:       </para>
                     72:       
                     73:       <para>
                     74:        The "Name Size" and "Desc Size" fields are integers (in the byte order
                     75:        specified by the binary's ELF header) which specify the size of the
                     76:        "Name" and "Desc" fields (excluding padding).
                     77:       </para>
                     78:     
                     79:       <para>
                     80:        The "Name" field specifies the vendor who defined the format of the Note.
                     81:        Typically, vendors use names which are related to their project and/or
                     82:        company names.  For instance, the GNU Project uses "GNU" as its name.
                     83:        No two vendors should use the same ELF Note Name, lest there be confusion
                     84:        when trying to interpret the meanings of notes.
                     85:       </para>
                     86:       
                     87:       <para>
                     88:        The "Type" field is vendor specific, but it is usually treated as an
                     89:        integer which identifies the type of the note.
                     90:       </para>
                     91:       
                     92:       <para>
                     93:        The "Desc" field is vendor specific, and usually contains data which
                     94:        depends on the note type.
                     95:       </para>
                     96:     </sect3>
                     97:     
                     98:     <sect3 id="note-names">
                     99:       <title>Known ELF Note Names</title>
                    100: 
                    101:       <para>
                    102:        The following are the strings known to be used as ELF Note Names, along
                    103:        with the organizations that use them.  Names with lengths that are
                    104:        not a multiples of 4 are padded in the note, but only the given length
                    105:        should be checked.
                    106:       </para>
                    107:       
                    108:       <segmentedlist>
                    109:        <segtitle>Note Name String</segtitle>
                    110:        <segtitle>Byte encoding of string</segtitle>
                    111:        <segtitle>Length</segtitle>
                    112:        <segtitle>Organization</segtitle>
                    113:        <?dbhtml list-presentation="table"?>
                    114:        <seglistitem>
                    115:          <seg><code>"NetBSD\0"</code></seg>
                    116:          <seg><code>0x4e 0x65 0x74 0x42 0x53 0x44 0x00</code></seg>
                    117:          <seg>7</seg>
                    118:          <seg><xref linkend="note-contents-netbsd" /></seg>
                    119:        </seglistitem>
                    120:        <seglistitem>
1.6     ! martin    121:          <seg><code>"PaX\0"</code></seg>
        !           122:          <seg><code>0x50 0x61 0x58 0x00</code></seg>
        !           123:          <seg>4</seg>
        !           124:          <seg>specific to <xref linkend="note-contents-netbsd" /> ? </seg>
        !           125:        </seglistitem>
        !           126:        <seglistitem>
1.1       dsieger   127:          <seg><code>"GNU\0"</code></seg>
                    128:          <seg><code>0x47 0x4e 0x55 0x00</code></seg>
                    129:          <seg>4</seg>
                    130:          <seg><xref linkend="note-contents-gnu" /></seg>
                    131:        </seglistitem>
                    132:       </segmentedlist>
                    133:     </sect3>
                    134:   <sect3 id="note-contents">
                    135:     <title>Vendor-specific ELF Notes</title>
                    136:       
                    137:     <para>
                    138:       This section contains information about the formats of ELF notes which
                    139:       vendors use in their <constant>PT_NOTE</constant> sections, and is split up by vendor.
                    140:     </para>
                    141: 
                    142:     <sect4 id="note-contents-netbsd" xreflabel="The NetBSD Project">
                    143:       <title>The NetBSD Project</title>
                    144:       
                    145:       <para>
1.6     ! martin    146:        There are four vendor-specific ELF Notes for NetBSD and the
        !           147:        PaX note also included in this list, as currently it is
        !           148:        not know wether it is used with other operating systems
        !           149:        as well.</para>
        !           150:       </para>
        !           151:       <para>The OS Version note 
        !           152:        is used to indicate what OS Version
1.1       dsieger   153:        native binaries were built with, and can be used to identify native
1.6     ! martin    154:        binaries.</para>
1.1       dsieger   155:       <para>
1.6     ! martin    156:        The format is:
1.1       dsieger   157:        
                    158:        <variablelist class="elf-note">
                    159:          <varlistentry>
                    160:            <term><varname>Name Size</varname></term>
                    161:            <listitem>7</listitem>
                    162:          </varlistentry>
                    163:          <varlistentry>
                    164:            <term><varname>Desc Size</varname></term>
                    165:            <listitem>4</listitem>
                    166:          </varlistentry>
                    167:          <varlistentry>
                    168:            <term><varname>Type</varname></term>
                    169:            <listitem>4-byte integer containing the value <code>0x01</code></listitem>
                    170:          </varlistentry>
                    171:          <varlistentry>
                    172:            <term><varname>Name</varname></term>
                    173:            <listitem><code>"NetBSD\0"</code> (padded to 8 bytes)</listitem>
                    174:          </varlistentry>
                    175:          <varlistentry>
                    176:            <term><varname>Desc</varname></term>
                    177:            <listitem>4-byte integer containing the NetBSD OS version constant</listitem>
                    178:          </varlistentry>
                    179:        </variablelist>
                    180:       </para>
                    181: 
                    182:       <para>
1.6     ! martin    183:        The Emulation Name note is used to mark binaries (both native an non-native) with
        !           184:        a name that indicates which set of binary emulation code is to be used
        !           185:        when they are run.</para>
        !           186:       <para>
        !           187:        The format is:
1.1       dsieger   188:        <variablelist class="elf-note">
                    189:          <varlistentry>
                    190:            <term><varname>Name Size</varname></term>
                    191:            <listitem>7</listitem>
                    192:          </varlistentry>
                    193:          <varlistentry>
                    194:            <term><varname>Desc Size</varname></term>
                    195:            <listitem>variable</listitem>
                    196:          </varlistentry>
                    197:          <varlistentry>
                    198:            <term><varname>Type</varname></term>
                    199:            <listitem>4-byte integer containing the value <code>0x02</code></listitem>
                    200:          </varlistentry>
                    201:          <varlistentry>
                    202:            <term><varname>Name</varname></term>
                    203:            <listitem><code>"NetBSD\0"</code> (padded to 8 bytes)</listitem>
                    204:          </varlistentry>
                    205:          <varlistentry>
                    206:            <term><varname>Desc</varname></term>
                    207:            <listitem><code>NUL</code>-terminated string naming the
                    208:            emulation to be used to run the binary
                    209:            (padded to the next 4-byte boundary)</listitem>
                    210:          </varlistentry>
                    211:        </variablelist>
                    212:       </para>
1.3       martin    213: 
                    214:       <para>
1.6     ! martin    215:        The PaX note encodes execution protection and addrss space
        !           216:        layout randomization flags.</para>
        !           217:       <para>
        !           218:        The format is:
1.3       martin    219:        
                    220:        <variablelist class="elf-note">
                    221:          <varlistentry>
                    222:            <term><varname>Name Size</varname></term>
                    223:            <listitem>4</listitem>
                    224:          </varlistentry>
                    225:          <varlistentry>
                    226:            <term><varname>Desc Size</varname></term>
                    227:            <listitem>4</listitem>
                    228:          </varlistentry>
                    229:          <varlistentry>
                    230:            <term><varname>Type</varname></term>
                    231:            <listitem>4-byte integer containing the value <code>0x03</code></listitem>
                    232:          </varlistentry>
                    233:          <varlistentry>
                    234:            <term><varname>Name</varname></term>
1.5       martin    235:            <listitem><code>"PaX\0"</code></listitem>
1.3       martin    236:          </varlistentry>
                    237:          <varlistentry>
                    238:            <term><varname>Desc</varname></term>
                    239:            <listitem>4-byte bitmask with the following bits:
                    240:            <segmentedlist>
                    241:              <segtitle>Bit</segtitle>
1.4       mbalmer   242:              <segtitle>Meaning</segtitle>
1.3       martin    243:              <?dbhtml list-presentation="table"?>
                    244:              <seglistitem>
                    245:                <seg><code>0x01</code></seg>
                    246:                <seg>Force enable Mprotect</seg>
                    247:              </seglistitem>
                    248:              <seglistitem>
                    249:                <seg><code>0x02</code></seg>
                    250:                <seg>Force disable Mprotect</seg>
                    251:              </seglistitem>
                    252:              <seglistitem>
                    253:                <seg><code>0x04</code></seg>
                    254:                <seg>Force enable Segvguard</seg>
                    255:              </seglistitem>
                    256:              <seglistitem>
                    257:                <seg><code>0x08</code></seg>
                    258:                <seg>Force disable Segvguard</seg>
                    259:              </seglistitem>
                    260:              <seglistitem>
                    261:                <seg><code>0x10</code></seg>
                    262:                <seg>Force enable ASLR</seg>
                    263:              </seglistitem>
                    264:              <seglistitem>
                    265:                <seg><code>0x20</code></seg>
                    266:                <seg>Force disable ASLR</seg>
                    267:              </seglistitem>
                    268:            </segmentedlist>
                    269:            </listitem>
                    270:          </varlistentry>
                    271:        </variablelist>
                    272:       </para>
                    273: 
                    274:       <para>
1.6     ! martin    275:        The Architecture Note encodes machine architecture details.</para>
        !           276:       <para>
        !           277:        The format is:
1.3       martin    278:        
                    279:        <variablelist class="elf-note">
                    280:          <varlistentry>
                    281:            <term><varname>Name Size</varname></term>
                    282:            <listitem>7</listitem>
                    283:          </varlistentry>
                    284:          <varlistentry>
                    285:            <term><varname>Desc Size</varname></term>
                    286:            <listitem>variable</listitem>
                    287:          </varlistentry>
                    288:          <varlistentry>
                    289:            <term><varname>Type</varname></term>
                    290:            <listitem>4-byte integer containing the value <code>0x05</code></listitem>
                    291:          </varlistentry>
                    292:          <varlistentry>
                    293:            <term><varname>Name</varname></term>
                    294:            <listitem><code>"NetBSD\0"</code> (padded to 8 bytes)</listitem>
                    295:          </varlistentry>
                    296:          <varlistentry>
                    297:            <term><varname>Desc</varname></term>
                    298:            <listitem>A string describing the architecture the binary was
                    299:                      compiled for (for example used on ARM to distinguish
                    300:                      hardware floating point ABI and softfloat)</listitem>
                    301:          </varlistentry>
                    302:        </variablelist>
                    303:       </para>
                    304: 
                    305:       <para>
1.6     ! martin    306:        The Code Model Note encodes code model details.
        !           307:       <para>
        !           308:        The format is:
1.3       martin    309:        
                    310:        <variablelist class="elf-note">
                    311:          <varlistentry>
                    312:            <term><varname>Name Size</varname></term>
                    313:            <listitem>7</listitem>
                    314:          </varlistentry>
                    315:          <varlistentry>
                    316:            <term><varname>Desc Size</varname></term>
                    317:            <listitem>variable</listitem>
                    318:          </varlistentry>
                    319:          <varlistentry>
                    320:            <term><varname>Type</varname></term>
                    321:            <listitem>4-byte integer containing the value <code>0x06</code></listitem>
                    322:          </varlistentry>
                    323:          <varlistentry>
                    324:            <term><varname>Name</varname></term>
                    325:            <listitem><code>"NetBSD\0"</code> (padded to 8 bytes)</listitem>
                    326:          </varlistentry>
                    327:          <varlistentry>
                    328:            <term><varname>Desc</varname></term>
                    329:            <listitem>A string describing the code model the binary was
                    330:                      compiled for. Used for example on sparc64 to tell
                    331:                      binaries compiled with -mcmodel=medlow apart from
1.5       martin    332:                      standard (-mcmodel=medmid) ones, because the former
1.3       martin    333:                      are not eligible for top-down virtual memory
                    334:                      layout.</listitem>
                    335:          </varlistentry>
                    336:        </variablelist>
                    337:       </para>
                    338: 
1.1       dsieger   339:     </sect4>
                    340: 
                    341:     <sect4 id="note-contents-gnu" xreflabel="The GNU Project">
                    342:       <title>The GNU Project</title>
                    343: 
                    344:       <para>
                    345:        Starting with glibc 2.1, the GNU project will be using a single ELF Note
                    346:        to indicate which GNU operating system and which version of that system
                    347:        a binary was built for.  The format of that note is:
                    348:        <variablelist>
                    349:          <varlistentry>
                    350:            <term><varname>Name Size</varname></term>
                    351:            <listitem>4</listitem>
                    352:          </varlistentry>
                    353:          <varlistentry>
                    354:            <term><varname>Desc Size</varname></term>
                    355:            <listitem>16</listitem>
                    356:          </varlistentry>
                    357:          <varlistentry>
                    358:            <term><varname>Type</varname></term>
                    359:            <listitem>4-byte integer containing the value <code>0x01</code></listitem>
                    360:          </varlistentry>
                    361:          <varlistentry>
                    362:            <term><varname>Name</varname></term>
                    363:            <listitem><code>"GNU\0"</code></listitem>
                    364:          </varlistentry>
                    365:          <varlistentry>
                    366:            <term><varname>Desc</varname></term>
                    367:            <listitem>
                    368:              Four 4-byte integers containing, in order:
                    369:              <orderedlist>
                    370:                <listitem>OS (0 = Linux, 1 = Hurd, 2 = Solaris)</listitem>
                    371:                <listitem>Major</listitem>
                    372:                <listitem>Minor</listitem>
                    373:                <listitem>Teeny</listitem>
                    374:              </orderedlist>
                    375:              The major, minor and teeny versions are that of the earliest OS version that supports this ABI.
                    376:            </listitem>
                    377:          </varlistentry>
                    378:        </variablelist>
                    379:       </para>
                    380: 
                    381:       <para>
                    382:        For more documentation on the GNU C Library's use of ELF notes,
                    383:        consult the sources:
                    384:        <ulink url="http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/abi-tags?cvsroot=glibc">abi-tags</ulink>
                    385:        and
                    386:        <ulink url="http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/csu/abi-note.S?cvsroot=glibc">csu/abi-note.S</ulink>.
                    387:       </para>
                    388:     </sect4>
                    389:   </sect3>
                    390:   
                    391:     <sect3 id="note-creation">
                    392:       <title>Creating ELF <constant>PT_NOTE</constant> Sections</title>
                    393: 
                    394:       <para>
                    395:        If you're using the GNU binutils 2.8 or greater to create your binaries,
                    396:        you can generate <constant>PT_NOTE</constant> sections in your final object files.
                    397:        To create a <constant>PT_NOTE</constant> section, create a section in one of your object
                    398:        files (for systems which generate <constant>PT_NOTE</constant> entries by default, this
                    399:        is typically the runtime startup code) with a name starting
                    400:        with ".note" and having the "allocate" property set.
                    401:        Put properly formed ELF Notes entries in that section.
                    402:        When final linking is done, all sections which have names starting
                    403:        with ".note" and which are marked "allocate" will be put into <constant>PT_NOTE</constant>
                    404:        sections in the final object file.
                    405:       </para>
                    406:       <para>
                    407:        An example of GNU assembler input which will create a <constant>PT_NOTE</constant> section
                    408:        during final link is:
                    409:       </para>
                    410: <programlisting language="assembler">
                    411:     .section ".note.ident", "a"
                    412:     .p2align 2
                    413:     .long 1f - 0f           # name size (not including padding)
                    414:     .long 3f - 2f           # desc size (not including padding)
                    415:     .long 0x01234567        # type
                    416: 0:  .asciz "NaMe"          # name
                    417: 1:  .p2align 2
                    418: 2:  .long 0x76543210        # desc
                    419:     .long 0x89abcdef
                    420: 3:  .p2align 2
                    421: </programlisting>
                    422: 
                    423: <para>
                    424:   That example will create a section called ".note.ident", marked
                    425:   "allocate" (so that it will be turned into a
                    426:   <constant>PT_NOTE</constant> section during final link), which
                    427:   contains a single note.  That note has a <varname>type</varname> of
                    428:   <code>0x012345678</code>, has the <varname>name</varname>
                    429:   <code>"NaMe\0"</code>, and has a <varname>desc</varname> value
                    430:   consisting of two 4-byte integers, <code>0x76543210</code> and
                    431:   <code>0x89abcdef</code>.
                    432: </para>
                    433:     </sect3>
                    434:     
                    435:     <sect3 id="netbsd-note">
                    436:       <title>Creating a NetBSD ELF <constant>PT_NOTE</constant> Section</title>
                    437:       
                    438:       <para>
                    439:        The NetBSD kernel will return ENOEXEC if an ELF binary does not contain
                    440:        a recognized <constant>PT_NOTE</constant> section. Normally, <filename>crtbegin.c</filename>
                    441:        contains this section
                    442:        for native NetBSD applications. The example below creates such a section
1.2       martin    443:        on NetBSD/sparc. (Other ports may use slightly different assembler syntax,
                    444:        for example arm uses %note - since @ starts a comment,
1.1       dsieger   445:        but, except for endian variations, they all use the same bits.)
                    446:       </para>
                    447: <programlisting language="assembler">
1.2       martin    448:         .section ".note.netbsd.ident", "", @note
1.1       dsieger   449:         .long   2f-1f
                    450:         .long   4f-3f
                    451:         .long   1
                    452: 1:      .asciz "NetBSD"
                    453: 2:      .p2align 2
1.2       martin    454: 3:      .long   499003600
1.1       dsieger   455: 4:      .p2align 2
                    456: </programlisting>
                    457:     </sect3>
                    458:   </sect2>
                    459: </sect1>
                    460: </webpage>
                    461: 

CVSweb <webmaster@jp.NetBSD.org>