yamas v1.1.1

Introduction

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).

Usage

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!

FAQs

Assembler FAQ

Why another assembler for the PDP-8?

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.

Which pseudo symbols are supported?

Currently, the following pseudos are supported:

Is the generated code correct?

"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.

Any deviations?

There are some known and accepted deviations:

• parameter assignment (A=B) uses the PAL8 syntax and not the MACRO-8 syntax. This means that things like A=DECIMAL 10 OCTAL are not supported.
• floating point literals are more accurate than the ones generated by PAL8.

But in my own tests, the generated bin files differ?

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.

Language FAQ

Why do both FIXMRI and FIXTAB exist when FIXTAB auto-detects MRIs?

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.

How are comments inside macros and conditional statements handled?

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.

Implementation FAQ

Why no parser generator?

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.

Why can expressions be null? Also, why not undefined?

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.

Why does the origin operator always lead to origin symbols in the binary tape? Couldn't this be optimized to only write them when necessary?

Some programs deliberately use the origin operator to generate RIM loader sections in the punched tape, e.g. TSS/8.

Why does the assembler emit callbacks instead of simply returning the target memory state and creating the bin tape from there?

See above: The origin statements must be preserved as they appeared in the code.