[erlang-questions] Fwd: Is there a good source for documentation on BEAM?

[Richard O'Keefe]

On 7/05/2012, at 8:47 PM, Joe Armstrong wrote:

> ---------- Forwarded message ----------
> From: Joe Armstrong <erlang@REDACTED>
> Date: Mon, May 7, 2012 at 10:46 AM
> Subject: Re: [erlang-questions] Is there a good source for
> documentation on BEAM?
> To: Jonathan Coveney <jcoveney@REDACTED>
> 
> 
> Hi,
> 
> I did start writing a description but it's not very complete.
> 
> This is on my list of things-to-do-one-day-when-you-get-time
> 
>   See http://dl.dropbox.com/u/4764922/beam.pdf
> 
> If there is any interest I could up the priority :-)
> 
> /Joe

I would have expected it to be a matter of personal and
professional pride that 
One reason that several of my EEPs and so on never got model
implementations is that the BEAM instructions have less than
a 10th of the documentation that the WAM instructions had at
Quintus.  It does seem clear that the Erlang/OTP team are
much better programmers than Quintus were, because whenever
we forgot to document some detail of an instruction, someone
was sure to get it wrong and new builds would start crashing
horribly.  It's also a reason I've never contributed at a low
level to SWI Prolog.

Two of the best documented abstract instruction sets I've seen
are Icon (there's a whole book about it) and Lua (there's a
document someone wrote with nearly a page per instruction; if
I could bring myself to _care_ about Lua I could start writing
extensions for it tomorrow).  Since Hassan Aït-Kaci wrote his
little book about the WAM, that counts as well documented too,
except of course that I doubt anyone actually follows it all
that closely, Quintus certainly departed from it.  (And yes of
course's there's the Java VM book too; I don't suppose it's a
coïncidence that Tim Lindholm worked at Quintus and times on
the WAM.)

Looking at that document of yours, Joe,
(a) Out of 8 pages, only 5 are actually about the BEAM.
(b) We learn only at the end of those 5 pages that there are
really TWO different things called BEAM:
	- the 'high level abstract instructions' generated
	  by the compiler, which is pretty stable, and
	- the 'internal form' meant for execution, generated
	  by the loader, which 'has changed many times'.
No *wonder* I failed to learn about the BEAM by reading the
emulator code and trying to match what I saw there against
the "instructions" I saw in the .S files.
(c) The document begins in the middle.  The beginning is
the *architecture*.  Given the architecture, a lot of the
instructions become much easier to understand.
(d) The document is very obviously a draft, so there's not
much more it's fair to say at the moment.

With there being two "BEAM"s, there need to be two manuals.
"External BEAM", quite full, for people working on tools that
generate, parse, or otherwise manipulate that kind of code.
"Internal BEAM", taking an external BEAM background and
architectural understanding for granted, that tells people
working on the loader, emulator, HiPE, &c what they need to
know.

Since the Erlang/OTP team and HiPE teams have evidently
managed without the "Internal BEAM" document, the
"External BEAM" document is the priority.