Re: [PATCH] elf(5): document notes

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

Hi Mike,

On 11/17/2016 09:59 PM, Mike Frysinger wrote:
> This is a rough first pass 

So, I'm not quite sure what you hope for here. At best, I'll have
time for some language feedback, but I'll pretty much trust you
on technical detail.

> for documenting the Elf{32,64}_Nhdr structure,
> the sections/segments that contain notes, and how to interpret them.  I've
> been lazy and only included the GNU extensions here, 

Any chance you include the non-GNU stuff also? Or, failing that,
some clear statements at appropriate points about what is not 
documented.

> especially as others
> are not defined in the elf.h header file as shipped by glibc.
> 
> I've mostly used binutils, glibc, and breakpad as sources of data for
> these fields.

Okay. A few comments below.

> Signed-off-by: Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>
> ---
> I'm sure there will be feedback on word smithing, so I didn't try too hard :).
> 
>  man5/elf.5 | 272 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 262 insertions(+), 10 deletions(-)
> 
> diff --git a/man5/elf.5 b/man5/elf.5
> index 2e731f2e4094..66d3bde9daf6 100644
> --- a/man5/elf.5
> +++ b/man5/elf.5
> @@ -708,7 +708,7 @@ However it may not occur more than once in a file.
>  If it is present, it must precede any loadable segment entry.
>  .TP
>  .BR PT_NOTE
> -The array element specifies the location and size for auxiliary information.
> +The array element specifies the location of notes (ElfN_Nhdr).
>  .TP
>  .BR PT_SHLIB
>  This segment type is reserved but has unspecified semantics.
> @@ -970,7 +970,7 @@ An object file may
>  have only one dynamic section.
>  .TP
>  .BR SHT_NOTE
> -This section holds information that marks the file in some way.
> +This section holds notes (ElfN_Nhdr).
>  .TP
>  .BR SHT_NOBITS
>  A section of this type occupies no space in the file but otherwise
> @@ -1281,17 +1281,31 @@ This section is of type
>  No attribute types are used.
>  .TP
>  .IR .note
> -This section holds information in the
> -"Note Section"
> -format.
> +This section holds various notes.
>  This section is of type
>  .BR SHT_NOTE .
>  No attribute types are used.
> -OpenBSD
> -native executables usually contain a
> -.I .note.openbsd.ident
> -section to identify themselves, for the kernel to bypass any compatibility
> -ELF binary emulation tests when loading the file.
> +.TP
> +.IR .note.ABI-tag
> +This section is used to declare the expected runtime ABI of the ELF.
> +It may include the OS and its runtime versions.

s/OS/operating system/

Probably this needs to be even clearer. "operating system name"? 

> +This section is of type
> +.BR SHT_NOTE .
> +The only attribute used is
> +.BR SHF_ALLOC .
> +.TP
> +.IR .note.gnu.build-id
> +This section is used to hold an ID that uniquely identifies the contents of the
> +ELF.
> +Different files with the same build ID should contain the same executable
> +content.
> +See the
> +.IR \-\-build\-id
> +option to the GNU linker (\fBld\fR (1)) for more details.
> +This section is of type
> +.BR SHT_NOTE .
> +The only attribute used is
> +.BR SHF_ALLOC .
>  .TP
>  .IR .note.GNU-stack
>  This section is used in Linux object files for declaring stack attributes.
> @@ -1302,6 +1316,11 @@ The only attribute used is
>  This indicates to the GNU linker that the object file requires an
>  executable stack.
>  .TP
> +.IR .note.openbsd.ident
> +OpenBSD native executables usually contain this section to identify themselves
> +so the kernel can bypass any compatibility ELF binary emulation tests when
> +loading the file.
> +.TP
>  .IR .plt
>  This section holds the procedure linkage table.
>  This section is of type
> @@ -1801,6 +1820,239 @@ Array containing all the dynamic structures in the
>  .I .dynamic
>  section.
>  This is automatically populated by the linker.
> +.\"
> +.SS Notes (Nhdr)
> +ELF notes allow for appending arbitrary information for the system to use.
> +They are largely used by core files (\fIe_type\fR of \fIET_CORE\fR),
> +but many projects define their own set of extensions.

What are "projects" in this context? (Naming one or two
examples in the text might be helpful.)

> +
> +Note sections contain a series of notes (see the structs below).
> +Each note is followed by the name field (whose length is defined in
> +\fIn_namesz\fR) and then by the desc field (whose length is defined in
> +\fIn_descsz\fR).

I think this could be a little clearer. I presume that the way things look is

     struct {} Nhdr
     <name>\0
     <desc>\0

?

Maybe shos something like that in the text?

> +Niether field is defined in the note struct due to their arbitrary lengths.

Neither...

> +
> +Keep in mind that the interpretation of
> +.I n_type
> +depends on the namespace defined by the
> +.I n_namesz
> +field.
> +After, of course, whether the ELF image has been determined to be a core.

I can't understand that last sentence...

> +.in +4n
> +.nf
> +
> +typedef struct {
> +    Elf32_Word n_namesz;
> +    Elf32_Word n_descsz;
> +    Elf32_Word n_type;
> +} Elf32_Nhdr;
> +.fi
> +.in
> +.in +4n
> +.nf
> +
> +typedef struct {
> +    Elf64_Word n_namesz;
> +    Elf64_Word n_descsz;
> +    Elf64_Word n_type;
> +} Elf64_Nhdr;
> +.fi
> +.in
> +.TP \n[l1_indent]
> +.IR n_namesz
> +The length of the name field in bytes.
> +The contents will immediately follow this note in memory.
> +The name will contain a null terminating byte.

s/will contain a null terminating byte/is null terminated/

> +e.g. If the name is "GNU", then

s/e.g. If/For example, if/

> +.I n_namesz
> +will be set to 4.
> +.TP
> +.IR n_descsz
> +The length of the desc field in bytes.
> +The contents will immediately follow the name field in memory.
> +.TP
> +.IR n_type
> +Depending on the value of the name field, this member may have any of the
> +following values:
> +.RS \n[l1_indent]
> +.TP 5
> +.B Core files (e_type = ET_CORE)
> +Notes used by all core files.
> +These are highly OS or architecture specific and often close coordination

s/OS/operating system/

> +with debuggers.

Some word(s) (a verb?) are messing in the last half of the preceding
sentence.

> +.RS
> +.TP 21
> +.PD 0
> +.B NT_PRSTATUS
> +prstatus struct
> +.TP
> +.B NT_FPREGSET
> +fpregset struct
> +.TP
> +.B NT_PRPSINFO
> +prpsinfo struct
> +.TP
> +.B NT_PRXREG
> +prxregset struct
> +.TP
> +.B NT_TASKSTRUCT
> +task structure
> +.TP
> +.B NT_PLATFORM
> +String from sysinfo(SI_PLATFORM)
> +.TP
> +.B NT_AUXV
> +auxv array
> +.TP
> +.B NT_GWINDOWS
> +gwindows struct
> +.TP
> +.B NT_ASRS
> +asrset struct
> +.TP
> +.B NT_PSTATUS
> +pstatus struct
> +.TP
> +.B NT_PSINFO
> +psinfo struct
> +.TP
> +.B NT_PRCRED
> +prcred struct
> +.TP
> +.B NT_UTSNAME
> +utsname struct
> +.TP
> +.B NT_LWPSTATUS
> +lwpstatus struct
> +.TP
> +.B NT_LWPSINFO
> +lwpinfo struct
> +.TP
> +.B NT_PRFPXREG
> +fprxregset struct
> +.TP
> +.B NT_SIGINFO
> +siginfo_t (size might increase over time)
> +.TP
> +.B NT_FILE
> +Contains information about mapped files
> +.TP
> +.B NT_PRXFPREG
> +user_fxsr_struct
> +.TP
> +.B NT_PPC_VMX
> +PowerPC Altivec/VMX registers
> +.TP
> +.B NT_PPC_SPE
> +PowerPC SPE/EVR registers
> +.TP
> +.B NT_PPC_VSX
> +PowerPC VSX registers
> +.TP
> +.B NT_386_TLS
> +i386 TLS slots (struct user_desc)
> +.TP
> +.B NT_386_IOPERM
> +x86 io permission bitmap (1=deny)
> +.TP
> +.B NT_X86_XSTATE
> +x86 extended state using xsave
> +.TP
> +.B NT_S390_HIGH_GPRS
> +s390 upper register halves
> +.TP
> +.B NT_S390_TIMER
> +s390 timer register
> +.TP
> +.B NT_S390_TODCMP
> +s390 TOD clock comparator register

TOD? Write this in full. "Time of day"?

> +.TP
> +.B NT_S390_TODPREG
> +s390 TOD programmable register

See above comment.

> +.TP
> +.B NT_S390_CTRS
> +s390 control registers
> +.TP
> +.B NT_S390_PREFIX
> +s390 prefix register
> +.TP
> +.B NT_S390_LAST_BREAK
> +s390 breaking event address
> +.TP
> +.B NT_S390_SYSTEM_CALL
> +s390 system call restart data
> +.TP
> +.B NT_S390_TDB
> +s390 transaction diagnostic block
> +.TP
> +.B NT_ARM_VFP
> +ARM VFP/NEON registers
> +.TP
> +.B NT_ARM_TLS
> +ARM TLS register
> +.TP
> +.B NT_ARM_HW_BREAK
> +ARM hardware breakpoint registers
> +.TP
> +.B NT_ARM_HW_WATCH
> +ARM hardware watchpoint registers
> +.TP
> +.B NT_ARM_SYSTEM_CALL
> +ARM system call number
> +.PD
> +.RE
> +
> +.TP
> +.B n_name = GNU
> +Extensions used by the GNU toolchain.

s/toolchain/tool chain/

> +.RS
> +.TP 21
> +.PD 0
> +.B NT_GNU_ABI_TAG
> +OS ABI information.
> +The desc field will be 4 words:
> +  word 0: OS descriptor (\fBELF_NOTE_OS_LINUX\fR, \fBELF_NOTE_OS_GNU\fR, etc...)
> +  word 1: major version of the ABI
> +  word 2: minor version of the ABI
> +  word 3: subminor version of the ABI
> +.TP
> +.B NT_GNU_HWCAP
> +Synthetic hwcap information.
> +The desc field begins with two words:
> +  word 0: number of entries
> +  word 1: bitmask of enabled entries
> +.br

Replace preceding line with a blank line.

> +Then follow variable-length entries, one byte followed by a null terminated

s/null /null-/

> +hwcap name string.
> +The byte gives the bit number to test if enabled, (1U << bit) & bitmask.
> +.TP
> +.B NT_GNU_BUILD_ID
> +Unique build ID as generated by GNU ld's \fI--build-id\fR.
> +The desc consists of any nonzero number of bytes.
> +.TP
> +.B NT_GNU_GOLD_VERSION
> +The desc contains the GNU Gold linker version used.
> +.PD
> +.RE
> +
> +.TP
> +.B Unknown system
> +The fallback set of note types when the namespace is unknown.
> +Usually the name field will be omitted (i.e.
> +.B n_namesz
> +will be set to 0).
> +.RS
> +.TP 21
> +.PD 0
> +.B NT_VERSION
> +A version string of some sort.
> +.TP
> +.B NT_ARCH
> +Architecture information.
> +.PD
> +.RE
> +
> +.RE
>  .SH NOTES
>  .\" OpenBSD
>  .\" ELF support first appeared in
> 

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html