elf.5: document FreeBSD ELF notes
ClosedPublic
Actions

Authored by emaste on Mar 6 2020, 12:22 AM.

Details

Reviewers

kib
jkoshy_users.sourceforge.net

Group Reviewers

manpages

Commits

rS359513: elf.5: add definitions of FreeBSD notes

Summary

Need some work on markup still and a few more details

Diff Detail

Repository

rS FreeBSD src repository - subversion

Lint

Lint Not Applicable

Unit

Tests Not Applicable

Event Timeline

emaste created this revision.Mar 6 2020, 12:22 AM

manpages, can you advise how to do appropriate markup for the NT_FREEBSD_* tags?

I'm hoping for something like
NT_FREEBSD_ABI_TAG (OS ABI version)
type: 1
desc: 32-bit integer
Specifies expected ABI version (i.e., __FreeBSD_version)

NT_FREEBSD_NOINIT_TAG
type: 2
desc: ignored
Indicates that crt does not call init.

emaste added a subscriber: manpages.Mar 6 2020, 12:28 AM

jkoshy_users.sourceforge.net accepted this revision.Mar 6 2020, 7:29 AM

jkoshy_users.sourceforge.net added inline comments.

share/man/man5/elf.5
1280 ↗	(On Diff #69247)	"FreeBSD Note sections ..."?
1314 ↗	(On Diff #69247)	Do these have symbolic constants too?

This revision is now accepted and ready to land.Mar 6 2020, 7:29 AM

kib added inline comments.Mar 6 2020, 2:57 PM

share/man/man5/elf.5
1280 ↗	(On Diff #69247)	I agree, it should be made clear that listed notes are defined by FreeBSD. In principle, freebsd binaries can contain vendor-independed notes too, e.g. build id (is it note ?)
1314 ↗	(On Diff #69247)	Point to security(7)
1315 ↗	(On Diff #69247)	Might be reference mmap(2), otherwise it is too cryptic.
1317 ↗	(On Diff #69247)	It might be better to write W+X as 'simultaneously writeable and executable'

emaste added inline comments.Mar 6 2020, 3:21 PM

share/man/man5/elf.5
1280 ↗	(On Diff #69247)	Yes, fair point, but note the existing text above This section holds information in the .Dq Note Section format described below. and in particular this table is about ELF notes in general, not FreeBSD specific. Perhaps another `.Ss` for FreeBSD ELF notes below (where `.Fx defines the following`... is)

emaste mentioned this in rS358891: elf.5: start documenting ELF note sections.Mar 11 2020, 6:15 PM

rebase after committing generic ELF note text.
add bit symbolic names

still need to add @kib's cross references/explanations, but need help with markup

This revision now requires review to proceed.Mar 16 2020, 1:54 PM

emaste marked an inline comment as done.Mar 16 2020, 1:55 PM

emaste added inline comments.

share/man/man5/elf.5
1280 ↗	(On Diff #69247)	And yes the build ID is in a note.
1317 ↗	(On Diff #69247)	The table already does not fit (each row is wrapped to two lines), so I need to figure out how to format this appropriately.

0mp added a subscriber: 0mp.Mar 26 2020, 8:25 PM

0mp added inline comments.

share/man/man5/elf.5
1300 ↗	(On Diff #69566)	I am not sure but please check that `defines` is not interpreted by `.Fx` as a FreeBSD version.

0mp added inline comments.Mar 26 2020, 8:41 PM

share/man/man5/elf.5
1306 ↗	(On Diff #69566)	Trailing whitespace.

@emaste, I've uploaded a (hopefully) improved patch here: https://people.freebsd.org/~0mp/elf.5.patch

I recommend looking at the HTML generated from the manual page. It helps getting the styles right: mandoc -Tlint elf.5 > elf.html && firefox elf.html.

@0mp should the struct elements instead be .Va? That's what's used in stat(2) for the definition of struct stat.

emaste added inline comments.Mar 27 2020, 7:57 PM

share/man/man5/elf.5
1300 ↗	(On Diff #69566)	It seems like not, but I suppose .Fx defines the ... is better anyhow?

In D23982#532450, @emaste wrote:

@0mp should the struct elements instead be .Va? That's what's used in stat(2) for the definition of struct stat.

Hmm, but in stat(2) those names are variables (or members of a struct). Hmmm, why not. .Va seems like a good idea.

(BTW, I'd not use .Sy as it is already used by table headers).