Annotation of htdocs/docs/kernel/elf-notes.xml, revision 1.3
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.3 ! martin 8: <config param="cvstag" value="$NetBSD: elf-notes.xml,v 1.2 2007/11/19 00:14:19 martin Exp $"/>
! 9: <config param="rcsdate" value="$Date: 2007/11/19 00:14:19 $"/>
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>
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>
1.3 ! martin 203:
! 204: <para>
! 205: The format of the PaX note is:
! 206:
! 207: <variablelist class="elf-note">
! 208: <varlistentry>
! 209: <term><varname>Name Size</varname></term>
! 210: <listitem>4</listitem>
! 211: </varlistentry>
! 212: <varlistentry>
! 213: <term><varname>Desc Size</varname></term>
! 214: <listitem>4</listitem>
! 215: </varlistentry>
! 216: <varlistentry>
! 217: <term><varname>Type</varname></term>
! 218: <listitem>4-byte integer containing the value <code>0x03</code></listitem>
! 219: </varlistentry>
! 220: <varlistentry>
! 221: <term><varname>Name</varname></term>
! 222: <listitem><code>"PaX\0"</code> (padded to 8 bytes)</listitem>
! 223: </varlistentry>
! 224: <varlistentry>
! 225: <term><varname>Desc</varname></term>
! 226: <listitem>4-byte bitmask with the following bits:
! 227: <segmentedlist>
! 228: <segtitle>Bit</segtitle>
! 229: <segtitle>Meaning<segtitle>
! 230: <?dbhtml list-presentation="table"?>
! 231: <seglistitem>
! 232: <seg><code>0x01</code></seg>
! 233: <seg>Force enable Mprotect</seg>
! 234: </seglistitem>
! 235: <seglistitem>
! 236: <seg><code>0x02</code></seg>
! 237: <seg>Force disable Mprotect</seg>
! 238: </seglistitem>
! 239: <seglistitem>
! 240: <seg><code>0x04</code></seg>
! 241: <seg>Force enable Segvguard</seg>
! 242: </seglistitem>
! 243: <seglistitem>
! 244: <seg><code>0x08</code></seg>
! 245: <seg>Force disable Segvguard</seg>
! 246: </seglistitem>
! 247: <seglistitem>
! 248: <seg><code>0x10</code></seg>
! 249: <seg>Force enable ASLR</seg>
! 250: </seglistitem>
! 251: <seglistitem>
! 252: <seg><code>0x20</code></seg>
! 253: <seg>Force disable ASLR</seg>
! 254: </seglistitem>
! 255: </segmentedlist>
! 256: </listitem>
! 257: </varlistentry>
! 258: </variablelist>
! 259: </para>
! 260:
! 261: <para>
! 262: The format of the NetBSD architecture note is:
! 263:
! 264: <variablelist class="elf-note">
! 265: <varlistentry>
! 266: <term><varname>Name Size</varname></term>
! 267: <listitem>7</listitem>
! 268: </varlistentry>
! 269: <varlistentry>
! 270: <term><varname>Desc Size</varname></term>
! 271: <listitem>variable</listitem>
! 272: </varlistentry>
! 273: <varlistentry>
! 274: <term><varname>Type</varname></term>
! 275: <listitem>4-byte integer containing the value <code>0x05</code></listitem>
! 276: </varlistentry>
! 277: <varlistentry>
! 278: <term><varname>Name</varname></term>
! 279: <listitem><code>"NetBSD\0"</code> (padded to 8 bytes)</listitem>
! 280: </varlistentry>
! 281: <varlistentry>
! 282: <term><varname>Desc</varname></term>
! 283: <listitem>A string describing the architecture the binary was
! 284: compiled for (for example used on ARM to distinguish
! 285: hardware floating point ABI and softfloat)</listitem>
! 286: </varlistentry>
! 287: </variablelist>
! 288: </para>
! 289:
! 290: <para>
! 291: The format of the NetBSD code model note is:
! 292:
! 293: <variablelist class="elf-note">
! 294: <varlistentry>
! 295: <term><varname>Name Size</varname></term>
! 296: <listitem>7</listitem>
! 297: </varlistentry>
! 298: <varlistentry>
! 299: <term><varname>Desc Size</varname></term>
! 300: <listitem>variable</listitem>
! 301: </varlistentry>
! 302: <varlistentry>
! 303: <term><varname>Type</varname></term>
! 304: <listitem>4-byte integer containing the value <code>0x06</code></listitem>
! 305: </varlistentry>
! 306: <varlistentry>
! 307: <term><varname>Name</varname></term>
! 308: <listitem><code>"NetBSD\0"</code> (padded to 8 bytes)</listitem>
! 309: </varlistentry>
! 310: <varlistentry>
! 311: <term><varname>Desc</varname></term>
! 312: <listitem>A string describing the code model the binary was
! 313: compiled for. Used for example on sparc64 to tell
! 314: binaries compiled with -mcmodel=medlow apart from
! 315: standard (-mcmodel=medmid) ones, because the forme
! 316: are not eligible for top-down virtual memory
! 317: layout.</listitem>
! 318: </varlistentry>
! 319: </variablelist>
! 320: </para>
! 321:
1.1 dsieger 322: </sect4>
323:
324: <sect4 id="note-contents-gnu" xreflabel="The GNU Project">
325: <title>The GNU Project</title>
326:
327: <para>
328: Starting with glibc 2.1, the GNU project will be using a single ELF Note
329: to indicate which GNU operating system and which version of that system
330: a binary was built for. The format of that note is:
331: <variablelist>
332: <varlistentry>
333: <term><varname>Name Size</varname></term>
334: <listitem>4</listitem>
335: </varlistentry>
336: <varlistentry>
337: <term><varname>Desc Size</varname></term>
338: <listitem>16</listitem>
339: </varlistentry>
340: <varlistentry>
341: <term><varname>Type</varname></term>
342: <listitem>4-byte integer containing the value <code>0x01</code></listitem>
343: </varlistentry>
344: <varlistentry>
345: <term><varname>Name</varname></term>
346: <listitem><code>"GNU\0"</code></listitem>
347: </varlistentry>
348: <varlistentry>
349: <term><varname>Desc</varname></term>
350: <listitem>
351: Four 4-byte integers containing, in order:
352: <orderedlist>
353: <listitem>OS (0 = Linux, 1 = Hurd, 2 = Solaris)</listitem>
354: <listitem>Major</listitem>
355: <listitem>Minor</listitem>
356: <listitem>Teeny</listitem>
357: </orderedlist>
358: The major, minor and teeny versions are that of the earliest OS version that supports this ABI.
359: </listitem>
360: </varlistentry>
361: </variablelist>
362: </para>
363:
364: <para>
365: For more documentation on the GNU C Library's use of ELF notes,
366: consult the sources:
367: <ulink url="http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/abi-tags?cvsroot=glibc">abi-tags</ulink>
368: and
369: <ulink url="http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/csu/abi-note.S?cvsroot=glibc">csu/abi-note.S</ulink>.
370: </para>
371: </sect4>
372: </sect3>
373:
374: <sect3 id="note-creation">
375: <title>Creating ELF <constant>PT_NOTE</constant> Sections</title>
376:
377: <para>
378: If you're using the GNU binutils 2.8 or greater to create your binaries,
379: you can generate <constant>PT_NOTE</constant> sections in your final object files.
380: To create a <constant>PT_NOTE</constant> section, create a section in one of your object
381: files (for systems which generate <constant>PT_NOTE</constant> 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 <constant>PT_NOTE</constant>
387: sections in the final object file.
388: </para>
389: <para>
390: An example of GNU assembler input which will create a <constant>PT_NOTE</constant> section
391: during final link is:
392: </para>
393: <programlisting language="assembler">
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: </programlisting>
405:
406: <para>
407: That example will create a section called ".note.ident", marked
408: "allocate" (so that it will be turned into a
409: <constant>PT_NOTE</constant> section during final link), which
410: contains a single note. That note has a <varname>type</varname> of
411: <code>0x012345678</code>, has the <varname>name</varname>
412: <code>"NaMe\0"</code>, and has a <varname>desc</varname> value
413: consisting of two 4-byte integers, <code>0x76543210</code> and
414: <code>0x89abcdef</code>.
415: </para>
416: </sect3>
417:
418: <sect3 id="netbsd-note">
419: <title>Creating a NetBSD ELF <constant>PT_NOTE</constant> Section</title>
420:
421: <para>
422: The NetBSD kernel will return ENOEXEC if an ELF binary does not contain
423: a recognized <constant>PT_NOTE</constant> section. Normally, <filename>crtbegin.c</filename>
424: contains this section
425: for native NetBSD applications. The example below creates such a section
1.2 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: </para>
430: <programlisting language="assembler">
1.2 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.2 martin 437: 3: .long 499003600
1.1 dsieger 438: 4: .p2align 2
439: </programlisting>
440: </sect3>
441: </sect2>
442: </sect1>
443: </webpage>
444:
CVSweb <webmaster@jp.NetBSD.org>