Yamas: Yet Another Macro Assembler (for the PDP-8)
AGPL-3.0 License
This is Yamas – Yet Another Macro Assembler: A PAL-compatible assembler for PDP-8 computers. It also includes support macros in the syntax of MACRO-8 (PDF manual). It is a complete clean-room implementation of a PDP-8 assembler using web technologies so that the assembler can be integrated into web applications, apps on phones and the like. Of course, it also comes with a traditional shell command (through Node.js).
If Node.js is installed, it should be possible to just do npx yamas <file.pa>
. The core assembler has no dependencies to Node.js and can run right in the browser, demo page coming soon!
While palbart and macro8x exist, it would be hard to adapt them for usage on the web. For example, creating a proper syntax highlighter requires knowledge about the abstract syntax tree (AST) of the program, something that the existing assemblers don't even have since they're traditional two-pass assemblers that directly emit output symbols while still parsing the input. Yamas is built more like a compiler than an assembler: it creates an AST using a parser and a lexer that is then passed to the actual assembler with the possibility to access the artifacts created in between. This enables tools like code editors to access the AST to query defined symbols, expanded macros and the like.
Currently, the following pseudos are supported:
Type | Pseudos |
---|---|
Control of origin |
PAGE , FIELD , RELOC
|
Conditionals and macros |
IFDEF , IFNDEF , IFNZRO , IFZERO , DEFINE
|
Data output |
TEXT , ZBLOCK , DUBL , FLTG , DEVICE , FILENAME
|
Symbol table control |
EXPUNGE , FIXTAB , FIXMRI
|
Radix control |
DECIMAL , OCTAL
|
Output control |
NOPUNCH , ENPUNCH
|
No-ops |
EJECT , XLIST , PAUSE
|
"Correct" is hard to define since there are many different dialects of the language that are treated differently by different assemblers. But the output should match the output of PAL8. Any mismatch is considered a bug. Yamas currently passes the palbart testbench, including the "bad" directory where palbart fails. It also uses extensive unit tests so that new features don't break things that once worked.
There are some known and accepted deviations:
A=B
) uses the PAL8 syntax and not the MACRO-8 syntax. This means that things like A=DECIMAL 10 OCTAL
are not supported.What matters is the machine state after reading the bin files. It's okay if things have a different order on the bin tape.
For example, the literal table is output at a different time. Palbart does the same and the bin tapes don't match PAL8.
That's why comparisons of bin files should be done with a special tool like cmp_tape. Yamas also includes the -c
option to compare its output with a given bin file, noting the differences in the resulting state.
Because some external hardware might use the data break to read memory and expect custom operations that act like MRIs.
A prominent example is the external floating point unit: It introduces custom opcodes that it executes as a co-processor.
Some of these custom opcodes need an MRI-like operand even though the opcode starts with 6 or 7. For example, the Focal code
defines FIXMRI FPT=6000
which wouldn't work with the auto-detection of FIXTAB
.
They are parsed as comments, but if they contain a '>', it will still end the current macro body.
Interestingly, the rest of the line after the closing '>' is still handled as a comment, i.e. not parsed.
Example: IFDEFA <I/O ERROR>
is legal: it either assembles as I
(value 0400) or not at all, depending on A
.
This matches the behavior of PAL8.
This project was also a personal project for me to strengthen skills that I hardly need for my day job, such as writing lexers and parsers.
Expressions can be null in pass 1, for example when a symbol is used that is only defined later. This is okay unless the expression changes the CLC.
For that reason, the assembler differentiates between defined and undefined expressions. Using an undefined expression in an IFZERO
is not okay
because the resulting CLC can't be calculated - but using it in something like A=JMS X
is completely fine.
null
is used instead of define
so that the linter will spot a missing case
in the eval functions after adding a new node type. It would probably be better to
use a Maybe
type so that expressions like if (!val)
are also caught.
Some programs deliberately use the origin operator to generate RIM loader sections in the punched tape, e.g. TSS/8.
See above: The origin statements must be preserved as they appeared in the code.