There are a handful of opcodes which are not valid in ABC files, but which are used internally in AVM. At the time of writing this bug, they are: lix8 lix16 callsuperid callinterface findpropglobalstrict findpropglobal restargc restarg On the one hand, the benefits of documenting them in the AVM spec is that it provides a framework for specifying their behavior, which aids implementation and testing. On the other hand, a possible drawback is that more may be added without any ABC version rev, and the supported set may be dropped also without any version rev. If this churn is unwanted in the AVM spec then we should find a new home or chapter for them. On the third hand (Lars, are you listening?) there are internal operations which do not have bytecodes, such as ToInt32, which require specification and which need to be mentioned in the specs for existing bytecodes. Internal bytecodes are not much different than these. Bug 693249 makes the case for specifying internal operations.
My gut feeling is that the internal bytecodes and the primitive subroutines are different cases that want different handling: - Internal bytecodes get documented but in a different spec: the documentation is essential for effective VM work but we want to make it clear that the bytecodes can be removed or changed arbitrarily in the future and are not available externally. So in addition to doc/bytecode there might be doc/internal-bytecode. We would not worry about publishing a PDF of that directory but every VM developer, external or internal, would have access to it. - Primitive subroutines like ToInt32 are different from internal instructions because the language definition will lean heavily on them and because their behavior cannot, in general, be changed arbitrarily from one version to the next. Also the published instruction definitions would reference them heavily. Documentation for these would go into doc/bytecode.
You need to log in before you can comment on or make changes to this bug.