PALBART(1)

okay bestie, pull up a chair and let me tell you about PALBART(1) — the manual page for palbart, straight out of the General Commands Manual section. She's a cross-assembler for PDP-8 assembly and she's thriving. Let's get into it 💖

---

🎀 NAME 🎀

palbart — BART enhanced PDP8 crossassembler 🦋

---

✨ SYNOPSIS ✨

palbart [options]inputfile

yeah that's it. no space between [options] and inputfile, that's just how she is, we respect it 💅

---

🌸 DESCRIPTION 🌸

okay so this manual page documents the palbart command briefly — short and sweet, like a story post. What she actually is is a cross-assembler for PDP/8 assembly language programs. 💻

She'll produce an output file in bin format, rim format, or — if you use the appropriate pseudo-ops — a combo of rim and bin formats together. A listing file is always produced (no opt-out, she's committed), and optionally you also get a symbol table and/or a symbol cross-reference (aka a concordance). 👑

The permanent symbol table can be output in a form that may be read back in, so you can build yourself a customized permanent symbol table. Very self-sustaining, very main character energy.

Any detected errors get output to a separate file — it tells you the filename where they were detected, plus the line number, column number and the error message, and it marks the error in the listing file too. Double coverage, she's thorough like that. 😌

The following file name extensions are used:

• .pal — source code (input)
• .lst — assembly listing (output)
• .bin — assembly output in DEC's bin format (output)
• .rim — assembly output in DEC's rim format (output)
• .err — assembly errors detected (if any) (output)
• .prm — permanent symbol table in form suitable for reading after the EXPUNGE pseudo-op.

---

💅 OPTIONS 💅

A summary of options is included below. Here's the whole roster, no skips:

• -$ — Don't require a $ at end of file
• -a — Enable additional features not compatible with PAL8.
• -d — Show symbol table at end of assembly
• -e — Generate error if link generated
• -h — Display help
• -l — Allow generation of links and literals (default)
• -n — Don't allow redefinition of permanent symbols
• -p — Generate a file with the permanent symbols in it. (To get the current symbol table, assemble a file than has only a $ in it.)
• -r — Produce output in rim format (default is bin format)
• -t N — Set tab stops to N
• -v — Display version information
• -x — Generate a cross-reference (concordance) of user symbols

---

🦋 ADDITIONAL FEATURES 🦋

So the additional features flag (-a, bestie, keep up 💖) enables functions that are not compatible with the PAL8 assembler. Currently only the TITLE and BANK pseudo operations are enabled with this function. And ngl, there are likely other incompatibilities that are not under this flag. 🙈 so like, proceed with awareness.

---

😭 DIAGNOSTICS 😭

Assembler error diagnostics get output to an error file and inserted in the listing file. Each line in the error file has the form:

<filename>(<line>:<col>) : error:  <message> at Loc = <loc>

An example error message is:

bintst.pal(17:9) : error:  undefined symbol "UNDEF" at Loc = 07616

The error diagnostics put in the listing start with a two character error code (if appropriate) and a short message. A carat '^' is placed under the item in error if appropriate. An example error message is:

      17 07616 3000          DCA     UNDEF
   UD undefined                      ^
      18 07617 1777          TAD  I  DUMMY

When an indirect is generated, an at character '@' is placed after the the instruction value in the listing as an indicator as follows:

      14 03716 1777@         TAD     OFFPAG

Undefined symbols are marked in the symbol table listing by prepending a '?' to the symbol. Redefined symbols are marked in the symbol table listing by prepending a '#' to the symbol. Examples are:

  #REDEF   04567
   SWITCH  07612
  ?UNDEF   00000

Refer to the code for the diagnostic messages generated. (iykyk, the code is the source of truth here 📖)

---

💀 BUGS 💀

okay so, full transparency time:

Only a minimal effort has been made to keep the listing format anything like the PAL-8 listing format. So don't come for her about aesthetics. 🫠

The RIMPUNch and BINPUNch pseudo-ops do not change the binary output file type that was specified on startup. This was intentional and and allows rim formatted data to be output prior to the actual binary formatted data. On UN*X style systems, the same effect can be achieved using the "cat" command, but on DOS/Windows systems, doing this was a major chore. 😮‍💨

The floating point input does not generate values exactly as the DEC compiler does. The author worked out several examples by hand and believes that this implementation is slightly more accurate. If that's mistaken, let them know and, if possible, a better method of generating the values. 👀

---

🌈 HISTORICAL NOTE 🌈

This assembler was written to support the fleet of PDP-8 systems used by the Bay Area Rapid Transit System. As of early 1997, this includes about 40 PDP-8/E systems driving the train destination signs in passenger stations. 🚆✨ literally running the trains, iconic behaviour.

---

📚 REFERENCES 📚

This assembler is based on the pal assembler by:

• Douglas Jones <jones@cs.uiowa.edu> and
• Rich Coon <coon@convexw.convex.com>

---

🧚 DISCLAIMER 🧚

• See the symbol table for the set of pseudo-ops supported.
• See the code for pseudo-ops that are not standard for PDP/8 assembly.
• Refer to DEC's "Programming Languages (for the PDP/8)" for complete documentation of pseudo-ops.
• Refer to DEC's "Introduction to Programming (for the PDP/8)" or a lower level introduction to the assembly language.

---

🙈 WARRANTY 🙈

If you don't like it the way it works or if it doesn't work, that's tough. You're welcome to fix it yourself. That's what you get for using free software. 💀 periodt. she said what she said.

---

👑 COPYRIGHT NOTICE 👑

This is free software. There is no fee for using it. You may make any changes that you wish and also give it away. If you can make a commercial product out of it, fine, but do not put any limits on the purchaser's right to do the same. If you improve it or fix any bugs, it would be nice if you told me and offered me a copy of the new version.

Gary Messenbrink <gam@rahul.net>

---

⭐ VERSIONS ⭐

okay the whole glow-up timeline, every single entry, no gatekeeping:

• v1.0 — 12Apr96 — GAM — Original
• v1.1 — 18Nov96 — GAM — Permanent symbol table initialization error.
• v1.2 — 20Nov96 — GAM — Added BINPUNch and RIMPUNch pseudo-operators.
• v1.3 — 24Nov96 — GAM — Added DUBL pseudo-op (24 bit integer constants).
• v1.4 — 29Nov96 — GAM — Fixed bug in checksum generation.
• v2.1 — 08Dec96 — GAM — Added concordance processing (cross reference).
• v2.2 — 10Dec96 — GAM — Added FLTG psuedo-op (floating point constants).
• v2.3 — 2Feb97 — GAM — Fixed paging problem in cross reference output.
• v2.4 — 11Apr97 — GAM — Fixed problem with some labels being put in cross reference multiple times.
• v2.9 — 23Jun13 — DJG David Gesswein djg@pdp8online.com — Combined versions found online and fixed many bugs. Used source from v2.5 03Nov07 RK and v2.6 14Jul03 PNT.

---

🍓 AUTHOR 🍓

This manual page was written by Vince Mulhollon <vlm@debian.org>, for the Debian GNU/Linux system (but may be used by others). 🫶

---

and that's the whole page bestie!! this little queen is dated June 23, 2013 and she's still serving. go assemble something gorgeous with her 💖✨🎀