[TUHS] UNIX v4 Source Code Commentary - complete book now available

[TUHS] UNIX v4 Source Code Commentary - complete book now available

[Briam Rodriguez via TUHS]

Hello,

Following the incredible recovery of the UNIX v4 tape from the University
of Utah last month, I've written a comprehensive line-by-line commentary
on the entire UNIX Fourth Edition source code.

The book covers:
- The kernel (boot, processes, memory management, scheduling)
- The file system (inodes, buffer cache, namei)
- Device drivers (TTY, RK05 disk, character devices)
- User space (shell, utilities, C compiler, assembler)
- Plus appendices with system call reference, file formats, and PDP-11 guide

It's open source (CC BY-NC-SA 4.0) and available on GitHub:

https://github.com/unix-v4-commentary/unix-v4-source-commentary

The PDF is included in the repo for those who just want to read.

It is my sincerest hope that this book can help someone, and I'd 
appreciate any feedback (and changes!).

Many thanks to Robert Ricci, and Al Kossow, and everyone involved in 
recovering this historic code.

Without that work, this book wouldn't have been possible. Also thanks to 
Mr. Warren for letting me in to the mailing list!

Please don't beat me up too bad!

Humbly yours,

Briam Rodriguez

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[Warren Toomey via TUHS]

On Mon, Jan 12, 2026 at 04:37:29PM -0500, Briam Rodriguez via TUHS wrote:
> Following the incredible recovery of the UNIX v4 tape from the University
> of Utah last month, I've written a comprehensive line-by-line commentary
> on the entire UNIX Fourth Edition source code.

> It is my sincerest hope that this book can help someone, and I'd appreciate
> any feedback (and changes!).
> Many thanks to Robert Ricci, and Al Kossow, and everyone involved in
> recovering this historic code.
> Without that work, this book wouldn't have been possible. Also thanks to Mr.
> Warren for letting me in to the mailing list!
> Please don't beat me up too bad!
> Briam Rodriguez

8-) No beating required. I've skimmed the first two dozen pages and so
far it's a good introduction to v4, setting the background in terms
of people, organisations and the PDP-11 architecture.

I'm sure that the TUHS members will give you well-advised and useful
criticism and suggestions.

Thanks for your hard work and effort Briam.

Cheers, just Warren

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[David Barto via TUHS]

Following up to my prior email.

It does look like the PDF got created. Some 294 pages of it.

Amazing. I can’t wait to read further. (At  4.4.4 now)

	David

> On Jan 12, 2026, at 1:37 PM, Briam Rodriguez via TUHS <tuhs@tuhs.org> wrote:
> 
> Hello,
> 
> Following the incredible recovery of the UNIX v4 tape from the University
> of Utah last month, I've written a comprehensive line-by-line commentary
> on the entire UNIX Fourth Edition source code.
> 
> The book covers:
> - The kernel (boot, processes, memory management, scheduling)
> - The file system (inodes, buffer cache, namei)
> - Device drivers (TTY, RK05 disk, character devices)
> - User space (shell, utilities, C compiler, assembler)
> - Plus appendices with system call reference, file formats, and PDP-11 guide
> 
> It's open source (CC BY-NC-SA 4.0) and available on GitHub:
> 
> https://github.com/unix-v4-commentary/unix-v4-source-commentary
> 
> The PDF is included in the repo for those who just want to read.
> 
> It is my sincerest hope that this book can help someone, and I'd appreciate any feedback (and changes!).
> 
> Many thanks to Robert Ricci, and Al Kossow, and everyone involved in recovering this historic code.
> 
> Without that work, this book wouldn't have been possible. Also thanks to Mr. Warren for letting me in to the mailing list!
> 
> Please don't beat me up too bad!
> 
> Humbly yours,
> 
> Briam Rodriguez
> 

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[Phil Budne via TUHS]

General question: Is "v4" really the right thing to call the tape?

Page 1 footnote 1 reads

  UNIX Fourth Edition was released in November 1973. The source code
  in this book comes from a tape sent to the University of Utah in
  June 1974, containing the V4 distribution with minor updates. See
  Ken Thompson’s letter to Martin Newell dated May 31, 1974

While https://gunkies.org/wiki/UNIX_Fifth_Edition says v5 was dated June 1974.

I understand the temptation to be the "John Lions of v5" and to be the
first to plant a flag on heretofore unknown ground, but I'm more
interested in understanding the tape in full context (what differences
are seen between tape contents fall in relation to the extant v4 man
pages, and the known "v5" sources?).

I'd probably be more interested in short summaries of how the new tape
differs from the Fourth Edition documentation, the "v5" sources, and
finally v6, as documented by Lions.

phil

P.S.
I'm probably just as, or more guilty of misnomering, since I may have
helped propogate the term "version zero" for the recovered PDP-7 UNIX
code when I was helping to bring it up and annotate it.

P.P.S.
Then there is the worm can of whether "Version" anything exists
(the manual was published in editions, and tapes were made at various
time) especially in earlier times...

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[Thalia Archibald via TUHS]

On Jan 12, 2026, at 16:20, Phil Budne wrote:
> General question: Is "v4" really the right thing to call the tape?


The manual editions are a messy way to refer to UNIX snapshots.
UNIX was versioned by the manual releases, but the system was distributed as a
copy of the current system on the Research machine, whenever the tape was cut.
Different licensees received different snapshots, but the same manual.

Since we only have a few snapshots now, it’s tempting to call them by the manual
in use at the time, but it’s rather inaccurate. It’s much better to call them by
some unique identifier; Utah V4 in this case or Dennis_v5, Henry_Spencer_v7,
Nijmegen_v7, etc., as in the TUHS Archive. Or alternatively, to call it a UNIX
V4 snapshot from 12 June 1974.

As you say, the V5 manual is dated June 1974. The files on the Utah V4 tape are
dated 12 June 1974 and documented to have been sent after May 1974, but with a
V4 manual. So we’re looking at near-V5 code just days or weeks before the V5
manual was released. However, I continue to call it “V4”, as that is evidently
what this particular tape was thought of as, since that was the manual version
that accompanied it.

Thalia

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[segaloco via TUHS]

On Monday, January 12th, 2026 at 15:51, Thalia Archibald via TUHS <tuhs@tuhs.org> wrote:

> On Jan 12, 2026, at 16:20, Phil Budne wrote:
> 
> > General question: Is "v4" really the right thing to call the tape?
> 
> 
> 
> The manual editions are a messy way to refer to UNIX snapshots.
> UNIX was versioned by the manual releases, but the system was distributed as a
> copy of the current system on the Research machine, whenever the tape was cut.
> Different licensees received different snapshots, but the same manual.
> 
> Since we only have a few snapshots now, it’s tempting to call them by the manual
> in use at the time, but it’s rather inaccurate. It’s much better to call them by
> some unique identifier; Utah V4 in this case or Dennis_v5, Henry_Spencer_v7,
> Nijmegen_v7, etc., as in the TUHS Archive. Or alternatively, to call it a UNIX
> V4 snapshot from 12 June 1974.
> 
> As you say, the V5 manual is dated June 1974. The files on the Utah V4 tape are
> dated 12 June 1974 and documented to have been sent after May 1974, but with a
> V4 manual. So we’re looking at near-V5 code just days or weeks before the V5
> manual was released. However, I continue to call it “V4”, as that is evidently
> what this particular tape was thought of as, since that was the manual version
> that accompanied it.
> 
> Thalia

The new USG docs refer to USGs providence as coming from a "frozen" machine.  This does make me wonder why they didn't just start shipping USG UNIX instead since it was separated into "stable" releases.

Granted either way they couldn't "support" it, but you'd figure it'd be easier for everyone to just keep sending out cuts of USG UNIX.  Would it being AT&Ts internal supported UNIX make it too close to shipping a supported product and shipping random cuts from Research instead kept them out of scrutiny?  They eventually warmed up to shipping PWB, so this remains a point of curiosity to me.

- Matt G.

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[Cameron Míċeál Tyre via TUHS]

Hello Briam,

Thank you. This is like a Christmas present, even though it is now mid-January. As an amateur, I can only read the content and absorb. I know for sure, having already skimmed through a few pages, that I will enjoy reading it and learn much.

Best regards,

Cameron



-------- Original Message --------
On Monday, 01/12/26 at 21:38 Briam Rodriguez via TUHS <tuhs@tuhs.org> wrote:
Hello,

Following the incredible recovery of the UNIX v4 tape from the University
of Utah last month, I've written a comprehensive line-by-line commentary
on the entire UNIX Fourth Edition source code.

The book covers:
- The kernel (boot, processes, memory management, scheduling)
- The file system (inodes, buffer cache, namei)
- Device drivers (TTY, RK05 disk, character devices)
- User space (shell, utilities, C compiler, assembler)
- Plus appendices with system call reference, file formats, and PDP-11 guide

It's open source (CC BY-NC-SA 4.0) and available on GitHub:

https://github.com/unix-v4-commentary/unix-v4-source-commentary

The PDF is included in the repo for those who just want to read.

It is my sincerest hope that this book can help someone, and I'd
appreciate any feedback (and changes!).

Many thanks to Robert Ricci, and Al Kossow, and everyone involved in
recovering this historic code.

Without that work, this book wouldn't have been possible. Also thanks to
Mr. Warren for letting me in to the mailing list!

Please don't beat me up too bad!

Humbly yours,

Briam Rodriguez

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[Briam Rodriguez via TUHS]

Thank you for your kind words, Cameron.

I want you and all the lovely folks here to know how glad I am to be 
here, and that I take all feedback to heart.

It's no mystery that the happenings of UNIX history were before my time, 
so I ask your patience with any errors or omissions; I'm approaching 
this as much as a historian as a programmer. But more than anything, 
this book is a mark of gratitude to K&R for making my livelihood 
possible. This is my way of attemping to contribute back to a community 
that has given me so much.

-- Briam R.

On 1/12/26 7:51 PM, Cameron Míċeál Tyre wrote:
> Hello Briam,
>
> Thank you. This is like a Christmas present, even though it is now mid-January. As an amateur, I can only read the content and absorb. I know for sure, having already skimmed through a few pages, that I will enjoy reading it and learn much.
>
> Best regards,
>
> Cameron
>
>
>
> -------- Original Message --------
> On Monday, 01/12/26 at 21:38 Briam Rodriguez via TUHS <tuhs@tuhs.org> wrote:
> Hello,
>
> Following the incredible recovery of the UNIX v4 tape from the University
> of Utah last month, I've written a comprehensive line-by-line commentary
> on the entire UNIX Fourth Edition source code.
>
> The book covers:
> - The kernel (boot, processes, memory management, scheduling)
> - The file system (inodes, buffer cache, namei)
> - Device drivers (TTY, RK05 disk, character devices)
> - User space (shell, utilities, C compiler, assembler)
> - Plus appendices with system call reference, file formats, and PDP-11 guide
>
> It's open source (CC BY-NC-SA 4.0) and available on GitHub:
>
> https://github.com/unix-v4-commentary/unix-v4-source-commentary
>
> The PDF is included in the repo for those who just want to read.
>
> It is my sincerest hope that this book can help someone, and I'd
> appreciate any feedback (and changes!).
>
> Many thanks to Robert Ricci, and Al Kossow, and everyone involved in
> recovering this historic code.
>
> Without that work, this book wouldn't have been possible. Also thanks to
> Mr. Warren for letting me in to the mailing list!
>
> Please don't beat me up too bad!
>
> Humbly yours,
>
> Briam Rodriguez
>
>

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[Clem Cole via TUHS]

Below

Sent from a handheld expect more typos than usual


On Mon, Jan 12, 2026 at 7:09 PM segaloco via TUHS <tuhs@tuhs.org> wrote:

> On Monday, January 12th, 2026 at 15:51, Thalia Archibald via TUHS <
> tuhs@tuhs.org> wrote:
>
> > On Jan 12, 2026, at 16:20, Phil Budne wrote:
> >
> > > General question: Is "v4" really the right thing to call the tape?
> >
> >
> >
> > The manual editions are a messy way to refer to UNIX snapshots.
> > UNIX was versioned by the manual releases, but the system was
> distributed as a
> > copy of the current system on the Research machine, whenever the tape
> was cut.
> > Different licensees received different snapshots, but the same manual.
> >
> > Since we only have a few snapshots now, it’s tempting to call them by
> the manual
> > in use at the time, but it’s rather inaccurate. It’s much better to call
> them by
> > some unique identifier; Utah V4 in this case or Dennis_v5,
> Henry_Spencer_v7,
> > Nijmegen_v7, etc., as in the TUHS Archive. Or alternatively, to call it
> a UNIX
> > V4 snapshot from 12 June 1974.
> >
> > As you say, the V5 manual is dated June 1974. The files on the Utah V4
> tape are
> > dated 12 June 1974 and documented to have been sent after May 1974, but
> with a
> > V4 manual. So we’re looking at near-V5 code just days or weeks before
> the V5
> > manual was released. However, I continue to call it “V4”, as that is
> evidently
> > what this particular tape was thought of as, since that was the manual
> version
> > that accompanied it.
> >
> > Thalia
>
> The new USG docs refer to USGs providence as coming from a "frozen"
> machine.  This does make me wonder why they didn't just start shipping USG
> UNIX instead since it was separated into "stable" releases.



I think you are applying a thinking and are ignoring the realities of the
time. Remember AT&T is under incredible scrutiny my the DOJ. They are
prohibited from being in the computer business. USG’s charter is supporting
the Bell System in a commercial manner. The last thing AT&T legal wants is
to be seen using a commercial team to be creating “products” for the
general market.  Research >>is<< allowed (ney required) work with the
research community.


>
> Granted either way they couldn't "support" it, but you'd figure it'd be
> easier for everyone to just keep sending out cuts of USG UNIX.  Would it
> being AT&Ts internal supported UNIX make it too close to shipping a
> supported product and shipping random cuts from Research instead kept them
> out of scrutiny?  They eventually warmed up to shipping PWB, so this
> remains a point of curiosity to me.

That really was a big deal during the 3.0 license negotiations. Al and Otis
were very careful about what they were willing to make available outside of
the Bell System.

Once judge Green change the rules, The USG “Product” was easier To be made
available

>

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[Jim Capp via TUHS]

I really like the first few pages.  I look forward to a deeper dive. 

J

> On Jan 12, 2026, at 4:37 PM, Briam Rodriguez via TUHS <tuhs@tuhs.org> wrote:
> 
> Hello,
> 
> Following the incredible recovery of the UNIX v4 tape from the University
> of Utah last month, I've written a comprehensive line-by-line commentary
> on the entire UNIX Fourth Edition source code.
> 
> The book covers:
> - The kernel (boot, processes, memory management, scheduling)
> - The file system (inodes, buffer cache, namei)
> - Device drivers (TTY, RK05 disk, character devices)
> - User space (shell, utilities, C compiler, assembler)
> - Plus appendices with system call reference, file formats, and PDP-11 guide
> 
> It's open source (CC BY-NC-SA 4.0) and available on GitHub:
> 
> https://github.com/unix-v4-commentary/unix-v4-source-commentary
> 
> The PDF is included in the repo for those who just want to read.
> 
> It is my sincerest hope that this book can help someone, and I'd appreciate any feedback (and changes!).
> 
> Many thanks to Robert Ricci, and Al Kossow, and everyone involved in recovering this historic code.
> 
> Without that work, this book wouldn't have been possible. Also thanks to Mr. Warren for letting me in to the mailing list!
> 
> Please don't beat me up too bad!
> 
> Humbly yours,
> 
> Briam Rodriguez
> 

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[Angelo Papenhoff via TUHS]

Looks very nice, thanks!

I was wondering about the RK driver, because there are issues with it.
The v4 RK11 driver does not work with simh emulation correctly when
using multiple disks. I've had to use the v5 driver for my v4
installation guide to get a usable system. Looking at the code i had the
impression that the v4 driver is fine (it also matches the nsys RK
driver, which i've also had trouble with recently. haven't tried v5 RK
with nsys yet). What i suspect is happening is that the seek/read dance
isn't working correctly, either in simh, or there were faulty
assumptions that only work on real hardware more or less accidentially
(the rewrite in v5 might suggest the latter).
In any case it looks like blocks aren't being read correctly, and
whatever process is waiting for the read will hang.

Would be nice to get to the bottom of this.

cheers,
aap

On 12/01/26, Briam Rodriguez via TUHS wrote:
> Hello,
> 
> Following the incredible recovery of the UNIX v4 tape from the University
> of Utah last month, I've written a comprehensive line-by-line commentary
> on the entire UNIX Fourth Edition source code.
> 
> The book covers:
> - The kernel (boot, processes, memory management, scheduling)
> - The file system (inodes, buffer cache, namei)
> - Device drivers (TTY, RK05 disk, character devices)
> - User space (shell, utilities, C compiler, assembler)
> - Plus appendices with system call reference, file formats, and PDP-11 guide
> 
> It's open source (CC BY-NC-SA 4.0) and available on GitHub:
> 
> https://github.com/unix-v4-commentary/unix-v4-source-commentary
> 
> The PDF is included in the repo for those who just want to read.
> 
> It is my sincerest hope that this book can help someone, and I'd 
> appreciate any feedback (and changes!).
> 
> Many thanks to Robert Ricci, and Al Kossow, and everyone involved in 
> recovering this historic code.
> 
> Without that work, this book wouldn't have been possible. Also thanks to 
> Mr. Warren for letting me in to the mailing list!
> 
> Please don't beat me up too bad!
> 
> Humbly yours,
> 
> Briam Rodriguez
> 

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[Briam Rodriguez via TUHS]

Angelo,

I took a look at the v4 RK driver source to see what might be going on here.

The v4 driver does something clever with multiple disks: overlapped 
seeks. When rkstart() runs, it iterates through all four drive queues 
and fires off SEEK commands for every drive that has pending work. The 
idea is that while drive 0 is seeking, drive 1 can be transferring data. 
Good for throughput on real hardware.

The tricky part is the interrupt handler. When an interrupt comes in, 
rkintr() checks the SEEKCMP bit in rkcs to figure out if this is a "seek 
finished" or "transfer finished" interrupt. For seek completion, it 
reads bits 13-15 of rkds to determine which drive just finished seeking, 
then kicks off the actual data transfer for that drive.

There's a global variable rk_ap that tracks which drive queue is 
currently mid-transfer. It gets set when a seek completes and used when 
the subsequent transfer completes. This is the state that ties the 
two-phase operation together.

My theory: SIMH isn't correctly emulating the behavior when multiple 
seeks complete at the same (or nearly the same) simulated time. On real 
hardware, you'd get separate interrupts as each drive's seek finishes, 
with rkds properly reflecting which drive triggered each interrupt. But 
in emulation, if two seeks "complete simultaneously," you might only get 
one interrupt, or rkds might only reflect one of the drives.

If that happens, the other drive's seek completion never triggers 
devstart(), so its read/write never actually happens. The process 
waiting in iowait() sleeps forever on B_DONE that never gets set. Hung 
process, exactly as you're seeing.

The busy-waits in the driver (waiting for CTLRDY after commands, waiting 
for DRY|ARDY in error recovery) could also be problematic if the 
emulated status bits don't update with the timing the code expects.

This would explain why v5 works: if they rewrote it to serialize 
operations more conservatively, or changed the state machine to not 
depend on precise interrupt ordering, the emulation timing issues 
wouldn't matter as much.

Might be worth instrumenting rkintr() to log the rkcs and rkds values on 
each interrupt, and see if the drive identification is coming through 
correctly when multiple disks are in use.

cheers

-- Briam R.

On 1/15/26 8:41 AM, Angelo Papenhoff via TUHS wrote:
> I was wondering about the RK driver, because there are issues with it.
> The v4 RK11 driver does not work with simh emulation correctly when
> using multiple disks. I've had to use the v5 driver for my v4
> installation guide to get a usable system. Looking at the code i had the
> impression that the v4 driver is fine (it also matches the nsys RK
> driver, which i've also had trouble with recently. haven't tried v5 RK
> with nsys yet). What i suspect is happening is that the seek/read dance
> isn't working correctly, either in simh, or there were faulty
> assumptions that only work on real hardware more or less accidentially
> (the rewrite in v5 might suggest the latter).
> In any case it looks like blocks aren't being read correctly, and
> whatever process is waiting for the read will hang.
>
> Would be nice to get to the bottom of this.
>
> cheers,
> aap

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[George Michaelson via TUHS]

If you patch an OS to run on a buggy simulator you're corrupting source to
fix non existent bugs in that source.

The fix is to get simh to respect interrupt signalling surely?

Pragmatism says fix the v4 code, sure.

G

On Fri, 16 Jan 2026, 4:08 am Briam Rodriguez via TUHS, <tuhs@tuhs.org>
wrote:

> Angelo,
>
> I took a look at the v4 RK driver source to see what might be going on
> here.
>
> The v4 driver does something clever with multiple disks: overlapped
> seeks. When rkstart() runs, it iterates through all four drive queues
> and fires off SEEK commands for every drive that has pending work. The
> idea is that while drive 0 is seeking, drive 1 can be transferring data.
> Good for throughput on real hardware.
>
> The tricky part is the interrupt handler. When an interrupt comes in,
> rkintr() checks the SEEKCMP bit in rkcs to figure out if this is a "seek
> finished" or "transfer finished" interrupt. For seek completion, it
> reads bits 13-15 of rkds to determine which drive just finished seeking,
> then kicks off the actual data transfer for that drive.
>
> There's a global variable rk_ap that tracks which drive queue is
> currently mid-transfer. It gets set when a seek completes and used when
> the subsequent transfer completes. This is the state that ties the
> two-phase operation together.
>
> My theory: SIMH isn't correctly emulating the behavior when multiple
> seeks complete at the same (or nearly the same) simulated time. On real
> hardware, you'd get separate interrupts as each drive's seek finishes,
> with rkds properly reflecting which drive triggered each interrupt. But
> in emulation, if two seeks "complete simultaneously," you might only get
> one interrupt, or rkds might only reflect one of the drives.
>
> If that happens, the other drive's seek completion never triggers
> devstart(), so its read/write never actually happens. The process
> waiting in iowait() sleeps forever on B_DONE that never gets set. Hung
> process, exactly as you're seeing.
>
> The busy-waits in the driver (waiting for CTLRDY after commands, waiting
> for DRY|ARDY in error recovery) could also be problematic if the
> emulated status bits don't update with the timing the code expects.
>
> This would explain why v5 works: if they rewrote it to serialize
> operations more conservatively, or changed the state machine to not
> depend on precise interrupt ordering, the emulation timing issues
> wouldn't matter as much.
>
> Might be worth instrumenting rkintr() to log the rkcs and rkds values on
> each interrupt, and see if the drive identification is coming through
> correctly when multiple disks are in use.
>
> cheers
>
> -- Briam R.
>
> On 1/15/26 8:41 AM, Angelo Papenhoff via TUHS wrote:
> > I was wondering about the RK driver, because there are issues with it.
> > The v4 RK11 driver does not work with simh emulation correctly when
> > using multiple disks. I've had to use the v5 driver for my v4
> > installation guide to get a usable system. Looking at the code i had the
> > impression that the v4 driver is fine (it also matches the nsys RK
> > driver, which i've also had trouble with recently. haven't tried v5 RK
> > with nsys yet). What i suspect is happening is that the seek/read dance
> > isn't working correctly, either in simh, or there were faulty
> > assumptions that only work on real hardware more or less accidentially
> > (the rewrite in v5 might suggest the latter).
> > In any case it looks like blocks aren't being read correctly, and
> > whatever process is waiting for the read will hang.
> >
> > Would be nice to get to the bottom of this.
> >
> > cheers,
> > aap
>

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[Briam Rodriguez via TUHS]

George,

To be clear, I'm not advocating patching v4 to work around emulator 
bugs. My email was purely diagnostic - trying to figure out /where/ the 
bug actually lives.

If the issue is SIMH not correctly handling overlapped seeks and 
interrupt coalescing, then yes, SIMH should be fixed. But before anyone 
fixes anything, it helps to understand the failure mode. That's all I 
was doing: reading the driver code and theorizing about what timing 
assumptions might not hold under emulation.

The suggestion to instrument rkintr() was to /confirm/ whether the 
emulator is the culprit, not to change the driver logic.

cheers, Briam

On 1/15/26 2:44 PM, George Michaelson via TUHS wrote:
> If you patch an OS to run on a buggy simulator you're corrupting source to
> fix non existent bugs in that source.
>
> The fix is to get simh to respect interrupt signalling surely?
>
> Pragmatism says fix the v4 code, sure.
>
> G
>
> On Fri, 16 Jan 2026, 4:08 am Briam Rodriguez via TUHS,<tuhs@tuhs.org>
> wrote:
>
>> Angelo,
>>
>> I took a look at the v4 RK driver source to see what might be going on
>> here.
>>
>> The v4 driver does something clever with multiple disks: overlapped
>> seeks. When rkstart() runs, it iterates through all four drive queues
>> and fires off SEEK commands for every drive that has pending work. The
>> idea is that while drive 0 is seeking, drive 1 can be transferring data.
>> Good for throughput on real hardware.
>>
>> The tricky part is the interrupt handler. When an interrupt comes in,
>> rkintr() checks the SEEKCMP bit in rkcs to figure out if this is a "seek
>> finished" or "transfer finished" interrupt. For seek completion, it
>> reads bits 13-15 of rkds to determine which drive just finished seeking,
>> then kicks off the actual data transfer for that drive.
>>
>> There's a global variable rk_ap that tracks which drive queue is
>> currently mid-transfer. It gets set when a seek completes and used when
>> the subsequent transfer completes. This is the state that ties the
>> two-phase operation together.
>>
>> My theory: SIMH isn't correctly emulating the behavior when multiple
>> seeks complete at the same (or nearly the same) simulated time. On real
>> hardware, you'd get separate interrupts as each drive's seek finishes,
>> with rkds properly reflecting which drive triggered each interrupt. But
>> in emulation, if two seeks "complete simultaneously," you might only get
>> one interrupt, or rkds might only reflect one of the drives.
>>
>> If that happens, the other drive's seek completion never triggers
>> devstart(), so its read/write never actually happens. The process
>> waiting in iowait() sleeps forever on B_DONE that never gets set. Hung
>> process, exactly as you're seeing.
>>
>> The busy-waits in the driver (waiting for CTLRDY after commands, waiting
>> for DRY|ARDY in error recovery) could also be problematic if the
>> emulated status bits don't update with the timing the code expects.
>>
>> This would explain why v5 works: if they rewrote it to serialize
>> operations more conservatively, or changed the state machine to not
>> depend on precise interrupt ordering, the emulation timing issues
>> wouldn't matter as much.
>>
>> Might be worth instrumenting rkintr() to log the rkcs and rkds values on
>> each interrupt, and see if the drive identification is coming through
>> correctly when multiple disks are in use.
>>
>> cheers
>>
>> -- Briam R.
>>
>> On 1/15/26 8:41 AM, Angelo Papenhoff via TUHS wrote:
>>> I was wondering about the RK driver, because there are issues with it.
>>> The v4 RK11 driver does not work with simh emulation correctly when
>>> using multiple disks. I've had to use the v5 driver for my v4
>>> installation guide to get a usable system. Looking at the code i had the
>>> impression that the v4 driver is fine (it also matches the nsys RK
>>> driver, which i've also had trouble with recently. haven't tried v5 RK
>>> with nsys yet). What i suspect is happening is that the seek/read dance
>>> isn't working correctly, either in simh, or there were faulty
>>> assumptions that only work on real hardware more or less accidentially
>>> (the rewrite in v5 might suggest the latter).
>>> In any case it looks like blocks aren't being read correctly, and
>>> whatever process is waiting for the read will hang.
>>>
>>> Would be nice to get to the bottom of this.
>>>
>>> cheers,
>>> aap

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[Clem Cole via TUHS]

Plus remember that V6 and V7 work fine and they do overlapped I/O also.
I’ll believe it’s possible for SIMH to be broken (hey UNIX had a history of
exposing HW issues that the DEC OSs and diagnostics, did not).  But I think
we need to show Bob the issue (I’ve sent him a heads up).

Sent from a handheld expect more typos than usual


On Thu, Jan 15, 2026 at 2:48 PM Briam Rodriguez via TUHS <tuhs@tuhs.org>
wrote:

> George,
>
> To be clear, I'm not advocating patching v4 to work around emulator
> bugs. My email was purely diagnostic - trying to figure out /where/ the
> bug actually lives.
>
> If the issue is SIMH not correctly handling overlapped seeks and
> interrupt coalescing, then yes, SIMH should be fixed. But before anyone
> fixes anything, it helps to understand the failure mode. That's all I
> was doing: reading the driver code and theorizing about what timing
> assumptions might not hold under emulation.
>
> The suggestion to instrument rkintr() was to /confirm/ whether the
> emulator is the culprit, not to change the driver logic.
>
> cheers, Briam
>
> On 1/15/26 2:44 PM, George Michaelson via TUHS wrote:
> > If you patch an OS to run on a buggy simulator you're corrupting source
> to
> > fix non existent bugs in that source.
> >
> > The fix is to get simh to respect interrupt signalling surely?
> >
> > Pragmatism says fix the v4 code, sure.
> >
> > G
> >
> > On Fri, 16 Jan 2026, 4:08 am Briam Rodriguez via TUHS,<tuhs@tuhs.org>
> > wrote:
> >
> >> Angelo,
> >>
> >> I took a look at the v4 RK driver source to see what might be going on
> >> here.
> >>
> >> The v4 driver does something clever with multiple disks: overlapped
> >> seeks. When rkstart() runs, it iterates through all four drive queues
> >> and fires off SEEK commands for every drive that has pending work. The
> >> idea is that while drive 0 is seeking, drive 1 can be transferring data.
> >> Good for throughput on real hardware.
> >>
> >> The tricky part is the interrupt handler. When an interrupt comes in,
> >> rkintr() checks the SEEKCMP bit in rkcs to figure out if this is a "seek
> >> finished" or "transfer finished" interrupt. For seek completion, it
> >> reads bits 13-15 of rkds to determine which drive just finished seeking,
> >> then kicks off the actual data transfer for that drive.
> >>
> >> There's a global variable rk_ap that tracks which drive queue is
> >> currently mid-transfer. It gets set when a seek completes and used when
> >> the subsequent transfer completes. This is the state that ties the
> >> two-phase operation together.
> >>
> >> My theory: SIMH isn't correctly emulating the behavior when multiple
> >> seeks complete at the same (or nearly the same) simulated time. On real
> >> hardware, you'd get separate interrupts as each drive's seek finishes,
> >> with rkds properly reflecting which drive triggered each interrupt. But
> >> in emulation, if two seeks "complete simultaneously," you might only get
> >> one interrupt, or rkds might only reflect one of the drives.
> >>
> >> If that happens, the other drive's seek completion never triggers
> >> devstart(), so its read/write never actually happens. The process
> >> waiting in iowait() sleeps forever on B_DONE that never gets set. Hung
> >> process, exactly as you're seeing.
> >>
> >> The busy-waits in the driver (waiting for CTLRDY after commands, waiting
> >> for DRY|ARDY in error recovery) could also be problematic if the
> >> emulated status bits don't update with the timing the code expects.
> >>
> >> This would explain why v5 works: if they rewrote it to serialize
> >> operations more conservatively, or changed the state machine to not
> >> depend on precise interrupt ordering, the emulation timing issues
> >> wouldn't matter as much.
> >>
> >> Might be worth instrumenting rkintr() to log the rkcs and rkds values on
> >> each interrupt, and see if the drive identification is coming through
> >> correctly when multiple disks are in use.
> >>
> >> cheers
> >>
> >> -- Briam R.
> >>
> >> On 1/15/26 8:41 AM, Angelo Papenhoff via TUHS wrote:
> >>> I was wondering about the RK driver, because there are issues with it.
> >>> The v4 RK11 driver does not work with simh emulation correctly when
> >>> using multiple disks. I've had to use the v5 driver for my v4
> >>> installation guide to get a usable system. Looking at the code i had
> the
> >>> impression that the v4 driver is fine (it also matches the nsys RK
> >>> driver, which i've also had trouble with recently. haven't tried v5 RK
> >>> with nsys yet). What i suspect is happening is that the seek/read dance
> >>> isn't working correctly, either in simh, or there were faulty
> >>> assumptions that only work on real hardware more or less accidentially
> >>> (the rewrite in v5 might suggest the latter).
> >>> In any case it looks like blocks aren't being read correctly, and
> >>> whatever process is waiting for the read will hang.
> >>>
> >>> Would be nice to get to the bottom of this.
> >>>
> >>> cheers,
> >>> aap

[TUHS] Re: RK disk, was UNIX v4 Source Code Commentary

[John Levine via TUHS]

It appears that Clem Cole via TUHS <clemc@ccc.com> said:
>Plus remember that V6 and V7 work fine and they do overlapped I/O also.

In 1975 at Yale I brought up v5 or v6 at a PDP-11 we had. I distinctly
recall that the RK11 driver was purely sequential because of
controller hardware bugs that made overlapped seeks unreliable. I
heard that they'd given up on a more sophsticated driver.

We added a pair of RP20 20MB disk pack drives.  The RP controller
worked fine so one of the first things I did was to write an RP driver
that sorted requests for each drive and did seek overlap.  It made
a difference, maybe 25% better throughput.

R's,
John

[TUHS] Re: UNIX v4 Source Code Commentary - complete book now available

[Angelo Papenhoff via TUHS]

So i tried v4 on my own pdp11/40 emulator [1] and there it seems to work
fine (after i fixed a bug in the RK controller). So i guess this is a
simh bug?

aap 

[1] https://github.com/aap/pdp11

On 15/01/26, Angelo Papenhoff via TUHS wrote:
> Looks very nice, thanks!
> 
> I was wondering about the RK driver, because there are issues with it.
> The v4 RK11 driver does not work with simh emulation correctly when
> using multiple disks. I've had to use the v5 driver for my v4
> installation guide to get a usable system. Looking at the code i had the
> impression that the v4 driver is fine (it also matches the nsys RK
> driver, which i've also had trouble with recently. haven't tried v5 RK
> with nsys yet). What i suspect is happening is that the seek/read dance
> isn't working correctly, either in simh, or there were faulty
> assumptions that only work on real hardware more or less accidentially
> (the rewrite in v5 might suggest the latter).
> In any case it looks like blocks aren't being read correctly, and
> whatever process is waiting for the read will hang.
> 
> Would be nice to get to the bottom of this.
> 
> cheers,
> aap
> 
> On 12/01/26, Briam Rodriguez via TUHS wrote:
> > Hello,
> > 
> > Following the incredible recovery of the UNIX v4 tape from the University
> > of Utah last month, I've written a comprehensive line-by-line commentary
> > on the entire UNIX Fourth Edition source code.
> > 
> > The book covers:
> > - The kernel (boot, processes, memory management, scheduling)
> > - The file system (inodes, buffer cache, namei)
> > - Device drivers (TTY, RK05 disk, character devices)
> > - User space (shell, utilities, C compiler, assembler)
> > - Plus appendices with system call reference, file formats, and PDP-11 guide
> > 
> > It's open source (CC BY-NC-SA 4.0) and available on GitHub:
> > 
> > https://github.com/unix-v4-commentary/unix-v4-source-commentary
> > 
> > The PDF is included in the repo for those who just want to read.
> > 
> > It is my sincerest hope that this book can help someone, and I'd 
> > appreciate any feedback (and changes!).
> > 
> > Many thanks to Robert Ricci, and Al Kossow, and everyone involved in 
> > recovering this historic code.
> > 
> > Without that work, this book wouldn't have been possible. Also thanks to 
> > Mr. Warren for letting me in to the mailing list!
> > 
> > Please don't beat me up too bad!
> > 
> > Humbly yours,
> > 
> > Briam Rodriguez
> >