Squashed 'third_party/elfutils/' content from commit 555e15e
Change-Id: I61cde98949e47e5c8c09c33260de17f30921be79
git-subtree-dir: third_party/elfutils
git-subtree-split: 555e15ebe8bf1eb33d00747173cfc80cc65648a4
diff --git a/doc/elfutils.sgml b/doc/elfutils.sgml
new file mode 100644
index 0000000..d7fea40
--- /dev/null
+++ b/doc/elfutils.sgml
@@ -0,0 +1,444 @@
+<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"[
+<!ENTITY package "<filename>new-bu</filename>">
+]>
+
+<book>
+ <title>New Binutils User's and Reference Manual</title>
+
+ <chapter>
+ <title><filename>libelf</filename> <acronym>ABI</acronym></title>
+
+ <simpara>The <acronym>ABI</acronym> of the
+ <filename>libelf</filename> implemented in the &package; package
+ is following that of Sun's implementation which in turn in derived
+ from the original SysVr4 implementation. There are some
+ extensions over Sun's versions, though, which makes it impossible
+ to replace this implementation with Sun's.</simpara>
+
+ <beginpage>
+
+ <refentry xreflabel="Elf_Data" id="ElfUData">
+ <refnamediv>
+ <refname>Elf_Data</refname>
+ <refpurpose>Descriptor for Data Buffer</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <synopsis>
+#include <libelf.h>
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <simpara>The <structname>Elf_Data</structname> structure is as
+ a descriptor for a data buffer associated with a section.
+ Every data buffer is associated with a specific section (see
+ <!-- xref --><structname>Elf_Scn</structname>).</simpara>
+
+ <simpara>A data buffer is created when reading a file. In
+ this case only a single buffer is present in the section. The
+ user can add as many sections as wanted to a section and they
+ can be retrieved using the <function>elf_getdata</function>
+ and <function>elf_rawdata</function> functions.<!-- xref
+ --></simpara>
+
+ <simpara>The <structname>Elf_Data</structname> structure
+ contains the following members:</simpara>
+
+ <programlisting>
+ void *d_buf
+ Elf_Type d_type
+ size_t d_size
+ off_t d_off
+ size_t d_align
+ unsigned int d_version
+</programlisting>
+
+ <simpara>All of these members can be modified directly by the
+ user. They can be used to resize a section, to change its
+ content or type, and many more tasks. This is also true for
+ the data read from a file. The meaning of each member is as
+ follows:</simpara>
+
+ <variablelist>
+ <varlistentry>
+ <term><structfield>d_buf</structfield></term>
+ <listitem>
+ <simpara>The <structfield>d_buf</structfield> member is
+ the pointer to the buffer with the actual data. When
+ the ELF file was read from a file the first and only
+ data buffer of a section is allocated by the
+ <filename>libelf</filename> library. The user should
+ not try to resize or free this buffer. When the user
+ adds a new data buffer to a section the associated
+ memory block is normally allocated by the user. It is
+ important that the buffer must have a lifetime at least
+ until the ELF file is closed entirely (important when
+ the buffer is allocated on the stack). If the buffer is
+ not allocated on the stack it is the user's
+ responsibility to free the buffer after it is not used
+ anymore. The <structfield>d_buf</structfield> member
+ can contain a null pointer if the data buffer is
+ empty.</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><structfield>d_type</structfield></term>
+ <listitem>
+ <simpara>The <structfield>d_type</structfield>
+ determines how the data of the buffer is interpreted.
+ This type is determined from the section type and must
+ be the same for all data buffers for a section. See
+ <!-- xref --><type>Elf_Type</type> for more information.
+ The <function><link linkend="elfUgetdata"
+ endterm="elfUgetdata.refname"></link></function>
+ function uses this information to convert the data of
+ the buffer between the external form and the form
+ represented to the user and back if necessary.</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><structfield>d_version</structfield></term>
+ <listitem>
+ <simpara>The <structfield>d_version</structfield>
+ contains the ELF version of the file.</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><structfield>d_size</structfield></term>
+ <listitem>
+ <simpara>The <structfield>d_size</structfield> contains
+ the size of the buffer in bytes.</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><structfield>d_off</structfield></term>
+ <listitem>
+ <simpara>The <structfield>d_off</structfield> is the
+ offset into the section in bytes.</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><structfield>d_align</structfield></term>
+ <listitem>
+ <simpara>The <structfield>d_align</structfield> is the
+ address alignment of the section in bytes.</simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ </refentry>
+
+ <beginpage>
+
+ <refentry id="elfUgetdata">
+ <refnamediv>
+ <refname id="elfUgetdata.refname">elf_getdata</refname>
+ <refpurpose>Get washed data of section</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>
+#include <libelf.h>
+</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>Elf_Data *<function>elf_getdata</function></funcdef>
+ <paramdef>Elf_Scn *<parameter>scn</parameter></paramdef>
+ <paramdef>Elf_Data *<parameter>data</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <simpara>The <function>elf_getdata</function> function allows
+ the user to retrieve the data buffers of the section
+ <parameter>scn</parameter>. There can be more than one buffer
+ if the user explicitly added them. When a file is read the
+ <filename>libelf</filename> library creates exactly one data
+ buffer.</simpara>
+
+ <simpara>The first buffer in the list can be obtained by
+ passing a null pointer in the parameter
+ <parameter>data</parameter>. To get the next data buffer the
+ previously returned value must be passed in the
+ <parameter>data</parameter> parameter. If there are no more
+ buffer left in the list a null pointer is returned.</simpara>
+
+ <simpara>If the <parameter>data</parameter> parameter is not a
+ null pointer it must be a descriptor for a buffer
+ associated with the section <parameter>scn</parameter>. If
+ this is not the case a null pointer is returned. To
+ facilitate error handling <function>elf_getdata</function>
+ also returns a null pointer if the <parameter>scn</parameter>
+ parameter is a null pointer.</simpara>
+ </refsect1>
+ </refentry>
+
+ <refentry>
+ <refnamediv>
+ <refname id="elfUupdate.refname">elf_update</refname>
+ <refpurpose>update an ELF descriptor</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>
+#include <libelf.h>
+</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>off_t <function>elf_update</function></funcdef>
+ <paramdef>Elf *<parameter>elf</parameter></paramdef>
+ <paramdef>Elf_Cmd <parameter>cmd</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <simpara>The user is responsible for filling in the following
+ fields in the named data structures:</simpara>
+
+ <table>
+ <title>Fields not set by <function>elf_update</function></title>
+ <tgroup cols="3">
+ <colspec colwidth="90pt">
+ <colspec colwidth="110pt">
+ <thead>
+ <row>
+ <entry>Data Structure</entry>
+ <entry>Member</entry>
+ <entry>Exception</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry morerows="8"><type>Elfxx_Ehdr</type></entry>
+ <entry>e_ident[EI_DATA]</entry>
+ <entry>see below</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>e_type</entry>
+ <!-- <entry morerows="1"></entry> -->
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>e_machine</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>e_version</entry>
+ <entry>see below</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>e_entry</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>e_phoff</entry>
+ <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>e_shoff</entry>
+ <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>e_flags</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>e_shstrndx</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry morerows="7">Elfxx_Phdr</entry>
+ <entry>p_type</entry>
+ <entry morerows="7"></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>p_offset</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>p_vaddr</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>p_paddr</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>p_filesz</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>p_memsz</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>p_flags</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>p_align</entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry morerows="9">Elfxx_Shdr</entry>
+ <entry>sh_name</entry>
+ <entry morerows="3"></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>sh_type</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>sh_flags</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>sh_addr</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>sh_offset</entry>
+ <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>sh_size</entry>
+ <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>sh_link</entry>
+ <!-- <entry morerows="1"></entry> -->
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>sh_info</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>sh_addralign</entry>
+ <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>sh_entsize</entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry morerows="5">Elf_Data</entry>
+ <entry>d_buf</entry>
+ <entry morerows="2"></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>d_type</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>d_size</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>d_off</entry>
+ <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>d_align</entry>
+ <!-- <entry morerows="1"></entry> -->
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>d_version</entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <simpara>Two fields of the ELF header are handled in a special
+ way:</simpara>
+
+ <variablelist>
+ <varlistentry>
+ <term>e_version</term>
+ <listitem>
+ <simpara>The user can set this field to the vvalue for
+ the version to be used. It is an error if the library
+ cannot handle this version. If the field contains the
+ value <symbol>EV_NONE</symbol> the library will fill in
+ its own internal version.</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>e_ident[EI_DATA]</term>
+ <listitem>
+ <simpara>The user should fill in the byte ordering for
+ the file. If the value of the field is
+ <symbol>ELFDATANONE</symbol> the library replaces it
+ with the native byte ordering for the machine.</simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ </refentry>
+ </chapter>
+
+ <chapter>
+ <title><filename>libelf</filename> Internals</title>
+
+ <simpara>Since the binary format handling tools need constant
+ attention since there are always new machines and varients
+ therefore coming out it is important to have the implementation
+ well documented. Only this way extensions can be made in the
+ right places and the mistakes of the past avoided.</simpara>
+ </chapter>
+</book>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omitag:nil
+sgml-shorttag:t
+End:
+-->