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>