Hacker News Reader

Comment by jcranmer | Hacker News Reader

One of the things I've been (very slowly) putting together is a master list of all the references one needs to build a compiler toolchain--such as processor ISA manuals, ABI specifications, language standards, even things like IEEE 754 or DWARF.

While IEEE 754 is an issue because it's not freely available for most people, the only document that has truly stumped me is the ELF specification. From your blog post, it seems like my failure to find the most up-to-date specification is simply because one doesn't exist.

View on HN

Are you familiar with the OSDev wiki? Perhaps their list of links will be helpful:

https://wiki.osdev.org/ELF#External_Links

That wiki's list of links isn't always the most up-to-date.

How often does anyone change the ELF file format, though?

No matter; but that's the most up-to-date list of references I know about.

The ELF format isn't the one that I'm the most concerned about, but for example compressed sections were updated in the past decade. The ABI for x86-64 is out-of-date (actually, the site it links to is now a 404, but my recollection was that was a version around 2013)--missing things like _Float16 rules, DWARF register naming for AMX and APX registers, microarchitecture levels, new relocation types,

The up to date ABI for x86-64 lives at https://gitlab.com/x86-psABIs/x86-64-ABI

I'm aware of that (and peeved that they've got runners set up for the x86-64 ABI but not the i386 ABI, so there's no nice PDF version of the i386 version I can use).

Thank you! This will be very useful. Yes, for C/C++ one needs:

* ISA manual * ELF (generic ABI, psABI (e.g. x86-64-psABI), OSABI) * DWARF * Floating-point * Language standards * Itanium C++ ABI

and probably a few other stuff.

> it seems like my failure to find the most up-to-date specification is simply because one doesn't exist.

While the up-to-date specification is unavailable, hopefully it is not too bad because all essential features have been completed as of 2001:)

RELR is a linker and loader feature, not on the compiler side. Compressed debug sections are a pretty natural extension.

I file things like linkers, loaders, and debuggers into the same bucket as compilers, so all of the ELF extensions are interesting to me, even if compilers directly don't interact with them. I'm also interested in things like the loader-debugger rendezvous interface. Basically any document anyone who touches any project in llvm-project might need to read.

And then there are things like the layout of .gcc_except_table, which are undocumented except for random blog posts.

In case this is of interest, here's an attempt at gathering the references, including random blog posts (as well as articles, documentation, papers, software, and talks), on these topics:

- assembly & ISA (instruction set architecture):

- Arm: https://github.com/MattPD/cpplinks/blob/master/assembly.arm....

- RISC-V: https://github.com/MattPD/cpplinks/blob/master/assembly.risc...

- x86: https://github.com/MattPD/cpplinks/blob/master/assembly.x86....

- debugging: https://github.com/MattPD/cpplinks/blob/master/debugging.md

- debugging: tracing: https://github.com/MattPD/cpplinks/blob/master/debugging.tra...

- executable and object file formats (ELF, Mach-O, PE); debugging data formats (DWARF, PDB): https://github.com/MattPD/cpplinks/blob/master/executables.m...

- linking and loading: https://github.com/MattPD/cpplinks/blob/master/executables.l...

- compilers: https://github.com/MattPD/cpplinks/blob/master/compilers.md

- compilers correctness: https://github.com/MattPD/cpplinks/blob/master/compilers.cor...

freecompilercamp.org has been hijacked.

Removed, thanks!

> even if compilers directly don't interact with them

Essentially they do as they put directives into the asm files to put things in specific sections, to define certain symbol visibility etc all of which depend on the object file format (e.g. a classic BSD a.out file, using a format I called “a.out” in BFD, can’t represent most of that). So the compiler does need to know. And the assembler absolutely needs to know since it generates object files!

So yes an a.out file can be an ELF file (always is on Linux) or could be an “a.out” file. Sorry! In retrospect I should have called that format “bsd”.

> there are things like the layout of .gcc_except_table, which are undocumented except for random blog posts.

The way I dealt with it was write an ELF dumper for the tables, and then run various C++ code snippets through g++ and look at how the tables were constructed.

You could just have called objdump — that’s what it’s for.

I like mine better :-/

The same executable will also detect and dump Elf, Mach, MScoff, and OMF object files.

Besides, one doesn't learn anything about how to decode the format by using an existing tool that presents it in decoded form.

I wish their was a better option, but people can at least get the IEEE 754 standard by putting the DOI for it into sci-hub.

Are you going to make this list of resources available online or is it for personal consumption only?

So far, the list of resources is a collection of PDFs I've downloaded plus a script to download the latest version of every relevant specification. (Although it does seem that Intel likes breaking its links to the latest ISA PDF every now and then). I don't have a great solution for things that are essentially web-only pages, which is how the Itanium ABI is handled (and unlike C, C++ makes it hard to find the relevant working draft copies, instead preferring to use the HTML-based https://eel.is/c++draft for that).

I probably will make it publicly available eventually, it just hasn't been a priority for me.

The most widespread standard for archiving collections of web pages is WARC - it is a publicly available ISO standard so it's very future-proof. WACZ (https://specs.webrecorder.net/wacz/1.1.1/) is a more recent take that is basically zipped WARC + index + metadata, and Internet Archive can generate them when archiving is requested (https://web.archive.org/save/).

In addition to that, I would also suggest using https://zimit.kiwix.org. It's a very compact representation that has full text index support for convenient searching, the format is open and documented, and first-party readers are available on all major platforms. And for stuff like this, Kiwix might actually be interested in adding them to their official library at https://library.kiwix.org/ if you contact them.

Reply on news.ycombinator.com