Annotation of htdocs/docs/kernel/elf-notes.xml, revision 1.8
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.8 ! martin 8: <config param="cvstag" value="$NetBSD: elf-notes.xml,v 1.7 2013/11/06 16:35:58 martin Exp $"/>
! 9: <config param="rcsdate" value="$Date: 2013/11/06 16:35:58 $"/>
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>
1.7 martin 150:
1.6 martin 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.8 ! martin 306: The Code Model Note encodes code model details.</para>
1.6 martin 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>