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

[Anthony Ramine]

Couldn't some of the bootstrap Perl scripts like beam_makeops and make_tables be
rewritten and documented in Erlang? I think it would make things more obvious if
they were not obscure Perl scripts without comments. Furthermore it would make
Erlang/OTP eat more of its own dog food.

The only thing that would need to be changed with regard to the bootstrap itself
is that their output would have to be versioned just as the erts/preloaded/ BEAM
files. A new command should also be added to otp_build to update them.

Some of these generated files are:

	beam_tr_funcs.h
	beam_pred_funcs.h
	beam_hot.h
	beam_cold.h
	beam_opcodes.c
	beam_opcodes.h
	beam_opcodes.erl
	beam_opcodes.hrl
	erl_am.c
	erl_bif_table.c
	erl_bif_wrap.c
	erl_pbifs.c
	erl_atom_table.h
	erl_bif_table.h

There may be an obvious reason for them not to be generated by Erlang itself but
I'm not aware of it.

Regards.

--
Anthony Ramine

Le 9 mai 2012 à 01:58, Richard O'Keefe a écrit :

> Let me illustrate the Icon approach by showing you a fragment of the
> micro-BEAM I wrote to get the performance numbers in the frames proposal.
> (The whole thing is fragmentary.)
> 
> ...
> @i
> max src, snd, dst
> @d
> dst := max(src, snd)
> 
> This computes the maximum using the micro-Erlang term ordering.
> If src and snd are tagged immediate integers the comparison is
> done inline; the compare() function is called otherwise.
> @c
>    T = @src;
>    U = @snd;
>    @dst = cmp(T, >, U) ? T : U;
>    @step;
> @e
> ...
> @i
> check_record src, size, const
> @d
> Type test.
> 
> Fail unless src is tagged as a pointer to a tuple or frame,
> the first word it points to is size, and the second is the
> const (which must be an atom, but we don't check that).
> Used for record matching.
> @c
>    T = @src;
>    if (!is_tuple(T))                   @fail "is_record"; else
>    if (FIELD(T, TUP_TAG, 0) != @size)  @fail "is_record"; else
>    if (FIELD(T, TUP_TAG, 1) != @const) @fail "is_record"; else
>    @step;
> @e
> ...
> There is a preprocessor written in AWK that turns this into
> several C files.  One of them is the emulator cases.  For
> the check_record instruction you get
> 
> #line 75 "frame.master"
>        case CHECK_RECORD:
> #line 76 "frame.master"
>            T = reg[(int)P[1]];
> #line 77 "frame.master"
>            if (!is_tuple(T))
>               P = failure, operation = "is_record"; else
> #line 78 "frame.master"
>            if (FIELD(T, TUP_TAG, 0) != 4)
> 	       P = failure, operation = "is_record"; else
> #line 79 "frame.master"
>            if (FIELD(T, TUP_TAG, 1) != P[3])
> 	       P = failure, operation = "is_record"; else
> #line 80 "frame.master"
>            P += 4;
>            break;
> 
> where I've broken the long lines (the preprocessor doesn't).
> The #line directives are option.
> 
> @i introduces an instruction; the next line is a template
> for it saying what the operands are.
> @d introduces the description for people.
> @c introduces the code.  In it, various built-in @macros
> are expanded.
> 
> One advantage of doing it this way is that by using
> @step to update the PC I *cannot* get the offset wrong;
> the preprocessor counted the operands and their sizes
> for me.  Similarly, what I write has *no* operand numbers;
> the preprocessor counted those, and supplies all necessary
> casts as well.  I can shuffle operands around (in @i)
> without revising the code (in @c), and have.
> 
> It wouldn't be too hard to write another preprocessor that
> built some kind of documentation (HTML would probably be
> easiest) out of this, but since this was an experiment,
> it didn't seem worth while.
> 
> Why did I write the preprocessor?
> Well, to be honest, the first draft didn't use one.
> I got a bit sick of debugging, and wrote the preprocessor
> (based on vague memories of Icon) to eliminate a class of
> errors.  It turned out to be _easier_ to develop a
> documented emulator than an undocumented one.
> 
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions