PC3 Fuzix v0.21 - the machine has a manual

Fuzix on the Pico Computer 2 and 3. Unix, BBC BASIC, a self-hosted C
compiler and an MMBasic translator, on a machine you can hold.

The machine has a manual

man awk and man sed answered "No manual entry" for every command
this machine has, because the card carried exactly one page. It carries
158 now — one for each command in /bin, /usr/bin and
/usr/games — plus the 27 system-call pages in section 2, which had
never been installed anywhere. About 295K on an 800MB card.

They describe the programs on this card, not the GNU ones of the same
name, and each says where it differs — because several of those
differences bite:

• rm silently ignores any argument beginning with a dash, so
  rm -rf junk removes junk and says nothing about the rest.
• killall takes no process name. It signals everything except
  init, itself and its parent.
• ssh is a small shell, not a remote login.
• cat has no options at all.
• expr spells equality ==; a plain = is a syntax error.
• tr wants its ranges in brackets, so tr a-z A-Z maps three literal
  characters and turns abc into Abc without complaining.

A gate checks that every command has a page, that every page names a
command that exists, that every page renders — man here is not
nroff and prints a warning into the middle of a page it cannot
format — and that every SEE ALSO resolves.

Two bugs turned up while reading the sources, documented rather than
quietly changed: cut -i's guard test is inverted, so the flag never
does anything; and tty always exits 0, so -s reports nothing.

Pins that count, and pins that time

SETPIN n, FIN, CIN and PER make a pin a frequency, counting or
period input. PULSIN(pin, state) measures a single pulse and
DISTANCE(trig, echo) reads an HC-SR04. All of them are timestamped by
the kernel inside the interrupt it already runs, so a program can be
descheduled for half a second — this machine's timeslice — and still
read back an exact answer. They live on GP4–GP7, which is where
that interrupt is.

LED strips, and arbitrary timed output

WS2812 drives an addressable strip and BITSTREAM emits a list of
timed transitions, both through a reserved state machine on PIO1 with
the pattern handed over by DMA. Neither stops the machine while it
runs: a long BITSTREAM on MMBasic is seconds of dead interpreter, and
here it is none.

Sound says when it has finished

PLAY MP3, PLAY WAV and PLAY FLAC take a completion interrupt, as
PLAY MODFILE already did — the handler used to be parsed and then
dropped, so the file played and nothing fired. Measured on the board:
the end of a file arrives about a third of a second after the last
sound, and a PLAY STOP about a second later, because the player holds
the hardware until its buffer drains. MMBasic answers a STOP at once,
and the manual says so.

Also

• MATH(CRC8, CRC12, CRC16, CRC32) with the catalogue forms
  — XMODEM, CCITT-FALSE, ARC and the CRC-32 that zip and PNG use — all
  reachable. Three of the reference interpreter's answers are
  deliberately not copied; Appendix C says which and why.
• OPTION ANGLE DEGREES, and OPTION stops swallowing what it does
  not know. An unrecognised option used to be accepted in silence.
• fat put — the FAT partition carries files in both directions
  now, with long names and subdirectories.
• clk_sys is 378 MHz, up from 375, so the text console lands on
  640x480 at exactly 60.0 Hz instead of 59.5.

Corrections to the manual

Four claims had gone stale and one contradicted itself. The on-board
flash has not held a recovery system since the flash filesystem was
removed; umount /dev/hdb3 named the PSRAM swap disc, which has no
partitions; and setdate's -u and -0 were described the wrong way
round. The C manual gains the counting inputs and the PIO output path.

Upgrading

Recompile. A .bc using the new statements asks the new bcrun
for functions an old one does not have, and is refused by name at load.
The card ships the matched set.

Write pc3-sd-cc.img.gz to a card and copy fuzix.uf2 to the board in
BOOTSEL. Remount the root read-only before flashing — remount -n / ro
— or the next boot spends minutes in fsck.

Revised 2026-08-23 — BBC BASIC in a graphics mode

fuzix.uf2 and pc3-sd-cc.img.gz were rebuilt and replaced after
publishing. In a BBC mode, BBC BASIC drew every character twice: its
own 8x8 glyph, and the kernel console's 8x12 one under it, with the
console's version left standing after a RETURN. The console has
rendered into the graphics framebuffer since "the console keeps
working in a graphics mode" — which is what MMBasic's PRINT in
MODE 2 needs — and the interpreter's mirror to the serial console had
been written when entering a mode silenced it.

The interpreter now asks for PICOIOC_CONMIRROR while the mode is
its own, exactly as MMBasic's runtime does for OPTION CONSOLE SERIAL: the display half off, the uart untouched. The kernel's own
half of the fix is that the cursor goes with that flag — a mode change
painted an inverted 8x12 cell at (0,0), and the 8-high glyph over it
left a white 8x4 block under the prompt.

The two manual PDFs are unchanged.