Annotation of htdocs/docs/kernel/elf-notes.xml, revision 1.2
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.2 ! martin 8: <config param="cvstag" value="$NetBSD: elf-notes.xml,v 1.1 2007/06/09 11:33:43 dsieger Exp $"/>
! 9: <config param="rcsdate" value="$Date: 2007/06/09 11:33:43 $"/>
1.1 dsieger 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
1.2 ! martin 307: on NetBSD/sparc. (Other ports may use slightly different assembler syntax,
! 308: for example arm uses %note - since @ starts a comment,
1.1 dsieger 309: but, except for endian variations, they all use the same bits.)
310: </para>
311: <programlisting language="assembler">
1.2 ! martin 312: .section ".note.netbsd.ident", "", @note
1.1 dsieger 313: .long 2f-1f
314: .long 4f-3f
315: .long 1
316: 1: .asciz "NetBSD"
317: 2: .p2align 2
1.2 ! martin 318: 3: .long 499003600
1.1 dsieger 319: 4: .p2align 2
320: </programlisting>
321: </sect3>
322: </sect2>
323: </sect1>
324: </webpage>
325:
CVSweb <webmaster@jp.NetBSD.org>