Real-time clock (design note, 2026-11-03)¶
A battery-backed real-time clock for the YACC1: the time and date for programs, Kermit's timeouts in real seconds
whatever the CPU clock, and file dates on the Y1/OS disk so that make can rebuild what is out of date. Not
designed in KiCad, not built; this note is the plan and its open questions.
1. Why¶
The machine has no clock or timer. Everything that waits counts loop passes, so its time scales with the CPU clock:
| What | Today | With a clock chip |
|---|---|---|
Kermit's timeouts (os/kermit_io.asm) |
PPS EQU 6528 wait-loop passes = 1 s at 1 MHz; at 2 MHz a "15 s" timeout is 7.5 s |
the seconds register: a timeout is N real seconds at any clock |
The ROM's CF wait (cfwait) |
at most 65,536 polls; a faster CPU gives up sooner | unchanged (the ROM needs no clock) |
| File dates | none: P8XFS keeps no time, so make builds what is missing, make -B after an edit (man make) |
a date on every file closed; make rebuilds a target older than a prerequisite, as on Unix |
| The date | none (y1cc's header says 0000-00-00 00:00) |
/bin/date; the compiler's header, dir's dates |
2. The chip¶
DS12C887 (Dallas, now Analog Devices): an MC146818-compatible clock in a 24-pin encapsulated DIP module with its own 32.768 kHz crystal and lithium cell. Time, date and century, an alarm, a periodic interrupt, a square-wave output, and about 113 bytes of battery-backed RAM; binary or BCD, 12 or 24 hours. Its register interface is the PC/AT clock's: a register number, then the register's data, on a multiplexed 8-bit bus. The DS12887 is the same without the century register.
The data sheet could not be read on 2026-11-03 (the host timed out). Everything about the chip below is the MC146818 family's, to verify on the DS12C887 data sheet before the circuit is drawn: the pin numbers, the bus timing, RESET's effect, the oscillator's state as shipped, and whether the part is still in production.
Alternatives considered:
| Option | For | Against |
|---|---|---|
| DS12C887 on two I/O ports (chosen) | one part: time, date, battery, RAM; the PC's interface, well known | a 24-pin module, not the cheapest part |
| The video card's ATmega (V2.0's PS/2 section, kept on the V4; PD/PE, 16 MHz crystal) | no new hardware: a firmware reply with a tick count | no battery (the time is lost at power-off: fine for timeouts, useless for file dates); needs that card built |
| 82C54 counter/timer from the UART's 1.8432 MHz | timeouts and ticks | no calendar, no battery |
| DS1307 / DS3231 (I2C) | cheap modules | the bus has no I2C: a bit-banged port or the ATmega |
| DS12885 + 32.768 kHz crystal + CR2032 holder (added 2026-11-12) | the DS12C887's registers and software, with a coin cell that can be replaced (the module's sealed cell lasts about 10 years, then the module goes) | two more parts; the crystal wants short tracks and a guard |
3. Ports¶
The clock needs two ports, as the PC's $70/$71: one for the register number, one for the data.
| Port | Direction | What |
|---|---|---|
| P6 | write | the register number (0..127): latched by the chip on AS's falling edge |
| P7 | read / write | the register P6 selected |
Why P6/P7: the video card V4 uses PA-PF (V2.0, removed 2026-11-18, used PA-PE), the CF section P8/P9, the I/O card
P0/P1, which leaves nothing in the upper half. The I/O card decodes P2-P7 (its IC5, strapped to the low half) but nothing on it uses P2-P7: the six selects
only reach its IO-ADDR and DATA-ADDR headers (docs/cards/io.md 3.1, docs/programming/IO-PORTS.md). A card that
decodes P6/P7 itself does not meet the I/O card on the data bus. To verify on the I/O card in the machine before
the RTC answers there: no jumper on IO-ADDR or DATA-ADDR selects P6 or P7.
4. The circuit¶
The CF card v1.0's decode (hardware/cards/cf/kicad/v1.0, docs/cards/cf.md), on other ports:
IO-ADDR0..3 ──► 74LS138 ── -P6SEL, -P7SEL (A,B,C = IO-ADDR0..2; enabled while IO-ADDR3 = 0)
-IO-WR, -IO-RD ──► gates: AS = P6SEL AND IO-WR (Intel ALE: the register number latched as AS falls)
-WR = NOT (P7SEL AND IO-WR) (the chip's R/W pin in Intel mode)
-RD = NOT (P7SEL AND IO-RD) (the chip's DS pin in Intel mode)
-CS = NOT (P6SEL OR P7SEL)
DATA0..7 ◄──► 74LS245 (enabled by -CS, direction from -IO-RD) ◄──► AD0..7 of the DS12C887 (MOT = GND: Intel mode)
IRQ (open drain) ──► jumper INT-EN ──► bus -INT (C13) SQW ──► test point / LED (optional)
About four TTL chips beside the module: a 74LS138, a 74LS08 and a 74LS32 (or one gate package, as the logic works out), a 74LS245. The 245 keeps the module's weak outputs off the backplane, as on the CF card.
Timing. The microcode puts the port number on IO-ADDR0..3 two or three steps before a strobe and holds it to the end
of the instruction; a strobe lasts one step, two clocks: 2 µs at 1 MHz (docs/cards/cf.md section 4). Writers take
the data on the strobe's trailing edge, which is also AS's falling edge here, while the data is still on the bus. The
MC146818 family's limits are in the hundreds of nanoseconds (a bus cycle of about 400 ns, strobe widths of about
150 ns): to verify on the data sheet; nothing is close at 1 MHz, and even at 6 MHz a step is 333 ns.
RESET. On the MC146818 family RESET clears interrupt enables and flags, not the time, the date or the RAM. Tie it to VCC (the PC does), or to the bus -RESET once the data sheet confirms that. To verify.
Interrupt. IRQ is open drain, so it can share -INT (C13) with the UART's 7406, through a jumper (INT-EN, off by default) as the video card's PS/2 section does with its interrupt (V2.0's section, kept on the V4). Nothing in the ROM or Y1/OS uses interrupts yet, so the jumper stays off until something does.
Power-up. The family needs about 200 ms after VCC rises before the bus may be used, and the oscillator may be
shipped stopped (register A's DV bits) to save the cell: the first date -s starts it. To verify.
5. Where it goes¶
| Option | For | Against |
|---|---|---|
| A small RTC card (the blank card V3.2 outline, generated like the CF card v1.0) | its own card: no change to a built one; the board-layout rules from the start (the INT-EN jumper and an LED at the front edge, labelled; cottageworker.com on the silk) | a slot |
| On the protocard first, hand-wired | quick bring-up of five chips; proves the ports and the software | not the final board |
| A future I/O card or memory card revision | no extra slot | both are built (the I/O card V1.1, the memory card v2.0): only as a new revision |
Proposed: a hand-wired prototype on the protocard to prove the software, then a small card.
5.1 On the I/O card's next revision (proposed 2026-11-12)¶
The I/O card is the natural home once it is revised: most of the circuit of section 4 is already on it.
- The decode is there. Its IC5 (74LS138) decodes all eight ports P0-P7 of its half and only P0 and P1 are used;
-IO-SEL6and-IO-SEL7reach only the IO-ADDR and DATA-ADDR headers (docs/cards/io.md3.1). The clock takes them directly: no 74LS138 of its own, only the gates that make AS,-WR,-RDand-CSfrom them and-IO-RD/-IO-WR(section 4). - The data buffer is planned. V1.2's first idea (
docs/cards/io.mdsection 8) is a 74LS245 between the card and the data bus, DIR from-IO-RD; the clock sits behind it with the UART, the latches and the LCD, so it needs no 245 of its own. - The interrupt path is there. The card drives the bus
-INTfor the UART (IC8, open collector); the clock's IRQ joins it through the INT-EN jumper. - Its own ports, not P1. The control latch IC10 has no free bit (switches/LEDs, LCD E and RS, UART A0-A2, UART CS, TIL311: section 3.3 there), so the clock cannot be another device behind P0/P1 as the UART is. P6/P7 also keep the software of section 6 as it is: the register number to P6, the data on P7, the PC's $70/$71.
- The chip: the DS12885 with a CR2032 holder (the battery can be changed), or the DS12C887 module for one part. Either way the registers and the software are the same.
- The board rules (
CLAUDE.md) apply to the new revision: the INT-EN jumper near an edge, the square-wave LED (if fitted) labelled and on the front edge, every part's reference and value on the silk outside its outline,cottageworker.combeside the name and revision, bypass capacitors on 0.1-inch spacing, and thepcb-checkpre-order check before it is ordered. The I/O card V1.1 in the machine is not changed; the clock comes with V1.2.
This replaces the small card of section 5 as the plan when the I/O card is revised; the protocard prototype is still the quickest way to prove the software first, on the same ports.
Drawn 2026-11-18, on the I/O card V1.2 (hardware/cards/io/kicad/v1.2, docs/cards/io.md section 8; designed and
routed, not ordered). As drawn:
- The chip: a DS12885+ in the 24-pin PDIP, with a 32.768 kHz crystal for a 6 pF load (Y1, beside the chip's pins 2
and 3: 3 mm of track each, nothing else routed beside or under them) and a CR2032 in a flat holder (BT1, Keystone
103) straight on VBAT. Its pins are the data sheet's as System-5's IO panel has them (
~/Developer/elfhardware/io-panel/kicad/rev-a, read from the data sheet on 2026-11-18): MOT low for Intel bus timing, -CS low, -RESET high (the data sheet's typical connection: the control registers then keep their state through a power failure), SQW open. - The strobes, from the bus's own -IO-RD and -IO-WR and the card's selects of ports 6 and 7: AS = NOT(-IO-SEL6 OR -IO-WR), the chip's DS = -IO-SEL7 OR -IO-RD, its R/-W = -IO-SEL7 OR -IO-WR (a 74LS32 and a spare gate of the card's 74LS00). AS falls as -IO-WR ends, with the register number still on the data lines: the microcode holds it a step.
- The data lines: the card's ID0-7, behind its 74LS245.
- -IRQ: open drain, to the bus -INT through JP8 (off). The pull-up is the card's RN1 (2.2k: 2.3 mA, inside the chip's 4 mA).
- -RCLR: JP9 to GND, no pull-up (the chip has its own, and its data sheet asks for none outside). Fitted for a moment with the power off, it clears the chip's 114 bytes of RAM, never the clock.
- The ports: the card's ports 6 and 7, P6 and P7 with the card in the low half (its JP3), so the software of section 6 stands as written.
6. Software¶
In the order it can be done, all testable on the emulators before the hardware exists:
- The emulators' model (
software/rtcmodel.h, besidecfmodel.h): done 2026-11-20. P6/P7 in both emulators, when the environment names the card:Y1IO_CARD=v1.2(without it the I/O card is the V1.1 of the machine, with nothing on those ports). The time is the host's local time and runs with the host's clock;Y1RTC_TIME="2026-11-20 12:34:56"starts the chip at that time and runs it on the emulated machine's own clocks, for transcripts that repeat (an environment variable and not-R, whichy1ucemuhas for something else);Y1RTC_NEW=1is a chip never set: the oscillator stopped, BCD and 12-hour, what the firstdate -smeets. As a chip already set it starts in binary and 24-hour mode (register B = $06). Modelled: the ten time, calendar and alarm registers in binary or BCD, 12- or 24-hour; SET and the oscillator's DV bits (the first update 500 ms after it starts); UIP, set from 244 us before a second ends to 1984 us after, so a reader that waits for it is tested; register C's flags (UF, AF, PF by the rate, IRQF by the enables), cleared by the read; the 114 bytes of RAM. Not modelled: the -IRQ pin (JP8 is left off), SQW, daylight saving, the cell (the RAM and a time that was set last as long as the emulator runs).tests/io/rtc/run.py, inmake check: the model on its own, and a YACC1 program that finds the chip, reads and sets it on both emulators. - Finding the chip. A read of an empty port does not give one value: the microcode emulator reads $FF (as the
V1.2 card's own pulled-up data lines would with the chip out), the instruction-level emulator leaves ACC as it
was, and on the V1.1 card in the machine the data bus floats. So
rtc_present()(below) writes two different bytes to two RAM registers and reads both back, with the register number the last byte on the bus before each read, astests/io/rtc/rtc.asmdoes. os/lib_rtc.c:rtc_present()(write and read back a RAM byte: an absent card reads as whatever is left on the bus),rtc_rd(reg),rtc_wr(reg, v),rtc_time(buf)(wait while UIP is set, then read the registers; or read twice until two reads agree),rtc_set(...). Binary and 24-hour mode, set once bydate -s./bin/date:dateprints2026-11-03 18:42:07,date -s 2026-11-03 18:42sets it (and starts the oscillator). A man page and ahelpline.- Kermit (
os/kermit_io.asm): if the clock is there, the wait loop counts changes of the seconds register while it waits (only on the empty-line path, so the per-character loop keeps its 217 clocks); elsePPSas now. - File dates. A P8XFS entry has seven spare bytes (25..31;
tools/p8xfs.pyleaves them alone, a fresh volume has them zero). Proposed: bytes 26-27 the time and 28-29 the date in the FAT layout (time: hour 5 bits, minute 6, second / 2 5; date: year - 1980 7 bits, month 4, day 5; little-endian), 0 = no date. Both kernels stamp a file at CLOSE when the clock is there;p8xfs.py putstamps the host file's time,lsshows it. The C kernel has 69 bytes free (2026-11-03): the stamping needs room found there first. P8X shares the format: to verify that P8X/OS ignores bytes 25..31 (~/Developer/p8x, read-only). make: when a target and a prerequisite both have dates, the target is rebuilt if it is older; else today's rule (missing, or a prerequisite built in this run).dirandlsshow the dates.- The compiler's header: y1cc on the machine writes the real date instead of
0000-00-00 00:00(the selfhost test already masks that line).
7. Open questions¶
- The DS12C887's pinout, timing, RESET and shipped oscillator state from its data sheet (sections 2 and 4).
- P6/P7: confirm on the I/O card that no header jumper selects them.
- A card of its own, the protocard first, or on the I/O card V1.2: on the I/O card V1.2 (2026-11-18, section 5.1).
- DS12885 + coin cell or the DS12C887 module: the DS12885 with a CR2032 (2026-11-18).
- The interrupt: wired, through a jumper that is left off (JP8 on the I/O card V1.2).
- File dates: the FAT layout in bytes 26-29, and P8X's use of the spare bytes.
Last updated 20 November 2026