Re: ABI document

["Vivek Das Mohapatra" <vivek@collabora.com>]

[-- Attachment #1: Type: text/plain, Size: 317 bytes --]

On Fri, 14 Aug 2020, Mark Wielaard wrote:

> Lets stick to plain text for now. Just so we have something that can
> simply be converted into anything. Best to start with content before
> worrying about format IMHO.

I've made a preliminary stab at documenting the non-arch/OS specific
ELF GNU extensions I could find.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-diff; name=0001-Document-GNU-extensions-to-ELF-related-to-loading-an.patch, Size: 11035 bytes --]

From ab7fc99345186ed0732a58f62b1082eeee09ff12 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vivek=20Das=C2=A0Mohapatra?= <vivek@collabora.com>
Date: Thu, 27 Aug 2020 17:39:17 +0100
Subject: [PATCH] Document GNU extensions to ELF related to loading and linking

Program header related:

PT_GNU_EH_FRAME
PT_SUNW_EH_FRAME
PT_GNU_STACK
PT_GNU_RELRO
PT_GNU_PROPERTY
  GNU_PROPERTY_STACK_SIZE
  GNU_PROPERTY_NO_COPY_ON_PROTECTED
  GNU_PROPERTY_LOPROC
  GNU_PROPERTY_HIPROC
  GNU_PROPERTY_LOUSER
  GNU_PROPERTY_HIUSER

PT_DYNAMIC entries
  DT_GNU_FLAGS_1 (DF_GNU_1_UNIQUE)
  DT_GNU_PRELINKED
  DT_GNU_CONFLICTSZ
  DT_GNU_LIBLISTSZ
  DT_GNU_HASH
  DT_GNU_CONFLICT
  DT_GNU_LIBLIST

Section header related

SHT_GNU_INCREMENTAL_INPUTS
SHT_GNU_ATTRIBUTES
SHT_GNU_HASH
SHT_GNU_LIBLIST
SHT_GNU_verdef
SHT_GNU_verneed
SHT_GNU_versym

SHT_NOTE extensions
  NT_GNU_ABI_TAG
    GNU_ABI_TAG_LINUX
    GNU_ABI_TAG_HURD
    GNU_ABI_TAG_SOLARIS
    GNU_ABI_TAG_FREEBSD
    GNU_ABI_TAG_NETBSD
    GNU_ABI_TAG_SYLLABLE
    GNU_ABI_TAG_NACL

  NT_GNU_HWCAP
  NT_GNU_BUILD_ID
  NT_GNU_GOLD_VERSION
  NT_GNU_PROPERTY_TYPE_0
---
 program-loading-and-dynamic-linking.txt | 272 ++++++++++++++++++++++++
 1 file changed, 272 insertions(+)
 create mode 100644 program-loading-and-dynamic-linking.txt

diff --git a/program-loading-and-dynamic-linking.txt b/program-loading-and-dynamic-linking.txt
new file mode 100644
index 0000000..751eaca
--- /dev/null
+++ b/program-loading-and-dynamic-linking.txt
@@ -0,0 +1,272 @@
+Program Headers
+===============
+
+These are GNU extended program header type values: They are typically
+found in ElfW(Phdr).p_type.
+
+PT_GNU_EH_FRAME  0x6474e550
+PT_SUNW_EH_FRAME 0x6474e550
+
+  Segment contains the EH_FRAME_HDR section (stack frame unwind information)
+
+  PT_SUNW_EH_FRAME is used by a non-GNU implementation for the same purpose,
+  and has the same value (although this does not imply compatible contents).
+
+PT_GNU_STACK     0x6474e551
+
+  The p_flags member of this ElfW(Phdr) structure apply to the stack.
+
+  If present AND p_flags DOES NOT contain PF_X (0x1) then the stack
+  should _not_ be executable.
+
+  Otherwise the stack is executable (the default).
+
+PT_GNU_RELRO     0x6474e552
+
+  The specified segment should be made read-only once run-time linking
+  has completed.
+
+PT_GNU_PROPERTY  0x6474e553
+
+  The Linux kernel uses this program header to locate the
+  .note.gnu.property section.
+
+  If there is a program property that requires the kernel to perform
+  some action before loading and ELF file (eg AArch64 BTI or intel CET)
+  then this header MUST be present.
+
+  The contents are laid out as follows:
+
+  Field      | Length   | Contents
+  n_namsz    | 4        | 4
+  n_descsz   | 4        | Size of n_desc (4 byte int, processor format)
+  n_type     | 4        | NT_GNU_PROPERTY_TYPE_0 (0x5)
+  n_name     | 4        | GNU\0
+  n_desc     | n_descsz | property array
+
+  Each element of n_desc, in turn is:
+
+  typedef struct {
+    Elf_Word pr_type;
+    Elf_Word pr_datasz;
+    unsigned char pr_data[PR_DATASZ];
+    unsigned char pr_padding[PR_PADDING];
+  } Elf_Prop;
+
+  Properties are sorted in ascending order of pr_type;
+
+  pr_data is aligned to 4 bytes in 32-bit objects and 8 bytes in 64-bit ones.
+
+  Defined properties are:
+
+  GNU_PROPERTY_STACK_SIZE  0x1
+
+  A native format & size integer specifying the minimum stack size.
+  The linker should pick the highest instance of this from all relocatable
+  objects in the link chain and ensure the stack is at least this big.
+
+  GNU_PROPERTY_NO_COPY_ON_PROTECTED 0x2
+
+  The linker should treat protected data symbol as defined locally at
+  run-time and copy this property to the output share object.
+
+  The linker should add this property to the output share object if
+  any protected symbol is expected to be defined locally at run-time.
+
+  The run-time loader should disallow copy relocations against protected
+  data symbols defined such objects.
+
+  This type has a PR_DATASZ of 0.
+
+  GNU_PROPERTY_LOPROC  0xc0000000
+  GNU_PROPERTY_HIPROC  0xdfffffff
+
+  Reserved for processor-specific values.
+
+  GNU_PROPERTY_LOUSER   0xe0000000
+  GNU_PROPERTY_HIUSER   0xffffffff
+
+  Reserved for application specific values.
+
+There are further extensions to p_type but currently they are all
+architecture specific and will be documented in the relevant ABIs.
+
+Dynamic segment extensions (PT_DYNAMIC entries)
+===============================================
+
+The following types within PT_DYNAMIC are GNU extensions:
+The values are typically found in the ElfW(Dyn).d_tag member.
+
+DT_GNU_FLAGS_1    0x6ffffdf4
+
+  Similar to DT_FLAGS and DT_FLAGS_1, but DT_FLAGS is generic and
+  the DT_FLAGS_1 bit mask has been exhausted (last bit claimed by Solaris).
+
+  Currently supports the following flag bit(s) in its d_val value:
+
+  DF_GNU_1_UNIQUE
+
+  This flag bit indicates that the library should be loaded at most once
+  across all namespaces unless a standalone copy is explicitly requested.
+
+  Some background:
+
+  By default libraries and all their dependencies are loaded into a single
+  namespace or link-map (LM_ID_BASE) - this applies to libraries loaded by
+  ld.so when a program starts, and to those loaded later by dlopen(3).
+
+  glibc implements a dynamic loading extension - dlmopen(3) which is similar
+  to dlopen(3) but can load libraries into secondary namespaces, each of
+  which has its own private link map.
+
+  Libraries in these namespaces are NOT used by the linker to resolve
+  symbols for one another: A library in namespaces 2 (for example)
+  will not use symbols or libraries from any other namespace, nor will it
+  be used to satisfy symbol lookups from libraries in those namespaces.
+
+  This mechanism is the basis for isolation of LD_AUDIT libraries (for example).
+
+  While this is generally desirable some libraries do not behave well under these
+  conditions - in particular libc (malloc/free get upset when they interact with
+  independent copies of themselves since they have no knowledge of one another's
+  memory accounting) and libpthread (which tends to deadlock of two different
+  namespaces attempt to initialise threadsafe locking). DF_GNU_1_UNIQUE is used to
+  mark such libraries so that when they are loaded only one copy (which resides in
+  LM_ID_BASE) is mapped, and all namespaces use that copy (unless such sharing is
+  explicitly suppressed, such as for LD_AUDIT libraries).
+
+  This behaviour can always be explicitly overridden by the caller of dlmopen(3).
+
+DT_GNU_PRELINKED  0x6ffffdf5
+
+  The d_val field contains a time_t value giving the UTC time at which the
+  object was (pre)linked.
+
+DT_GNU_CONFLICTSZ 0x6ffffdf6
+
+  Used in prelinked objects.
+  d_val contains the size of the conflict segment.
+
+DT_GNU_LIBLISTSZ  0x6ffffdf7
+
+  Used in prelinked objects.
+  d_val contains the size of the library list.
+
+DT_GNU_HASH       0x6ffffef5
+
+  The d_ptr value gives the location of the GNU style symbol hash table.
+
+DT_GNU_CONFLICT   0x6ffffef8
+
+  Used in prelinked objects.
+  The d_ptr value gives the location of the conflict segment.
+  This will contain an array of ElfW(Rela) structs.
+
+  If DT_GNU_LIBLIST matches the library searchlist after loading
+  then these relocation records are replayed immediately after
+  run-time loading.
+
+DT_GNU_LIBLIST    0x6ffffef9
+
+  Used in prelinked objects.
+  The d_ptr value gives the location of the ElfW(Lib) array giving the
+  SONAME, checksum and timestamp or each library encountered at prelink time.
+
+  This is used to check that all required prelinked libraries are still
+  present, loaded, and have the correct checksums at runtime.
+
+Section Headers
+===============
+
+The GNU extensions to section header type values.
+Typically found in ElfW(Shdr).sh_type.
+
+SHT_GNU_INCREMENTAL_INPUTS 0x6fff4700
+
+  The section should be named ".gnu_incremental_inputs".
+  Currently used for incremental linking by gold.
+
+SHT_GNU_ATTRIBUTES         0x6ffffff5
+
+  GNU specific program attributes, sh_size bytes at sh_offset into the file.
+
+  The first byte is the version of the attribute spec: Currently only 'A'
+  is defined. Each attribute is stored as:
+
+  - len:  4 byte integer in native format (total attribute length)
+  - data: (len - 4) bytes of attribute data
+    - starting with a \0 terminated name
+    - at least 6 bytes of tag-byte+value
+      - a tag byte
+      - a 4 byte native integer size (including the tag byte and the size itself)
+        - if the tag is 2 or 3: a LEB128 encoded value stored in the remaining space
+      - DOCUMENTME: possibly some remaining attribute bytes
+
+SHT_GNU_HASH               0x6ffffff6
+
+SHT_GNU_LIBLIST            0x6ffffff7
+
+SHT_GNU_verdef             0x6ffffffd
+
+SHT_GNU_verneed            0x6ffffffe
+
+SHT_GNU_versym             0x6fffffff
+
+Note section descriptors (SHT_NOTE extensions)
+==============================================
+
+These Note descriptor types are GNU extensions
+Found in the type field of the ELF note layout.
+
+NT_GNU_ABI_TAG         1
+
+  Use to indicate kernel type and minimum kernel version:
+  Section must be named ".note.ABI-tag"
+
+  The name field (namesz/name) contains the string "GNU".
+
+  The descsz field must be at least 16,
+  The first 16 bytes of the desc [aka descdata] field are as follows:
+
+  The first 4 byte word is a native integer indicating the kernel type:
+  GNU_ABI_TAG_LINUX     0
+  GNU_ABI_TAG_HURD      1
+  GNU_ABI_TAG_SOLARIS   2
+  GNU_ABI_TAG_FREEBSD   3
+  GNU_ABI_TAG_NETBSD    4
+  GNU_ABI_TAG_SYLLABLE  5
+  GNU_ABI_TAG_NACL      6
+
+  The second, third, and fourth 4-byte words of the desc field contain the earliest
+  compatible kernel version.
+
+  For example, if the 3 words are 2, 2, and 5, this signifies a 2.2.5 kernel.
+
+NT_GNU_HWCAP           2
+
+  The first 4 bytes are a native integer giving the number of capabilities.
+
+  The next 4 bytes give the bitmask of enabled capabilities.
+
+  The remainder is a packed array of:
+  [  1 byte ][ N bytes                ]
+  [ TESTBIT ][ \0 terminated cap name ]
+
+NT_GNU_BUILD_ID        3
+
+  descsz bytes of build-id data.
+  Typically presented as a hex string.
+
+NT_GNU_GOLD_VERSION    4
+
+  Up to descsz of [printable] gold version string bytes.
+
+NT_GNU_PROPERTY_TYPE_0 5
+
+  32 or 64 bit aligned (matching the architecture) bytes of data.
+  Each entry within this data blob consists of:
+
+  4 bytes, a native integer giving the subtype.
+  4 bytes, a native integer giving the size of the entry
+
+  See PT_GNU_PROPERTY and/architecture specific ABIs for details.
-- 
2.20.1