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

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"/>
        !             8: <config param="cvstag" value="$NetBSD: elf-notes.xml,v 1.2 2007/04/09 16:24:15 kano Exp $"/>
        !             9: <config param="rcsdate" value="$Date: 2007/04/09 16:24:15 $"/>
        !            10: <head>
        !            11: 
        !            12: <!-- Copyright (c) 1994-2007
        !            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
        !            40:        <ulink url="mailto:cgd@NetBSD.org">Chris Demetriou</ulink>
        !            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>
        !           121:          <seg><code>"GNU\0"</code></seg>
        !           122:          <seg><code>0x47 0x4e 0x55 0x00</code></seg>
        !           123:          <seg>4</seg>
        !           124:          <seg><xref linkend="note-contents-gnu" /></seg>
        !           125:        </seglistitem>
        !           126:       </segmentedlist>
        !           127:     </sect3>
        !           128:   <sect3 id="note-contents">
        !           129:     <title>Vendor-specific ELF Notes</title>
        !           130:       
        !           131:     <para>
        !           132:       This section contains information about the formats of ELF notes which
        !           133:       vendors use in their <constant>PT_NOTE</constant> sections, and is split up by vendor.
        !           134:     </para>
        !           135: 
        !           136:     <sect4 id="note-contents-netbsd" xreflabel="The NetBSD Project">
        !           137:       <title>The NetBSD Project</title>
        !           138:       
        !           139:       <para>
        !           140:        There are two vendor-specific ELF Notes for NetBSD, an OS Version note and
        !           141:        an Emulation Name note.
        !           142:        The former is used to indicate what OS Version
        !           143:        native binaries were built with, and can be used to identify native
        !           144:        binaries.
        !           145:        The latter is used to mark binaries (both native an non-native) with
        !           146:        a name that indicates which set of binary emulation code is to be used
        !           147:        when they are run.
        !           148:       </para>
        !           149:       <para>
        !           150:        The format of the NetBSD OS Version note is:
        !           151:        
        !           152:        <variablelist class="elf-note">
        !           153:          <varlistentry>
        !           154:            <term><varname>Name Size</varname></term>
        !           155:            <listitem>7</listitem>
        !           156:          </varlistentry>
        !           157:          <varlistentry>
        !           158:            <term><varname>Desc Size</varname></term>
        !           159:            <listitem>4</listitem>
        !           160:          </varlistentry>
        !           161:          <varlistentry>
        !           162:            <term><varname>Type</varname></term>
        !           163:            <listitem>4-byte integer containing the value <code>0x01</code></listitem>
        !           164:          </varlistentry>
        !           165:          <varlistentry>
        !           166:            <term><varname>Name</varname></term>
        !           167:            <listitem><code>"NetBSD\0"</code> (padded to 8 bytes)</listitem>
        !           168:          </varlistentry>
        !           169:          <varlistentry>
        !           170:            <term><varname>Desc</varname></term>
        !           171:            <listitem>4-byte integer containing the NetBSD OS version constant</listitem>
        !           172:          </varlistentry>
        !           173:        </variablelist>
        !           174:       </para>
        !           175: 
        !           176:       <para>
        !           177:        The format of the NetBSD Emulation Name note is:
        !           178:        <variablelist class="elf-note">
        !           179:          <varlistentry>
        !           180:            <term><varname>Name Size</varname></term>
        !           181:            <listitem>7</listitem>
        !           182:          </varlistentry>
        !           183:          <varlistentry>
        !           184:            <term><varname>Desc Size</varname></term>
        !           185:            <listitem>variable</listitem>
        !           186:          </varlistentry>
        !           187:          <varlistentry>
        !           188:            <term><varname>Type</varname></term>
        !           189:            <listitem>4-byte integer containing the value <code>0x02</code></listitem>
        !           190:          </varlistentry>
        !           191:          <varlistentry>
        !           192:            <term><varname>Name</varname></term>
        !           193:            <listitem><code>"NetBSD\0"</code> (padded to 8 bytes)</listitem>
        !           194:          </varlistentry>
        !           195:          <varlistentry>
        !           196:            <term><varname>Desc</varname></term>
        !           197:            <listitem><code>NUL</code>-terminated string naming the
        !           198:            emulation to be used to run the binary
        !           199:            (padded to the next 4-byte boundary)</listitem>
        !           200:          </varlistentry>
        !           201:        </variablelist>
        !           202:       </para>
        !           203:     </sect4>
        !           204: 
        !           205:     <sect4 id="note-contents-gnu" xreflabel="The GNU Project">
        !           206:       <title>The GNU Project</title>
        !           207: 
        !           208:       <para>
        !           209:        Starting with glibc 2.1, the GNU project will be using a single ELF Note
        !           210:        to indicate which GNU operating system and which version of that system
        !           211:        a binary was built for.  The format of that note is:
        !           212:        <variablelist>
        !           213:          <varlistentry>
        !           214:            <term><varname>Name Size</varname></term>
        !           215:            <listitem>4</listitem>
        !           216:          </varlistentry>
        !           217:          <varlistentry>
        !           218:            <term><varname>Desc Size</varname></term>
        !           219:            <listitem>16</listitem>
        !           220:          </varlistentry>
        !           221:          <varlistentry>
        !           222:            <term><varname>Type</varname></term>
        !           223:            <listitem>4-byte integer containing the value <code>0x01</code></listitem>
        !           224:          </varlistentry>
        !           225:          <varlistentry>
        !           226:            <term><varname>Name</varname></term>
        !           227:            <listitem><code>"GNU\0"</code></listitem>
        !           228:          </varlistentry>
        !           229:          <varlistentry>
        !           230:            <term><varname>Desc</varname></term>
        !           231:            <listitem>
        !           232:              Four 4-byte integers containing, in order:
        !           233:              <orderedlist>
        !           234:                <listitem>OS (0 = Linux, 1 = Hurd, 2 = Solaris)</listitem>
        !           235:                <listitem>Major</listitem>
        !           236:                <listitem>Minor</listitem>
        !           237:                <listitem>Teeny</listitem>
        !           238:              </orderedlist>
        !           239:              The major, minor and teeny versions are that of the earliest OS version that supports this ABI.
        !           240:            </listitem>
        !           241:          </varlistentry>
        !           242:        </variablelist>
        !           243:       </para>
        !           244: 
        !           245:       <para>
        !           246:        For more documentation on the GNU C Library's use of ELF notes,
        !           247:        consult the sources:
        !           248:        <ulink url="http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/abi-tags?cvsroot=glibc">abi-tags</ulink>
        !           249:        and
        !           250:        <ulink url="http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/csu/abi-note.S?cvsroot=glibc">csu/abi-note.S</ulink>.
        !           251:       </para>
        !           252:     </sect4>
        !           253:   </sect3>
        !           254:   
        !           255:     <sect3 id="note-creation">
        !           256:       <title>Creating ELF <constant>PT_NOTE</constant> Sections</title>
        !           257: 
        !           258:       <para>
        !           259:        If you're using the GNU binutils 2.8 or greater to create your binaries,
        !           260:        you can generate <constant>PT_NOTE</constant> sections in your final object files.
        !           261:        To create a <constant>PT_NOTE</constant> section, create a section in one of your object
        !           262:        files (for systems which generate <constant>PT_NOTE</constant> entries by default, this
        !           263:        is typically the runtime startup code) with a name starting
        !           264:        with ".note" and having the "allocate" property set.
        !           265:        Put properly formed ELF Notes entries in that section.
        !           266:        When final linking is done, all sections which have names starting
        !           267:        with ".note" and which are marked "allocate" will be put into <constant>PT_NOTE</constant>
        !           268:        sections in the final object file.
        !           269:       </para>
        !           270:       <para>
        !           271:        An example of GNU assembler input which will create a <constant>PT_NOTE</constant> section
        !           272:        during final link is:
        !           273:       </para>
        !           274: <programlisting language="assembler">
        !           275:     .section ".note.ident", "a"
        !           276:     .p2align 2
        !           277:     .long 1f - 0f           # name size (not including padding)
        !           278:     .long 3f - 2f           # desc size (not including padding)
        !           279:     .long 0x01234567        # type
        !           280: 0:  .asciz "NaMe"          # name
        !           281: 1:  .p2align 2
        !           282: 2:  .long 0x76543210        # desc
        !           283:     .long 0x89abcdef
        !           284: 3:  .p2align 2
        !           285: </programlisting>
        !           286: 
        !           287: <para>
        !           288:   That example will create a section called ".note.ident", marked
        !           289:   "allocate" (so that it will be turned into a
        !           290:   <constant>PT_NOTE</constant> section during final link), which
        !           291:   contains a single note.  That note has a <varname>type</varname> of
        !           292:   <code>0x012345678</code>, has the <varname>name</varname>
        !           293:   <code>"NaMe\0"</code>, and has a <varname>desc</varname> value
        !           294:   consisting of two 4-byte integers, <code>0x76543210</code> and
        !           295:   <code>0x89abcdef</code>.
        !           296: </para>
        !           297:     </sect3>
        !           298:     
        !           299:     <sect3 id="netbsd-note">
        !           300:       <title>Creating a NetBSD ELF <constant>PT_NOTE</constant> Section</title>
        !           301:       
        !           302:       <para>
        !           303:        The NetBSD kernel will return ENOEXEC if an ELF binary does not contain
        !           304:        a recognized <constant>PT_NOTE</constant> section. Normally, <filename>crtbegin.c</filename>
        !           305:        contains this section
        !           306:        for native NetBSD applications. The example below creates such a section
        !           307:        on NetBSD/alpha. (Other ports may use slightly different assembler syntax,
        !           308:        but, except for endian variations, they all use the same bits.)
        !           309:       </para>
        !           310: <programlisting language="assembler">
        !           311:         .section ".note.netbsd.ident", "a"
        !           312:         .long   2f-1f
        !           313:         .long   4f-3f
        !           314:         .long   1
        !           315: 1:      .asciz "NetBSD"
        !           316: 2:      .p2align 2
        !           317: 3:      .long   199905
        !           318: 4:      .p2align 2
        !           319: </programlisting>
        !           320:     </sect3>
        !           321:   </sect2>
        !           322: </sect1>
        !           323: </webpage>
        !           324: 

CVSweb <webmaster@jp.NetBSD.org>