[TUHS] What It Takes to Read Lions in 2026

[Otto Moerbeek via TUHS]

"Getting Started" talks about the machine, not about the reader :)

 -Otto

On Thu, Jul 30, 2026 at 07:56:10AM -0500, Will Senn via TUHS wrote:

> Clem,
> 
> Wow. This makes so much sense. I "randomly" picked page 28 as a starting
> point, never mind that the section was called "Getting Started". That was
> possibly the worst/best place to begin, because it is where the PDP11 ->
> unix transition takes place. When Lions talks about it, it's clear that he's
> speaking from the unix side of things with enough PDP to orient a denizen of
> the times, but not a techie from the future who is ot familiar with stuff
> like core, I/O regions of memory, or severe hardware limitations. Having
> struggled to parse every sentence along the way, I've made the journey from
> the processor handbook - where I found a typo in the 11/40 version... it
> says:
> 
>     Certain memory locations have been reserved by the system for inter·
>     rupt and trap handling, processor stacks, general registers, and
> peripheral
>     device registers. K.ernel virtual addresses from 0 to 370, are always
> re-
>     served and those to 777, are reserved on large system configurations for
>     traps and interrupt handling. The top 4,096 word addresses (from
>     770000, up) have been reserved for general registers and peripheral
>     devices.
> 
> But, after a couple of hours of head scratching it dawned on me that
> 770000-777777 was only 2K words and couldn't possibly be right, 760000 is
> the correct number. Which is click 7600, which is what's loaded into KIPAR7,
> which the m40 assist maps as IO. Which is properly described in the 1976
> 11/04/34/45/44 version as:
> 
>     If the Memory Management option is not used, an octal address be-
>     tween 160 000 and 177 777 is interpreted as 760 000 to 777 777. That
>     is, if bit 15, 14 and 13 are 1 's, then bits 17 and 16 (the extended ad-
>     dress bits) are considered to be 1's, which relocates the last 4K words.
>     (8K bytes) to become the highest location accessed by the UNIBUS.
> 
> Then on into the peripherals book, the memory management options book, and
> the v6 manual. In addition, whereas previously, I ignored the source code,
> now I find it invaluable. Where it says _end is some linker thing (I
> originally read it as a pseudo op, but it's more something the loader adds).
> I just pulled up the source, figured out it adds it to the binary if it's
> referenced in code and that it refers to the boundary of the image (one past
> the last byte) or in the "as" documentation where Dennis say it's a rather
> ordinary 2 pass assembler with no macros. I no longer take this as gospel,
> it's off to the as source where it turns out it's anything but ordinary, not
> really a two pass assembler (two programs, one that builds a very nice
> compact representation and the other that takes two passes)  and it trades
> an insane amount of language affordance for macros... heck it'll even let
> you define your own assembly instructions :).
> 
> It's the little things :).
> 
> Will
> 
> On 7/28/26 9:07 PM, Clem Cole via TUHS wrote:
> > Will/Matt,
> > 
> > You both make interesting observations, and I tried to go back a little and
> > remember what resources I had when I encountered Lions (and made my
> > xerographic copy).  At the time (which I think was late 1977 or early 78),
> > I had my own copy of the 1974/75 PDP-11 04/34/45/55 Processor Handbook [
> > https://bitsavers.trailing-edge.com/pdf/dec/pdp11/handbooks/PDP-11_04-55_Processor_Handbook_1976.pdf]
> > and the 1976 PDP-11 Peripherals Handbook†  [
> > https://bitsavers.trailing-edge.com/pdf/dec/pdp11/handbooks/PDP-11_PeripheralsHbk_1976.pdf]
> >   Note I had the 34 docs, not the 40 docs.   I also had access to the docs
> > from Sixth Edition, such as the C Reference manual.
> > 
> > Also remember that I was not using it as a course text, which is why he
> > wrote it.  When I discovered it, the book was just a wonderful resource
> > that helped explain in more detail a lot of things I already had an inkling
> > of, and as I look back, probably corrected some misunderstandings too.
> > 
> > That said, before I read Lions, I had already been programming UNIX for a
> > year or two on the 11/40E (IUS and SUS) in the CS Dept.  We had converted
> > from Fifth Edition to Sixth (I personally had very brief experiences with
> > Fifth - it was in my "what is this strange system and language phase,"
> > introduction to UNIX having come over from BLISS and both a DEC and IBM
> > flavor of how OS's were supposed to present themselves).  But in the summer
> > before I saw Lions, we had received our first 11/34 in the EE Dept.  We
> > couldn't just use Dennis's distribution tape, since a 34 is a 40-class
> > processor (which are similar but different enough; it's not going to "just
> > work" — *i.e*., not something the stock Sixth Edition knew about).  So, we
> > bootstrapped the EE 34 from IUS, which was tricky because we had to add 34
> > support to mch40.s, more importantly, the 34 didn't have the CSV/CRET in
> > the writable microcode of the 11/40Es that the C compiler on the CS systems
> > expected (I have memories of walking back and forth between the two
> > buildings creating yet another RK05 boot image when we found some other
> > important program that was expecting CSV/CRET but weren't far/stable enough
> > along in the bootstrap to correct it ourselves).
> > 
> > FWIW: I had had some exposure to RT-11 on an 11/05 [running from DEC
> > cassette tapes], as well as programming the PDP-8 running TSS/8 and the 10s
> > under TOPS, as well as working for the Computer Center supporting York/APL
> > on the IBM 360/67.  But I think most importantly for my UNIX kernel
> > experience, I had started to work on the Computer Center's version of the
> > CMU Front End, trying to add support for the 11/45 they had running RSTS
> > for the School of Humanities and Social Science.   As I have mentioned in
> > other emails, the CMU FE was a standalone system (no OS) with a ton of
> > serial ports, a card reader and printer, and some sort of interface to
> > larger systems (in the CC's case, the 360 for interactive serial ports and
> > as an RJE station for the 360 and Univac 1008, and we were adding the then
> > new RSTS system).  At that point, it was based on an 11/15 (no MMU, of
> > course, and the code was primarily in BLISS-11 with a very small assembler
> > assist).  The key is I was already inoculated with the core PDP-11 ISA and
> > differences between models, so much of what you are commenting about with
> > PDP-11-ism, such as the RESET instruction or the PARS, was already
> > something I had learned before. To me, Lions was explaining how Ken uses
> > them in the kernel.
> > 
> > My point is I didn't walk into reading Lions without some core experience
> > with the PDP-11 family.  Some of the peripherals, like the KL/DLs and
> > clock, I was certainly extremely familiar with, and I already understood
> > about MMUs (the 67 running TSS was IBM's first VM system). Across so many
> > different CMU systems, we had aftermarket disks on most of them [the DEC
> > RP03/04 were made by Univac, but they were actually clones of the IBM
> > 2314/2316 (only slightly different)].   IIRC we had CDC flavors of them
> > which they called the 84x series, and IIRC we had to modify the rp.c driver
> > slightly to make them work properly.  So I had already learned how to hack
> > the disk drivers by then.     But I never had access to real manuals for
> > any of the DEC peripherals other than the 76 Peripherals Handbook until we
> > got one of the first RK07s and the RK611/711 controller.   Danny Klein and
> > I wrote the first UNIX driver for it, cribbing from the already hacked
> > RP04/5/6 driver and reading Dennis' V6 driver manual.  I had already been
> > doing a small amount of the kernel mods by then, and we had started to
> > write fsck(8) as well.  But when I saw it (and made my own copy), I thought
> > Lions helped me better understand the system than I had before.  It
> > certainly gave me more confidence about what subsystems I would attack
> > (more in a minute).
> > 
> > At some point, but it had to have been after I saw Lions, Ted Kowalski had
> > a xerographic copy of the proofs for K&R1 in a binder (which I copied), and
> > by late 78 I had obtained a xerographic copy of the "Unix program
> > description" doc that Matt referred to (I think I got that from Phil Karn,
> > but it might have been Ted).
> > 
> > FWIW: A few years later, my old friend and then colleague at Tektronix,
> > Mike Zuhl, made an interesting observation, which I think actually plays
> > into your comments about Lions.  Zuhl was one of the Purdue EE UNIX folks
> > (like the late George Goble and Ward Cunningham).   Zuhl said: *"Hacking on
> > the Unix kernel is a lot like riding a motorcycle.  At first you are scared
> > sh*tless that you don't want to screw up.   After a while, you get
> > confident in your abilities and are willing to try anything.  Finally, you
> > realize it is really just an incredibly beautiful hack that works in a
> > manner like no other, and you start to respect it and those that came
> > before you*."
> > 
> > For me, reading Lions was part of my transition in the third phase.  He
> > explains things I basically knew before at a more macro level.
> > 
> > My thoughts/recollections if it is of any help,
> > Clem
> > 
> > †  To this day, I still think the 1976 Peripherals Handbook was the best
> > one DEC made, and if you are looking at Sixth or Seventh Editions, it is
> > really all you need for most of the peripherals they supported.   Later
> > ones include some information about later products such as the RL01/2 and
> > RK06/7, but they dropped many of them outright in some cases, and in others
> > the core descriptions are not nearly as detailed/useful.
> > 
> > On Tue, Jul 28, 2026 at 2:41 PM segaloco via TUHS <tuhs at tuhs.org> wrote:
> > 
> > > On Tuesday, July 28th, 2026 at 10:14, Will Senn via TUHS <tuhs at tuhs.org>
> > > wrote:
> > > 
> > > > Lions is great, but today's reader needs more of a leg up. I think it
> > > > illustrates how much architectural knowledge his original audience could
> > > > take for granted. Nearly fifty years later, recovering that context has
> > > > become part of reading the book. So, reading through Lions in 2026 is an
> > > > archaeological dig, really :). That said, if you're planning to read
> > > > Lions with any depth, be sure to minimally have on hand:
> > > > 
> > > > * Lions Commentary
> > > > 
> > > > * Lions Source Code
> > > > 
> > > > * PDP-11/40 Processor Handbook
> > > > 
> > > > * KT11-D Memory Management Option User Manual
> > > > 
> > > > * Repeatable notes for setting up a working lab
> > > > 
> > > > Later,
> > > > 
> > > > Will
> > > > 
> > > For the record, the intro does indicate what auxiliary knowledge may be
> > > necessary, pointing the reader to the manual, several papers such as C
> > > tutorials and UNIX for Beginners, as well as listing knowledge of the
> > > following PDP-11 hardware useful:
> > > 
> > > - PDP11/40
> > > - RK05
> > > - LP11
> > > - PC11
> > > - KL11
> > > 
> > > You also do get a bit of hardware exposition, albeit not too much, in
> > > Chapter 2.
> > > 
> > > This implies having the PDP-11 Peripherals Handbook on hand would also be
> > > helpful.  Naturally our biases allow us to overlook this, but having both
> > > the UNIX Assember Manual and C Reference Manual on hand would be helpful to
> > > the uninitiated as those are the two languages at play in the source
> > > volume.  Not sure how necessary this would be in practice but UNIX is an
> > > ASCII system, so non-ASCII-ites, however rare these days, would be going in
> > > with some unhelpful biases, but I don't know if that would peg the ASCII
> > > standard as required context.  I'm a sucker for building complete reference
> > > documentation graphs...so I'm going to hold my urge further for now.
> > > 
> > > Still, it would be an interesting exercise to pursue the full graph of
> > > primary references needed to establish a normative reference graph for
> > > Lions's Commentary.
> > > 
> > > Will, I don't know if this would be a comparable follow-on project, but
> > > there is the Program Description document published with USG UNIX that
> > > serves as another detailed analysis of the UNIX kernel[1] that may be worth
> > > inspecting with a similar lens.  By the way, I have a later hardcopy of [1]
> > > issued with Program Generic 3.  Unfortunately its just a reprint of the
> > > Program Generic 2 version and does not include the kernel changes in PG3,
> > > but it is complete, so I plan on scanning it in my next round of documents.
> > > 
> > > - Matt G.
> > > 
> > > [1] - unix_program_description_jan_1976.pdf
> > >