PiDP-8/I Software

inst
test

examples/*.fc

src/*.[ch]
src/*.in

src/cc8/*/*.[ch]
src/cc8/include/*
src/cc8/os8/*.sb
src/cc8/os8/bldcc8.bi

src/PDP8/pdp8_*.[ch]
src/PDP8/pidp8i.c.in

doc/simh/*.pdf
test/*

.agignore

# Creators of and Major Contributors to the PiDP-8/I Project

*   **[Oscar Vermeulen](mailto:oscar.vermeulen@hotmail.com)**:

    -   Creator of the project (both hardware and software)
    
    -   Author of the initial modifications to the SIMH PDP-8 simulator
        necessary to make it use the PiDP-8/I front panel hardware

    -   Curator of the default set of binary demo media

    -   Author of the simulator setup scripts

    -   Initiator of much else in the project

    -   Author of the bulk of the documentation

    -   Host and major contributor to the PiDP-8/I support forum on
        Google Groups

    -   Hardware kit assembler and distributor

*   **Robert M Supnik** is the primary author of the SIMH PDP-8
    simulator upon which this project is based.

*   **Mike Barnes** ported Oscar Vermeulen's SIMH 3.9 based PiDP-8/I
    simulator to the new SIMH 4.0 code base.  (September 2015.)

*   **Dylan McNamee** ported the software to Buildroot for the official
    2015.12.15 binary OS images and helped to merge the James L-W
    "alt-serial" mode in.

*   **Mark G. Thomas** wrote the installation scripts for the 2015.12.15
    release, which were folded into the `make install` handler within
    the current `Makefile.in`. He also wrote the version of the SysV

    init script shipped here as `etc/pidp8i-init.in`.

*   **[Ian Schofield](mailto:isysxp@gmail.com)** modified the LED lamp
    driving code in the simulator to better simulate the incandescent lamps
    in the original PDP-8/I hardware.  (The bulk of his original code
    has since been rewritten, but the core idea remains, and it is
    doubtful whether the current method would exist without his
    instigation.)

*   **[Henk Gooijen](mailto:henk.gooijen@boschrexroth.nl)** pushed the
    PDP-8 simulator's internal EAE step counter value down into the
    PiDP-8/I's LED manipulation code, without which the step counter
    LEDs remain dark even when using the EAE.

*   **[Paul R. Bernard](mailto:prb@downspout.ca)** wrote `src/test.c`
    and the core of what now appears as `doc/pidp8i-test.md`. (The program
    builds and installs as `pidp8i-test`.)  He also provided a one-line
    fix that completes the work of Henk Gooijen's step counter patch.

*   **[Rick Murphy](mailto:k1mu.nospam@gmail.com)** is the current
    maintainer of [OS/8 Adventure][advent] which we've included in our
    OS/8 disk image. He's also provided several other files which have
    landed in the distribution such as the [VTEDIT][vtedit] feature. He
    also optimized the `pep001.pal` example so that it fits into a
    single page of PDP-8 core.

*   **[Tony Hill](mailto:hill.anthony@gmail.com)** merged all the
    upstream SIMH changes produced between late September 2015 and late
    December 2016 into the PiDP-8/I simulator. This is the basis for the
    current automatic upstream feature merge capability, which is why
    many releases since December 2016 include an update to the latest
    version of upstream SIMH. His contributions are made to the project
    [as `tony`][thcomm].

*   **[Jonathan Trites](mailto:tritesnikov@gmail.com)** wrote the

    initial version of the script now called `libexec/mkos8`, which
    builds the OS/8 disk images from source tapes.


*   **[Bill Cattey](mailto:bill.cattey@gmail.com)** is the project lead


    and primary developer of the system that builds the OS/8 RK05 disk
    images from source tapes. He greatly extended the `mkos8` script,
    curated the tape collection we ship as `media/.../*.tu56`, created
    some of those tapes, and more. He has also contributed to other
    areas of the software project. His contributions are made to the
    project [as `poetnerd`][pncomm].

*   **[Warren Young](mailto:tangentsoft@gmail.com)** Did everything



    listed in [the change log][cl] that is not attributed to anyone
    else.




    His contributions are made to the project [as `tangent`][wycomm],
    though keep in mind that some of those are commits of external
    contributions made by people who do not have commit rights on our
    software repository. The changelog provides proper attribution for
    these where the checkin comments do not.


[advent]: http://www.rickmurphy.net/advent/
[cl]:     https://tangentsoft.com/pidp8i/doc/trunk/ChangeLog.md
[pncomm]: https://tangentsoft.com/pidp8i/timeline?u=poetnerd
[thcomm]: https://tangentsoft.com/pidp8i/timeline?u=tony
[vtedit]: https://tangentsoft.com/pidp8i/wiki?name=Using+VTEDIT
[wycomm]: https://tangentsoft.com/pidp8i/timeline?u=tangent

# Licenses

The PiDP-8/I software distribution is an agglomeration of software from
multiple sources.  Several different licenses apply to its parts.  This
file guides you to those individual licenses.


## <a id="simh"></a>SIMH License

Most of the files in this software distribution are released under the
terms of the SIMH license, a copy of which typically appears at the top
of each file it applies to. This includes not only SIMH proper but also
several files written by PiDP-8/I software project contributors who
chose to license their contributions under the same license.

For a few files, textual inclusion of the license inside the file itself
was impractical, so this license is applied by reference to [a file
included with the distribution][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md


## <a id="hw"></a>PiDP-8/I Design Files

The PiDP-8/I design files in [`hardware/pidp8i`][hwp] were released
under the Creative Commons [Attribution-NonCommercial-ShareAlike 4.0
International][ccl] license [on the mailing list][pdp8il] by their
author, Oscar Vermeulen.

[ccl]: https://creativecommons.org/licenses/by-nc-sa/4.0/
[hwp]: https://tangentsoft.com/pidp8i/dir?name=hardware/pdp8i&ci=trunk
[pdp8il]: https://groups.google.com/d/msg/pidp-8/bcIH9uEB_kU/zg9uho7NDAAJ


## <a id="autosetup"></a>autosetup License

The `configure` script and the contents of the `autosetup` directory are
released under the FreeBSD license given in [`autosetup/LICENSE`][as].

[as]: https://tangentsoft.com/pidp8i/doc/trunk/autosetup/LICENSE


## <a id="palbart"></a>palbart License

The `palbart` program and its manual page are released under the terms
of the license given in [`src/palbart/LICENSE.md`][pl].

[pl]: https://tangentsoft.com/pidp8i/doc/trunk/src/palbart/LICENSE.md


## <a id="d8tape"></a>d8tape License

The `d8tape` program is distributed under the license given in
[`src/d8tape/LICENSE.md`][d8tl].

[d8tl]: https://tangentsoft.com/pidp8i/doc/trunk/src/d8tape/LICENSE.md


## <a id="cc8"></a>CC8 Compiler License

The license for the `src/cc8` subtree is messy as it comes to us from
multiple authors over many years.

There are two compilers here.

First we have the OS/8 "native" compiler in `src/cc8/os8`, which is
entirely Ian Schofield's work, released under the terms of the [GNU
General Public License version 3][gpl3].

Then we have the CC8 cross-compiler which is based on Ron Cain's
[Small-C][smc], originally published in [Dr.  Dobbs' Journal][ddj].
Wikipedia describes Small-C as "copyrighted but sharable," which I take
to mean that we cannot claim it as our exclusive property, but we can
modify it and distribute those modifications to others, which is what
we're doing here.

Ian Schofield then took the Small-C source base and added a SABR
back-end, `code8.c`, which is also distributed under the [GPLv3][gpl3].

There is [another PDP-8 C compiler project][smsc] based on Small-C by
Vincent Slyngstad, which uses an entirely different approach for code
generation.  Ian Schofield took some of the library routines from this
implementation.

[ddj]:  https://en.wikipedia.org/wiki/Dr._Dobb%27s_Journal
[gpl3]: https://tangentsoft.com/pidp8i/doc/trunk/src/cc8/LICENSE.txt
[smc]:  https://en.wikipedia.org/wiki/Small-C
[smsc]: http://so-much-stuff.com/pdp8/C/C.php


## <a id="os8"></a>OS/8 License

The OS/8 media images included with this software distribution are
released under the Digital License Agreement presented in
[`media/os8/LICENSE.md`][dla].

[dla]: https://tangentsoft.com/pidp8i/doc/trunk/media/os8/LICENSE.md


## <a id="dec"></a>Other DEC Software

The other files in the [`media`][md] and [`examples`][ed] directories
that originate from Digital Equipment Corporation are believed to fall
under the [public domain license][pdp8pd] DEC released all their PDP-8
software under after it stopped being ecomonmically viable. Documented
releases for specific software (e.g. TSS/8) may be difficult to come by,
however.

[md]: https://tangentsoft.com/pidp8i/dir?ci=trunk&name=media
[ed]: https://tangentsoft.com/pidp8i/dir?ci=trunk&name=examples
[pdp8pd]: http://mailman.trailing-edge.com/pipermail/simh/2017-January/016164.html


## <a id="etos"></a>ETOS License

ETOS was a commercial product produced outside of DEC. No public
documented declaration of license is known to be available for it, but
we have [a third-hand report][el] that its creators are fine with ETOS
being redistributed.

[el]: http://mailman.trailing-edge.com/pipermail/simh/2017-January/016169.html

# PiDP-8/I Changes

## Version 2017.12.eh? — The "Languages and Custom OS/8 Disk Packs" release

*   All prior versions were shipping `os8.rk05`, a "Field Service
    Diagnostic" OS/8 disk pack image with uncertain provenance,
    configuration, and modification history.  We have replaced that with
    a script run at build time that programmatically assembles a set of
    clean OS/8 RK05 disk images from curated, pristine, tested sources
    based on the user's chosen configuration options.

    This provides the following features and benefits as compared to the
    old `os8.rk05`:

    -   The PiDP-8/I software build process now builds up to three RK05
        disk images:

        -   `os8v3d-bin.rk05` is a bootable OS/8 V3D disk configured
            according to your chosen configuration options, which are
            described below and in [`README.md`][tlrm].  It is made from
            the pristine DECtape images shipped by DEC for OS/8 V3D plus
            several third-party tapes curated for and built by the
            project's maintainers.  See [the OS/8 media `README.md`
            file][os8rm] for more details.

        -   `os8v3d-patched.rk05` is a copy of the `bin` disk with
            [most][os8p] of the patches DEC published over the years for
            OS/8 V3D applied.  That set of patches was chosen and tested
            for applicability to our modern PiDP-8/I world and for
            mutual compatibility.

            This is the boot disk used for the IF=0 and IF=7 cases
            unless you give `--disable-os8-patches` to the `configure`
            script, in which case these boot options use the `bin` disk.

        -   `os8v3d-src.rk05` is a non-bootable disk containing the
            contents of the OS/8 V3D source code tapes plus the source
            code for the extensions to OS/8 V3D.  The *ten* TU56 tape
            images used as input to this process are also included among
            the PiDP-8/I software — see `media/os8/al-*-sa-*.tu56` — but
            we find it much more convenient to explore the sources on a
            single RK05 disk than to repeatedly attach and detach the
            TU56 tapes.

            You can suppress building this with `--disable-os8-src`.

        Default versions of these disk images are also now published on
        the project's home page for the benefit of those not running our
        PiDP-8/I software.  There are quite a few OS/8 RK05 disk images
        floating around on the Internet these days, and many of them
        have bugs and breakage in them that we've fixed.  It would
        completely fail to break our hearts if these images were used by
        many people outside the PiDP-8/I project.

    -   U/W FOCAL V4E is installed on SYS: by default. Start with our
        [U/W FOCAL Manual Supplement for the PiDP-8/I][uwfs], then
        follow links from there to further information.
        
        The primary linked source is the [U/W FOCAL Manual][uwfm] by Jim
        van Zee (creator of U/W FOCAL) converted from scanned and OCR'd
        PDF form to Markdown format, which Fossil renders nicely for us
        on the web.

        This is a fascinating programming language, well worth studying!

    -   Ian Schofield's CC8 OS/8 C compiler is installed on `SYS:` by
        default, and its examples and other files are on `DSK:`.  We
        have also merged in his `cc8` host-side cross-compiler.  See
        [the CC8 `README`][cc8rm] for details.
        
        This is a considerably improved compiler relative to what
        was distributed on the mailing list in August 2017.  Ian has
        been working within the PiDP-8/I project since that initial
        public release, which we are now distributing publicly for
        the first time.  We thank him for trusting us to host and
        distribute his project.

    -   The MACREL v2 macro assembler and its associated FUTIL V8B tool
        are installed by default.  Not only is this new functionality
        relative to prior releases of the PiDP-8/I software, it is a
        considerable upgrade over to the original MACREL and FUTIL V7
        that are more commonly found on the net.

    -   DCP disassembler is installed by default.

    -   John Comeau's CHECKMO-II chess program is installed by default.

    -   By default, SIMH no longer folds lowercase input and output to
        uppercase.  Instead, we apply patches to OS/8's command
        processor and its BASIC implementation to up-case input, since
        neither OS/8 nor BASIC can cope with lowercase input.

        All other programs are left to fend for themselves, which
        often works out fine.  U/W FOCAL, Adventure, and TECO all handle
        lowercase input to some extent, for example, and all three can
        emit lowercase text if given it.  With the prior SIMH setting,
        you could not use lowercase in these programs at all.

        This default can be overridden.  See the documentation for the
        new `--lowercase` configuration option in `README.md`.

    -   The `INIT.TX` message displayed by default on OS/8 boot is now
        more informative than the old `FIELD SERVICE PDP-8 DIAGNOSTIC
        SYSTEM` message.  It also now uses lowercase unless you built
        the simulator to force uppercase with `--lowercase=upper`.

        Those that do not want any boot message can disable it at
        configuration time with the `--disable-os8-init` flag.

        The message can be modified by editing `media/os8/init.tx.in`
        and saying `make`, which will rebuild the OS/8 media.

    -   All of the above features can be disabled if not wanted, as can
        several features present on the old `os8.rk05` disk: Adventure,
        FORTRAN IV, FORTRAN II, Kermit-12, and the BASIC game and demo
        programs.

        You can disable each feature above with a `--disable-os8-*`
        option to the `configure` script, or you can disable all of them
        collectively with the `--os8-minimal` option, which gets you a
        nearly bare-bones OS/8 installation with lots of spare disk
        space with which you can do what *you* want.

    -   Replaced the mismatched FORTRAN compiler and runtime with
        matched versions from the distribution DECtapes, and ensured that
        Adventure runs under this version of the FORTRAN Run Time System
        (FRTS). At various points in the past, either FORTRAN or
        Adventure has been broken.

    -   Repaired several broken BASIC programs on `RKB0:` by going back
        to primary sources.  Either the `os8.rk05` disk image was corrupted
        at some point or it is an image of a real RK05 disk pack that
        was corrupted, causing several of these BASIC programs to not
        run properly.

    -   The `*.MU` and music player files are left off of `RKB0:` by
        default, since they apparently do not cause sufficient RFI on
        the PiDP-8/I hardware to be picked up by normal AM radios.  This
        saves space for things that *do* work.

    -   No longer installing the `VTEDIT` macros for TECO by default.
        Although some may enjoy this alternative way of running TECO, it
        was decided that we should offer stock TECO by default for its
        historical value.  If you want VTEDIT back, it can be re-enabled
        with a `configure` script option.

    -   In the old `os8.rk05` disk image, both `SYS:` and `DSK:` were
        set to `RKA0:`, which meant that to address anything on `RKB0:`, you
        had to specify the device path explicitly or manually change the
        default in OS/8 with an `ASSIGN RKB0 DSK` command or similar.

        In the new disk pack, programs run with the OS/8 `R` command are
        installed on `RKA0:` which is the `SYS:` disk, and user data
        files, FOCAL and BASIC programs, etc. are on `RKB0:` which is
        assigned as `DSK:`. This means OS/8 and its programs are now far
        more likely to find files without an explicit device name,
        because files are installed where OS/8 looks for them by
        default.  Example:

            .R FRTS                   ⇠ loads FRTS from SYS: (RKA0:)
            *ADVENT                   ⇠ loads ADVENT.LD from DSK: (RKB0:)
            *[Esc]
            Welcome to Adventure!!

        Notice that no device names had to be specified.  OS/8 did the
        right thing by default here, even though the files involved are
        on two separate OS/8 devices.

        To a very rough approximation, `SYS:` on these new RK05 disk
        packs acts like the Unix `PATH` and `DSK:` acts like your user's
        home directory.

        The idea for this came from Ian Schofield's `cc8.rk05` disk
        image, which we are also shipping in this release.

    -   OS/8 has a limit on the number of devices it can support, and we
        made different choices than the creator of `os8.rk05`.

        Briefly, we replaced the second floppy (`RXA1:`) with a third
        RK05 disk, that being deemed a more useful configuration for
        this hard disk based OS/8 configuration.  A dual-floppy
        configuration implies that you are booting from floppy and need
        the second one for user files and such.  In our RK05 based
        configuration, users should need floppy disk support rarely, and
        then primarily to get data on and off of the attached hard
        disk(s).

        We chose to stick with the dual TU56 tape drive setup of the
        prior version as we found the ability to mount two tapes very
        helpful, particularly during the `mkos8` build process.

        The difference in the `RESORC` output between the versions is:

            Old: RKA0,RKB0,RKA1,RKB1,          RXA0,RXA1,DTA0,DTA1,TTY,LPT,PTP,PTR
            New: RKA0,RKB0,RKA1,RKB1,RKA2,RKB2,RXA0,     DTA0,DTA1,TTY,LPT,PTP,PTR

    This automatic OS/8 media build feature was suggested by Jonathan
    Trites who wrote the initial version of the script that is now
    called `libexec/mkos8`.  That script was then extended and factored
    into its current form by Bill Cattey and Warren Young.

    Warren thinks Bill did most of the hard work in the items above.

    The source media used by the `mkos8` script comes from many sources
    and was curated for the PiDP-8/I project by Bill Cattey.  See the
    [OS/8 media README][os8rm] for more details.

    See the [the top-level `README`][tlrm] for information on modifying
    the default OS/8 configuration.  Pretty much everything above can be
    disabled if it's enabled by default, and vice versa.

*   Added several new wiki articles covering the above:

    *   More Project Euler Problem #1 solutions in:

        *   [C][pe1c]
        *   [FORTRAN IV][pe1f4]
        *   [FORTRAN II][pe1f2]
        *   [U/W FOCAL][pe1u]

    *   [Demos in BASIC][dibas], deescribing `DSK:*.BA`

    *   [OS/8 Console TTY Setup][os8ct], describing how we have
        modified the stock behavior of OS/8 to behave appropriately
        with a glass terminal or SSH on its console, as opposed to
        its default behavior, which assumes a teletype.

    *   [OS/8 LCSYS.BI Disassembled][os8lc], a symbolic
        disassembly of the `LCSYS.BI` patch we distribute with the
        system, which is widely available online elsewhere. That script
        is a raw binary patch, which makes its operation a mystery
        unless you happen to be able to read PDP-8 machine code.

*   Added Bill Cattey's `txt2ptp` program which converts plain ASCII
    text files files to the paper tape format used by SIMH, which eases
    transfer of text data into the simulator.  That program is also
    linked to `ptp2txt`, which makes it perform the inverse function:
    given a SIMH paper tape image file, produce an ASCII text file on
    the host machine with its contents.

    This program was written to ease the movement of FOCAL program text
    between SIMH and its host OS, but they should prove useful for other
    similar tasks.

*   Integrated Robert Krten's `d8tape` PDP-8 host-side disassembler.
    This is distinct from the OS/8 DCP disassembler, which runs inside
    the simulator.  It is intended as a companion to `palbart`, which we
    integrated last year.

*   Added a new "blinkenlights" demo program called `bin/teco-pi-demo`
    which drives SIMH from the outside, running a TECO macro under OS/8
    to calculate *pi* to 248 digits at a very slow rate, producing a
    display that manages to land somewhere between the random default
    display of [Deeper Thought][dt2vk] and the clear, boring patterns of
    our preexisting IF=5 demo script.

    Why 248 digits?  Because at 249, TECO8 runs out of memory, aborting
    the demo early.  At the default execution rate, it would take over
    17 years to complete this demo, making it a good choice to run on
    PiDP-8/I units primarily being used as *objets d'art*.  The demo has
    a finite run time, but your Raspberry Pi is likely to die before it
    completes. `;)`

    This script is also included as a demonstration of how the end user
    can reuse the technology that we developed to automatically build
    the custom OS/8 disk images described above to achieve different
    ends.  Perhaps you have some other program you'd like to run within
    SIMH in an automated fashion?  This shows one way how, and
    demonstrates a pre-built and tested set of tools for achieving it.

    We have also written [a tutorial][csd] explaining how
    `bin/teco-pi-demo` works and how to reuse the components it is built
    atop for your own ends.

    This demo also has a benchmark mode (command line option `-b`) which
    has two purposes:

    1.  It lets you see how much faster your host system runs PDP-8 code
        than a Raspberry Pi Model B+ running the PiDP-8/I simulator.

    2.  Given that information, the benchmark overrides a hardcoded
        timing value in the source code as distributed which prevents
        programs like `teco-pi-demo` from spamming the OS/8 terminal
        input handler.  The default is for the slowest host we support
        this software on, that same Model B+ referred to above, but if
        we know you're running on a faster host, we can shorten this
        delay and remain reliable.
        
    If you run the demo in benchmark mode twice, you'll notice that the
    TECO script is input nearly instantaneously the second time, whereas
    you can see the demo "type" the script in very quickly the first
    time.  (Remove `lib/pidp8i/ips.py`, say `make reconfig` and run the
    demo again to see the difference.)

*   The `DF` + `SING_STEP` feature for automatically attaching binary
    media images to the simulator from files on USB sticks now looks
    at all directories under `/media`, not just `usb0` through `usb7`
    so that it works with several other common Linux USB automounting
    schemes, such as the one Raspbian Desktop uses.

*   Fixed the order of initialization in the GPIO setup code for the
    James L-W serial mod case.  Fix by Dylan McNamee.

*   The helper program that selects which boot script to run when the
    PiDP-8/I boots based on the IF switch settings broke at some point
    in the past, apparently because it was using its own idiosyncratic
    GPIO handling code, and thus did not track our evolving GPIO
    handling methods.  Now it shares the same code used by `pidp8i-sim`
    and `pidp8i-test`, so it works properly again.

*   The SysV init script that starts `pidp8i-sim` under GNU Screen on
    the PiDP-8/I now sets the working directory to `$prefix/share/media`
    on start, so relative paths given to SIMH commands (e.g. `ATTACH`)
    are more likely to do what you want.  In prior releases, you
    generally had to give absolute paths to attach media and such
    because CWD would be set somewhere unhelpful.

*   The Fetch LED is no longer lit when in STOP or single-step mode.  In
    real hardware, it can be either on or off in this mode, depending
    on various conditions, but it is most often off, so while it is not
    perfectly correct now, it is less wrong.  Most of the investigation
    into this issue is by Bill Cattey, with the current partial fix by
    me.  A more precise fix may come later.  (See ticket [347ae45403] if
    you care to know the details.)

*   The Pause LED state was over-counted in the LED sub-sampling scheme
    so that it would tend to be brighter than it should have been.
    Problem noticed by Ian Schofield.

*   The MB row's state was not showing the right thing.  The problem was
    noticed in comparison to real PDP-8/I hardware by Vincent Slyngstad
    and verified by William Cattey.  Ian Schofield suggested the current
    fix.

*   Updated SIMH to upstream checkin ID 27f9fc3c3, December 11, 2017.
    There have been no substantial changes to the PDP-8 simulator since
    the last update, 8 months ago, but there have been a lot of bug
    fixes to the SCP core program.

*   Updated for Raspbian Stretch, released in September 2017.  It should
    still run on Raspbian Jessie, however.

*   Assorted portability, build system, and documentation improvements.

*   **TODO**

    -   Create udev script replacement for usbmount so that `DF` +
        `SING_STEP` works on Stretch.

[apt]:   https://linux.die.net/man/8/apt
[cc8rm]: https://tangentsoft.com/pidp8i/doc/trunk/src/cc8/README.md
[csd]:   https://tangentsoft.com/pidp8i/doc/trunk/doc/class-simh.md
[dibas]: https://tangentsoft.com/pidp8i/wiki?name=Demos+in+BASIC
[dt2vk]: https://github.com/VentureKing/Deeper-Thought-2
[os8ct]: https://tangentsoft.com/pidp8i/wiki?name=OS/8+Console+TTY+Setup
[os8lc]: https://tangentsoft.com/pidp8i/wiki?name=OS/8+LCSYS.BI+Disassembled
[os8p]:  https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-patching.md
[os8rm]: https://tangentsoft.com/pidp8i/doc/trunk/media/os8/README.md
[pe1c]:  https://tangentsoft.com/pidp8i/wiki?name=PEP001.C
[pe1f2]: https://tangentsoft.com/pidp8i/wiki?name=PEP001.FT#fortran-ii
[pe1f4]: https://tangentsoft.com/pidp8i/wiki?name=PEP001.FT#fortran-iv
[pe1u]:  https://tangentsoft.com/pidp8i/wiki?name=PEP001.FC
[uwfm]:  https://tangentsoft.com/pidp8i/doc/trunk/doc/uwfocal-manual.md
[uwfs]:  https://tangentsoft.com/pidp8i/doc/trunk/doc/uwfocal-manual-supp.md


## Version 2017.04.04

*   Removed the PDP-8 CPU idle detection feature.  Oscar Vermeulen
    reports that it also interfered with NLS LED driving mode in his
    last version, and we have no reason to believe our NLS code is
    sufficiently different to avoid the problem.

    percentage style throttle rates.  We now explicitly set the throttle
    rate to "50%" which not only achieves an even higher throttle rate
    than in earlier releases, it's reliable in the face of varying
    background CPU usage.  See the single-core section of
    `README-throttle.md` for details.


## Version 2017.04.01 — The "I May Be a Fool, but I am *Your* Fool" release

*   Added the `configure --alt-serial-mod` option to change the GPIO
    code to work with [James L-W's alternative serial mod][sm2].

*   Increased the stock CPU throttle from 0.67 MIPS to 0.85 MIPS on most
    Pi 1 class devices, except for the Pi Zero which is a bit faster and
    so is able to run at 1.25 MIPS.

*   The simulator now reports the upstream Git commit ID it is based on
    in its version string, so that if you report bugs upstream to the
    SIMH project, you can give them a version number that will be
    meaningful to them.  (They don't care about our vYYYYMMDD release
    numbers or our Fossil checkin IDs.)


## Version 2016.12.26 — The Boxing Day release

*   Tony Hill updated SIMH to the latest upstream version.

    This change represents about 15 months worth of work in the
    [upstream project][simh] — plus a fair bit of work by Tony to merge
    it all — so I will only summarize the improvements affecting the
    PDP-8 simulator here:

[p1saga]: https://tangentsoft.com/pidp8i/wiki?name=PEP001.PA


## Version 2016.11.28

*   Added an intelligent, powerful build system, replacing the
    bare-bones `Makefile` based build system in the upstream version.
    See [`README.md`][tlrm] for more info on this.

*   The installation is now completely relocatable via `./configure
    --prefix=/some/other/place`. The upstream version would not work if
    installed somewhere other than `/opt/pidp8` due to many hard-coded
    absolute paths.  (This is enabled by the new build system, but
    fixing it was not simply a matter of swapping out the build system.)

    In particular, the software now builds under Mac OS X, though it
    does not yet run properly.  (The modified SimH PDP-8 simulator
    currently misbehaves if the PiDP-8/I panel is not present.  Fixing
    this is on the radar.)

*   Fixed a bunch of bugs!

[tlrm]:    https://tangentsoft.com/pidp8i/doc/trunk/README.md
[dupatch]: https://groups.google.com/forum/#!topic/pidp-8/fmjt7AD1gIA
[dudis]:   https://tangentsoft.com/pidp8i/tktview?name=e06f8ae936
[wiki]:    https://tangentsoft.com/pidp8i/wcontent
[ex]:      https://tangentsoft.com/pidp8i/doc/trunk/examples/README.md
[art]:     https://tangentsoft.com/pidp8i/dir?c=trunk&name=labels
[tix]:     https://tangentsoft.com/pidp8i/tickets

You must use Fossil version 2.1 or higher with our repository, or you
will get an error.

If you started with one of our PiDP-8/I binary OS images made in or
after April 2017, Fossil 2.x is already installed.

If you're starting from some other OS, you either won't have Fossil
installed at all, or you'll most likley be using an older version,
since the Debian project is still shipping version 1.37 and likely
will continue to do so until 2020 or so.  You could build Fossil from
source, or you could just go grab a prebuilt binary we keep on the
project site:


    $ wget https://tangentsoft.com/pidp8i/uv/fossil-raspbian-9.1-stretch


    $ sudo install -m 755 fossil-* /usr/local/bin/fossil




Fossil is also available for all common desktop platforms.  One of [the
official binaries][fbin] may work on your system.  If you're getting
binaries from a third party, be sure it is Fossil 2.1 or higher.


[fbin]:   https://fossil-scm.org/index.html/uv/download.html
[dvcs]:   https://en.wikipedia.org/wiki/Distributed_revision_control
[fbook]:  https://www.fossil-scm.org/schimpf-book/home
[fml]:    https://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/fossil-users
[fossil]: https://fossil-scm.org/
[fqsg]:   https://fossil-scm.org/index.html/doc/trunk/www/quickstart.wiki
[ggml]:   https://groups.google.com/forum/#!forum/pidp-8


Fossil Anonymous Access
----

To clone the code repository anonymously, say:

    $ mkdir -p ~/museum ~/src/pidp8i/trunk

    $ fossil clone https://tangentsoft.com/pidp8i ~/museum/pidp8i.fossil
    $ cd ~/src/pidp8i/trunk
    $ fossil open ~/museum/pidp8i.fossil

The `clone` command gets you a file called `pidp8i.fossil` containing
the full history of the PiDP-8/I software project from the upstream
2015.12.15 release onward.  You can call that clone file anything you
like and put it in any directory you like.  Even the `.fossil` extension
is largely a convention, not a requirement.


Working with Existing Tags and Branches
----

The directory structure shown in the commands above is more complicated
than strictly necessary, but it has a number of nice properties.

First, it collects other software projects under a common top-level
directory, which I'm calling `~/src`, but you are free to use any scheme

our scope here.  See the [Fossil Quick Start Guide][fqsg] and the
documents it links to for more details.)

This directory scheme shows an important difference between Fossil and
Git: with Git, the checkout and the clone are intermingled in the same
directory tree, but in Fossil, they are strictly separate.  Git can
emulate Fossil's normal working style through its [worktree][gitwt]
feature, but it employs some trickery that causes some unwanted side
effects that don't affect Fossil by design: the repository clone is a
single SQLite database file — here, `pidp8i.fossil` — and the checkouts
are made from the contents of that database.

Another important difference relative to Git is that with Fossil, local
checkins attempt to automatically sync checked-in changes back to the
repository you cloned from.  (This only works if you have a login on the
remote repository, the subject of the next section.)  This solves a
number of problems with Git, all stemming from the fact that Git almost
actively tries to make sure every clone differs from every other in some

Fossil Developer Access
----

If you have a developer account on tangentsoft.com's Fossil instance, just
add your username to the URL like so:

    $ fossil clone https://username@tangentsoft.com/pidp8i pidp8i.fossil

If you've already cloned anonymously, you don't have to clone again to
inform Fossil about your developer account.  Just do a manual sync,
changing the URL to include the user name:

    $ fossil sync https://username@tangentsoft.com/pidp8i

Either way, Fossil will ask you for the password for `username` on the
remote Fossil instance, and it will offer to remember it for you.  If
you let it remember the password, operation from then on is scarcely
different from working with an anonymous clone, except that on checkin,
your changes will be sync'd back to the repository on tangentsoft.com if
you're online at the time, and you'll get credit under your developer
account name for the checkin.

If you're working offline, Fossil will still do the checkin locally, and
it will sync up with the central repoisitory after you get back online.
It is best to work on a branch when unable to use Fossil's autosync
feature, as you are less likely to have a sync conflict when attempting
to send a new branch to the central server than in attempting to merge
your changes to the tip of trunk into the current upstream trunk, which
may well have changed since you went offline.

You can purposely work offline by disabling autosync mode:

    $ fossil set autosync 0

Until you re-enable it (`autosync 1`) Fossil will stop trying to sync
your local changes back to the central repo.  In this mode, Fossil works
more like Git's default mode, buying you many of the same problems that
go along with that working style.  I recommend disabling autosync mode
only when you are truly going to be offline and don't want Fossil
attempting to sync when you know it will fail.


Getting Developer Access
----

The administrator of this repository is Warren Young, whose email you

Manipulating the Build System Source Files
----

The [autosetup build system][asbs] is composed of these files and
directories:

     auto.def
     autosetup/*
     configure
     Makefile.in

Unlike with GNU Autoconf, which you may be familiar with, the
`configure` script is not output from some other tool.  It is just a
driver for the Tcl and C code under the `autosetup` directory.

If you have to modify any of the files in `autosetup/` to get some
needed effect, you should try to get that change into the upstream
[Autosetup][asbs] project, then merge that change down into the local
copy when it lands upstream.

The bulk of the customization to the build system is in `auto.def`,
which is a Tcl script run by `autosetup` via the `configure` script.
Some knowledge of [Tcl syntax][tcldoc] will therefore be helpful in
modifying it.

If you do not have Tcl installed on your system, `configure` builds a
minimal Tcl interpreter called `jimsh0`, based on the [Jim Tcl][jim]
project.  Developers working on the build system are encoruaged to use
this stripped-down version of Tcl rather than "real" Tcl because Jim Tcl
is more or less a strict subset of Tcl, so any changes you make that
work with the `jimsh0` interpreter should also work with "real" Tcl, but
not vice versa.  If you have Tcl installed and don't really need it,
consider uninstalling it to force `autosetup` to build and use `jimsh0`.

The `Makefile.in` file is largely a standard [GNU `make`][gmake] file
excepting only that it has variables substituted into it by `autosetup`
using its `@VARIABLE@` syntax.  At this time, we do not attempt to
achieve compatibility with other `make` programs, though in the future
we may need it to work with [BSD `make`][bmake] as well, so if you are
adding features, you might want to stick to the common subset of
features implemented by both the GNU and BSD flavors of `make`.  We do
not anticpate any need to support any other `make` flavors.


(This, by the way, is why we're not using some heavy-weight build system
such as the GNU Autotools, CMake, etc.  The primary advantage of GNU
Autotools is that you can generate source packages that will configure
and build on weird and ancient flavors of Unix; we don't need that.
Cross-platform build systems such as CMake ease building the same
software on multiple disparate platforms straightforward, but the
PiDP-8/I software is built primarily on and for a single operating
system, Rasbpian Linux.  It also happens to build and run on other
modern Unix and Linux systems, for which we also do not need the full
power of something like CMake.  `autosetup` and GNU `make` suffice for
our purposes here.)

[asbs]:   http://msteveb.github.io/autosetup/
[bmake]:  https://www.freebsd.org/doc/en/books/developers-handbook/tools-make.html
[gmake]:  https://www.gnu.org/software/make/
[jim]:    http://jim.tcl.tk/
[tcldoc]: http://wiki.tcl.tk/11485


<a id="dirs"></a>
Directory Structure
----

The directory structure of the PiDP-8/I project is as follows:

*   <b>`.`</b> - Top level, occupied only by the few files the end user
    of the source code needs immediately at hand on first unpacking the
    project: the top level build system files, the top-level
    `README*.md` files, and licensing information. If a given file *can*
    be buried deeper, it *should* be buried to reduce clutter at this
    most precious level of the hierarchy.

*   <b>`.fossil-settings`</b> - Versioned settings for the Fossil build
    system.  Say `fossil help set` at the command line for more on this.
    Such settings are intended to be correct for all users of the
    system; rather than expressing defaults, they express *policy*.

    Any setting whose value may vary between users of the Fossil
    repository should be done locally with a `fossil set` command.

*   <b>`autosetup`</b> - The bulk of the [Autosetup build system][asbs].
    These are generic files, not modified by the project itself. We
    occasionally run `tools/autosetup-update` to merge in upstream
    changes.

*   <b>`bin`</b> - Programs run both in development and after
    installation.  Some files here are created directly by the project's
    developers, while others are outputs of the build system. The
    content of this directory is copied to `$prefix/bin` at installation
    time, which is added to the user's `PATH` by the installer.

*   <b>`boot`</b> - SIMH initialization scripts. The `*.script.in` files
    are written by the project developers but have build-time values
    substituted in by the `configure` script to produce a `*.script`
    version. Some of the remaining `*.script` files are hand-written and
    as such are checked into Fossil directly. The remainder are outputs
    of `tools/mkbootscript`, which produces them from `palbart` assembly
    listings.

    All of these `*.script` files are installed to `$prefix/share/boot`
    regardless of their origin.

*   <b>`doc`</b> - Documentation files not immediately important enough
    to a new user of the software that they do not have to be at the top
    level of the project tree.

    Fossil allows us to treat the contents of `doc` much like the wiki,
    so how do we decide whether to put a given document into `doc` or
    the wiki?  The rule is simple: is the document's history tied to the
    history of the PiDP-8/I project itself?  If so, it goes in `doc`,
    else it goes in the wiki.  When checking out older versions of the
    PiDP-8/I software, you expect to roll back to contemporaneous
    versions of the project documentation; such files go into `doc`.
    Documents which are independent of the PiDP-8/I project history go
    into the wiki.

    (The wiki does also have history, but rolling back to a prior
    version of the PiDP-8/I repository and then saying `fossil ui` will
    show you the current version of the wiki documents, not the versions
    as they existed at the time of the historical checkin you rolled
    back to.)

    The `doc/graphics` subdirectory holds JPEGs and SVGs displayed
    inline within wiki articles.

*   <b>`etc`</b> - Files which get copied to `/etc` or one of its
    subdirectories at installation time.

*   <b>`examples`</b> - Example programs for the end user's edification.
    Many of these are referenced by documentation files.

*   <b>`hardware`</b> - Schematics and such for the PiDP-8/I board or
    associated hardware.

*   <b>`labels`</b> - Graphics intended to be printed out and used as
    labels for removable media.

*   <b>`lib`</b> - Library routines used by other programs.

*   <b>`libexec`</b> - A logical extension of `lib`, these are
    standalone programs that nevertheless are intended to be run
    primarily by other programs. Whereas a file in `lib` might have its
    interface described by a programmer's reference manual, the
    interface of a program in `libexec` is described by its usage
    message. Examples:

    *   <b>`mkos8`</b> - Run by the build system.
    
        <p>It is sometimes run by hand in development, but primarily
        only to further its development. Once it runs correctly after
        adding some feature, we let <code>make</code> run it for us.</p>

    *   <b>`scanswitch`</b> - Run by `etc/pidp8i`.
    
        <p>As with <code>mkos8</code>, it is generally run by hand only
        by developers modifying its behavior.</p>

    Programs in `libexec` are installed to `$prefix/libexec`, which is
    *not* put into the user's `PATH`, on purpose. If a program should
    end up in the user's `PATH`, it belongs in `bin`. Alternately, a
    wrapper may be put in `bin` which calls a `libexec` program as a
    helper.

*   <b>`media`</b> - Binary media images used either by SIMH directly or
    by tools like `mkos8` to produce media used by SIMH.

    The contents of this tree are installed to `$prefix/share/media`.

*   <b>`obj`</b> - Intermediate output directory used by the build
    system.  It is safe to remove this directory at any time, as its
    contents may be recreated by `make`. No file checked into Fossil
    should be placed here.

    (Contrast `bin` which does have some files checked into Fossil; all
    of the *other* files that end up in `bin` can be recreated by
    `make`, but not these few hand-written programs.)

*   <b>`src`</b> - Source code for the project's programs, especially
    those that cannot be used until they are built. The build system's
    output directories are `bin`, `boot`, `libexec`, and `obj`.

    Programs that can be used without being "built", example programs,
    and single-file scripts are placed elsewhere: `bin`, `examples`,
    `libexec`, `tools`, etc. Basically, we place such files where the
    build system *would* place them if they were built from something
    under `src`.

    The top level of `src` is for the SIMH core, with the PDP-8
    simulator specific bits in the `PDP8` subdirectory.

    The subdirectories of `src` are for other programs' source code.

*   <b>`test`</b> - Output directory used by `tools/test-*`.

*   <b>`tools`</b> - Programs run only during development and not
    installed.

    If a program is initially created here but we later decide that it
    should be installed for use by end users of the PiDP-8/I system, we
    move it to either `bin` or `libexec`, depending on whether it is run
    directly at the command line or run from some other program that is
    also installed, respectively.


<a id="patches"></a>
Submitting Patches
----

If you do not have a developer login on the PiDP-8/I software
repository, you can still send changes to the project.

The simplest way is to say this after developing your change against the

Please make your patches or experimental branch bundles against the tip
of the current trunk.  PiDP-8/I often drifts enough during development
that a patch against a stable release may not apply to the trunk cleanly
otherwise.

[osil]:  https://opensource.org/licenses
[repo]:  https://tangentsoft.com/pidp8i/
[simhl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md
[viral]: https://en.wikipedia.org/wiki/Viral_license


The PiDP-8/I Software Project Code Style Rules
----

# shall not be used in advertising or otherwise to promote the sale,
# use or other dealings in this Software without prior written
# authorization from those authors.
########################################################################

# Git commit ID of the latest version of the SIMH 4 project on GitHub 
# that has been merged into this source base.
SGCID=27f9fc3c3e7ff105c6102dfffc6da7fb838d1e8f

# C build flags for src/*.c and PDP8/*.c, containing the SIMH core
# modules and the SIMH PDP-8 simulator, respectively.
TOP_CFLAGS := @CFLAGS@ @BUILDMODE@ \
	-Wno-unused-result -Wno-parentheses \
	-DUSE_READER_THREAD -DHAVE_DLOPEN=$(subst .,,@SH_SOEXT@) -DPIDP8I \
	-DSIM_ASYNCH_IO -DHAVE_REGEX_H -DHAVE_GLOB \
	-DSIM_GIT_COMMIT_ID=$(SGCID) -D_GNU_SOURCE \
	-U__STRICT_ANSI__ \
	-I @srcdir@/src -I @srcdir@/src/PDP8 -I src
PDP8_CFLAGS = $(TOP_CFLAGS)

# Greatly stripped-down build options for the cc8 cross-compiler
# primarily because it's K&R C.  Building under TOP_CFLAGS spews
# pages of warnings.  The only thing we share is whether to build
# a debug or optimized version, from BUILDMODE, set by auto.def.
CC8_CROSS_CFLAGS = -w @BUILDMODE@

# Krten's d8tape doesn't need much in the way of options.  It builds
# without warnings under the supported version of Raspbian.  On some
# other OS types, it complains about one of the printf() format
# specifiers, which we cannot fix portably, so we suppress that one.
D8TAPE_CFLAGS = -Wno-format @BUILDMODE@

# Ditto palbart.
PALBART_CFLAGS = @BUILDMODE@

SIM = bin/pidp8i-sim
BINS = $(SIM) @CC8_CROSS@ \
	bin/d8tape \
	bin/palbart \
	bin/pidp8i-test \
	bin/ptp2txt \
	libexec/scanswitch
BIN_SCRIPTS = \
	bin/pidp8i \
	@srcdir@/bin/teco-pi-demo

# Some *.py files are generated by Autosetup, so they need different
# handling than the other libraries for the out-of-tree build case.
PIDP8I_DIRS := lib/pidp8i/dirs.py
PIDP8I_DIN  := @srcdir@/$(PIDP8I_DIRS).in
GENNED_PY   := \
	lib/pidp8i/__init__.py \
	lib/pidp8i/ips.py \
	$(PIDP8I_DIRS)

SIMH_PY     := lib/simh.py
SIMH_PY_SRC := @srcdir@/$(SIMH_PY)

MKOS8         := @srcdir@/libexec/mkos8
MKOS8_LIB     := @srcdir@/lib/mkos8
MKOS8_PY      := \
	$(MKOS8_LIB)/__init__.py \
	$(MKOS8_LIB)/argparser.py \
	lib/mkos8/opts.py
MKOS8_PY_ALL  := $(GENNED_PY) $(MKOS8_PY) $(SIMH_PY_SRC)
MKOS8_SRCS    := $(MKOS8) $(MKOS8_PY_ALL) $(PIDP8I_DIN)

BUILDDIRS := bin libexec obj/cc8/cross obj/d8tape obj/palbart obj/PDP8

INSTDIRS := bin etc lib/mkos8 lib/pidp8i libexec share/boot share/media share/include share/man/man1

SIM_OBJS := \
	obj/gpio-common.o \
	obj/PDP8/pdp8_df.o \
	obj/PDP8/pdp8_cpu.o \
	obj/PDP8/pdp8_clk.o \
	obj/PDP8/pdp8_ct.o \
	obj/PDP8/pdp8_dt.o \
	obj/PDP8/pdp8_fpp.o \

	obj/sim_serial.o \
	obj/sim_sock.o \
	obj/sim_tape.o \
	obj/sim_timer.o \
	obj/sim_tmxr.o \
	obj/sim_video.o

CC8_OBJS := \
	obj/cc8/cross/code8.o \
	obj/cc8/cross/data.o \
	obj/cc8/cross/error.o \
	obj/cc8/cross/expr.o \
	obj/cc8/cross/function.o \
	obj/cc8/cross/gen.o \
	obj/cc8/cross/io.o \
	obj/cc8/cross/lex.o \
	obj/cc8/cross/main.o \
	obj/cc8/cross/preproc.o \
	obj/cc8/cross/primary.o \
	obj/cc8/cross/stmt.o \
	obj/cc8/cross/sym.o \
	obj/cc8/cross/while.o

D8TAPE_OBJS := \
	obj/d8tape/dasm.o \
	obj/d8tape/flow.o \
	obj/d8tape/main.o \
	obj/d8tape/version.o

MISC_OBJS := \
	obj/ptp2txt.o \
	obj/scanswitch.o \
	obj/test.o

PALBART_OBJS := obj/palbart/palbart.o

ifeq (@BUILD_DEEPER_THOUGHT@, 1)
BINS += bin/deeper
endif

LIBS = -lm -ldl -lpthread

ASM_PTS     := $(wildcard @srcdir@/src/asm/*.pal)
ASM_PTS     := $(subst @srcdir@/src/asm,bin,$(ASM_PTS))
ASM_PTS     := $(ASM_PTS:.pal=-pal.pt)
FC_EX_PTS   := $(wildcard @srcdir@/examples/*.fc)
FC_EX_PTS   := $(subst @srcdir@/examples,bin,$(FC_EX_PTS))
FC_EX_PTS   := $(FC_EX_PTS:.fc=-focal.pt)
PAL_EX_PTS  := $(wildcard @srcdir@/examples/*.pal)
PAL_EX_PTS  := $(subst @srcdir@/examples,bin,$(PAL_EX_PTS))
PAL_EX_PTS  := $(PAL_EX_PTS:.pal=-pal.pt)
LISTINGS    := $(ASM_PTS:-pal.pt=.lst) $(PAL_EX_PTS:-pal.pt=.lst)
LISTINGS    := $(subst bin/,obj/,$(LISTINGS))
BOOTSCRIPTS := $(LISTINGS:.lst=.script)
BOOTSCRIPTS := $(subst obj/,boot/,$(BOOTSCRIPTS)) \
	boot/1.script \
	boot/5.script

# List of *.in files from auto.def file, except for this present file
# (Makefile.in) which is handled separately.  This list should only
# change when the list of "make-template" calls in auto.def changes.
# 
# The MKOS8_INFILES set of files are those which, if changed, require
# rebuilding the OS/8 media.  Touching the combined set merely causes
# a reconfig and build.
#
# The PRECIOUS set are those whose outfiles we want make(1) to treat as
# "precious", meaning it won't delete files generated by a target if the
# rule being processed to create that target fails.
# 
# The rest have no special treatment.
MKOS8_INFILES = \
	@srcdir@/lib/pidp8i/__init__.py.in \
	@srcdir@/lib/pidp8i/ips.py.in \
	@srcdir@/media/os8/init.tx.in \
	@srcdir@/src/PDP8/pidp8i.c.in \
	$(PIDP8I_DIN)
PRECIOUS_INFILES = \
	@srcdir@/Makefile.in \
    @srcdir@/examples/Makefile.in \
    @srcdir@/src/Makefile.in \
    @srcdir@/src/cc8/Makefile.in \
    @srcdir@/src/PDP8/Makefile.in
INFILES = \
	@srcdir@/bin/pidp8i.in \
	@srcdir@/boot/0.script.in \
	@srcdir@/boot/2.script.in \
	@srcdir@/boot/3.script.in \
	@srcdir@/boot/4.script.in \
	@srcdir@/boot/6.script.in \
	@srcdir@/boot/7.script.in \
	@srcdir@/boot/run.script.in \
	@srcdir@/etc/pidp8i-init.in \
	@srcdir@/etc/sudoers.in \
	@srcdir@/src/gpio-common.c.in \


	@srcdir@/tools/simh-update.in \
	$(MKOS8_INFILES)




MKOS8_OUTFILES := $(subst @srcdir@/,,$(MKOS8_INFILES))
MKOS8_OUTFILES := $(subst .in,,$(MKOS8_OUTFILES))
PRECIOUS_OUTFILES := $(subst @srcdir@/,,$(PRECIOUS_INFILES))
PRECIOUS_OUTFILES := $(subst .in,,$(PRECIOUS_OUTFILES))
OUTFILES := $(subst @srcdir@/,,$(INFILES))
OUTFILES := $(subst .in,,$(OUTFILES))

OS8_BIN_RK05 = bin/os8v3d-bin.rk05
OS8_SRC_RK05 = @OS8_SRC_RK05@
OS8_RK05S = $(OS8_BIN_RK05) $(OS8_SRC_RK05)

CLTXT = /boot/cmdline.txt

ADF := adrules.mk

.PHONY: all tags
.PRECIOUS: $(PRECIOUS_OUTFILES)

all: $(OUTFILES) $(PRECIOUS_OUTFILES) $(BUILDDIRS) $(BINS) $(BOOTSCRIPTS) $(LISTINGS) $(ASM_PTS) $(FC_EX_PTS) $(PAL_EX_PTS) $(OS8_RK05S)


clean:
	@rm -f $(BINS) $(BOOTSCRIPTS) $(ASM_PTS) $(PAL_EX_PTS) $(LISTINGS) \
		$(OUTFILES) $(ADF) \
		config.log cscope.out tags \
		bin/*.pt bin/*.rk05 bin/*.save bin/txt2ptp \
		lib/*.pyc lib/*/*.pyc lib/mkos8/opts.py \
		obj/*.log obj/*.pt obj/mkos8.opts \

		src/config.h \
		@srcdir@/examples/*.err
	@find obj \( -name \*.o -o -name \*.d \) -delete
	@-rmdir -p $(BUILDDIRS) 2> /dev/null || true

distclean: clean
	@rm -f \
		$(PRECIOUS_OUTFILES) \
		config.log \
		autosetup/jimsh0 \
		src/config.h

ctags tags:
	ctags -R @srcdir@/src @srcdir@/lib @srcdir@/libexec/mkos8
ifeq (@HAVE_PROG_CSCOPE@, 1)
	@cscope -bR -s@srcdir@
endif

install: all instdirs
	@echo Installing to @prefix@...




	@# Install files into those dirs and set their perms
	@for f in $(BINS) ; do \
		dest=@prefix@/bin/$$(basename $$f) ; \
		echo "Installing binary $$dest..." ; \
		@INSTALL@ -m 755 -D -s $$f $$dest ; \
	done
	@for f in $(BIN_SCRIPTS) ; do \
		dest=@prefix@/bin/$$(basename $$f) ; \
		echo "Installing script $$dest..." ; \
		@INSTALL@ -m 755 -D $$f $$dest ; \
	done
	@( cd @prefix@/bin ; \
	   echo "Installing txt2ptp symlink..." ; \
	   ln -f ptp2txt txt2ptp ; \
    )
	@(test -x /sbin/setcap && \
		for f in @prefix@/bin/pidp8i-* ; do \
			echo "Setting real-time priority capabilities on $$(basename $$f)..." ; \
			/sbin/setcap 'cap_sys_nice=eip' $$f ; \
		done \
	) || true
	@test -e @MEDIADIR@/os8/os8.rk05 || echo "Installing media..." && $(MAKE) mediainstall

	@# If this is a Debian-type system, install needed helper programs
	@test -x /usr/bin/apt-get -a ! -h /media/usb && apt-get -y install usbmount || true
	@test -x /usr/bin/apt-get -a ! -x /usr/bin/screen && apt-get -y install screen || true

	@# Disable competing services if this is a Raspberry Pi
	@(test -x /bin/systemctl && /bin/systemctl disable deeper || true)
	@(test -x /bin/systemctl && /bin/systemctl disable pidp8  || true)

	@# Install the init script if this system is systemd based.
	@@INSTALL@ -m 755 @srcdir@/etc/pidp8i-init @prefix@/etc
	@(  test -w /etc/init.d -a -x /bin/systemctl && \
		ln -sf @ABSPREFIX@/etc/pidp8i-init /etc/init.d/pidp8i && \
		/bin/systemctl enable pidp8i \
	) || true

	@# Give the install user permission to use GPIO if done on a Pi
	@grep -q '^gpio:' /etc/group && usermod -a -G gpio @INSTUSR@ || true

	done) || true

	@# Ditto for MANPATH
	@(for p in .profile .bash_profile ; do \
		test -n "$$SUDO_USER" -a -w "/home/$$SUDO_USER/$$p" && \
			! grep -qF "@ABSPREFIX@/share/man" "/home/$$SUDO_USER/$$p" && \
			echo "export MANPATH=\$$MANPATH:@ABSPREFIX@/share/man" >> "/home/$$SUDO_USER/$$p" ; \
		done \
	) || true

	@# If serial mod is disabled, turn off serial console and kgdb stuff
	@# in case they were enabled previously, else they will fight with
	@# our use of GPIO.
	@(  test -z "@PCB_SERIAL_MOD_ANY@" -a -r $(CLTXT) && ! -w $(CLTXT) && \
		cp -p $(CLTXT) "$(CLTXT)"_orig && \
		sed -e 's/console\=[a-zA-Z0-9]+,[0-9]+ //' \
		    -e  's/kgdboc\=[a-zA-Z0-9]+,[0-9]+ //' -i $(CLTXT) \
	) || true

	@# Install CC8 stuff if built
	@test -n "@CC8_CROSS@" && \
		echo "Installing cc8 cross-compiler..." ; \
		@INSTALL@ -m 755 bin/cc8 @prefix@/bin && \
		@INSTALL@ -m 644 @srcdir@/src/cc8/include/* @prefix@/share/include

	@# Install palbart stuff
	@@INSTALL@ -m 755 bin/palbart @prefix@/bin
	@@INSTALL@ -m 644 @srcdir@/src/palbart/palbart.1 @prefix@/share/man/man1

	@# Install mkos8 and its dependencies
	@echo "Installing mkos8..."
	@@INSTALL@ -m 775 -g @INSTGRP@ $(MKOS8) @prefix@/libexec
	@( for src in $(MKOS8_PY_ALL) ; do \
		test -e $$src || src=@srcdir@/$$src ; \
		dest=@prefix@/$$(echo $$src | sed -e 's_^@srcdir@/__') ; \
		echo "Installing $$src to $$dest..." ; \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D $${src}  $${dest}  ; \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D $${src}c $${dest}c ; \
	  done \
	)
	@sed -e 's#^build =.*#build = "@ABSPREFIX@"#' \
	     -e 's#^media =.*#media = os.path.join (build, "share/media/")#' \
	     -e 's#^os8mo =.*#os8mo = os8mi#' \
		 < $(PIDP8I_DIRS) > @prefix@/$(PIDP8I_DIRS)
	@chgrp @INSTGRP@ @prefix@/$(PIDP8I_DIRS)

instdirs:
	@echo "Creating installation directory tree..."
	@for d in $(INSTDIRS) ; do @INSTALL@ -m 755 -d @prefix@/$$d ; done

mediainstall: instdirs
	@echo "[Re]installing OS and program media..."
	@cd @srcdir@ ; \
	find media \( \
		-name \*.bin  -o \
		-name \*.dsk  -o \
		-name \*.rk05 -o \
		-name \*.tu56 \
	\) -exec @INSTALL@ -D -m 664 -o @INSTUSR@ -g @INSTGRP@ {} @ABSPREFIX@/share/{} \;
	@@INSTALL@ -m 644 -o @INSTUSR@ -g @INSTGRP@ bin/os8v3d-*.rk05 @ABSPREFIX@/share/media/os8
	@@INSTALL@ -m 664 -o @INSTUSR@ -g @INSTGRP@ boot/*.script @BOOTDIR@

# No-dependencies versions of the bin/os8v3d-*.rk05 targets used by
# tools/test-mkos8, because there's no point rebuilding the simulator
# on each iteration.
os8-bin:
	$(MKOS8)@MKOS8_OPTS@ bin
os8-patched:
	$(MKOS8)@MKOS8_OPTS@ bin patch

reconfig:
	@AUTOREMAKE@

release: all
	@srcdir@/tools/mkrel

run: $(SIM)
	$(SIM) boot/run.script

simh-update simh-update-f:
	@@srcdir@/tools/simh-update $(subst simh-update,,$@)

test-mkos8:
	tools/test-mkos8


# Build the OS/8 binary media needed by 0.script.
#
# We use order-only prerequisites for the simulator here because we only
# care that it *exists*, not whether it is newer than the previously
# built RK05 media or not.
#
# Also notice that the init.tx file is not a prerequisite: we purposely
# do not rebiuld the RK05 media just because the configure script was
# re-run, which *always* regenerates the init.tx file because the
# timestamp always changes from one run to the next.  (Until computers
# get fast enough to do a complete re-configure in under a second,
# anyway!)  The thing is, we only want the RK05 bin media rebuilt when
# the configure --*-os8-* options change.  *That* is when we care about
# the updated init.tx file, not before.  We needn't even make it an
# order-only prereq because configure and the INFILES rules above ensure
# that it always exists.
OS8_BIN_SRCS := $(MKOS8_SRCS) \

	@srcdir@/media/os8/al-*-ba-*.tu56 \
	@srcdir@/media/os8/subsys/*.tu56
ifneq (@MKOS8_BIN_PATCHES@,)
	OS8_BIN_SRCS += @srcdir@/media/os8/patches/patch_list.txt
endif
$(OS8_BIN_RK05): $(OS8_BIN_SRCS) | $(SIM) $(MKOS8_OUTFILES)
	$(MKOS8)@MKOS8_OPTS@ bin @MKOS8_BIN_PATCHES@

# Also build an OS/8 source disk, as a convenience to avoid the 
# need to mount up the 7 source tapes in succession.
#
# Using an order-only dependency for the simulator and the bin disk: we
# only need *a* version of each, they don't have to be recent!
OS8_SRC_SRCS = $(MKOS8_SRCS) \

	@srcdir@/media/os8/al-*-sa-*.tu56
$(OS8_SRC_RK05): $(OS8_SRC_SRCS) | $(SIM) $(OS8_BIN_RK05)
	$(MKOS8)@MKOS8_OPTS@ src

























# Rule for building PAL assembly language programs in src/asm/*.pal.
obj/%.lst bin/%-pal.pt: @srcdir@/src/asm/%.pal bin/palbart
	bin/palbart -lr $< || cat obj/$*.err
	mv @srcdir@/src/asm/$*.lst obj
	mv @srcdir@/src/asm/$*.rim bin/$*-pal.pt

# Ditto for those in examples/*.pal.
obj/%.lst bin/%-pal.pt: @srcdir@/examples/%.pal bin/palbart
	bin/palbart -lr $< || cat obj/$*.err
	mv @srcdir@/examples/$*.lst obj
	mv @srcdir@/examples/$*.rim bin/$*-pal.pt

# Rule for converting ASCII FOCAL examples in examples/*.fc to
# bin/*-focal.pt.
bin/%-focal.pt: @srcdir@/examples/%.fc bin/txt2ptp
	bin/txt2ptp < $< > bin/$*-focal.pt

# Rule for translating PAL assembly language program listings to SIMH
# boot scripts.
boot/%.script: obj/%.lst
	@srcdir@/tools/mkbootscript $<

# Rules for making aliases of named example programs translated to boot
# scripts as special numbered boot scripts
boot/1.script: boot/hs-rim-loader.script
	ln -f $< $@
boot/5.script: boot/ac-mq-blinker.script
	ln -f $< $@





$(BUILDDIRS):
	mkdir -p $@

$(SIM): $(SIM_OBJS) obj/gpio-@LED_DRIVER_MODULE@ls.o
	$(CC) -o $@ $^ $(LIBS)

bin/cc8: $(CC8_OBJS)
	$(CC) -o $@ $^ $(LIBS)

bin/d8tape: $(D8TAPE_OBJS)
	$(CC) -o $@ $^

bin/palbart: $(PALBART_OBJS)
	$(CC) -o $@ $^

bin/pidp8i-test: obj/test.o obj/gpio-nls.o obj/gpio-common.o
	$(CC) -o $@ $^ $(LIBS) -lncurses

bin/ptp2txt: obj/ptp2txt.o
	$(CC) -o $@ $^
	ln -f bin/ptp2txt bin/txt2ptp

bin/txt2ptp: bin/ptp2txt
	ln -f bin/ptp2txt bin/txt2ptp

bin/deeper: obj/deeper.o obj/gpio-@LED_DRIVER_MODULE@ls.o obj/gpio-common.o
	$(CC) -o $@ $^ $(LIBS)

libexec/scanswitch: obj/scanswitch.o obj/gpio-nls.o obj/gpio-common.o
	$(CC) -o $@ $^ $(LIBS)

# Reconfigure whenever one of the *.in or autosetup files changes unless
# this is "make clean".
# 
# We purposely list only one of the OUTFILES on the left hand side
# because to list them all is to invite Make to run N copies of the
# configure script in parallel up to the limit of -j or the number of
# files in INFILES, whichever is lower.  Order-only prerequisites can't
# help here (|) as that only affects the right hand side.
ifeq ($(findstring clean,$(MAKECMDGOALS)),)
media/os8/init.tx: $(INFILES) $(PRECIOUS_INFILES) @AUTODEPS@
	@AUTOREMAKE@ && $(MAKE)



# Also do it if the autodep tool is newer than its output, suggesting










# that if re-run, it would generate different output.

$(ADF): @srcdir@/tools/mkadrules
	@AUTOREMAKE@ && $(MAKE)
endif

# Rebuild simulator if the version string tool changes, since its output
# may have changed.
src/gpio-common.c: @srcdir@/tools/version

# Pull in *.d files generated by the autodependency mechanism.  See the
# header comment of tools/mkadrules.
-include \
	$(SIM_OBJS:.o=.d) \
	$(CC8_OBJS:.o=.d) \
	$(D8TAPE_OBJS:.o=.d) \
	$(MISC_OBJS:.o=.d) \
	$(PALBART_OBJS:.o=.d)
-include $(ADF)

# Getting Started with the PiDP-8/I Software

## Prerequisites

*   A Raspberry Pi with the 40-pin GPIO connector.  That rules out the
    first-generation Raspberry Pi model A and B boards which had a
    26-pin GPIO connector.

*   An SD card containing [a compatible OS][os].

*   This software distribution, unpacked somewhere convenient within the
    filesystem on the Raspberry Pi.

    We recommend that you unpack it somewhere your user has read/write
    access like `$HOME/src/pidp8i`. Since it installs as a system
    service, you might prefer `/usr/local/src` or `/opt/src`, though
    you'll have to adjust permissions for that.

    The [old stable 2015.12.15 release][osd] required that you unpack
    the software into `/opt/pidp8`, but we now neither require nor
    recommend that.

*   We require several tools and libraries that aren't always installed:

    *   A working C compiler and other standard Linux build tools,
        such as `make(1)`.

    *   Python's `pexpect` library

    *   The `usbmount` tool
    
        This is provides two things:
        
        *   USB stick auto-mounting on stripped-down OSes like Raspbian
            Lite so you can use the PiDP-8/I `SING_STEP` + `DF` feature
            without having to manually mount the USB stick first.
        
        *   A known directory structure that allows the PiDP-8/I
            software to find the media image files on those sticks.
            (`*.pt`, `*.dt`, `*.rk`, etc.)

        Full-blown GUI OSes tend to have USB auto-mounting set up
        already, though they won't meet the second criteria unless they
        use the same directory layout as `usbmount`: `/media/usbN`,
        where `N` is a number from 0 to 7, depending on the order
        you attached the USB stick.  Many Linuxes use `/media/LABEL`
        instead, for example, where `LABEL` is the partition's label;
        the PiDP-8/I software won't find the files on those USB sticks
        in that case.

    *   The `ncurses` development libraries

    To install all of this on a Raspbian type OS, say:

        $ sudo apt update
        $ sudo apt install build-essential
        $ sudo apt install libncurses-dev python-pip usbmount
        $ sudo pip install pexpect

[os]: https://tangentsoft.com/pidp8i/wiki?name=OS+Compatibility


<a id="unpacking"></a>
## Getting the Software onto Your Pi

If you're reading this file within an unpacked distribution of the
PiDP-8/I software, you should skip this section, because you have
already achieved its aim.

If you are reading this [online][this] and have not yet downloaded and
unpacked the software source code onto your Pi, this section will get
you going.

[this]: https://tangentsoft.com/pidp8i/doc/trunk/README.md


<a id="transferring"></a>
### Transferring the File to the Pi

The first step is to get the tarball (`*.tar.gz` file) or Zip file onto
the Pi. There are many options:

1.  **Copy the file to the SD card** you're using to boot the Pi.
    When inserted into a Mac or Windows PC, typically only the `/boot`
    partition mounts as a drive your OS can see.  (There's a much
    larger partition on the SD card, but most PCs cannot see it.)
    There should be enough free space left in this small partition to
    copy the file over.  When you boot the Pi up with that SD card,
    you will find the tarball or Zip file in `/boot`.

2.  **Pull the file down to the Pi** over the web, directly to the Pi:

        $ wget -O pidp8i.tar.gz https://goo.gl/JowPoC

    That will get you a file called `pidp8i.tar.gz` in the current
    working directory.

3.  **SCP the file over** to a running Pi from another machine.
    If your Pi has OpenSSH installed and running, you can use
    [WinSCP][wscp], [Cyberduck][cd], [FileZilla][fz] or another SCP
    or SFTP-compatible file transfer program to copy the file to the
    Pi over the network.

[cd]:   https://cyberduck.io/
[fz]:   https://filezilla-project.org/
[wscp]: https://winscp.net/eng/

4.  **Clone the Fossil repository** using the instructions in the
    [`HACKERS.md` file][hack]. (Best for experts or those who wish to
    become experts.)

[hack]: https://tangentsoft.com/pidp8i/doc/trunk/HACKERS.md

5.  **Switch to the binary OS installation images** available from the
    [top-level project page][cprj].  These are default installations of
    Raspbian Lite with the PiDP-8/I software already downloaded, built,
    and installed.  These images were produced in part using option #4
    above, so you can use Fossil to update your software to the current
    version at any time, as long as the Pi is connected to the Internet.


<a id="unpacking"></a>
### Unpacking the Software on Your Pi

Having transferred the distribution file onto your Pi, you can unpack it
with one of the two following commands.

If you grabbed the tarball:

    $ tar xvf /path/to/pidp8i-VERSION.tar.gz

If you grabbed the Zip file instead:

    $ unzip /path/to/pidp8i-VERSION.zip

The file name will vary somewhat, depending on when and how you
transferred the file.  After unpacking it, you will have a new
directory beginning with `pidp8i`.  `cd` into that directory, then
proceed with the [configuration](#configuring) steps below.


<a id="help"></a>
### If You Need More Help

If the above material is not sufficient to get you started, you might
want to look at [the documentation][rpfd] provided by the Raspberry
Pi Foundation.  In particular, we recommend their [Linux][rpfl] and
[Raspbian][rpfr] guides.  The book "[Make: Linux for Makers][lfm]"
by Aaron Newcomb is also supposed to be good.


[rpfd]: https://www.raspberrypi.org/documentation/
[rpfl]: https://www.raspberrypi.org/documentation/linux/
[rpfr]: https://www.raspberrypi.org/documentation/raspbian

[lfm]:  https://www.makershed.com/products/make-linux-for-makers


<a id="configuring"></a>
## Configuring, Building and Installing

This software distribution builds and installs in the same way as most
other Linux/Unix software these days.  The short-and-sweet is:

    $ ./configure && make && sudo make install

The `configure` step is generally needed only the first time you build
the software in a new directory.  You may want to add options after it,
as described [below](#options).

After that initial configuration, the software normally auto-reconfigures
itself on updates using the same options you gave before, but occasionally
we make some change that prevents this from happening.  If you get a
build error after updating to a new version of the software, try saying:

    $ make reconfig

...and then continuing with the `make && sudo make install` steps before
reporting a build error.

If `make reconfig` also fails, you can try running the `configure`
script again manually.


<a id="running"></a>
### Running the Software

For the most part, this is covered in the documentation linked from the
[Learning More](/#learning) section of the project home page.

The only tricky bit is that if this is the first time you have
configured, built and installed the software as above on a given system,
you will have to log out and back in before commands like `pidp8i` will
be in your user's `PATH`.


<a id="options"></a>
### Configure Script Options

You can change many things about the way the software is built and
installed by giving options to the `configure` script:


<a id="prefix"></a>
#### --prefix

Perhaps the most widely useful `configure` script option is `--prefix`,
which lets you override the default installation directory, `/opt/pidp8i`.
There are many good reasons to change where the software gets installed,
but the default is also a good one, so unless you know for a fact that
you want to change this default, leave it alone.

For example, you might prefer that the installer put the built software
under your home directory.  This will do that:

    $ ./configure --prefix=$HOME/pidp8i && sudo make install

You might think that installing to a directory your user has complete
control over would remove the need for installing via `sudo`, but that
is not the case, since the installation script needs root privileges to

mark a few of the executables as having permission to run at high priority
levels, which improves the quality of the display, particularly with the
[incandescent lamp simulator][ils] feature enabled.


<a id="lowercase"></a>
#### --lowercase

The American Standards Association (predecessor to ANSI) delivered the
second major version of the ASCII character encoding standard the same
year the first PDP-8 came out, 1965. The big new addition? Lowercase.

That bit of history means that when the PDP-8 was new, lowercase was a

    getting the software to work as you expect when built in this mode,
    try enabling CAPS LOCK.

[sa]:  http://homepage.cs.uiowa.edu/~jones/pdp8/faqs/#charsets
[tty]: https://tangentsoft.com/pidp8i/wiki?name=OS/8+Console+TTY+Setup


<a id="nls"></a>
#### --no-lamp-simulator

If you build the software on a multi-core host, the PDP-8/I simulator is
normally built with the [incandescent lamp simulator][ils] feature,
which drives the LEDs in a way that mimics the incandescent lamps used
in the original PDP-8/I. (We call this the ILS for short.) This feature
currently takes too much CPU power to run on anything but a multi-core
Raspberry Pi, currently limited to the Pi 2 and Pi 3 series.

If you configure the software on a single-core Pi — models A+, B+, and
Zero — the simulator uses the original low-CPU-usage LED driving method
instead. (a.k.a. NLS for short, named after this configuration option.)

Those on a multi-core host who want this low-CPU-usage LED driving
method can give the `--no-lamp-simulator` option to `configure`.  This
method not only uses less CPU, which may be helpful if you're trying to
run a lot of background tasks on your Pi 2 or Pi 3, it can also be
helpful when the CPU is [heavily throttled][thro].


<a id="serial-mod"></a>
#### --serial-mod

If you have done [Oscar's serial mod][sm1] to your PiDP-8/I PCB and the
Raspberry Pi you have connected to it, add `--serial-mod` to the
`configure` command above.

If you do not give this flag at `configure` time with these hardware
modifications in place, the front panel will not work correctly, and
trying to run the software may even crash the Pi.

If you give this flag and your PCBs are *not* modified, most of the
hardware will work correctly, but several lights and switches will not
work correctly.


<a id="alt-serial-mod"></a>
#### --alt-serial-mod

This flag is for an [alternative serial mod by James L-W][sm2]. It
doesn't require mods to the Pi, and the mods to the PiDP-8/I board are
different from Oscar's.  This flag changes the GPIO code to work with
these modifications to the PiDP-8/I circuit design.

See the linked mailing list thread for details.

As with `--serial-mod`, you should only enable this flag if you have
actually done the mods as specified by James L-W.


#### --throttle

See [`README-throttle.md`][thro] for the values this option takes.  If
you don't give this option, the simulator runs as fast as possible, more
or less.


#### --disable-cc8-cross

Give this option if you do not want to build Ian Schofield's `cc8` C
cross-compiler on the host.

Note that this is different from `--disable-os8-cc8`, which disables the
*native OS/8* C compiler. They are two different C compilers: one runs
outside the SIMH PDP-8 simulator and the other runs inside the simulator
under OS/8.


<a id="disable-os8"></a>
#### --disable-os8-\*

Several default components of the [OS/8 RK05 disk image](#os8di) used by
boot options IF=0 and IF=7 can be left out to save space and build time:

*   **--disable-os8-advent** — Leave out the [Adventure][advent] game.

*   **--disable-os8-ba** - Leave out the BASIC games and demos which
    come from DEC's book "101 BASIC Computer Games." These are normally
    installed to `RKB0:` as `*.BA`, thus the option's name.

    (We considered naming it `--disable-os8-basic-games-and-demos`, but
    that's too long, and it can't be `--disable-os8-basic` because that
    implies that it is the OS/8 BASIC subsystem that is being left out,
    which is not even currently an option.)

*   **--disable-os8-chess** — Leave out John Comeau's
    [CHECKMO-II chess implementation][chess].

*   **--disable-os8-cc8** - Leave out Ian Schofield's native OS/8 CC8
    compiler normally installed to `SYS:`.  This option is implicitly
    given if you give `--disable-os8-fortran-ii` because the output of
    the OS/8 CC8 compiler is a SABR file, and SABR is part of the
    FORTRAN II subsystem.

*   **--disable-os8-crt** — Suppress the [console rubout behavior][tty]
    enabled while building the OS/8 binary RK05 disk image. You
    probably only want to do this if you have attached a real teletype
    to your PiDP-8/I, and thus do not want video terminal style rubout
    processing.

*   **--disable-os8-focal** - Do not install any version of FOCAL on the
    OS/8 system disk. This option sets `--disable-os8-uwfocal` and
    overrides `--enable-os8-focal69`, both discussed below.

*   **--disable-os8-fortran-ii** - Leaves out the FORTRAN II compiler,
    SABR, the linking loader (`LOADER`), the `LIBSET` tool, and the
    `*.RL` library files.

*   **--disable-os8-fortran-iv** - Leave the FORTRAN IV compiler out.

*   **--disable-os8-init** - Generate `RKB0:INIT.TX` but do not display
    it on OS/8 boot.  Rather than disable the default on-boot init
    message, you may want to edit `media/os8/init.tx.in` to taste
    and rebuild.

    (We still build the file when you give this option in case you
    later decide you want to enable the boot message, or you need to
    call up configuration information stored in `INIT.TX`.)

*   **--disable-os8-k12** - Leave out the Kermit-12 implementation
    normally installed to `RKA0:`

*   **--disable-os8-macrel** - Leave the MACREL v2 assembler and its
    associated FUTIL V8B tool out.

*   **--disable-os8-patches** - Do not apply any of the OS/8 V3D
    patches published by DEC.  See the [documentation][os8p] for this
    option for more information.

*   **--disable-os8-src** - Do not build the `os8v3d-src.rk05` disk
    image from the OS/8 source tapes.  This is not controlled by
    `--os8-minimal` because that only affects `os8v3d-bin.rk05`.

*   **--disable-os8-uwfocal** - Leave out the U/W FOCAL V4E programming
    environment normally installed to `RKA0:`.
    
    Note that the default installation only installs `UWF16K.SV`, not
    the rest of the files on `media/os8/subsys/uwfocal*.tu56`. There is
    much more to explore here, but we cannot include it in the default
    installation set because that would overrun OS/8's limitation on the
    number of files on a volume.

[advent]: http://www.rickmurphy.net/advent
[chess]:  https://chessprogramming.wikispaces.com/CHEKMO-II
[os8p]:   https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-patching.md


<a id="enable-os8"></a>
#### --enable-os8-\*

There are a few file sets not normally installed to the [OS/8 RK05 disk
image](#os8di) used by boot options IF=0 and IF=7. You can install them
with the following options:

*   **--enable-os8-music** — The `*.MU` music scores and Rich Wilson's
    associated compiler (`MUSIC.PA`) and player overlay (`PLAYOV.PA`)
    are not normally installed to the built OS/8 binary RK05 disk image
    because the Raspberry Pi reportedly does not emit eufficient RFI at
    AM radio frequencies when running these programs to cause audible
    music on a typical AM radio, the very point of these demos.  Until a
    way is found around this problem — what, low RFI is a *problem* now?
    — this option will default to "off".

*   **--enable-os8-vtedit** — This option installs a default-run macro
    pack called VTEDIT which causes the OS/8 version of TECO to run in
    full-screen mode and to react to [several special keyboard
    commands][uvte] not normally recognized by TECO.

    This feature is disabled by default because the VTEDIT macro pack
    changes the way TECO operates, and many people want TECO to behave
    like *TECO*. VTEDIT was first created during the PDP-8's commercial
    lifetime, so enabling this option is not an anachronism, but TECO is
    much older and had a much more wide-reaching impact in history, so
    we choose to provide unvarnished TECO by default.

    That having been said, people don't go to a ren fair and expect to
    experience the historical ubiquity of typhoid fever, so do not feel
    guilty if you choose to try this option.

[uvte]: https://tangentsoft.com/pidp8i/wiki?name=Using+VTEDIT

*   **--enable-os8-focal69** — Because the default installation includes
    U/W FOCAL, we have chosen to leave FOCAL 69 out by default to save
    space on the O/S 8 system disk. You can give this option to install
    this implementation alongside U/W FOCAL, or you can couple this
    option with `--disable-os8-uwfocal` to reverse our choice of which
    FOCAL implementation to install by default.

    You should know that the reason we made this choice is that the
    version of FOCAL 69 we are currently shipping is fairly minimal: we
    believe we are shipping the original DEC version of FOCAL 69 plus a
    few carefully-selected overlays. There are many more overlays and
    patches available on the Internet for FOCAL 69, but we have not had
    time to sort through these and make choices of which ones to ship or
    how to manage which ones get installed. Thus our choice: we want to
    provide the most functional version of FOCAL by default, and within
    the limitations of the time we have chosen to spend on this, that is
    U/W FOCAL today.

    (See our [U/W FOCAL manual supplement][suppd] for a list of
    differences between these versions of FOCAL, which implicitly
    explains why we chose it.)

    It is possible that we will eventually add enough patches and
    overlays to FOCAL 69 that it will become more powerful than U/W
    FOCAL, so we might then choose to switch the defaults, but that is
    just speculation at the time of this writing.

[suppd]: https://tangentsoft.com/pidp8i/doc/trunk/doc/uwfocal-manual-supp.md#diffs


#### --os8-minimal

If you set this flag, it sets all `--enable-os8-*` flags to false and
all `--disable-os8-*` flags to true. If you explicitly give any of these
flags to the `configure` script, this flag overrides them.

This flag only affects the optional installs made after the `BUILD`
step: it does not remove optional features of OS/8 itself, such as its
BASIC interpreter.

Giving this option therefore gets you an empty OS/8 `DSK:` device and
nothing in `SYS:` beyond what was left after the OS/8 `BUILD` step.

There are a few exceptions:

1.  This option does not affect the `--lowercase` option because that
    affects only OS/8's command interpreter and OS/8's BASIC
    implementation, so we deem it to be orthogonal to the purpose of the
    `--os8-minimal` flag, which only affects the optional post-`BUILD`
    features. If you want a *truly* pristime OS/8 disk, you should
    therefore also give `--lowercase=none`.

2.  This option does not affect `--disable-os8-src`, because it only
    suppresses optional features in the "bin" media.  If you want a
    minimal OS/8 bin disk and no src disk, give that option as well.


#### --help

Run `./configure --help` for more information on your options here.


## <a id="os8di"></a>OS/8 Disk Images

For the first several years of the PiDP-8/I project, the OS/8 RK05 disk
image included with the PiDP-8/I software (called `os8.rk05`) was based
on an image of a real RK05 disk pack that someone allegedly found in a
salvaged PDP-8 system.  Parts of the image were corrupt, and not all of
the pieces of software on the disk worked properly with the other parts.
It was also a reflection of the time it was created and used out in the
world, which was not always what we would wish to use today.

In late 2017 [several of us][aut] created the `mkos8` tool, which takes
the `--*-os8-*` options documented above and generates the
`os8v3d-*.rk05` RK05 disk image files with your chosen configuration
options.

This set of disk images entirely replaces the old `os8.rk05` disk image,
in that all features of the old disk image are still available, though
not necessarily in the default configuration. In some cases, we have
disabled some features that were included in the stock `os8.rk05` disk
image, and in other cases we have changed the behavior of features.
Mostly, though, the new disk images are simply more functional than the
old ones.

If you wish to know the full details of how these disk images are
created, the best documentation so far is [the source code for the
`mkos8` script][mkos8] and the [documentation for `class simh`][cs].

The remainder of this section describes some aspects of these disk
images which are not clear from the descriptions of the `--*-os8-*`
configuration options above.

[aut]: https://tangentsoft.com/pidp8i/doc/trunk/AUTHORS.md


### Baseline

The baseline for the bootable OS/8 disk images comes from a set of
DECtapes distributed by Digital Equipment Corporation which are now
included with the PiDP-8/I software; see the [`media/os8/*.tu56`
files][os8mf]. From these files and your configuration options, the
`mkos8` script creates the baseline `os8v3d-bin.rk05` disk image.

The default build creates a complete OS/8 system including `BUILD`
support, FORTRAN IV, MACREL v2, and more.


### Subtractions

It turns out that it's pretty easy to run out of directory space on an
OS/8 RK05 disk due to a limitation in the number of files on an OS/8
filesystem.  For this reason, the archive of device drivers and TD8E
system are left off the system packs.  They can be found in [OS/8
Binary Distribution DECtape #2][bdt2].

If you do fancy work with `BUILD`, you may need to attach that DECtape
image and copy files in from it.


### Default Additions

The OS/8 RK05 disk image build process normally installs many software
and data file sets to the disk image.  See the [option descriptions
above](#disable-os8): the "disable" option set effectively lists those
packages that `mkos8` installs by default, and the following set of
["enable" options](#enable-os8) lists those left out by default.


### Console Enhancements

The default build [enhances the console](/wiki?name=Console+TTY+Setup),
adding support for lower case terminals where:

1.  The SIMH PDP-8 simulator and a few select parts of OS/8 are adjusted
    to cope with lowercase input to [varying degrees](#lowercase).

2.  Rubout/backspace handling is set to assume a video terminal rather
    than a teletype by default.


### Patches

After the baseline disk image is created, `mkos8` makes a copy of it as
`os8v3d-patched.rk05` and applies a [carefully selected set of official
DEC patches][os8p] to it unless you give the `--disable-os8-patches`
configuration option.  The IF=0 and IF=7 boot options boot from the
patched disk unless you give that option.


[bdt2]:  https://tangentsoft.com/pidp8i/file/media/os8/al-4712c-ba-os8-v3d-2.1978.tu56
[cl]:    https://tangentsoft.com/pidp8i/doc/trunk/ChangeLog.md
[cs]:    https://tangentsoft.com/pidp8i/doc/trunk/doc/class-simh.md
[mkos8]: https://tangentsoft.com/pidp8i/doc/trunk/libexec/mkos8
[os8mf]: https://tangentsoft.com/pidp8i/file/media/os8
[tlrm]:  https://tangentsoft.com/pidp8i/doc/trunk/README.md


<a id="overwrite-setup"></a>
## Overwriting the Local Simulator Setup

When you run `sudo make install` step on a system that already has an
existing installation, it purposely does not overwrite two classes of
files:

1.  **The binary PDP-8 media files**, such as the RK05 disk image that
    holds the OS/8 image the simulator boots from by default. These media
    image files are considered "precious" because you may have modified
    the OS configuration or saved personal files to the disk the OS
    boots from, which in turn modifies this media image file out in the
    host operating environment.

    There is an important exception here: when upgrading from v20170404
    to v201712xx or newer, the old `os8.rk05` disk image will be left
    untouched per the above, but because `os8v3d-*.rk05` does not exist
    yet, those will be copied alongside `os8.rk05`. However, the next
    item still holds, so that the simulator will continue to use
    `os8.rk05` because it will be booted by the preexisting scripts.

2.  **The PDP-8 simulator configuration files**, installed as
    `$prefix/share/boot/*.script`, which may similarly have local
    changes, and thus be precious to you.

Sometimes this "protect the precious" behavior isn't what you want.
(Gollum!) One common reason this may be the case is that you've damaged
your local configuration and want to start over. Another common case is
that the newer software you're installing contains changes that you want
to reflect into your local configuration.

You have several options here:

1.  If you just want to reflect the prior PDP-8 simulator configuration
    file changes into your local versions, you can hand-edit the
    installed simulator configuration scripts to match the changes in
    the newly-generated `boot/*.script` files under the build directory.

2.  If the change is to the binary PDP-8 media image files — including
    the [generated OS/8 disk images](#os8di) — and you're unwilling to
    overwrite your existing ones wholesale, you'll have to mount both
    versions of the media image files under the PDP-8 simulator and copy
    the changes over by hand.

3.  If your previously installed binary OS media images — e.g. the
    [OS/8 RK05 disk image](#os8di) that the simulator boots from by
    default — are precious but the simulator configuration scripts
    aren't precious, you can just copy the generated `boot/*.script`
    files from the build directory into the installation directory,
    `$prefix/share/boot`.  (See the `--prefix` option above for the
    meaning of `$prefix`.)

4.  If neither your previously installed simulator configuration files
    nor the binary media images are precious, you can force the
    installation script to overwrite them both with a `sudo make
    mediainstall` command after `sudo make install`.

    Beware that this is potentially destructive! If you've made changes
    to your PDP-8 operating systems or have saved files to your OS
    system disks, this option will overwrite those changes!


<a id="testing"></a>
## Testing Your PiDP-8/I Hardware

You can test your PiDP-8/I LED and switch functions with these commands:

    $ sudo systemctl stop pidp8i
    $ pidp8i-test

You may have to log out and back in before the second command will work,
since the installation script modifies your normal user's `PATH` the
first time you install onto a given system.

It is important to stop the PiDP-8/I simulator before running the test
program, since both programs need exclusive access to the LEDs and
switches on the front panel.  After you are done testing, you can start
the PiDP-8/I simulator back up with:

    $ sudo systemctl start pidp8i

See [its documentation][test] for more details.


<a id="using"></a>
## Using the Software

For the most part, this software distribution works like the [old stable
2015.12.15 distribution][osd]. Its [documentation][oprj] therefore
describes this software too, for the most part.

The largest user-visible difference between the two software
distributions is that all of the shell commands affecting the software
were renamed to include `pidp8i` in their name:

1.  To start the simulator:

    what else you can do with the simulator command language, or read
    the [SIMH Users' Guide][sdoc].

5.  To shut the simulator down from the Raspbian command line:

        $ sudo systemctl stop pidp8i

There are [other major differences][mdif] between the old stable
distribution and this one.  See that linked wiki article for details.


## License

Copyright © 2016-2017 by Warren Young. This document is licensed under
the terms of [the SIMH license][sl].


[cprj]: https://tangentsoft.com/pidp8i/

[sm1]:  http://obsolescence.wixsite.com/obsolescence/2016-pidp-8-building-instructions
[sm2]:  https://groups.google.com/d/msg/pidp-8/-leCRMKqI1Q/Dy5RiELIFAAJ
[osd]:  http://obsolescence.wixsite.com/obsolescence/pidp-8-details
[dt2]:  https://github.com/VentureKing/Deeper-Thought-2
[sdoc]: https://tangentsoft.com/pidp8i/uv/doc/simh/main.pdf
[oprj]: http://obsolescence.wixsite.com/obsolescence/pidp-8
[test]: https://tangentsoft.com/pidp8i/doc/trunk/doc/pidp8i-test.md
[thro]: https://tangentsoft.com/pidp8i/doc/trunk/README-throttle.md
[mdif]: https://tangentsoft.com/pidp8i/wiki?name=Major+Differences
[sl]:   https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md
[ils]:  https://tangentsoft.com/pidp8i/wiki?name=Incandescent+Lamp+Simulator

# authorization from those authors.
########################################################################

define defaultprefix /opt/pidp8i

use cc
use cc-lib
use cc-shared

# Canonicalize some paths which may be relative and generate others from them
set abspfx [file-normalize [get-define prefix]]
define ABSPREFIX $abspfx
define BOOTDIR  "$abspfx/share/boot"
define MEDIADIR "$abspfx/share/media"

# Define command line options
options {
    alt-serial-mod    => "use GPIO drive scheme suitable for James L-W's serial mod method"
    cc8-cross=1       => "do not build the cc8 cross-compiler on the host"
    debug-mode        => "create a debug build (default is release)"
    lowercase:        => "select how lowercase input is to be handled"
    no-lamp-simulator => "use simple LED driver instead of incandescent lamp simulator"
    os8-advent=1      => "leave Adventure off the built OS/8 RK05 image"
    os8-ba=1          => "leave *.BA BASIC games and demos off the built OS/8 RK05 image"
    os8-cc8=1         => "leave the native OS/8 CC8 compiler off the built OS/8 RK05 image"
    os8-crt=1         => "suppress CRT-style rubout processing in the built OS/8 RK05 image"
    os8-chess=1       => "leave the CHECKMO-II game of chess off the built OS/8 RK05 image"
    os8-dcp=1         => "leave the DCP disassembler off the built OS/8 RK05 image"
    os8-focal=1       => "leave FOCAL 69 and U/W FOCAL off the built OS/8 RK05 image"
    os8-focal69       => "add FOCAL 69 to the built OS/8 RK05 image"
    os8-fortran-ii=1  => "leave FORTRAN II off the built OS/8 RK05 image"
    os8-fortran-iv=1  => "leave FORTRAN IV off the built OS/8 RK05 image"
    os8-init=1        => "do not show the OS/8 INIT message in the built OS/8 RK05 image"
    os8-k12=1         => "leave 12-bit Kermit off the built OS/8 RK05 image"
    os8-macrel=1      => "leave MACREL assembler off the built OS/8 RK05 image"
    os8-minimal       => "set all --disable-os8-* options, giving minimal OS/8 bin disk"
    os8-music         => "add *.MU files to the built OS/8 RK05 image"
    os8-patches=1     => "do not apply DEC patches to the built OS/8 RK05 bin image"
    os8-src=1         => "do not build os8v3d-src.rk05 from OS/8 source tapes"
    os8-uwfocal=1     => "leave U/W FOCAL (only) off the built OS/8 RK05 image"
    os8-vtedit        => "add the TECO VTEDIT setup to built OS/8 RK05 image"
    serial-mod        => "use GPIO drive scheme suitable for Oscar Vermeulen's serial mod method"
    throttle:         => "override the throttle values in the boot scripts"
}

# Handle meta-options first.
if {![opt-bool os8-focal]} {
    if {[opt-bool os8-focal69]} {
        dict set $::autosetup(optset) "os8-focal69" 0
    }
    if {[opt-bool os8-uwfocal]} {
        dict set $::autosetup(optset) "os8-uwfocal" 0
    }
}
set os8min [opt-bool os8-minimal]
set os8src [opt-bool os8-src]

# Translate the --*-os8-* options to mkos8 command line option format
# and build the Python option map it uses to interpret them.  This
# avoids the need to define the options by hand in both places.
set mkos8_opts ""
set os "# GENERATED BY auto.def; DO NOT MODIFY.\n\nopts = {\n"
foreach opt [lsort [dict keys $::autosetup(optdefault)]] {
    # Skip meta-options handled above and non --*-os8-* options.
    if {$opt in {os8-focal os8-minimal os8-src}} { continue }
    if {[string first "os8-" $opt] != 0} { continue }

    # Add next line to Python output
    set od [dict get $::autosetup(optdefault) $opt]
    set oh [dict get $::autosetup(opthelpline) $opt]
    set obn [string replace $opt 0 3]
    append os "\t\"" $obn "\": \[ $od, \"" $oh "\" \],\n"

    # Fix grammar for upcoming msg-result calls
    if {[string first "do not " $oh] == 0} {
        set oh [string replace $oh 0 6]
    } elseif {[string first "do " $oh] == 0} {
        set oh [string replace $oh 0 2]
    }

    # Choose option to pass to mkos8 corresponding to this configure
    # script option.  Also tell user what we're going to do; grammar
    # is inverted because the option help text says what happens when
    # you give the opposite of the option's default argument.
    set ov [opt-bool $opt]
    if {$ov == $od} {
        # Don't append a mkos8 option; the default is correct.
        msg-result "Will not $oh."
    } elseif {!$os8min && $ov} {
        append mkos8_opts " --enable-" $obn
    } else {
        append mkos8_opts " --disable-" $obn
    }
}
append os "}\n"
if {![file exists "lib/mkos8"]} { file mkdir "lib/mkos8" }
write-if-changed "lib/mkos8/opts.py" $os

# Handle the OS/8 options not passed to mkos8 generically by above.
if {$os8src} {
    msg-result "Building os8v3d-src.rk05 from OS/8 source tapes."
    define OS8_SRC_RK05 bin/os8v3d-src.rk05
} else {
    msg-result "Will not build os8v3d-src.rk05 from OS/8 source tapes."
    define OS8_SRC_RK05 {}
}
if {$os8min || ![opt-bool os8-patches]} {
    msg-result "Will not patch OS/8 on the RK05 bin disk."
    define OS8_BOOT_DISK "os8v3d-bin.rk05"
    define MKOS8_BIN_PATCHES {}
} else {
    msg-result "Will apply OS/8 V3D patches to the RK05 bin disk."
    define OS8_BOOT_DISK "os8v3d-patched.rk05"
    define MKOS8_BIN_PATCHES patch
}

# React to remaining chosen command line options
if {[opt-bool alt-serial-mod]} {
    msg-result "GPIO drive adjusted for James L-W's serial mods to the PiDP-8/I PCB."
    define PCB_SERIAL_MOD_JLW
    define PCB_SERIAL_MOD_ANY
}

if {[opt-bool serial-mod]} {
    msg-result "GPIO drive adjusted for O. Vermeulen's serial mods to the Pi & PiDP-8/I PCBs."
    define PCB_SERIAL_MOD_OV
    define PCB_SERIAL_MOD_ANY
}

if {[opt-bool cc8-cross]} {
    define CC8_CROSS bin/cc8
} else {
    define CC8_CROSS {}
    msg-result "Will not build the cc8 cross-compiler."
}

if {[opt-bool debug-mode]} {
    msg-result "Creating a debuggable build."
    define BUILDMODE {-O0 -g}
} else {
    msg-result "Creating a release build."
    define BUILDMODE {-O2}
}



set lv [opt-val lowercase]
if {$lv == ""} { set lv "auto" }
if {$lv == "auto"} {
    define SIMH_PASS_LOWERCASE
} elseif {$lv == "pass"} {
    define SIMH_PASS_LOWERCASE
    append mkos8_opts " --disable-lcmod"
} elseif {$lv == "upper"} {
    append mkos8_opts " --disable-lcmod"
} else {
    user-error "Legal values for --lowercase are {auto,pass,upper}."
}
msg-result "Lowercase handling set to '$lv' mode."

if {[opt-bool os8-cc8] && ![opt-bool os8-fortran-ii]} {
    msg-result "Must clear --disable-os8-fortran-ii when CC8 is enabled."
    regsub -- {--disable-os8-fortran-ii } $mkos8_opts {}
}






# We've purposely held off exporting the mkos8 option set until now
# because some of the configuration options can affect the option set.

define MKOS8_OPTS $mkos8_opts




# Force a rebuild of the OS/8 media if the option set changed.


if {![file exists "obj"]} { file mkdir "obj" }
write-if-changed "obj/mkos8.opts" $mkos8_opts {
    file delete -force bin/os8v3d-bin.rk05
    msg-result "mkos8 options changed; will rebuild OS/8 disk images."

}












# High-level definitions
set builddir [get-define builddir]
set srcdir [get-define srcdir]
set cores [exec $srcdir/tools/corecount]

# Translate --throttle value to a SIMH command

    user-error "No install(1) type program found; install GNU Coreutils."
}
msg-result "Found GNU install(1) program as [get-define INSTALL]."

# If we have cscope here, we'll use it in the "tags" target
define HAVE_PROG_CSCOPE [cc-check-progs cscope]






# Remember the name and primary group of the user who installed this, since
# we want to give that group write privileges to some files when they're
# installed, and we want them to own the screen(1) session.
set instgrp [exec id -grn]
set instusr [exec id -urn]
if {$instusr == "root"} {
    msg-result "Error: This software will not install and run as root."

# mask a real problem that needs to be diagnosed.
set tool "tools/version"
set cmd "$srcdir/$tool"
set status [catch {exec $cmd} version]
if {$status != 0} {
    # The most likely cause for tools/version to fail is that the repo
    # file has become disassociated from the local checkout directory.
    set sql ".timeout 5000 ; select value from vvar where name=\"repository\""
    set cmd "fossil sql --no-repository $srcdir/.fslckout '$sql'"
    set status [catch {exec /bin/sh -c $cmd} path]
    if {$status != 0} {
        user-error "Fossil doesn't seem to work here.  Is it installed?\nCMD: $cmd"
    } elseif {[file exists $path]} {
        user-error "$tool failed to get checkout version from $path"
    } else {
        user-error "$tool failed: $path does not exist."
    }
}
define VERSION $version

# Get host, user, and date info for use by media/os8/init.tx.
catch {exec hostname} host
set user $::env(USER)
define BUILDUSER "$user@$host"
define BUILDTS [clock format [clock seconds] -format "%Y.%m.%d at %T %Z"]

# The mkos8 script requires Python and some non-core modules.
set status [catch {exec python -c exit} result]
if {$status != 0} {
    user-error "Python does not appear to be installed here.  It is required."
}
msg-result "Python is installed here."
set status [catch {exec python -c "import pexpect" 2> /dev/null} result]
if {$status != 0} {
    set msg "The Python pexpect module is not installed here.  Fix with\n"
    append msg "\n    sudo pip install pexpect\n"
    append msg "\nOR:\n"
    append msg "\n    sudo easy_install pexpect\n"
    append msg "\nOR:\n"
    append msg "\n    sudo apt install python-pexpect\n"
    user-error $msg
}
msg-result "Python module pexpect is installed here."
set status [catch {exec python -c "import pkg_resources" 2> /dev/null} result]
if {$status != 0} {
    set msg "The Python pkg_resources module is not installed here.  Fix with\n"
    append msg "\n    sudo pip install pkg_resources\n"
    append msg "\nOR:\n"
    append msg "\n    sudo easy_install pkg_resources\n"
    append msg "\nOR:\n"
    append msg "\n    sudo apt install python-pkg-resources\n"
    user-error $msg
}
msg-result "Python module pkg_resources is installed here."

# Build Deeper Thought if we find it here
if {[file exists "[get-define srcdir]/src/deeper.c"]} {
    set ls [string toupper "[get-define LED_DRIVER_MODULE]ls"]
    msg-result "Found Deeper Thought; building it against $ls GPIO module"
    define BUILD_DEEPER_THOUGHT 1
}

# Generate autodependency Makefile rule sets.
#
# It is important to list "src" last, because GNU make takes the first
# one that matches, and the wildcards in the generated rules for "src"
# match all "src/*" subdirs.
set status [catch {
    exec $srcdir/tools/mkadrules $srcdir src/cc8/cross src/d8tape src/palbart src/PDP8 src
} result]
if {$status == 0} {
    msg-result $result
} else {
    user-error "Failed to generate autodependency rules: $result!"
}

# Write outputs.
#
# NOTE: If you change the list of files here, change INFILES in
# Makefile.in, too.
make-config-header src/config.h \
    -auto {ENABLE_* HAVE_* PACKAGE_* SIZEOF_*} \
    -bare {ILS_MODE PCB_*}
make-template Makefile.in
make-template bin/pidp8i.in
make-template boot/0.script.in
make-template boot/2.script.in
make-template boot/3.script.in
make-template boot/4.script.in
make-template boot/6.script.in
make-template boot/7.script.in
make-template boot/run.script.in
make-template etc/pidp8i-init.in
make-template etc/sudoers.in
make-template examples/Makefile.in
make-template lib/pidp8i/__init__.py.in
make-template lib/pidp8i/dirs.py.in
make-template lib/pidp8i/ips.py.in
make-template media/os8/init.tx.in
make-template src/Makefile.in
make-template src/cc8/Makefile.in
make-template src/cc8/os8/Makefile.in
make-template src/gpio-common.c.in
make-template src/PDP8/Makefile.in
make-template src/PDP8/pidp8i.c.in

make-template tools/simh-update.in

exec chmod +x "$builddir/tools/simh-update"

	set autosetup(argv) $argv
	set autosetup(cmdline) {}
	# options is a list of known options
	set autosetup(options) {}
	# optset is a dictionary of option values set by the user based on getopt
	set autosetup(optset) {}
	# optdefault is a dictionary of default values
	set autosetup(optdefault) {}
	# options-defaults is a dictionary of overrides for default values for options
	set autosetup(options-defaults) {}
	set autosetup(optionhelp) {}
	set autosetup(opthelpline) {}
	set autosetup(showhelp) 0

	# Parse options
	use getopt

	# At the is point we don't know what is a valid option
	# We simply parse anything that looks like an option
	set autosetup(getopt) [getopt argv]

	#"=Core Options:"
	options-add {
		help:=local  => "display help and options. Optionally specify a module name, such as --help=system"
		licence license => "display the autosetup license"
		version      => "display the version of autosetup"
		ref:=text manual:=text
		reference:=text => "display the autosetup command reference. 'text', 'wiki', 'asciidoc' or 'markdown'"
		debug        => "display debugging output as autosetup runs"

		install:=.   => "install autosetup to the current or given directory"
	}
	if {$autosetup(installed)} {
		# hidden options so we can produce a nice error
		options-add {
			sysinstall:path
		}
	} else {
		options-add {
			sysinstall:path  => "install standalone autosetup to the given directory (e.g.: /usr/local)"
		}
	}
	options-add {
		force init:=help   => "create initial auto.def, etc.  Use --init=help for known types"
		# Undocumented options
		option-checking=1
		nopager
		quiet
		timing
		conf:
	}

	if {[opt-bool version]} {
		puts $autosetup(version)
		exit 0
	}

	# autosetup --conf=alternate-auto.def
	if {[opt-str conf o]} {
		set autosetup(autodef) $o
	}

	# Debugging output (set this early)
	incr autosetup(debug) [opt-bool debug]
	incr autosetup(force) [opt-bool force]
	incr autosetup(msg-quiet) [opt-bool quiet]
	incr autosetup(msg-timing) [opt-bool timing]

	# If the local module exists, source it now to allow for
	# project-local customisations
	if {[file exists $autosetup(libdir)/local.tcl]} {
		use local
	}

	# Now any auto-load modules
	autosetup_load_auto_modules

	if {[opt-str help o]} {
		incr autosetup(showhelp)
		use help
		autosetup_help $o
	}

	if {[opt-bool licence license]} {
		use help
		autosetup_show_license
		exit 0
	}

	if {[opt-str {manual ref reference} o]} {
		use help
		autosetup_reference $o
	}

	# Allow combining --install and --init
	set earlyexit 0
	if {[opt-str install o]} {
		use install
		autosetup_install $o
		incr earlyexit
	}

	if {[opt-str init o]} {
		use init
		autosetup_init $o
		incr earlyexit
	}

	if {$earlyexit} {
		exit 0
	}
	if {[opt-str sysinstall o]} {
		use install
		autosetup_install $o 1
		exit 0
	}

	if {![file exists $autosetup(autodef)]} {
		# Check for invalid option first
		options {}
		user-error "No auto.def found in \"$autosetup(srcdir)\" (use [file tail $::autosetup(exe)] --init to create one)"

}

# @opt-val optionlist ?default=""?
#
# Returns a list containing all the values given for the non-boolean options in '$optionlist'.
# There will be one entry in the list for each option given by the user, including if the
# same option was used multiple times.

#


# If no options were set, '$default' is returned (exactly, not as a list).
#
# Note: For most use cases, 'opt-str' should be preferred.
#
proc opt-val {names {default ""}} {
	option-check-names {*}$names

	foreach opt $names {
		if {[dict exists $::autosetup(optset) $opt]} {
			lappend result {*}[dict get $::autosetup(optset) $opt]
		}
	}
	if {[info exists result]} {
		return $result
	}
	return $default
}

# @opt-str optionlist varname ?default?
#
# Sets '$varname' in the callers scope to the value for one of the given options.
#
# For the list of options given in '$optionlist', if any value is set for any option,
# the option value is taken to be the *last* value of the last option (in the order given).
#
# If no option was given, and a default was specified with 'options-defaults',
# that value is used.
#
# If no 'options-defaults' value was given and '$default' was given, it is used.
#
# If none of the above provided a value, no value is set.
#
# The return value depends on whether '$default' was specified.
# If it was, the option value is returned.
# If it was not, 1 is returns if a value was set, or 0 if not.
#
# Typical usage is as follows:
#
## if {[opt-str {myopt altname} o]} {
##     do something with $o
## }
#
# Or:
## define myname [opt-str {myopt altname} o "/usr/local"]
#
proc opt-str {names varname args} {
	global autosetup

	option-check-names {*}$names
	upvar $varname value

	if {[llength $args]} {
		# A default was given, so always return the string value of the option
		set default [lindex $args 0]
		set retopt 1
	} else {
		# No default, so return 0 or 1 to indicate if a value was found
		set retopt 0
	}

	foreach opt $names {
		if {[dict exists $::autosetup(optset) $opt]} {
			set result [lindex [dict get $::autosetup(optset) $opt] end]
		}
	}

	if {![info exists result]} {
		# No user-specified value. Has options-defaults been set?
		foreach opt $names {
			if {[dict exists $::autosetup(options-defaults) $opt]} {
				set result [dict get $autosetup(options-defaults) $opt]
			}
		}
	}

	if {[info exists result]} {
		set value $result
		if {$retopt} {
			return $value
		}
		return 1
	}

	if {$retopt} {
		set value $default
		return $value
	}

	return 0
}

proc option-check-names {args} {
	foreach o $args {
		if {$o ni $::autosetup(options)} {
			autosetup-error "Request for undeclared option --$o"
		}
	}

		set opt [lindex $opts $i]
		if {[string match =* $opt]} {
			# This is a special heading
			lappend autosetup(optionhelp) $opt ""
			set header {}
			continue
		}
		unset -nocomplain defaultvalue equal value

		#puts "i=$i, opt=$opt"
		regexp {^([^:=]*)(:)?(=)?(.*)$} $opt -> name colon equal value
		if {$name in $autosetup(options)} {
			autosetup-error "Option $name already specified"
		}

		#puts "$opt => $name $colon $equal $value"

		# Find the corresponding value in the user options
		# and set the default if necessary
		if {[string match "-*" $opt]} {
			# This is a documentation-only option, like "-C <dir>"
			set opthelp $opt
		} elseif {$colon eq ""} {
			# Boolean option
			lappend autosetup(options) $name

			# Check for override
			if {[dict exists $autosetup(options-defaults) $name]} {
				# A default was specified with options-defaults, so use it
				set value [dict get $autosetup(options-defaults) $name]
			}

			if {$value eq "1"} {
				set opthelp "--disable-$name"
			} else {
				set opthelp "--$name"
			}

			# Set the default
			if {$value eq ""} {
				set value 0
			}
			set defaultvalue $value
			dict set autosetup(optdefault) $name $defaultvalue

			if {[dict exists $autosetup(getopt) $name]} {
				# The option was specified by the user. Look at the last value.
				lassign [lindex [dict get $autosetup(getopt) $name] end] type setvalue
				if {$type eq "str"} {
					# Can we convert the value to a boolean?
					if {$setvalue in {1 enabled yes}} {
						set setvalue 1
					} elseif {$setvalue in {0 disabled no}} {
						set setvalue 0
					} else {
						user-error "Boolean option $name given as --$name=$setvalue"
					}
				}
				dict set autosetup(optset) $name $setvalue
				#puts "Found boolean option --$name=$setvalue"
			}
		} else {
			# String option.
			lappend autosetup(options) $name

			if {$colon eq ":"} {
				# Was ":name=default" given?
				# If so, set $value to the display name and $defaultvalue to the default
				# (This is the preferred way to set a default value for a string option)
				if {[regexp {^([^=]+)=(.*)$} $value -> value defaultvalue]} {
					dict set autosetup(optdefault) $name $defaultvalue
				}
			}

			# Maybe override the default value
			if {[dict exists $autosetup(options-defaults) $name]} {
				# A default was specified with options-defaults, so use it
				set defaultvalue [dict get $autosetup(options-defaults) $name]
				dict set autosetup(optdefault) $name $defaultvalue
			} elseif {![info exists defaultvalue]} {
				# For backward compatiblity, if ":name" was given, use name as both
				# the display text and the default value, but only if the user
				# specified the option without the value
				set defaultvalue $value
			}

			if {$equal eq "="} {
				# String option with optional value
				set opthelp "--$name?=$value?"
			} else {
				# String option with required value
				set opthelp "--$name=$value"
			}


			# Get the values specified by the user
			if {[dict exists $autosetup(getopt) $name]} {
				set listvalue {}

				foreach pair [dict get $autosetup(getopt) $name] {
					lassign $pair type setvalue
					if {$type eq "bool" && $setvalue} {
						if {$equal ne "="} {
							user-error "Option --$name requires a value"
						}
						# If given as a boolean, use the default value
						set setvalue $defaultvalue
					}
					lappend listvalue $setvalue
				}

				#puts "Found string option --$name=$listvalue"
				dict set autosetup(optset) $name $listvalue
			}
		}

		# Now create the help for this option if appropriate
		if {[lindex $opts $i+1] eq "=>"} {
			set desc [lindex $opts $i+2]
			if {[info exists defaultvalue]} {
				set desc [string map [list @default@ $defaultvalue] $desc]
			}
			#string match \n* $desc
			if {$header ne ""} {
				lappend autosetup(optionhelp) $header ""
				set header ""
			}
			# A multi-line description
			lappend autosetup(optionhelp) $opthelp $desc
			dict set autosetup(opthelpline) $name $desc
			incr i 2
		}
	}
}

# @module-options optionlist
#

		}
	}
}

# @options optionspec
#
# Specifies configuration-time options which may be selected by the user
# and checked with 'opt-str' and 'opt-bool'. '$optionspec' contains a series
# of options specifications separated by newlines, as follows:
#
# A boolean option is of the form:
#
## name[=0|1]  => "Description of this boolean option"
#
# The default is 'name=0', meaning that the option is disabled by default.
# If 'name=1' is used to make the option enabled by default, the description should reflect
# that with text like "Disable support for ...".
#
# An argument option (one which takes a parameter) is of the form:
#
## name:[=]value  => "Description of this option"
#
# If the 'name:value' form is used, the value must be provided with the option (as '--name=myvalue').
# If the 'name:=value' form is used, the value is optional and the given value is used as the default
# if it is not provided.
#
# The description may contain '@default@', in which case it will be replaced with the default
# value for the option (taking into account defaults specified with 'options-defaults'.
#
# Undocumented options are also supported by omitting the '=> description'.
# These options are not displayed with '--help' and can be useful for internal options or as aliases.
#
# For example, '--disable-lfs' is an alias for '--disable=largefile':
#
## lfs=1 largefile=1 => "Disable large file support"

		foreach o [dict keys $::autosetup(getopt)] {
			if {$o ni $::autosetup(options)} {
				user-error "Unknown option --$o"
			}
		}
	}
}

# @options-defaults dictionary
#
# Specifies a dictionary of options and a new default value for each of those options.
# Use before any 'use' statements in 'auto.def' to change the defaults for
# subsequently included modules.
proc options-defaults {dict} {
	foreach {n v} $dict {
		dict set ::autosetup(options-defaults) $n $v
	}
}

proc config_guess {} {
	if {[file-isexec $::autosetup(dir)/autosetup-config.guess]} {
		if {[catch {exec-with-stderr sh $::autosetup(dir)/autosetup-config.guess} alias]} {
			user-error $alias
		}
		return $alias

# If the variable is not defined or empty, it is set to '$value'.
# Otherwise the value is appended, separated by a space.
# Any extra values are similarly appended.
# If any value is already contained in the variable (as a substring) it is omitted.
#
proc define-append {name args} {
	if {[get-define $name ""] ne ""} {
		# Avoid duplicates
		foreach arg $args {
			set found 0
			foreach str [split $::define($name) " "] {
				if {$str eq $arg} {
					incr found
				}
			}
			if {!$found} {
				append ::define($name) " " $arg
			}
		}
	} else {
		set ::define($name) [join $args]
	}
	#dputs "$name += [join $args] => $::define($name)"

# Module which can install autosetup

# autosetup(installed)=1 means that autosetup is not running from source
# autosetup(sysinstall)=1 means that autosetup is running from a sysinstall verion
# shared=1 means that we are trying to do a sysinstall. This is only possible from the development source.

proc autosetup_install {dir {shared 0}} {
	global autosetup
	if {$shared} {
		if {$autosetup(installed) || $autosetup(sysinstall)} {
			user-error "Can only --sysinstall from development sources"
		}
	} elseif {$autosetup(installed) && !$autosetup(sysinstall)} {
		user-error "Can't --install from project install"
	}

	if {$autosetup(sysinstall)} {
		# This is the sysinstall version, so install just uses references
		cd $dir

		puts "[autosetup_version] creating configure to use system-installed autosetup"
		autosetup_create_configure 1
		puts "Creating autosetup/README.autosetup"
		file mkdir autosetup

		file mkdir $targetdir

		set f [open $target w]

		set publicmodules {}

		# First the main script, but only up until "CUT HERE"
		set in [open $autosetup(dir)/autosetup]
		while {[gets $in buf] >= 0} {
			if {$buf ne "##-- CUT HERE --##"} {
				puts $f $buf
				continue
			}

			# Insert the static modules here
			# i.e. those which don't contain @synopsis:
			# All modules are inserted if $shared is set
			puts $f "set autosetup(installed) 1"
			puts $f "set autosetup(sysinstall) $shared"
			foreach file [lsort [glob $autosetup(libdir)/*.{tcl,auto}]] {
				set modname [file tail $file]
				set ext [file ext $modname]
				set buf [readfile $file]
				if {!$shared} {
					if {$ext eq ".auto" || [string match "*\n# @synopsis:*" $buf]} {
						lappend publicmodules $file
						continue
					}
				}
				dputs "install: importing lib/[file tail $file]"
				puts $f "# ----- @module $modname -----"
				puts $f "\nset modsource($modname) \{"
				puts $f $buf
				puts $f "\}\n"
			}
			if {$shared} {
				foreach {srcname destname} [list $autosetup(libdir)/README.autosetup-lib README.autosetup \
						$autosetup(srcdir)/LICENSE LICENSE] {
					dputs "install: importing $srcname as $destname"
					puts $f "\nset modsource($destname) \\\n[list [readfile $srcname]\n]\n"
				}
			}
		}
		close $in
		close $f
		catch {exec chmod 755 $target}

		set installfiles {autosetup-config.guess autosetup-config.sub autosetup-test-tclsh}
		set removefiles {}

		if {!$shared} {
			autosetup_install_readme $targetdir/README.autosetup 0

		foreach fileinfo $installfiles {
			if {[llength $fileinfo] == 2} {
				lassign $fileinfo source dest
			} else {
				lassign $fileinfo source
				set dest $source
			}
			autosetup_install_file $autosetup(dir)/$source $targetdir/$dest

		}

		# Remove obsolete files
		foreach file $removefiles {
			if {[file exists $targetdir/$file]} {
				file delete $targetdir/$file
			}

proc autosetup_install_file {source target} {
	dputs "install: $source => $target"
	if {![file exists $source]} {
		error "Missing installation file '$source'"
	}
	writefile $target [readfile $source]\n
	# If possible, copy the file mode
	file stat $source stat
	set mode [format %o [expr {$stat(mode) & 0x1ff}]]
	catch {exec chmod $mode $target}
}

proc autosetup_install_readme {target sysinstall} {
	set readme "README.autosetup created by [autosetup_version]\n\n"
	if {$sysinstall} {
		append readme \
{This is the autosetup directory for a system install of autosetup.

## CC_FOR_BUILD
## LD

use system

module-options {}






# Checks for the existence of the given function by linking
#
proc cctest_function {function} {
	cctest -link 1 -declare "extern void $function\(void);" -code "$function\();"
}

# Checks for the existence of the given type by compiling

	cc-check-some-feature $args {
		cctest_type $each
	}
}

# @cc-check-defines define ...
#
# Checks that the given preprocessor symbols are defined.
proc cc-check-defines {args} {
	cc-check-some-feature $args {
		cctest_define $each
	}
}

# @cc-check-decls name ...

						incr found
						break
					}
				}
			}
		}
	}
	define-feature $function $found
	if {!$found} {


		msg-result "no"
	}
	return $found
}

# @cc-check-tools tool ...
#

		}
	} else {
		msg-result $version
		define PKG_CONFIG_VERSION $version

		set found 1

		if {[opt-str sysroot o]} {
			define SYSROOT [file-normalize $o]
			msg-result "Using specified sysroot [get-define SYSROOT]"
		} elseif {[get-define build] ne [get-define host]} {
			if {[catch {exec-with-stderr [get-define CC] -print-sysroot} result errinfo] == 0} {
				# Use the compiler sysroot, if there is one
				define SYSROOT $result
				msg-result "Found compiler sysroot $result"
			} else {

## infodir
## mandir
## includedir
#
# If '--prefix' is not supplied, it defaults to '/usr/local' unless 'defaultprefix' is defined *before*
# including the 'system' module.

if {[is-defined defaultprefix]} {
	user-notice "Note: defaultprefix is deprecated. Use options-defaults to set default options"
	options-defaults [list prefix [get-define defaultprefix]]
}

module-options [subst -noc -nob {
	host:host-alias =>		{a complete or partial cpu-vendor-opsys for the system where
							the application will run (defaults to the same value as --build)}
	build:build-alias =>	{a complete or partial cpu-vendor-opsys for the system
							where the application will be built (defaults to the
							result of running config.guess)}
	prefix:dir=/usr/local => {the target directory for the build (default: '@default@')}

	# These (hidden) options are supported for autoconf/automake compatibility
	exec-prefix:
	bindir:
	sbindir:
	includedir:
	mandir:
	infodir:
	libexecdir:
	datadir:
	libdir:
	sysconfdir:
	sharedstatedir:
	localstatedir:
	maintainer-mode=0
	dependency-tracking=0
	silent-rules=0
}]

# @check-feature name { script }
#
# defines feature '$name' to the return value of '$script',
# which should be 1 if found or 0 if not found.
#

		writefile $file $buf\n
		uplevel 1 $script
	}
}

# @make-template template ?outfile?
#
# Reads the input file '<srcdir>/$template' and writes the output file '$outfile'
# (unless unchanged).
# If '$outfile' is blank/omitted, '$template' should end with '.in' which
# is removed to create the output file name.
#
# Each pattern of the form '@define@' is replaced with the corresponding
# "define", if it exists, or left unchanged if not.
# 
# The special value '@srcdir@' is substituted with the relative

					set cond [expr {!$cond}]
				}
			}
			continue
		}
		lappend result $line
	}
	write-if-changed $out [string map $mapping [join $result \n]] {

		msg-result "Created [relative-path $out] from [relative-path $template]"
	}
}

# build/host tuples and cross-compilation prefix
opt-str build build ""
define build_alias $build
if {$build eq ""} {
	define build [config_guess]
} else {
	define build [config_sub $build]
}

opt-str host host ""
define host_alias $host
if {$host eq ""} {
	define host [get-define build]
	set cross ""
} else {
	define host [config_sub $host]
	set cross $host-

		user-error "Invalid canonical $type: $v"
	}
	define ${type}_cpu $cpu
	define ${type}_vendor $vendor
	define ${type}_os $os
}

opt-str prefix prefix /usr/local

# These are for compatibility with autoconf
define target [get-define host]
define prefix $prefix
define builddir $autosetup(builddir)
define srcdir $autosetup(srcdir)
define top_srcdir $autosetup(srcdir)
define abs_top_srcdir [file-normalize $autosetup(srcdir)]
define abs_top_builddir [file-normalize $autosetup(builddir)]

# autoconf supports all of these

define exec_prefix [opt-str exec-prefix exec_prefix $prefix]
foreach {name defpath} {
	bindir /bin
	sbindir /sbin
	libexecdir /libexec
	libdir /lib
} {
	define $name [opt-str $name o $exec_prefix$defpath]
}
foreach {name defpath} {
	datadir /share

	sharedstatedir /com

	infodir /share/info
	mandir /share/man
	includedir /include
} {
	define $name [opt-str $name o $prefix$defpath]
}
if {$prefix ne {/usr}} {
	opt-str sysconfdir sysconfdir $prefix/etc
} else {
	opt-str sysconfdir sysconfdir /etc
}
define sysconfdir $sysconfdir

define localstatedir [opt-str localstatedir o /var]

define SHELL [get-env SHELL [find-an-executable sh bash ksh]]

# These could be used to generate Makefiles following some automake conventions
define AM_SILENT_RULES [opt-bool silent-rules]
define AM_MAINTAINER_MODE [opt-bool maintainer-mode]
define AM_DEPENDENCY_TRACKING [opt-bool dependency-tracking]

# Windows vs. non-Windows
switch -glob -- [get-define host] {
	*-*-ming* - *-*-cygwin - *-*-msys {
		define-feature windows
		define EXEEXT .exe
	}

}

cc-check-tools ar ranlib

set objdir [get-env BUILDDIR objdir]

make-config-header $objdir/include/autoconf.h
make-tmake-settings $objdir/settings.conf {[A-Z]*} *dir lib_*
}

	autosetup_check_create project.spec \
{# Initial project.spec created by 'autosetup --init=tmake'

tmake-require-version 0.7.3

# vim:set syntax=tcl:
define? DESTDIR _install

# XXX If configure creates additional/different files than include/autoconf.h
#     that should be reflected here








Autosetup include/autoconf.h








# e.g. for autoconf.h
IncludePaths include

ifconfig !CONFIGURED {
	# Not configured, so don't process subdirs
	AutoSubDirs off
	# And don't process this file any further
	ifconfig false
}


}

	if {![file exists build.spec]} {
		puts "Note: I don't see build.spec. Try running: tmake --genie"
	}
}

*.pt
*.rk05

.agignore

#!/usr/bin/env perl
########################################################################
# cc8-to-os8 - Filter C code meant for the CC8 cross-compiler so that it
#   will work with the OS/8 version of CC8.
#
#   This is not meant to fix up 100% of the differences in the C
#   compilers, just the ones which prevent src/cc8/examples/*.c
#   from building under OS/8 CC8 as-is.
#
#   You can run it like a filter: 
#
#       $ cc8-to-os8 < foo.c | txt2ptp > foo.pt
#
#   Or you can just give it one or more file name(s), with output going
#   to stdout, which gives this way to hack around the lack of #include:
#
#       $ cc8-to-os8 myheader.h foo.c > OS8FOO.C
#
# Copyright © 2017 Warren Young
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS LISTED ABOVE BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
# OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Except as contained in this notice, the names of the authors above
# shall not be used in advertising or otherwise to promote the sale,
# use or other dealings in this Software without prior written
# authorization from those authors.
########################################################################

use strict;
use warnings;

my $nblines = 0;        # number of non-blank lines written out

while (<>) {
    if (m{^[a-zA-Z_][a-zA-Z0-9_]*\s*\(}) {
        # Looks like a function definition without a type; assume int.
        print "int $_";
        ++$nblines;
    }
    elsif (!m{^\#include } and length and $nblines) {
        # Pass it through unchanged.
        print;
    }
    else {
        # Unlike the CC8 cross-compiler, the OS/8 version of CC8 doesn't
        # process #includes, or in fact any C preprocessor directives,
        # not even #asm.  Strip just the #includes in the hope that it's
        # init.h or libc.h, the contents of which are hard-coded into
        # the OS/8 CC8 compiler.
    }
}

#!/usr/bin/python
# -*- coding: utf-8 -*-
########################################################################
# teco-pi-demo - Starts the simulator with the OS/8, sends one of the
#   famous TECO "calculate pi" program to it, and starts it running at
#   a very slow rate of speed to act as a blinkenlights demo.
#
# Copyright © 2017 by Warren Young.
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS LISTED ABOVE BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
# OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Except as contained in this notice, the names of the authors above
# shall not be used in advertising or otherwise to promote the sale,
# use or other dealings in this Software without prior written
# authorization from those authors.
########################################################################

# Bring in just the basics so we can bring in our local modules
import os
import sys
sys.path.insert (0, os.path.dirname (__file__) + '/../lib')
sys.path.insert (0, os.getcwd () + '/lib')

# Other core modules we need
from datetime import datetime
import time

# Our local modules
from pidp8i import *
from simh   import *


#### main ##############################################################

def main ():
  # Check for command line flags
  benchmark = len (sys.argv) > 1 and sys.argv[1] == '-b'

  # Create the SIMH child instance and tell it where to send log output
  try:
    s = simh (dirs.build)
  except (RuntimeError) as e:
    print "Could not start simulator: " + e.message + '!'
    exit (1)
  s.set_logfile (os.fdopen (sys.stdout.fileno (), 'w', 0))

  # Find and boot the built OS/8 bin disk
  rk = os.path.join (dirs.os8mo, 'os8v3d-bin.rk05')
  if not os.path.isfile (rk):
    print "Could not find " + rk + "; OS/8 media not yet built?"
    exit (1)
  print "Booting " + rk + "..."
  s.send_cmd ("att rk0 " + rk)
  s.send_cmd ("boot rk0")

  # Start TECO8 in the simulator under OS/8
  s.os8_send_cmd ('\\.', "R TECO")

  # The macro comes from http://www.iwriteiam.nl/HaPi_TECO_macro.html
  #
  # The 248 preceding "UN" in the first line of the macro is the number
  # of digits of pi to calculate.  That value was reached by experiment
  # as the largest value that runs without crashing TECO with a
  #
  #    ?MEM  STORAGE CAPACITY EXCEEDED
  #
  # error.  You can see that by increasing the value below, commenting
  # out the throttle setting below, and running the demo.  On a Pi 3, it
  # should take a bit over an hour to complete, if it doesn't error out.
  #
  # With the simulator throttled, generating 248 digits takes 17 years!
  #
  # That is based on generating 1 digit every ~16 seconds on a Pi 3 when
  # running unthrottled, roughly 8 MIPS.  When throttled to 59 IPS — or
  # 17ms per instruction, as below — you multiply the seconds by the
  # factor 8 MIPS / 59 IPS = ~136000, giving about 2.2 million seconds
  # per digit.  Multiplying that by 248 gives ~17 years.
  macro = [
    'GZ0J\UNQN"E 248UN \' BUH BUV HK',
    'QN< J BUQ QN*10/3UI',
    'QI< \+2*10+(QQ*QI)UA B L K QI*2-1UJ QA/QJUQ',
    'QA-(QQ*QJ)-2\ 10@I// -1%I >',
    'QQ/10UT QH+QT+48UW QW-58"E 48UW %V \' QV"N QV^T \' QWUV QQ-(QT*10)UH >',
    'QV^T @^A/',
    '/HKEX',
  ]

  # First and last lines are handled specially, so slice them off.
  first = macro.pop (0)
  last  = macro.pop ()

  # Send the first line of the macro; implicitly awaits 1st TECO prompt
  s.os8_send_cmd ('\*', first)

  # Blindly send core lines of the macro; TECO gives no prompts for 'em.
  for line in macro: 
    s.os8_send_line (line)

  # Send last line of macro sans CR, followed by two Esc characters to
  # start it running.
  s.os8_send_str (last)     # not os8_send_line!
  s.os8_send_ctrl ('[')
  s.os8_send_ctrl ('[')

  if benchmark:
    # Run demo long enough to get a good sense of the simulator's
    # execution rate while unthrottled on this host hardware.  If
    # you don't run it long enough, the IPS value is untrustworthy.
    try:
      s.spin (10)
    except pexpect.TIMEOUT:
      # Find out how many IPS was executing
      s.os8_send_ctrl ('e')
      s.send_cmd ('show clocks')
      line = s.read_tail ('Execution Rate:')
      curr_ips = int (line.strip().replace(',', '').split(' ')[0])
      pf = open ('lib/pidp8i/ips.py', 'a')
      pf.write ('current = ' + str (curr_ips) + '    # ' + \
            str (datetime.today ()) + '\n')
      pf.close ()
      s.send_cmd ('quit')
      pdp_ratio = float (curr_ips) / ips.pdp8i
      rpi_ratio = float (curr_ips) / ips.raspberry_pi_b_plus
      print "\nYour system is " + format (rpi_ratio, '.1f') + \
          " times faster than a Raspberry Pi Model B+"
      print "or " + format (pdp_ratio, '.1f') + \
          " times faster than a PDP-8/I.\n"
  else:
    # Normal mode.  Pop out to SIMH and throttle it down to a rate
    # suitable for a blinkenlights demo.  1/17 means SIMH runs one
    # instruction then waits for 17ms, yielding ~59 IPS.
    time.sleep (0.02)   # FIXME: simulator chokes on 'cont' without this
    s.os8_send_ctrl ('e')
    s.send_cmd ('set throttle 1/17')

    # You can't hit Ctrl-E while running this script in the foreground
    # since pexpect takes over stdio.  Therefore, if you want to be able
    # to send commands to the simulator while the demo is running,
    # uncomment the line below, which will let you send commands to the
    # simulator via telnet.  From another terminal or SSH session:
    #
    #     $ telnet localhost 3141
    #
    # or from a remote machine:
    #
    #     $ telnet 192.168.1.2 3141
    #
    # It's disabled by default because SIMH can't be made to listen only
    # on localhost, so doing this may be a security risk.  SIMH disables
    # obviously-unsafe commands like ! on the remote console, but it is
    # possible some mischief may be possible via this path anyway.  It
    # could be used to exfiltrate a sensitive file via ATTACH, for one
    # thing.  For another, it's a potential DoS vector.
    #s.send_cmd ('set remote telnet=3141')

    # Let it run.  Never exits.
    s.send_cmd ('cont')
    s.spin ()


if __name__ == "__main__":
    main()

#!/usr/bin/python
# -*- coding: utf-8 -*-
########################################################################
# Create a tu56 or rk05 image and fill it with ASCII files, i.e.  source code.
#
# It is intended to be be called manually when we have a POSIX
# directory full of ASCII files we want to bulk-copy into SIMH.
#
# The argument is taken both as the name of the image to create
# and the list of files to copy in.
#
# For now, it takes all input and produces all output in the
# current working directory.
#
# IMPORTANT:  Currently all input files are mindlessly passed through
# txt2ptp which transforms POSIX ASCII files to OS/8 ASCII files.
# It WILL mutilate non-ASCII files.
#
# This program is based on cc8-tu56-update.
#
# Copyright © 2017 by Warren Young and Bill Cattey
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS LISTED ABOVE BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
# OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Except as contained in this notice, the names of the authors above
# shall not be used in advertising or otherwise to promote the sale,
# use or other dealings in this Software without prior written
# authorization from those authors.
########################################################################

# Bring in just the basics so we can bring in our local modules
import os
import sys
import argparse

sys.path.insert (0, os.path.dirname (__file__) + '/../lib')
sys.path.insert (0, os.getcwd () + '/lib')

# Our local modules
from pidp8i import *
from simh   import *

# Other global Python modules
import glob
import subprocess


#### GLOBALS AND CONSTANTS #############################################

progmsg = True


#### main ##############################################################

def main ():
  global progmsg

  # Set up the arg parser and use it to parse the command line.
  parser = argparse.ArgumentParser()
  parser.add_argument("name",
                      help="Create an OS/8 image from a list of ASCII files.")
  group = parser.add_mutually_exclusive_group(required=True)
  group.add_argument("--tu56", "-t", action="store_true")
  group.add_argument("--rk05a", "-ra", action="store_true")
  group.add_argument("--rk05b", "-rb", action="store_true")

  args = parser.parse_args()
  
  print "Filename: " + args.name
  if args.tu56:
    sdev = "dt0"
    os8dev = "DTA0:"
    imagename = args.name + ".tu56"
    stat_str = "DECtape"

  if args.rk05a:
    sdev = "rk1"
    os8dev = "RKA1:"
    imagename = args.name + ".rk05"
    stat_str = "partition A of"
    
  if args.rk05b:
    sdev = "rk1"
    os8dev = "RKB1:"
    imagename = args.name + ".rk05"
    stat_str = "partition B of"
  
  listname = args.name + ".list"

  # Create the SIMH child instance and tell it where to send log output
  try:
    s = simh (dirs.build, True)
  except (RuntimeError) as e:
    print "Could not start simulator: " + e.message + '!'
    exit (1)
  s.set_logfile (os.fdopen (sys.stdout.fileno (), 'w', 0))

  # Attach a clean version of the image to the simulator
  if os.path.exists (imagename):
    print "Overwriting old " + stat_str + " image " + imagename

  s.send_cmd ("att " + sdev + " " + imagename)

  # Find and boot the bootable OS/8 disk.  Use the "patched" version
  # because that is what "make run" uses; we use that command to
  # inspect this script's work.
  rk = os.path.join (dirs.os8mo, 'os8v3d-patched.rk05')
  if not os.path.isfile (rk):
    print "Could not find " + rk + "; OS/8 media not yet built?"
    exit (1)
  print "Booting " + rk + "..."
  s.send_cmd ("att rk0 " + rk)
  s.send_cmd ("boot rk0")

  s.os8_send_cmd ('\\.', "ZERO " + os8dev)

  manifest = open (listname, "r")

  for line in manifest:
    src = line.strip()
    if src == "": continue
    if src[0] == '#': continue      # Allow commenting out files

    dest = src.upper ()
    s.os8_send_file (src, os8dev + dest)

  # Exit simulator nicely so that image detaches cleanly
  s.back_to_cmd ('\\.')
  s.send_cmd ("det " + sdev)
  s.send_cmd ('quit')


if __name__ == "__main__": main()

@else
; The software was configured with --lowercase=upper, meaning the user
; wants lowercase text to be forced to uppercase.  This is bidirectional,
; affecting both input to the simulated PDP-8 and output from it.
set tti ksr
@endif

att rk0 @MEDIADIR@/os8/@OS8_BOOT_DISK@
boot rk0

; A stripped down version of 5.script with the throttle value set to a
; ratio between two values.  Used primarily to test our handling of this
; throttle type.  For example, we need to disable ILS at simulator
; start/continue time when this throttle type is used because it
; throws our timing logic way off.

set throttle 30/1
set df disabled
set cpu noidle
echo Running reeeealy slow version of the AC/MQ blinker...
dep 00000 2020
dep 00001 5000
dep 00002 7200
dep 00003 1021
dep 00004 7421
dep 00005 1021
dep 00006 7040
dep 00007 2021
dep 00010 7000
dep 00011 5000
dep 00020 0000
dep 00021 0000
go  00000

; Same as 0.script, only with RK0 attached to the *.rk05 file in the
; build directory, not the one in the installation directory.  Used
; by "make run" so you don't have to "make mediainstall" first.
;
reset
echo Loading OS/8 from the RK05 cartridge disk in the build directory...
set cpu 32k
set cpu noidle
set df disabled
@SET_THROTTLE@

@if SIMH_PASS_LOWERCASE
set tti 7b
@else
set tti ksr
@endif

att rk0 bin/@OS8_BOOT_DISK@
boot rk0

# PiDP-8/I Software Release Process

This documents the process for producing release versions of the
software.


## *Can* You Release Yet?

Before release, you must:

*   Fix all Immediate, High, and Medium priority [Bugs](/bugs)
*   Implement all Immediate and High priority [Features](/features)

Or reclassify them, of course.

Most of the bug levels simply aid scheduling: Immediate priority bugs
should be fixed before High, etc. Low priority bugs are "someone should
fix this someday" type of problems, so they can move from release to
release.

The Features levels may be read as:

*   **Immediate**: ASAP, or sooner. :)
*   **High**: Features for this release.
*   **Medium**: Features we'll look at lifting individually to High for
    the next release.
*   **Low**: "Wouldn't it be nice if..."


## Update SIMH

If `tools/simh-update` hasn't been run recently, you might want to do
that and re-test before publishing a new version.


## Publish OS/8 RK05s

Re-configure the software with default settings, remove `bin/*.rk05`,
rebuild, and run `tools/publish-os8` to send the "final" OS/8 disk
images for this version of the software up to tangentsoft.com as
unversioned assets.

Update the date stamp in the "OS/8 RK05 Media" section of the project
home page.


## Update ChangeLog.md

Trawl the Fossil timeline for user-visible changes since the last
release, and write them up in user-focused form into the `ChangeLog.md`
file.  If a regular user of the software cannot see a given change, it
shouldn't go in the `ChangeLog.md`; let it be documented via the
timeline only.


## Update the Release Branch

Run `make release` to check the `ChangeLog.md` file changes in, tagging
that checkin with a release version tag of the form vYYYYMMDD and merge
those changes into the `release` branch.

It runs entirely automatically unless an error occurs, in which case it
stops immediately, so check its output for errors before continuing.


## Update the Home Page Links

The zip and tarball links on the front page produce files named after
the date of the release. Those dates need to be updated immediately
after tagging the release, since they point at the "release" tag applied
by the previous step, so they begin shipping the new release immediately
after tagging it.


## Produce the Normal Binary OS Image

Start with the latest version of [Raspbian Lite][os] on a multi-core
Raspberry Pi.

1.  If the version of the base OS has changed since the last binary OS
    image was created, download the new one.

    While the OS is downloading, zero the SD card you're going to use
    for this, so the prior contents don't affect this process.
    
    Blast the base OS image onto the cleaned SD card.

2.  Boot it up on a multi-core Pi.

    Log in, then retreive and initialize BOSI:

        $ wget https://tangentsoft.com/bosi
        $ chmod +x bosi
        $ exec sudo ./bosi init

    The `exec` bit is required so that the `bosi` invocation is run as
    root without any processes running as `pi` in case the `init` step
    sees that user `pi` hasn't been changed to `pidp8i` here: the
    `usermod` command we give to make that change will refuse to do what
    we ask if there are any running processes owned by user `pi`.

    It will either reboot the system after completing its tasks
    successfully or exit early, giving the reason it failed.

3.  Clone the software repo and build the softare:

        $ ./bosi build

    On reboot, say `top -H` to make sure the software is running and
    that the CPU percentages are reasonable for the platform.

    You may also want to check that it is running properly with a
    `pidp8i` command.  Is the configuration line printed by the
    simulator correct?  Does OS/8 run?  Are there any complaints from
    SIMH, such as about insufficient CPU power?

4.  Do final inside-the-image steps:

        $ ./bosi prepare

5.  Move the SD card to a USB reader plugged into the Pi, boot the Pi
    from its prior SD card, and shrink the OS image:

        $ wget https://tangentsoft.com/bosi
        $ chmod +x bosi
        $ ./bosi shrink

6.  Move the USB reader to the Mac,¹ then say:

        $ bosi image [nls]

    For the ILS images, you can give "ils" as a parameter or leave it
    blank.

7.  The prior step rewrote the SD card with the image file it created.
    Boot it up and make sure it still works.  If you're happy with it,
    give this command *on the desktop PC*.

        $ bosi finish [nls]

    As above, the parameter can be "ils" or left off for the ILS images.

[os]: https://www.raspberrypi.org/downloads/raspbian/


## Produce the "No Lamp Simulator" Binary OS Image

Do the same series of steps above on a single-core Raspberry Pi, except
that you give "nls" parameters to the `image` and `finish` steps.


## Publicizing

While the NLS image uploads — the ILS image was already sent in step 7
in the first pass through the list above — compose the announcement
message, and modify the front page to point to the new images.  You
might also need to update the approximate image sizes reported on that
page.  Post the announcement message and new front page once that second
upload completes.


----------------------

### Footnotes

1.  The image production steps could just as well be done on a Linux box
    or on a Windows box via Cygwin or WSL, but the commands in that
    final stage change due to OS differences.  Since this document
    exists primarily for use by the one who uses it, there is little
    point in having alternatives for other desktop OSes above.  Should
    someone else take over maintainership, they can translate the above
    commands for their own desktop PC.


### License

Copyright © 2016-2017 by Warren Young. This document is licensed under
the terms of [the SIMH license][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md

# How to Control SIMH and OS/8 from Python

## Introduction

While we were building the `libexec/mkos8` tool, we built up a set of
functionality for driving SIMH and OS/8 running under SIMH from the
outside using [Python][py], a very powerful programming language well
suited to scripting tasks. It certainly beats writing PDP-8 code to
achieve the same ends!

When someone on the mailing list asked for a way to automatically drive
a demo script he'd found online, it was natural to generalize the core
functionality of `mkos8` as a reusable Python class, then write a script
to make use of it. I called resulting demo script `teco-pi-demo` and the
reusable bits `class simh`, which is now shared with `mkos8`.

This document describes how `teco-pi-demo` works, and through it, how
`class simh` works, with an eye toward teaching you how to reuse this
functionality for your own ends.

[py]: https://www.python.org/


## Invocation

Because we do not install these components in the system's Python
library path, you must modify that path to allow your script to find
these components. Simply copy this invocation block into the top of your
script:

    import os
    import sys
    sys.path.insert (0, os.path.dirname (__file__) + '/../lib')
    sys.path.insert (0, os.getcwd () + '/lib')

    from pidp8i import *
    from simh   import *

That adjusts the path, then imports all of the generic functionality
from the PiDP-8/I `lib` directory into the current namespace.

We do not pull the `mkos8` components into `teco-pi-demo` because they
are intended only to be used by `libexec/mkos8`. If you find something
in the `lib/mkos8` directory that you think is widely useful, make a
case for it on the mailing list, and we'll see about moving it to either
the `simh` or `pidp8i` namespace.

The `sys.path.insert` business assumes that your script is installed
into the PiDP-8/I's `bin` directory alongside `teco-pi-demo`. If you've
installed it somewhere else, you'll need to adjust these paths.


## Starting SIMH

The first thing we'lld do is start SIMH as a child process of our Python
script under control of an instance of `class simh`:

    s = simh (dirs.build)

We call that instance `s` for short, because we will be calling its
methods a lot in this script. 

We pass `dirs.build` to its constructor, which tells it how to find the
`pidp8i-sim` program, which is a version of the PDP-8 simulator from the
SIMH project, configured and modified for the needs of the PiDP-8/I
project. We call this the child program, which is what `class simh`
controls from the outside.

(Currently, we don't have a way to make it use other versions of the
SIMH `pdp8` simulator. Please send a patch if you do that.)

The next step is to tell the `s` object where to send its logging
output:

    s.set_logfile (os.fdopen (sys.stdout.fileno (), 'w', 0))

Contrast the corresponding line in `mkos8` which chooses whether to send
logging output to the console or to a log file:

    s.set_logfile (open (dirs.log + 'mkos8-' + first_act + '.log', 'w') \
        if progmsg else os.fdopen (sys.stdout.fileno (), 'w', 0))


## Finding and Booting the OS/8 Media

If your program will use our OS/8 boot disk, you can find it
programmatically by using the `dirs.os8mo` constant, which means "OS/8
media output directory", where "output" refers to the worldview of
`mkos8`.  Contrast `dirs.os8mi`, which points to the directory holding
the input media for `mkos8`.

This snippet shows how to use it:

    rk = os.path.join (dirs.os8mo, 'os8v3d-bin.rk05')
    if not os.path.isfile (rk):
        print "Could not find " + rk + "; OS/8 media not yet built?"
        exit (1)

Now we attach the RK05 disk image to the PiDP-8/I simulator found by the
`simh` object and boot from it:

    print "Booting " + rk + "..."
    s.send_cmd ("att rk0 " + rk)
    s.send_cmd ("boot rk0")

This shows one of the most-used methods in `class simh`, `send_cmd`,
which sends a line of text along with a carriage return to the spawned
child program, which again is `pidp8i-sim`.


## Driving SIMH and OS/8

After the simulator starts up, we want to wait for an OS/8 `.` prompt
and then send the first OS/8 command to start our demo. We use the
`simh.os8_send_cmd` method for that:

    s.os8_send_cmd ('\.', "R TECO")

This method differs from `send_cmd` in a couple of key ways.

First, it waits for a configurable prompt character — sent as the first
parameter — before sending the command.  This is critical when driving
OS/8 because OS/8 lacks a keyboard input buffer, so if you send text to
it too early, all or part of your input is likely to be lost, so your
command won't work.

Second, because OS/8 can only accept so many characters of input per
second, `os8_send_cmd` inserts a small delay between each input
character to prevent character losses.

(See the commentary for `simh._kbd_delay` if you want to know how that
delay value was calculated.)

The bulk of `teco-pi-demo` consists of more calls to `simh.os8_send_cmd`
and `simh.send_cmd`. Read the script if you want more examples.

Notice that we escape the OS/8 `.` command prompt in the first parameter
because `class simh` treats it as a [regular expression][re], and a `.`
in REs means "any character," which we definitely do *not* want to match
on!  If we did not escape this special RE character with a backslash,
`class simh` would send the command when the first character from the
running OS/8 instance came through, likely causing some or all of the
command to be lost by the time OS/8 is ready to accept input.

[re]: https://en.wikipedia.org/wiki/Regular_expression


## Escaping OS/8 to SIMH

Sometimes you need to escape from OS/8 back to SIMH with a
<kbd>Ctrl-E</kbd> keystroke so that you can send more SIMH commands
after OS/8 starts up. This accomplishes that:

    s.os8_send_ctrl ('e')

While out in the SIMH context, you *could* continue to call the
`simh.os8_*` methods, but since SIMH can accept input as fast as your
program can give it, it is best to use methods like `simh.send_cmd`
which don't insert artificial delays.  For many programs, this
difference won't matter, but it results in a major speed improvement in
a program like `mkos8` which sends many SIMH and OS/8 commands
back-to-back!


## Getting Back to OS/8 from SIMH

There are several ways to get back to the simulated OS/8 environment
from SIMH context, each with different tradeoffs.


### Rebooting

You saw the first one above: send a `boot rk0` command to SIMH. This
restarts OS/8 entirely. This is good if you need a clean environment.
If you need to save state between one run of OS/8 and the next, save it
to the RK05 disk pack or other SIMH media, then re-load it when OS/8
reboots.


### Continuing

The way `teco-pi-demo` does it is to send a `cont` command to SIMH.

The problem with this method is that it sometimes hangs the simulator.
The solution is to insert a small delay *before* escaping to the SIMH
context. I'm not sure why this is sometimes necessary. My best guess is
required to give OS/8 time to settle into an interruptible state before
escaping to SIMH, so that on "continue," we re-enter OS/8 in a sane
state.

You can usually avoid the need for that delay by waiting for an OS/8
command prompt before escaping to SIMH, since that is a reliable
indicator that OS/8 is in such an interruptible state.

You don't see these anomalies when using OS/8 interactively because
humans aren't fast enough to type commands at OS/8 fast enough to cause
the problem.  That is doubtless why there this bug still exists in OS/8
in 2017.


### Re-Entering

If your use of OS/8 is such that all required state is saved to disk
before re-entering OS/8, you can call the `simh.os8_restart` method to
avoid the need for a delay *or* a reboot.  It re-calls OS/8's entry
point from SIMH context, which we've found through much testing is
entirely reliable, as compared to sending a SIMH `cont` command without
having delayed before escaping to SIMH context.

`mkos8` uses this option extensively.


## Sending Escape Characters

Several OS/8 programs expect an <kbd>Escape</kbd> (a.k.a. `ALTMODE`)
keystroke to do things. Examples are `TECO` and `FRTS`. There isn't a
specific method to do this because we can do that in terms of one we've
just described:

    s.os8_send_ctrl ('[')

Yes, <kbd>Escape</kbd> is <kbd>Ctrl-\[</kbd>. Now you can be the life of
the party with that bit of trivia up your sleeve. Or maybe you go to
better parties than I do.


## But There's More!

The above introduced you to most of the functionality of `class simh`
used by `teco-pi-demo`, but there's more to the class than that,
primarily because the `mkos8` script's needs are broader.  Rather than
just recapitulate the class documentation here, please read through [the
class's source code][ssc], paying particular attention to the method
comments. It's a pretty simple class, making it a quick read.

Another useful module is [`pidp8i.dirs`][dsc] which contains paths to
many directories in the PiDP-8/I system, which you can reuse to avoid
having to hard-code their locations.  This not only makes your script
independent of the installation location, which is configurable at build
time via `./configure --prefix=/some/path`, but also allows it to run
correctly from the PiDP-8/I software's build directory, which has a
somewhat different directory structure from the installation tree.

[ssc]: https://tangentsoft.com/pidp8i/file/lib/simh.py
[dsc]: https://tangentsoft.com/pidp8i/file/lib/pidp8i/dirs.py


## <a id="license" name="credits"></a>Credits and License

Written by and copyright © 2017 by Warren Young. Licensed under the
terms of [the SIMH license][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md

# DCP Disassembler for PDP-8

This document is based on the file DCP.WU found with DCP binaries.

| Author              | A.E. Brouwer, Math. Center, Amsterdam |
| Date                | 73-10-03                              |
| Version Number      | DCP AB-V21                            |
| Last Update         | 74-11-12                              |
| Environment         | OS/8 operating system                 |
| Memory Requirements | 16K, Optional 24K mode                |


## DCP (Preliminary Description)

DCP (sometimes called `deass`) is a program to deassemble (or disassemble)
a PAL program given in binary or in core image format as 1st input file.
Information about the program and meaningful tags can be given
in a second input file. A well readable listing with meaningful
tags but without comment can be obtained in a few passes
(typically four). The first time no information is supplied; while
reading the output one recognizes certain parts as messages
("NO ROOM FOR OUTPUT") or numeric tables (6030,7634,7766,7777)
or simple subroutines (TTYOUT, PUSH, PRINT).

Putting these things in an information file and then running
dcp again gives you a much nicer output the second time.
Now you may embark on the program itself and obtain after a small
number of passes (depending on the complexity of the program and
your laziness.) A source that might have been the original one except
for its lack of comment. At this moment you could profitably use
the CTRL/E feature of MCEDIT to provide the whole source of comment.
(For example, we obtained a source of a fortran compiler in three
days after five passes.)

Below we will describe the OS/8 version of the program

## Assembly Instructions

(Alas, we do not yet have source.)

    .R PAL8
    *102,DCP_SBIN,DCPZ/L$
    .SAVE SYS DCP

## Operating Instructions

    .R DCP
    *OUTPUT<INPUT,INFO(OPTIONS)

## Command Line Interpretation

1.  If no input and no output specified then delete <kbd>DSK:DCPLS.TM<kbd>
    If command closed with altmode then exit to OS/8 monitor
    else call command decoder again.

2.  If no output given but an output file is required because
    chaining to CREF.SV is requested then DSK:DCPLS.TM is used.

3.  If no input given then use output filename with extensions
    .SV and .SM (if present.)
    E.G.
   
        *DEASS<

    is equivalent to

        *DEASS<DEASS.V
       
    if DEASS.SM does not exist, and to

       *DEASS<DEASS.SV,DEASS.SM

    otherwise.

    In this case a previous version of the output file is
    deleted first (if necessary).

4.  If the output file has no explicit extension then add
    .DC if a source is produced, and .LS otherwise
    (One would expect .PA instead of .DC but that proved dangerous.)

## Options Affecting Interpretation of Command Line

| /B    | Expect .BN rather than .SV format in first inputfile     |
|       | This changes the default extension into .BN if no        |
|       | input is specified.                                      |
| /L    | Produce .LS rather than .DC output                       |
| /X    | Chain to CREF.SV                                         |
|       | (1st output becomes input and 2nd output becomes output) |
|       | This option implies the options /L and /T                |

e.g.

    .R DCP
    *DEASS,TTY:</X/B
    
is equivalent to

    .R PIP
    *DEASS.LS</D$
    .R DCP
    *DEASS.LS<DEASS.BN,DEASS.SM/L/T/B
    .R CREF
    *TTY:<DEASS.LS
    
also

     DCP
     *
     *DEAS.SV,SPECS1,SPECS2,SPECS3/S
     
means

    .R PIP
    *DEASS.TM</D$
    .R DCP
    *DCPLS.TM<DEASS.SV,SPECS1,SPECS2,SPECS3/L/T
    .R CREF
    *DCPLS.TM

## Options

| /A    | Do not generate a 'START' label.
|       | (By default a label 'START' is generated when decoding
|       | core image file. This is possible since the core control
|       | contains the starting address.)
| /B    | Expect .BN instead of .SV input.
| /C    | The info file after the output
| /D    | 'JMP .-3', 'JMP I .+1' instructions
|       | for each reference a tag is generated)
| /H    | Do not generate literals.
| /K    | allow modification of literals.
|       | (Normally an instruction like 1377 will be translated as
|       | 'TAD (1234' but 2377 as 'ISZ A177' since no decent programmer
|       | ever writes 'ISZ (1234'. It was found however that several
|       | DEC programs contain such constructs.)
| /L    | Produce output in .LS format.
| /N    | Do not generate table of undefined symbols.
| /S    | Generate table of all symbols.
| /T    | Convert tabs into spaces.
| /W    | Do not interpret 6141 as the PDP12 'LINC' instruction.
| /X    | Chain to CREF.SV.
| /(F)  | (Where F designates a digit between 0 and 7.)
|       | Translate field F of the program (default: /0)
| =NNNNMMMM | The = OPTION can be used to specify a part of the program to be decoded. NNN gives begin and MMMM end+1 of the range. (Note that if begin>3777 the command has to be closed with altmode instead of return.)

## Translation Is Done One Field at A Time

Therefore, binaries that load into extended memory must be
disassembled with /(F) for all memory fields used.

This causes some flaws in the output:

    CIF 10
    JMS I   (200

is translated as:

    CIF 10
    JMS I   (START

If LOC 200 in the current field is labeled START.
Note that assembling the produced source gives the
correct binary.)

## Input Format

Each input section starts with $X (where X is a letter indicating
the type of the section) and ends with $ .

$\<CR\> indicates the end of all input (when not within a secion).
Between the sections comment not containing $ may be inserted.

### Section Types

| $A    | Translate as 6bit ASCII (TEXT "STRING")
| $D    | Dont translate
| $I    | Translate as instruction (overriding other specs)
| $L    | Translate as identifier rather than as instruction
| $N    | Translate octal
| $S    | Subroutine with args
| $T    | Symbol definitions
| $Z    | Special coding
| $     | End of input

### Content of Section

1.  Sections $X where X is A,D,I,L or N.

    Contents: Lines of the form:

        MMMM-NNNN

    or

        NNNN

    Where NNNN and MMMM are octal addresses.
   
    e.g. the section:

        $N
        1717-1730
        1750
        $

    specifies that the locations 1717-1730 and 1750 are
    to be translated as octal numbers.

2.  Sections $S.

    Contents: Lines of the form:

        SSSS:XXXXX

    Where SSSS is a subroutine address and XXXXX specifies
    the kind of arguments the subroutine has.

    e.g. the section:

        $S
        1000:NL
        $

    indicates that each call to the subroutine at LOC 1000 has two
    arguments of type octal and label respectively.

3. Sections $T.

    Contents: Lines of the form:

        TAG=NNNN

    or

        TAG

    Meaning: If no octal value of a tag is specified then its value is
    taken as one more than the value of the previous tag.

4. Section $Z.

    This is an ad hoc construct to enable the translation of
    symbol tables like those of PAL8 and CREF.
   
    e.g.

        $Z=52;0=240;1=301;40=260
        NNNN-MMMM:(UUUL)
        $
       
    indicates that the range NNNN-MMMM is a table of four-word entries
    three words in a special format and one label.

    The special format is as follows:

    The value is divided by 52 giving a quotient and a remainder.
    Both are converted into a character as follows: 0 gives a space,
    1-37 give letters A-_, and 40-51 give digits 0-9.

    The coding here is not foolproof yet: A strange command might
    give strange output instead of an error message.

    In later versions this command will be generalized, so we don't
    describe it in full here.

## Error Messages

These are very poor (because of lack of space): HLTNNNN,
where NNNN indicates the address of the routine in DCP that
detected the error.

Errors are almost always violations of the input format.

A complete list will appear in the final report.

| Name    | DCP (ERROR TABLE)
| Author  | A.E. Brouwer
| Date    | 75-02-13

As noted: The error messages of DCP look like 'HLT....'
where .... stands for the octal address of the routine
that detected the error.

(Of course giving intelligible messages is highly desirable
but lack of space prevented this. Some future version of DCP
will chain to a file `DECPERR.SV` containing the messages.)

Below the error numbers are given for DCP AB-V21.
[Note: These numbers may change slightly each time that
DCP is assembled anew.]

### DCP16 Error Table

| Number | ERROR
| ------ | -------------------------------------------------------------|
| 0000   | PREMATURE END OF .BN INPUT                                   |
| 0230   | CLOSE ERROR                                                  |
| 0301   | LOOKUP FOR SYS:CREV.SV FAILED                                |
| 1414   | OUTPUT ERROR OR NO ROOM FOR OUTPUT                           |
| 1451   | INPUT ERROR (INFO FILE)                                      |
| 1522   | NO CARRIAGE RETURN WHERE EXPECTED IN THE INFO FILE           |
| 1755   | UPPER BOUND IN BOUND PAIR LESS THAN LOWER BOUND              |
| 2031   | ASCII STRING CONTAINED A SIXBIT ZERO, BUT NOT AT THE END     |
|        | (I.E. A WORD 00XX). (THIS MIGHT HAVE BEEN AN @,              |
|        | BUT IS USUALLY AN ERROR.)                                    |
| 2046   | ASCII STRING WITHOUT TRAILING ZERO                           |
| 2061   | DCP COULD NOT FIND A SUITABLE DELIMITER FOR THE ASCII STRING |
|        | IN THE RANGE "" TO "?                                        |
| 2125   | IMPOSSIBLE                                                   |
| 2214   | TEXT BUFFER OVERFLOW (TOO MANY OR TOO LONG IDENTIFIERS).     |
| 2234   | NO IDENTIFIER WHERE EXPECTED (IN A $T SECTION).              |
| 2666   | ZERO SUBROUTINE ADDRESS SPECIFIED IN A $S SECTION            |
| 2705   | S-BUFFER OVERFLOW (TOO MANY SUBROUTINES WITH ARGS.)          |
| 2761   | UNKNOWN TYPE LETTER IN SPECIFICATION OF SUBROUTINE ARGS      |
| 3006   | $Z NO FOLLOWED BY =                                          |
| 3011   | $Z= NOT FOLLOWED BY A NONZERO NUMBER                         |
| 3022   | NO CARRIAGE RETURN OR SEMICOLON WHERE EXPECTED IN $Z HEADER  |
| 3030   | NO = WHERE EXPECTED IN $Z HEADER LINE                        |
| 3041   | ZERO LOWER BOUND IN BOUND PAIR IN $Z SECTION                 |
| 3064   | Z-BUFFER OVERFLOW                                            |
| 3117   | PREMATURELY EXHAUSTED Z-FORMAT                               |
| 3135   | UNKNOWN Z-FORMAT SYMBOL                                      |
| 3470   | T-BUFFER OVERFLOW                                            |
| 3723   | NO VALUE ASSIGNED TO FIRST TAG IN $T SECTION                 |
| 4213   | NO INPUT AND NO OUTPUT AND NO DSK:DCPLS.TM TO DELETE         |
| 4245   | HANDLER FETCH ERROR                                          |
| 4341   | LOOKUP FOR INPUTFILE FAILED                                  |
| 4442   | OUTPUT OPEN ERROR                                            |
| 4456   | NO 16K MEMORY AVAILABLE                                      |
| 4470   | CHECKSUM OR FORMAT ERROR IN BINARY INPUT FILE                |
| 4613   | FORMAT ERROR IN CORE CONTROL BLOCK OF .SV INPUT FILE         |
| 4647   | ERROR READING CORE CONTROL BLOCK OF .SV INPUT                |
| 4723   | ERROR READING .SV INPUT FILE                                 |

## DCP24

DCP Version 24 is a 24K version of DCP.

| Name   | DCP-AB-WW-V24
| Author | W.F. Wakker, Math. Center, Amsterdam
| Date   | 76-03-25

### The Following Extensions Are Made

-   DCP24 Translates EAE instructions in both A and B mode

    (For mode switching, see below.)

    Example:

        1200    DAD;1234

    is translated as if the info-file contains the following info:

        $I
        1200
        $
        $L
        1201
        $
        $N
        1234+
        $

-   In the info-file one can give : NNNN+ which has the same
    effect as NNNN-MMMM where MMMM=NNNN+1.

-   Several buffers have been enlarged.

-   The output is paginated and has a heading on each page.
    (The page number is in octal ....)

-   Error messages are unfortunately as poor as before (See DCP24
    error table).

-   New sections, now possible in the info-file are:

    | $B    | TRANSLATE AS 8-BIT ASCII  |
    | $C    | GIVE COMMENT              |
    | $E    | FORCE EAE MODE A          |
    | $F    | FORCE EAE MODE B          |
    | $M    | TRANSLATE NEGATIVE        |

- Section $B

        $B
        NNNN-MMMM
        $

    Causes the location NNNN-MMMM to be translated as
    8-bit ASCII, E.G. 0301 is translated as "A.
    Values less then 241 are translated as octal numbers.

- Sections $E and $F

    When DCP encounters EAE instructions, some slight heuristics
    are done to determine the mode. The mode is initially A; SWAB,
    DAD, and DST cause the mode to change to mode B etc.
    When these heuristics are too poor, you can use  the $E section
    to force mode A and the $F section to force mode B.

- Section $M

    This section has the same effect as section $N, only all
    octals are given negative, E.G. 7770 becomes -10.
    It is also possible to give $B and $M to the same LOC.
    Example: 7477 is now translated as -"A.

- Section $C

    Now you can give comment!!

    | Format    | NNNN:THIS IS COMMENT
    | Effect    | NNNN    ........    /THIS IS COMMENT
    | Attention | The $C section must be the last one in the info-file:

    When $C is seen in the info-file, a setup is made to
    give the comment and no more input will be read ( E.G. The program
    acts like $$ on the end is seen). The comments are added to
    the listing in the last pass of the program.

    __YOU MUST SORT THE ADDRESSES.__

        300:COMM1
        200:COMM2

    Has as effect that from adress 300 on, no more comment will
    be given, since address 200 is not found any more.

    __DO NOT GIVE COMMENT ON ADDRESSES WHICH DO NOT BELONG
    TO THE PROGRAM__

- Extension of $S section

    As arguments in the $S section you can give N, L, A, I, B, M,
    (with the obvious meaning, see above ) and also U.
    U should only be used for the addresses 200 and 7700.
    It marks the entrypoint of the user service routine and gives
    a nice translation of each USR call.

- Extension of $Z section

    New possible arguments: M, B.

### DCP-V24 (ERROR TABLE)

| Number | ERROR
| ------ | -------------------------------------------------------------|
| 0000   | PREMATURE END OF .BN INPUT                                   |
| 0237   | CLOSE ERROR                                                  |
| 0305   | LOOKUP FOR SYS:CREF.SV FAILED                                |
| 1414   | OUTPUT ERROR OR NO ROOM FOR OUTPUT                           |
| 1511   | NO CARRIAGE RETURN WHERE EXPECTED IN THE INFO FILE           |
| 1707   | NO : AS SEPARATOR IN $C SECTION                              |
| 2145   | UPPER BOUND IN BOUND PAIR LESS THAN LOWER BOUND              |
| 2235   | NO : AS SEPARATOR IN FIRST LINE OF $C SECTION                |
| 2331   | INPUT ERROR (INFO FILE)                                      |
| 2431   | ASCII STRING CONTAINED A SIXBIT ZERO, BUT NO AT THE END      |
|        | (I.E. A WORD 00XX). (THIS MIGHT HAVE BEEN AN @,              |
|        | BUT IS USUALLY AN ERROR.)                                    |
| 2446   | ASCII STRING WITHOUT TRAILING ZERO                           |
| 2461   | DCP COULD NOT FIND A SUITABLE DELIMITER FOR THE ASCII STRING |
|        | IN THE RANGE "" TO "?                                        |
| 2525   | IMPOSSIBLE                                                   |
| 2614   | TEXT BUFFER OVERFLOW (TOO MANY OR TOO LONG IDENTIFIERS)      |
| 2634   | NO IDENTIFIER WHERE EXPECTED (IN A $T SECTION)               |
| 3266   | ZERO SUBROUTINE ADDRESS SPECIFIED IN A $S SECTION            |
| 3305   | S-BUFFER OVERFLOW (TOO MANY SUBROUTINES WITH ARGS)           |
| 3367   | UNKNOWN TYPE LETTER IN SPECIFICATION OF SUBROUTINE ARGS      |
| 3406   | $Z NOT FOLLOWED BY =                                         |
| 3411   | $Z= NOT FOLLOWED BY A NONZERO NUMBER                         |
| 3422   | NO CARRIAGE RETURN OR SEMICOLON WHERE EXPECTED IN $Z HEADER  |
| 3430   | NO = WHERE EXPECTED IN $Z HEADER LINE                        |
| 3441   | ZERO LOWER BOUND IN BOUND PAIR IN $Z SECTION                 |
| 3463   | Z-BUFFER OVERFLOW                                            |
| 3517   | PREMATURELY EXHAUSTED Z-FORMAT                               |
| 3541   | UNKNOWN Z-FORMAT SYMBOL                                      |
| 4070   | T-BUFFER OVERFLOW                                            |
| 4324   | NO VALUE ASSIGNED TO FIRST TAG IN $T SECTION                 |

# schofield-brtval.R: Generate SVG graph of the brightness curves
#    produced by Ian Schofield's ILS patch.
#
# The schofield-brtval.svg file checked into Fossil is modified from the
# version output by this program:
#
# 1. The colors are modified to match the scheme on tangentsoft.com/pidp8i
#
# 2. The data line thickness was increased
#
# 3. The data lines were smoothed by Inkscape's "simplify" function
#
# Copyright © 2017 Warren Young
#
# Permission is hereby granted, free of charge, to any person obtaining a
# copy of this software and associated documentation files (the "Software"),
# to deal in the Software without restriction, including without limitation
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
# and/or sell copies of the Software, and to permit persons to whom the
# Software is furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
# THE AUTHORS LISTED ABOVE BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
# DEALINGS IN THE SOFTWARE.
#
# Except as contained in this notice, the names of the authors above shall
# not be used in advertising or otherwise to promote the sale, use or other
# dealings in this Software without prior written authorization from those
# authors.
#

min = 0
max = 32
a = min
b = max

rising  = c(min);
falling = c(max);

for (i in 1:400) {
  a = a + (max - a) * 0.01
  b = b + (min - b) * 0.01
  
  rising[i]  = a
  falling[i] = b
  
  if (a > 31 || b < 1) break
}

data = data.frame(Rising = rising, Falling = falling)
dts = ts(data)
svg("schofield-brtval.svg", width=8, height=6)
plot.ts(dts, plot.type='single', ylab='Brightness',
        yaxp=c(min, max, 8))
dev.off()

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
   xmlns:dc="http://purl.org/dc/elements/1.1/"
   xmlns:cc="http://creativecommons.org/ns#"
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:svg="http://www.w3.org/2000/svg"
   xmlns="http://www.w3.org/2000/svg"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
   width="576pt"
   height="396.73468pt"
   viewBox="0 0 576 396.73468"
   version="1.1"
   id="svg4276"
   inkscape:version="0.91 r13725"
   sodipodi:docname="schofield-brtval.svg">
  <title
     id="title4481">Schofield ILS Brightness Curves</title>
  <metadata
     id="metadata267">
    <rdf:RDF>
      <cc:Work
         rdf:about="">
        <dc:format>image/svg+xml</dc:format>
        <dc:type
           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
        <dc:title>Schofield ILS Brightness Curves</dc:title>
        <cc:license
           rdf:resource="https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md" />
        <dc:date>2017-02-02</dc:date>
        <dc:creator>
          <cc:Agent>
            <dc:title>Warren Young</dc:title>
          </cc:Agent>
        </dc:creator>
        <dc:language>English</dc:language>
        <dc:description>Curves showing the brightness levels of an LED driven from 0 to full brightness and from full brightness back to 0 under Ian Schofield's indandescent lamp simulator for the PiDP-8/I.</dc:description>
      </cc:Work>
    </rdf:RDF>
  </metadata>
  <sodipodi:namedview
     pagecolor="#ffffff"
     bordercolor="#666666"
     borderopacity="1"
     objecttolerance="10"
     gridtolerance="10"
     guidetolerance="10"
     inkscape:pageopacity="0"
     inkscape:pageshadow="2"
     inkscape:window-width="2560"
     inkscape:window-height="1391"
     id="namedview4548"
     showgrid="false"
     inkscape:zoom="1.6333333"
     inkscape:cx="360"
     inkscape:cy="253.95917"
     inkscape:window-x="0"
     inkscape:window-y="1"
     inkscape:window-maximized="1"
     inkscape:current-layer="svg4276"
     fit-margin-top="0"
     fit-margin-left="0"
     fit-margin-right="0"
     fit-margin-bottom="0" />
  <defs
     id="defs4278">
    <g
       id="g4280">
      <symbol
         overflow="visible"
         id="glyph0-0"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m 0.390625,0 0,-8.609375 6.828125,0 0,8.609375 z m 5.75,-1.078125 0,-6.453125 -4.671875,0 0,6.453125 z"
           id="path4283"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph0-1"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m 7.171875,-8.609375 0,1.03125 -2.890625,0 0,7.578125 -1.1875,0 0,-7.578125 -2.90625,0 0,-1.03125 z"
           id="path4286"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph0-2"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m 0.78125,-6.25 1.0625,0 0,6.25 -1.0625,0 z m 0,-2.359375 1.0625,0 0,1.203125 -1.0625,0 z"
           id="path4289"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph0-3"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m 0.78125,-6.28125 1.03125,0 0,0.890625 C 2.0625,-5.691406 2.289062,-5.914062 2.5,-6.0625 c 0.34375,-0.238281 0.738281,-0.359375 1.1875,-0.359375 0.5,0 0.898438,0.125 1.203125,0.375 0.164063,0.136719 0.320313,0.34375 0.46875,0.625 0.226563,-0.34375 0.5,-0.59375 0.8125,-0.75 0.320313,-0.164063 0.679687,-0.25 1.078125,-0.25 0.84375,0 1.414062,0.308594 1.71875,0.921875 0.164062,0.324219 0.25,0.765625 0.25,1.328125 L 9.21875,0 8.125,0 l 0,-4.359375 C 8.125,-4.773438 8.019531,-5.0625 7.8125,-5.21875 7.601562,-5.375 7.347656,-5.453125 7.046875,-5.453125 c -0.417969,0 -0.777344,0.140625 -1.078125,0.421875 -0.292969,0.273438 -0.4375,0.730469 -0.4375,1.375 l 0,3.65625 -1.078125,0 0,-4.09375 c 0,-0.425781 -0.054687,-0.738281 -0.15625,-0.9375 C 4.140625,-5.320312 3.84375,-5.46875 3.40625,-5.46875 3.007812,-5.46875 2.644531,-5.3125 2.3125,-5 1.988281,-4.695312 1.828125,-4.140625 1.828125,-3.328125 L 1.828125,0 0.78125,0 Z"
           id="path4292"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph0-4"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m 3.390625,-6.421875 c 0.445313,0 0.878906,0.105469 1.296875,0.3125 0.414062,0.210937 0.734375,0.480469 0.953125,0.8125 0.207031,0.324219 0.347656,0.695313 0.421875,1.109375 0.0625,0.292969 0.09375,0.757812 0.09375,1.390625 l -4.609375,0 C 1.566406,-2.160156 1.71875,-1.648438 2,-1.265625 2.28125,-0.878906 2.71875,-0.6875 3.3125,-0.6875 c 0.550781,0 0.988281,-0.179688 1.3125,-0.546875 C 4.8125,-1.441406 4.945312,-1.6875 5.03125,-1.96875 l 1.03125,0 C 6.039062,-1.738281 5.953125,-1.484375 5.796875,-1.203125 5.640625,-0.921875 5.46875,-0.6875 5.28125,-0.5 4.957031,-0.1875 4.554688,0.0195312 4.078125,0.125 3.828125,0.1875 3.539062,0.21875 3.21875,0.21875 2.4375,0.21875 1.773438,-0.0625 1.234375,-0.625 c -0.542969,-0.570312 -0.8125,-1.367188 -0.8125,-2.390625 0,-1.007813 0.269531,-1.828125 0.8125,-2.453125 0.550781,-0.632812 1.269531,-0.953125 2.15625,-0.953125 z M 5.0625,-3.640625 C 5.019531,-4.097656 4.921875,-4.460938 4.765625,-4.734375 4.484375,-5.242188 4.003906,-5.5 3.328125,-5.5 2.835938,-5.5 2.425781,-5.320312 2.09375,-4.96875 1.769531,-4.625 1.597656,-4.179688 1.578125,-3.640625 Z m -1.78125,-2.78125 z"
           id="path4295"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph0-5"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m 3.25,-8.390625 c 1.082031,0 1.867188,0.449219 2.359375,1.34375 0.375,0.6875 0.5625,1.636719 0.5625,2.84375 C 6.171875,-3.066406 6,-2.125 5.65625,-1.375 5.164062,-0.300781 4.359375,0.234375 3.234375,0.234375 c -1,0 -1.75,-0.4375 -2.25,-1.3125 C 0.578125,-1.816406 0.375,-2.800781 0.375,-4.03125 c 0,-0.945312 0.125,-1.765625 0.375,-2.453125 0.457031,-1.269531 1.289062,-1.90625 2.5,-1.90625 z m -0.015625,7.65625 c 0.550781,0 0.988281,-0.238281 1.3125,-0.71875 0.320313,-0.488281 0.484375,-1.394531 0.484375,-2.71875 0,-0.945313 -0.121094,-1.726563 -0.359375,-2.34375 C 4.441406,-7.128906 3.988281,-7.4375 3.3125,-7.4375 c -0.625,0 -1.085938,0.292969 -1.375,0.875 -0.28125,0.585938 -0.421875,1.445312 -0.421875,2.578125 0,0.855469 0.09375,1.542969 0.28125,2.0625 0.28125,0.792969 0.757813,1.1875 1.4375,1.1875 z"
           id="path4298"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph0-6"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m 1.484375,-2.140625 c 0.070313,0.605469 0.351563,1.023437 0.84375,1.25 0.25,0.117187 0.535156,0.171875 0.859375,0.171875 0.625,0 1.085938,-0.195312 1.390625,-0.59375 C 4.878906,-1.707031 5.03125,-2.148438 5.03125,-2.640625 5.03125,-3.222656 4.847656,-3.675781 4.484375,-4 4.128906,-4.320312 3.703125,-4.484375 3.203125,-4.484375 c -0.367187,0 -0.679687,0.074219 -0.9375,0.21875 C 2.003906,-4.128906 1.785156,-3.9375 1.609375,-3.6875 L 0.6875,-3.734375 1.328125,-8.25 l 4.359375,0 0,1.015625 -3.5625,0 -0.359375,2.328125 c 0.195313,-0.144531 0.382813,-0.253906 0.5625,-0.328125 0.3125,-0.125 0.671875,-0.1875 1.078125,-0.1875 0.769531,0 1.421875,0.25 1.953125,0.75 0.539063,0.492187 0.8125,1.117187 0.8125,1.875 0,0.792969 -0.25,1.496094 -0.75,2.109375 -0.492187,0.6054688 -1.273437,0.90625 -2.34375,0.90625 -0.679687,0 -1.28125,-0.1953125 -1.8125,-0.578125 -0.523437,-0.382813 -0.8125,-0.976563 -0.875,-1.78125 z"
           id="path4301"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph0-7"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m 1.15625,-5.9375 0,-0.8125 c 0.757812,-0.070312 1.285156,-0.195312 1.578125,-0.375 0.300781,-0.175781 0.53125,-0.585938 0.6875,-1.234375 l 0.828125,0 L 4.25,0 3.125,0 l 0,-5.9375 z"
           id="path4304"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph0-8"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="M 0.375,0 C 0.414062,-0.71875 0.566406,-1.34375 0.828125,-1.875 1.085938,-2.414062 1.59375,-2.90625 2.34375,-3.34375 L 3.46875,-4 c 0.5,-0.289062 0.851562,-0.539062 1.0625,-0.75 0.320312,-0.320312 0.484375,-0.691406 0.484375,-1.109375 0,-0.488281 -0.152344,-0.875 -0.453125,-1.15625 -0.292969,-0.289063 -0.679688,-0.4375 -1.15625,-0.4375 -0.730469,0 -1.230469,0.273437 -1.5,0.8125 -0.15625,0.304687 -0.242188,0.710937 -0.25,1.21875 l -1.078125,0 c 0.007813,-0.726563 0.144531,-1.320313 0.40625,-1.78125 0.457031,-0.8125 1.265625,-1.21875 2.421875,-1.21875 0.957031,0 1.65625,0.261719 2.09375,0.78125 0.445312,0.523437 0.671875,1.101563 0.671875,1.734375 0,0.667969 -0.234375,1.242188 -0.703125,1.71875 C 5.195312,-3.90625 4.707031,-3.566406 4,-3.171875 l -0.8125,0.4375 C 2.8125,-2.523438 2.515625,-2.320312 2.296875,-2.125 1.898438,-1.789062 1.648438,-1.414062 1.546875,-1 l 4.59375,0 0,1 z"
           id="path4307"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph0-9"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m 3.125,0.234375 c -1,0 -1.726562,-0.2695312 -2.171875,-0.8125 -0.449219,-0.550781 -0.671875,-1.21875 -0.671875,-2 l 1.109375,0 c 0.039063,0.542969 0.140625,0.9375 0.296875,1.1875 0.28125,0.4375 0.773438,0.65625 1.484375,0.65625 0.5625,0 1.007813,-0.144531 1.34375,-0.4375 0.332031,-0.300781 0.5,-0.6875 0.5,-1.15625 0,-0.570313 -0.179687,-0.972656 -0.53125,-1.203125 -0.355469,-0.238281 -0.84375,-0.359375 -1.46875,-0.359375 -0.074219,0 -0.148437,0.00781 -0.21875,0.015625 -0.074219,0 -0.148437,0 -0.21875,0 l 0,-0.9375 c 0.113281,0.023438 0.207031,0.03125 0.28125,0.03125 0.070313,0 0.148437,0 0.234375,0 0.394531,0 0.71875,-0.0625 0.96875,-0.1875 C 4.507812,-5.1875 4.734375,-5.578125 4.734375,-6.140625 4.734375,-6.554688 4.582031,-6.875 4.28125,-7.09375 3.988281,-7.320312 3.644531,-7.4375 3.25,-7.4375 c -0.699219,0 -1.183594,0.234375 -1.453125,0.703125 -0.148437,0.25 -0.230469,0.617187 -0.25,1.09375 l -1.046875,0 c 0,-0.625 0.125,-1.15625 0.375,-1.59375 0.425781,-0.78125 1.179688,-1.171875 2.265625,-1.171875 0.851563,0 1.515625,0.195312 1.984375,0.578125 0.46875,0.375 0.703125,0.929687 0.703125,1.65625 0,0.511719 -0.136719,0.929687 -0.40625,1.25 -0.179687,0.199219 -0.402344,0.355469 -0.671875,0.46875 0.4375,0.125 0.78125,0.359375 1.03125,0.703125 0.25,0.34375 0.375,0.765625 0.375,1.265625 0,0.804687 -0.265625,1.460937 -0.796875,1.96875 -0.523437,0.5 -1.265625,0.75 -2.234375,0.75 z"
           id="path4310"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-0"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m 0,-0.390625 -8.609375,0 0,-6.828125 8.609375,0 z m -1.078125,-5.75 -6.453125,0 0,4.671875 6.453125,0 z"
           id="path4313"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-1"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -4.96875,-4.15625 c 0,-0.488281 -0.066406,-0.867188 -0.203125,-1.140625 -0.21875,-0.425781 -0.601563,-0.640625 -1.15625,-0.640625 -0.5625,0 -0.941406,0.230469 -1.140625,0.6875 -0.113281,0.25 -0.171875,0.632812 -0.171875,1.140625 l 0,2.078125 2.671875,0 z M -1,-4.546875 c 0,-0.707031 -0.207031,-1.21875 -0.625,-1.53125 -0.257812,-0.1875 -0.570312,-0.28125 -0.9375,-0.28125 -0.625,0 -1.050781,0.28125 -1.28125,0.84375 -0.125,0.292969 -0.1875,0.683594 -0.1875,1.171875 l 0,2.3125 3.03125,0 z m -7.609375,3.65625 0,-3.6875 c 0,-1.007813 0.304687,-1.726563 0.90625,-2.15625 0.355469,-0.25 0.765625,-0.375 1.234375,-0.375 0.542969,0 0.984375,0.15625 1.328125,0.46875 0.1875,0.15625 0.355469,0.386719 0.5,0.6875 0.167969,-0.4375 0.359375,-0.765625 0.578125,-0.984375 0.375,-0.394531 0.890625,-0.59375 1.546875,-0.59375 0.554687,0 1.054687,0.179688 1.5,0.53125 C -0.335938,-6.476562 0,-5.65625 0,-4.53125 l 0,3.640625 z"
           id="path4316"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-2"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -6.28125,-0.796875 0,-1.015625 1.09375,0 c -0.21875,-0.070312 -0.476562,-0.269531 -0.78125,-0.59375 -0.300781,-0.320312 -0.453125,-0.691406 -0.453125,-1.109375 0,-0.019531 0.00781,-0.050781 0.015625,-0.09375 0,-0.050781 0.00781,-0.132813 0.015625,-0.25 l 1.109375,0 c -0.00781,0.0625 -0.015625,0.121094 -0.015625,0.171875 0,0.054688 0,0.109375 0,0.171875 0,0.53125 0.171875,0.945313 0.515625,1.234375 0.335938,0.28125 0.726562,0.421875 1.171875,0.421875 l 3.609375,0 0,1.0625 z"
           id="path4319"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-3"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -6.25,-0.78125 0,-1.0625 6.25,0 0,1.0625 z m -2.359375,0 0,-1.0625 1.203125,0 0,1.0625 z"
           id="path4322"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-4"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -6.390625,-2.984375 c 0,-0.5 0.121094,-0.929687 0.359375,-1.296875 0.148438,-0.195312 0.351562,-0.398438 0.609375,-0.609375 l -0.796875,0 0,-0.96875 5.703125,0 c 0.800781,0 1.429687,0.117187 1.890625,0.34375 0.851562,0.4375 1.28125,1.265625 1.28125,2.484375 0,0.679688 -0.152344,1.246094 -0.453125,1.703125 -0.304687,0.460937 -0.777344,0.71875 -1.421875,0.78125 l 0,-1.078125 c 0.28125,-0.050781 0.5,-0.148438 0.65625,-0.296875 0.226562,-0.238281 0.34375,-0.613281 0.34375,-1.125 0,-0.8125 -0.289062,-1.34375 -0.859375,-1.59375 C 0.585938,-4.785156 -0.0078125,-4.851562 -0.875,-4.84375 c 0.324219,0.210938 0.5625,0.464844 0.71875,0.765625 0.15625,0.292969 0.234375,0.683594 0.234375,1.171875 0,0.679688 -0.238281,1.273438 -0.71875,1.78125 -0.488281,0.511719 -1.289063,0.765625 -2.40625,0.765625 -1.050781,0 -1.867187,-0.253906 -2.453125,-0.765625 -0.59375,-0.519531 -0.890625,-1.140625 -0.890625,-1.859375 z m 3.21875,-1.90625 c -0.769531,0 -1.34375,0.164063 -1.71875,0.484375 -0.375,0.324219 -0.5625,0.730469 -0.5625,1.21875 0,0.75 0.351563,1.261719 1.046875,1.53125 0.367188,0.148438 0.851562,0.21875 1.453125,0.21875 0.710937,0 1.25,-0.140625 1.625,-0.421875 0.367187,-0.289063 0.546875,-0.679687 0.546875,-1.171875 0,-0.757812 -0.34375,-1.289062 -1.03125,-1.59375 -0.382812,-0.175781 -0.835938,-0.265625 -1.359375,-0.265625 z m -3.25,1.78125 z"
           id="path4325"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-5"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -8.640625,-0.78125 0,-1.046875 3.21875,0 C -5.742188,-2.078125 -5.96875,-2.300781 -6.09375,-2.5 -6.3125,-2.84375 -6.421875,-3.269531 -6.421875,-3.78125 c 0,-0.90625 0.320313,-1.519531 0.953125,-1.84375 0.34375,-0.175781 0.824219,-0.265625 1.4375,-0.265625 l 4.03125,0 0,1.078125 -3.953125,0 c -0.457031,0 -0.796875,0.0625 -1.015625,0.1875 -0.34375,0.1875 -0.515625,0.546875 -0.515625,1.078125 0,0.4375 0.152344,0.835937 0.453125,1.1875 0.304688,0.355469 0.871094,0.53125 1.703125,0.53125 l 3.328125,0 0,1.046875 z"
           id="path4328"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-6"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -8.03125,-0.984375 0,-1.0625 1.75,0 0,-1 0.859375,0 0,1 4.109375,0 c 0.21875,0 0.367188,-0.078125 0.4375,-0.234375 0.042969,-0.070312 0.0625,-0.207031 0.0625,-0.40625 0,-0.050781 0,-0.101562 0,-0.15625 -0.007812,-0.0625 -0.015625,-0.128906 -0.015625,-0.203125 l 0.828125,0 c 0.03125,0.117187 0.0507812,0.242187 0.0625,0.375 0.0195312,0.125 0.03125,0.265625 0.03125,0.421875 0,0.492188 -0.125,0.824219 -0.375,1 -0.25,0.179688 -0.578125,0.265625 -0.984375,0.265625 l -4.15625,0 0,0.84375 -0.859375,0 0,-0.84375 z"
           id="path4331"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-7"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -6.28125,-0.78125 0,-1 0.890625,0 c -0.363281,-0.289062 -0.625,-0.601562 -0.78125,-0.9375 -0.164063,-0.332031 -0.25,-0.703125 -0.25,-1.109375 0,-0.882813 0.3125,-1.484375 0.9375,-1.796875 0.34375,-0.175781 0.828125,-0.265625 1.453125,-0.265625 l 4.03125,0 0,1.078125 -3.953125,0 c -0.382813,0 -0.691406,0.058594 -0.921875,0.171875 -0.394531,0.1875 -0.59375,0.527344 -0.59375,1.015625 0,0.25 0.027344,0.453125 0.078125,0.609375 0.085937,0.292969 0.257813,0.546875 0.515625,0.765625 0.210938,0.179688 0.421875,0.292969 0.640625,0.34375 0.21875,0.054688 0.539063,0.078125 0.953125,0.078125 l 3.28125,0 0,1.046875 z M -6.421875,-3.25 Z"
           id="path4334"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-8"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -6.421875,-3.390625 c 0,-0.445313 0.105469,-0.878906 0.3125,-1.296875 0.210937,-0.414062 0.480469,-0.734375 0.8125,-0.953125 0.324219,-0.207031 0.695313,-0.347656 1.109375,-0.421875 0.292969,-0.0625 0.757812,-0.09375 1.390625,-0.09375 l 0,4.609375 C -2.160156,-1.566406 -1.648438,-1.71875 -1.265625,-2 -0.878906,-2.28125 -0.6875,-2.71875 -0.6875,-3.3125 c 0,-0.550781 -0.179688,-0.988281 -0.546875,-1.3125 C -1.441406,-4.8125 -1.6875,-4.945312 -1.96875,-5.03125 l 0,-1.03125 c 0.230469,0.023438 0.484375,0.109375 0.765625,0.265625 0.28125,0.15625 0.515625,0.328125 0.703125,0.515625 0.3125,0.324219 0.5195312,0.726562 0.625,1.203125 0.0625,0.25 0.09375,0.539063 0.09375,0.859375 0,0.78125 -0.28125,1.445312 -0.84375,1.984375 -0.570312,0.542969 -1.367188,0.8125 -2.390625,0.8125 -1.007813,0 -1.828125,-0.269531 -2.453125,-0.8125 -0.632812,-0.550781 -0.953125,-1.269531 -0.953125,-2.15625 z m 2.78125,-1.671875 c -0.457031,0.042969 -0.820313,0.140625 -1.09375,0.296875 -0.507813,0.28125 -0.765625,0.761719 -0.765625,1.4375 0,0.492187 0.179688,0.902344 0.53125,1.234375 0.34375,0.324219 0.789062,0.496094 1.328125,0.515625 z m -2.78125,1.78125 z"
           id="path4337"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-9"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -1.96875,-1.40625 c 0.355469,-0.03125 0.625,-0.117188 0.8125,-0.265625 0.335938,-0.257813 0.5,-0.71875 0.5,-1.375 0,-0.394531 -0.082031,-0.738281 -0.25,-1.03125 -0.164062,-0.300781 -0.425781,-0.453125 -0.78125,-0.453125 -0.269531,0 -0.476562,0.121094 -0.625,0.359375 -0.082031,0.15625 -0.179688,0.460937 -0.296875,0.90625 L -2.8125,-2.421875 C -2.945312,-1.890625 -3.097656,-1.5 -3.265625,-1.25 c -0.28125,0.460938 -0.675781,0.6875 -1.1875,0.6875 -0.59375,0 -1.070313,-0.210938 -1.4375,-0.640625 C -6.253906,-1.628906 -6.4375,-2.207031 -6.4375,-2.9375 c 0,-0.9375 0.277344,-1.613281 0.828125,-2.03125 0.355469,-0.269531 0.734375,-0.398438 1.140625,-0.390625 l 0,1 c -0.238281,0.023437 -0.457031,0.105469 -0.65625,0.25 -0.269531,0.242187 -0.40625,0.664063 -0.40625,1.265625 0,0.398438 0.078125,0.699219 0.234375,0.90625 0.148437,0.199219 0.34375,0.296875 0.59375,0.296875 0.273437,0 0.492187,-0.132813 0.65625,-0.40625 0.09375,-0.15625 0.179687,-0.382813 0.25,-0.6875 l 0.171875,-0.6875 c 0.1875,-0.757813 0.367188,-1.269531 0.53125,-1.53125 0.273438,-0.40625 0.699219,-0.609375 1.28125,-0.609375 0.554688,0 1.03125,0.214844 1.4375,0.640625 0.40625,0.417969 0.609375,1.058594 0.609375,1.921875 0,0.9375 -0.2109375,1.605469 -0.625,2 -0.425781,0.386719 -0.953125,0.589844 -1.578125,0.609375 z m -4.453125,-1.546875 z"
           id="path4340"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-10"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -8.390625,-3.25 c 0,-1.082031 0.449219,-1.867188 1.34375,-2.359375 0.6875,-0.375 1.636719,-0.5625 2.84375,-0.5625 1.136719,0 2.078125,0.171875 2.828125,0.515625 1.074219,0.492188 1.609375,1.296875 1.609375,2.421875 0,1 -0.4375,1.75 -1.3125,2.25 -0.738281,0.40625 -1.722656,0.609375 -2.953125,0.609375 -0.945312,0 -1.765625,-0.125 -2.453125,-0.375 -1.269531,-0.457031 -1.90625,-1.289062 -1.90625,-2.5 z m 7.65625,0.015625 c 0,-0.550781 -0.238281,-0.988281 -0.71875,-1.3125 -0.488281,-0.320313 -1.394531,-0.484375 -2.71875,-0.484375 -0.945313,0 -1.726563,0.121094 -2.34375,0.359375 -0.613281,0.230469 -0.921875,0.683594 -0.921875,1.359375 0,0.625 0.292969,1.085938 0.875,1.375 0.585938,0.28125 1.445312,0.421875 2.578125,0.421875 0.855469,0 1.542969,-0.09375 2.0625,-0.28125 0.792969,-0.28125 1.1875,-0.757813 1.1875,-1.4375 z"
           id="path4343"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-11"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -2.96875,-3.96875 -3.8125,0 3.8125,2.6875 z M 0,-3.984375 l -2.046875,0 0,3.671875 -1.03125,0 -5.34375,-3.84375 0,-0.890625 5.453125,0 0,-1.234375 0.921875,0 0,1.234375 2.046875,0 z"
           id="path4346"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-12"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -4.875,-3.265625 c 0,-0.46875 -0.128906,-0.832031 -0.390625,-1.09375 C -5.523438,-4.617188 -5.832031,-4.75 -6.1875,-4.75 c -0.3125,0 -0.597656,0.125 -0.859375,0.375 -0.269531,0.25 -0.40625,0.632812 -0.40625,1.140625 0,0.511719 0.136719,0.882813 0.40625,1.109375 0.261719,0.230469 0.5625,0.34375 0.90625,0.34375 0.398437,0 0.710937,-0.144531 0.9375,-0.4375 0.21875,-0.300781 0.328125,-0.648438 0.328125,-1.046875 z m 4.15625,-0.0625 c 0,-0.488281 -0.128906,-0.894531 -0.390625,-1.21875 -0.269531,-0.320313 -0.664063,-0.484375 -1.1875,-0.484375 -0.539063,0 -0.953125,0.167969 -1.234375,0.5 -0.28125,0.335938 -0.421875,0.761719 -0.421875,1.28125 0,0.5 0.148437,0.914062 0.4375,1.234375 0.28125,0.3125 0.679687,0.46875 1.1875,0.46875 0.4375,0 0.820313,-0.144531 1.140625,-0.4375 0.3125,-0.289063 0.46875,-0.738281 0.46875,-1.34375 z m -3.75,1.5 c -0.125,0.292969 -0.269531,0.523437 -0.4375,0.6875 -0.3125,0.304687 -0.71875,0.453125 -1.21875,0.453125 -0.625,0 -1.160156,-0.222656 -1.609375,-0.671875 -0.457031,-0.457031 -0.6875,-1.097656 -0.6875,-1.921875 0,-0.8125 0.214844,-1.441406 0.640625,-1.890625 0.429688,-0.457031 0.921875,-0.6875 1.484375,-0.6875 0.523437,0 0.949219,0.132813 1.28125,0.390625 0.179687,0.148438 0.355469,0.375 0.53125,0.6875 0.15625,-0.34375 0.339844,-0.613281 0.546875,-0.8125 0.398438,-0.375 0.90625,-0.5625 1.53125,-0.5625 0.742188,0 1.367188,0.25 1.875,0.75 0.5117188,0.492188 0.765625,1.1875 0.765625,2.09375 0,0.824219 -0.21875,1.515625 -0.65625,2.078125 -0.445313,0.5625 -1.09375,0.84375 -1.9375,0.84375 -0.488281,0 -0.914063,-0.117187 -1.28125,-0.359375 -0.363281,-0.238281 -0.640625,-0.597656 -0.828125,-1.078125 z"
           id="path4349"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-13"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -5.9375,-1.15625 -0.8125,0 c -0.070312,-0.757812 -0.195312,-1.285156 -0.375,-1.578125 -0.175781,-0.300781 -0.585938,-0.53125 -1.234375,-0.6875 l 0,-0.828125 8.359375,0 0,1.125 -5.9375,0 z"
           id="path4352"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-14"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="M 0,-0.375 C -0.71875,-0.414062 -1.34375,-0.566406 -1.875,-0.828125 -2.414062,-1.085938 -2.90625,-1.59375 -3.34375,-2.34375 L -4,-3.46875 c -0.289062,-0.5 -0.539062,-0.851562 -0.75,-1.0625 -0.320312,-0.320312 -0.691406,-0.484375 -1.109375,-0.484375 -0.488281,0 -0.875,0.152344 -1.15625,0.453125 -0.289063,0.292969 -0.4375,0.679688 -0.4375,1.15625 0,0.730469 0.273437,1.230469 0.8125,1.5 0.304687,0.15625 0.710937,0.242188 1.21875,0.25 l 0,1.078125 c -0.726563,-0.007813 -1.320313,-0.144531 -1.78125,-0.40625 -0.8125,-0.457031 -1.21875,-1.265625 -1.21875,-2.421875 0,-0.957031 0.261719,-1.65625 0.78125,-2.09375 0.523437,-0.445312 1.101563,-0.671875 1.734375,-0.671875 0.667969,0 1.242188,0.234375 1.71875,0.703125 0.28125,0.273438 0.621094,0.761719 1.015625,1.46875 l 0.4375,0.8125 c 0.210937,0.375 0.414063,0.671875 0.609375,0.890625 0.335938,0.398437 0.710938,0.648437 1.125,0.75 l 0,-4.59375 1,0 z"
           id="path4355"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-15"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m -8.421875,-3.515625 c 0,-0.9375 0.246094,-1.585937 0.734375,-1.953125 0.480469,-0.375 0.980469,-0.5625 1.5,-0.5625 l 0,1.046875 c -0.332031,0.0625 -0.59375,0.164063 -0.78125,0.296875 C -7.320312,-4.425781 -7.5,-4.039062 -7.5,-3.53125 c 0,0.59375 0.277344,1.070312 0.828125,1.421875 0.542969,0.34375 1.320313,0.53125 2.328125,0.5625 -0.351562,-0.238281 -0.617188,-0.539063 -0.796875,-0.90625 -0.15625,-0.332031 -0.234375,-0.707031 -0.234375,-1.125 0,-0.707031 0.226562,-1.320313 0.671875,-1.84375 0.449219,-0.519531 1.121094,-0.78125 2.015625,-0.78125 0.761719,0 1.4375,0.25 2.03125,0.75 0.5859375,0.492187 0.875,1.195313 0.875,2.109375 0,0.792969 -0.296875,1.476562 -0.890625,2.046875 -0.601563,0.5625 -1.609375,0.84375 -3.015625,0.84375 -1.039062,0 -1.925781,-0.125 -2.65625,-0.375 -1.382812,-0.488281 -2.078125,-1.382813 -2.078125,-2.6875 z M -0.71875,-3.4375 c 0,-0.550781 -0.1875,-0.960938 -0.5625,-1.234375 -0.375,-0.28125 -0.816406,-0.421875 -1.328125,-0.421875 -0.425781,0 -0.832031,0.125 -1.21875,0.375 -0.382813,0.242188 -0.578125,0.6875 -0.578125,1.34375 0,0.449219 0.152344,0.84375 0.453125,1.1875 0.292969,0.34375 0.742187,0.515625 1.34375,0.515625 0.53125,0 0.980469,-0.15625 1.34375,-0.46875 0.367187,-0.3125 0.546875,-0.742187 0.546875,-1.296875 z"
           id="path4358"
           inkscape:connector-curvature="0" />
      </symbol>
      <symbol
         overflow="visible"
         id="glyph1-16"
         style="overflow:visible">
        <path
           style="stroke:none"
           d="m 0.234375,-3.125 c 0,1 -0.2695312,1.726562 -0.8125,2.171875 -0.550781,0.449219 -1.21875,0.671875 -2,0.671875 l 0,-1.109375 c 0.542969,-0.039063 0.9375,-0.140625 1.1875,-0.296875 0.4375,-0.28125 0.65625,-0.773438 0.65625,-1.484375 0,-0.5625 -0.144531,-1.007813 -0.4375,-1.34375 -0.300781,-0.332031 -0.6875,-0.5 -1.15625,-0.5 -0.570313,0 -0.972656,0.179687 -1.203125,0.53125 -0.238281,0.355469 -0.359375,0.84375 -0.359375,1.46875 0,0.074219 0.00781,0.148437 0.015625,0.21875 0,0.074219 0,0.148437 0,0.21875 l -0.9375,0 c 0.023438,-0.113281 0.03125,-0.207031 0.03125,-0.28125 0,-0.070313 0,-0.148437 0,-0.234375 0,-0.394531 -0.0625,-0.71875 -0.1875,-0.96875 -0.21875,-0.445312 -0.609375,-0.671875 -1.171875,-0.671875 -0.414063,0 -0.734375,0.152344 -0.953125,0.453125 -0.226562,0.292969 -0.34375,0.636719 -0.34375,1.03125 0,0.699219 0.234375,1.183594 0.703125,1.453125 0.25,0.148437 0.617187,0.230469 1.09375,0.25 l 0,1.046875 c -0.625,0 -1.15625,-0.125 -1.59375,-0.375 -0.78125,-0.425781 -1.171875,-1.179688 -1.171875,-2.265625 0,-0.851563 0.195312,-1.515625 0.578125,-1.984375 0.375,-0.46875 0.929687,-0.703125 1.65625,-0.703125 0.511719,0 0.929687,0.136719 1.25,0.40625 0.199219,0.179687 0.355469,0.402344 0.46875,0.671875 0.125,-0.4375 0.359375,-0.78125 0.703125,-1.03125 0.34375,-0.25 0.765625,-0.375 1.265625,-0.375 0.804687,0 1.460937,0.265625 1.96875,0.796875 0.5,0.523437 0.75,1.265625 0.75,2.234375 z"
           id="path4361"
           inkscape:connector-curvature="0" />
      </symbol>
    </g>
  </defs>
  <rect
     id="rect4364"
     style="fill:#fff3df;fill-opacity:1;stroke:none"
     height="396.73468"
     width="576"
     y="0"
     x="0" />
  <path
     style="fill:none;stroke:#45873b;stroke-width:1.60000002;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1"
     d="M 88.266406,310.63218 C 122.02676,237.79712 168.07359,167.7088 234.99687,121.36656 298.00502,77.074005 374.52101,57.963738 449.84844,47.956407 c 29.57913,-3.956704 59.3163,-6.634684 89.08593,-8.656254"
     id="path4366"
     inkscape:connector-curvature="0" />
  <path
     style="fill:none;stroke:#95473f;stroke-width:1.60000002;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1"
     d="M 88.266406,33.300157 C 122.02506,106.13557 168.07177,176.22644 234.99687,222.56578 c 63.74354,44.80848 141.26877,63.83721 217.47266,73.75781 28.71422,3.77216 57.57485,6.34594 86.46484,8.31216"
     id="path4368"
     inkscape:connector-curvature="0" />
  <g
     id="g4370"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-41.632655)">
    <use
       height="100%"
       width="100%"
       id="use4372"
       y="413.28125"
       x="289.06641"
       xlink:href="#glyph0-1"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4374"
       y="413.28125"
       x="296.39648"
       xlink:href="#glyph0-2"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4376"
       y="413.28125"
       x="299.0625"
       xlink:href="#glyph0-3"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4378"
       y="413.28125"
       x="309.05859"
       xlink:href="#glyph0-4"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4380"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4382"
       y="237.14844"
       x="12.960938"
       xlink:href="#glyph1-1"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4384"
       y="229.14453"
       x="12.960938"
       xlink:href="#glyph1-2"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4386"
       y="225.14844"
       x="12.960938"
       xlink:href="#glyph1-3"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4388"
       y="222.48242"
       x="12.960938"
       xlink:href="#glyph1-4"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4390"
       y="215.80859"
       x="12.960938"
       xlink:href="#glyph1-5"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4392"
       y="209.13477"
       x="12.960938"
       xlink:href="#glyph1-6"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4394"
       y="205.80078"
       x="12.960938"
       xlink:href="#glyph1-7"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4396"
       y="199.12695"
       x="12.960938"
       xlink:href="#glyph1-8"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4398"
       y="192.45312"
       x="12.960938"
       xlink:href="#glyph1-9"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4400"
       y="186.45312"
       x="12.960938"
       xlink:href="#glyph1-9"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <path
     inkscape:connector-curvature="0"
     id="path4402"
     d="m 86.957812,321.72593 458.527348,0"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4404"
     d="m 86.957812,321.72593 0,7.20313"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4406"
     d="m 152.46172,321.72593 0,7.20313"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4408"
     d="m 217.96562,321.72593 0,7.20313"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4410"
     d="m 283.46953,321.72593 0,7.20313"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4412"
     d="m 348.97344,321.72593 0,7.20313"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4414"
     d="m 414.47734,321.72593 0,7.20313"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4416"
     d="m 479.98125,321.72593 0,7.20313"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4418"
     d="m 545.48516,321.72593 0,7.20313"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <g
     id="g4420"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4422"
       y="384.48047"
       x="72.421875"
       xlink:href="#glyph0-5"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4424"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4426"
       y="384.48047"
       x="134.58984"
       xlink:href="#glyph0-6"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4428"
       y="384.48047"
       x="141.26367"
       xlink:href="#glyph0-5"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4430"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4432"
       y="384.48047"
       x="196.75391"
       xlink:href="#glyph0-7"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4434"
       y="384.48047"
       x="203.42773"
       xlink:href="#glyph0-5"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4436"
       y="384.48047"
       x="210.10156"
       xlink:href="#glyph0-5"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4438"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4440"
       y="384.48047"
       x="262.25781"
       xlink:href="#glyph0-7"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4442"
       y="384.48047"
       x="268.93164"
       xlink:href="#glyph0-6"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4444"
       y="384.48047"
       x="275.60547"
       xlink:href="#glyph0-5"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4446"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4448"
       y="384.48047"
       x="327.76172"
       xlink:href="#glyph0-8"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4450"
       y="384.48047"
       x="334.43555"
       xlink:href="#glyph0-5"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4452"
       y="384.48047"
       x="341.10938"
       xlink:href="#glyph0-5"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4454"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4456"
       y="384.48047"
       x="393.26562"
       xlink:href="#glyph0-8"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4458"
       y="384.48047"
       x="399.93945"
       xlink:href="#glyph0-6"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4460"
       y="384.48047"
       x="406.61328"
       xlink:href="#glyph0-5"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4462"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4464"
       y="384.48047"
       x="458.76953"
       xlink:href="#glyph0-9"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4466"
       y="384.48047"
       x="465.44336"
       xlink:href="#glyph0-5"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4468"
       y="384.48047"
       x="472.11719"
       xlink:href="#glyph0-5"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4470"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4472"
       y="384.48047"
       x="524.27344"
       xlink:href="#glyph0-9"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4474"
       y="384.48047"
       x="530.94727"
       xlink:href="#glyph0-6"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4476"
       y="384.48047"
       x="537.62109"
       xlink:href="#glyph0-5"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <path
     inkscape:connector-curvature="0"
     id="path4478"
     d="m 70.239062,313.46421 0,-282.992177"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4480"
     d="m 70.239062,313.46421 -7.199218,0"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4482"
     d="m 70.239062,278.08921 -7.199218,0"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4484"
     d="m 70.239062,242.71421 -7.199218,0"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4486"
     d="m 70.239062,207.34312 -7.199218,0"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4488"
     d="m 70.239062,171.96812 -7.199218,0"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4490"
     d="m 70.239062,136.59312 -7.199218,0"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4492"
     d="m 70.239062,101.21812 -7.199218,0"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4494"
     d="m 70.239062,65.843125 -7.199218,0"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <path
     inkscape:connector-curvature="0"
     id="path4496"
     d="m 70.239062,30.472033 -7.199218,0"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
  <g
     id="g4498"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4500"
       y="353.63281"
       x="41.761719"
       xlink:href="#glyph1-10"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4502"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4504"
       y="318.25781"
       x="41.761719"
       xlink:href="#glyph1-11"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4506"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4508"
       y="282.88281"
       x="41.761719"
       xlink:href="#glyph1-12"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4510"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4512"
       y="250.84766"
       x="41.761719"
       xlink:href="#glyph1-13"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4514"
       y="244.17383"
       x="41.761719"
       xlink:href="#glyph1-14"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4516"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4518"
       y="215.47266"
       x="41.761719"
       xlink:href="#glyph1-13"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4520"
       y="208.79883"
       x="41.761719"
       xlink:href="#glyph1-15"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4522"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4524"
       y="180.09766"
       x="41.761719"
       xlink:href="#glyph1-14"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4526"
       y="173.42383"
       x="41.761719"
       xlink:href="#glyph1-10"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4528"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4530"
       y="144.72266"
       x="41.761719"
       xlink:href="#glyph1-14"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4532"
       y="138.04883"
       x="41.761719"
       xlink:href="#glyph1-11"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4534"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4536"
       y="109.34766"
       x="41.761719"
       xlink:href="#glyph1-14"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4538"
       y="102.67383"
       x="41.761719"
       xlink:href="#glyph1-12"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <g
     id="g4540"
     style="fill:#5d4734;fill-opacity:1"
     transform="translate(11.2,-36.832655)">
    <use
       height="100%"
       width="100%"
       id="use4542"
       y="73.976562"
       x="41.761719"
       xlink:href="#glyph1-16"
       style="fill:#5d4734;fill-opacity:1" />
    <use
       height="100%"
       width="100%"
       id="use4544"
       y="67.302734"
       x="41.761719"
       xlink:href="#glyph1-14"
       style="fill:#5d4734;fill-opacity:1" />
  </g>
  <path
     inkscape:connector-curvature="0"
     id="path4546"
     d="m 70.239062,321.72593 486.722658,0 0,-299.519523 -486.722658,0 0,299.519523"
     style="fill:none;stroke:#5d4734;stroke-width:0.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-opacity:1" />
</svg>

# OS/8 FORTRAN IV

OS/8 `FORTRAN IV` is extensively documented:

* Chapter 8 of the [1974 OS/8 Handbook][os8h1974] (large file!).
* Section 2 of the [OS/8 Language Reference Manual AA-H609A-TA][os8lang].
* The [OS/8 Fortran IV Software Support Manual DEC-S8-LFSSA-A-D][os8f4suppt]

This file serves more as a quick guide to what has been gathered
to this repository as far as distribution DECtapes, and patches
are concerned.

The [1979 OS/8 Software Components Catalog][os8cat] provides an
inventory of and part numbers for the OS/8 V3D binary and source
distribution DECtapes. Images of these DECtapes are all found in
media/os8/subsys as follows:

| DEC Part    | Filename                        | Description       |   
| ----------- | ------------------------------- | ----------------- |
| AL-4549D-BA | al-4549d-ba-fr4-v3d-1.1978.tu56 | Binary DECtape #1 |
| AL-5596D-BA | al-5596d-ba-fr4-v3d-2.1978.tu56 | Binary DECtape #2 |
| AL-4545D-SA | al-4545d-sa-fr4-v3d-1.tu56      | Source DECtape #1 |
| AL-4546D-SA | al-4546d-sa-fr4-v3d-2.tu56      | Source DECtape #2 |
| AL-4547D-SA | al-4547d-sa-fr4-v3d-3.tu56      | Source DECtape #3 |

When with-os8-fortran-iv is enabled (which is the default), the
contents of Binary DECtape #1 are installed on the OS/8 RK05 images
built by `mkos8`.

Binary DECtape #2 contains the `.RA` sources for the components
of the FORTRAN IV library.  Those files are already assembled
and archived in `FORLIB.RL` and installed from Binary DECtape #1.

The three source DECtapes contain the buildable source code for the
rest of OS/8 FORTRAN IV system.  Build instructions are found in
Appendix B of the _OS/8 Fortran IV Software Support Manual_.

If with-os8-patches is configured, the `os8v3d-patched.rk05` image will contain the following patches:

* `F4 21.1.2 M` Fix for the `EQUIVALENCE` statement that brings
  `F4.SV` and `PASS3.SV` up to version 4B.
* `F4 51.3.1 M` Enable recognition of `"` as an incorrect character in
  a subroutine call argument that brings `F4.SV` up to version 4C.
* `F4 51.3.2 M` Enable recognition of syntax errors in type
  declarations.
* `FORLIB 51.10.1 M` Updates `FORLIB.RL` to contain an corrected
  `DLOG` function that will correctly handle numbers smaller than
  `1.1-018`.

There is one more patch available, `FRTS 51.3.3 O`, an optional patch
that enables the FORTRAN IV runtime system to accommodate 2 page
system handlers in addition to the TD8E handler.  This patch has not
yet been verified.

FORTRAN IV on the system packs should work.

The sources are available in the tree in the files named above.

Enjoy!

[os8h1974]: http://bitsavers.trailing-edge.com/pdf/dec/pdp8/os8/OS8_Handbook_Apr1974.pdf
[os8lang]: http://bitsavers.trailing-edge.com/pdf/dec/pdp8/os8/AA-H609A-TA_OS8_Language_Reference_Manual_Mar79.pdf
[os8f4suppt]: http://bitsavers.trailing-edge.com/pdf/dec/pdp8/os8/DEC-S8-LFSSA-A-D_F4swSupp.pdf
[os8cat]: https://ia601002.us.archive.org/8/items/bitsavers_decpdp8sofoftwareComponentsCatalogJul79_7798622/AV-0872E-TA_PDP-8_Software_Components_Catalog_Jul79.pdf

### <a id="license"></a>License

Copyright © 2017 by Bill Cattey. Licensed under the terms of
[the SIMH license][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md

# OS/8 `MACREL`

`MACREL`, the MAcro RELocating assembler, was a late development. It
was an attempt to replace `PAL8` with a Macro assembler capable of
producing relocatable modules.  When `MACREL` first came on the scene,
several companies decided to port their next major upgrade to `MACREL`
from `PAL8`.  `MACREL` was so buggy that everybody basically had to
revert to `PAL8` and back-port all the new code originally intended
for the new major upgrade.  This situation befell ETOS Version 5.

We have a binary distribution DECtape image of `MACREL` version 1, DEC
part number `AL-5642A-BA`. Unfortunately the version numbers of the
patches did not match what was shown in the binaries.

With the `MACREL` V1 patches, I wanted to do more research before
recommending application of the patches. In the course of that
research, I discovered that all the archived manuals to be found online
were for `MACREL` v2.

See: [Willem van der Mark's PDP-8 Manuals archive][vandermarkman] for:

* [OS/8 MACREL/LINK -- Software Support -- Version 2C -- September 1980 AA-J7073-TA][maclinkss]
* [OS/8 MACREL/LINK -- User Manual -- Version 2D -- January 1979 AA-5664B-TA][maclinkuser]

Or see the [PDP8 doc tree on ftp.dbit com][dbitdocs] for:

* [maclkssm.doc -- OS/8 MACREL/LINK V2 Software Support Manual][dbitmacssm]
* [maclnkum.doc -- OS/8 MACREL/LINK V2 User's Manual.][dbitmacuser]
* [macrelrn.doc -- OS/8 MACREL/LINK V2 Release Notes][dbitmacrel]

Version 2 was the clearly better baseline.  I didn't hold out much
hope to find binary and source distributions of `MACREL` v2.  (DEC
Part numbers `AL-5642B-BA` for the binary DECtape and the 4 source
DECtapes, `AL-5643B-SA`, `AL-5644B-SA`, `AL-H602B-SA`, and
`AL-H602B-SA`.)

Very recently we found a complete set of `MACREL` version 2 binaries
as part of a buildable RTS-8 Archive at [ibiblio.org ... pdp-8/rts8/v3/release][rts8rel]

We found a source distribution of `MACREL` v2 in Dave Gesswein's
[misc_floppy][dgfloppy] archive.  Part one is flagged as having
errors, but another obscure site had a mis-labeled archive of this
same stuff so we may be ok.

The `MACREL` v2 source would not build under `MACREL` v1, but now we
have `MACREL` v2 and initial tests look promising.

Baseline `MACREL` v2 will be integrated into the system packs.
Because we didn't have `MACREL` v2, no work was done to create patch
files, or to validate them.  With both source and binary for `MACREL`
v2 now in hand, this work can proceed.  The plan is to fetch the
patches, validate them, and install all mandatory patches that can be
verified. 

The current integration of `MACREL` v2 includes a hand-applied patch
to `FUTIL`.  We want the latest version of `FUTIL` because it contains
new code handles extended memory and certain `MACREL` data
structures. However version 8A of `FUTIL` shipped on the `MACREL` v2
tape had a bug that causes it to *hang* when run under `BATCH`.

Patch `35.13.1M` fixes this problem and upgrades `FUTIL` to version
8B.  This patch was applied by hand tested, and grouped with what we
integrate onto the system packs when we add `MACREL`.

To reduce uncertainty around the operation of `OVRDRV.MA`, Source
patch `41.5.1M` has been applied by hand to `OVRDRV.MA`.

See also: [our documentaiton on the OS/8 Patching][os8patches]

[vandermarkman]:   http://vandermark.ch/pdp8/index.php?n=PDP8.Manuals
[maclinkss]: 	   http://vandermark.ch/pdp8/uploads/PDP8/PDP8.Manuals/AA-J073A-TA.txt
[maclinkuser]:	   http://vandermark.ch/pdp8/uploads/PDP8/PDP8.Manuals/AA-5664B-TA.txt
[dbitdocs]:	   ftp://ftp.dbit.com/pub/pdp8/doc/
[dbitmacssm]:	   ftp://ftp.dbit.com/pub/pdp8/doc/maclkssm.doc
[dbitmacuser]:	   ftp://ftp.dbit.com/pub/pdp8/doc/maclnkum.doc
[dbitmacrel]:	   ftp://ftp.dbit.com/pub/pdp8/doc/macrelrn.doc
[rts8rel]:	   http://www.ibiblio.org/pub/academic/computer-science/history/pdp-8/rts8/v3/release 
[dgfloppy]:	   http://www.pdp8online.com/images/images/misc_floppy.shtml
[os8patches]:	   https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-patching.md

### <a id="license"></a>License

Copyright © 2017 by Bill Cattey. Licensed under the terms of
[the SIMH license][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md

# OS/8 System Patches

Between major updates to distribution media, DEC would send out
important information and patches to customers through its publication
_PDP-8 Digital Software News_ (_DSN_ for short).

Many issues of _DSN_ can be found on bitsavers.org under
[pdf/dec/pdp8/softwarenews][dsn].

To help customers keep track of which patches to apply, _DSN_ added a
Cumulative Index.

Using the _PDP-8 DIGITAL Software News Cumulative Index_ found in the
latest available issue of _DSN_, [October/November 1980][dsn8010], I
created a spreadsheet of all patches relevant to the OS/8 V3D packs
under construction.  That spreadsheet enabled me to go to the
particular issues containing the patches, and keep track of what
action I took with them.

I reviewed all the patches and came up with a list of the mandatory
patches.  Using OCR'd text from each relevant _DSN_ issue, I created a
file per patch, which I then compared to the scanned PDF and corrected
the OCR errors.

Then I enhanced our `mkos8` script to apply the patches in an
automated way.  Most of the patches were for programs available
in source form, so I built the programs from source, and then bench
checked the patch against the source.  In a few cases the code was too
obscure, and I marked the patch as "plausable" rather than "verified"
in my spreadsheet.

The file [patch_list.txt][pl] lists all of the patch files in
`media/os8/patches`.  Comments in that file begin with `#` and are
used to disable patches we have rejected for one reason or another.
Each rejected patch also has a comment that explains why that
particular patch was rejected from the default set.  Typical reasons
are:

*   The patch requires hardware our simulator doesn't have.
*   The patch conflicts with another patch we deem more important.
*   The patch changes some behavior, and we prefer that the unpatched
    behavior be the default.

You may want to examine this file to see if there are any decisions you
would reverse.  After modifying that file, say "`make`" to rebuild the
OS/8 binary RK05 disk image file with your choice of patches.

You can disable all of these OS/8 patches by giving the
`--disable-os8-patches` option to the `configure` script.

[dsn]:     http://bitsavers.org/pdf/dec/pdp8/softwarenews/
[dsn8010]: http://bitsavers.org/pdf/dec/pdp8/softwarenews/198010_PDP8swNews_AA-K629A-BA.pdf
[pl]:      https://tangentsoft.com/pidp8i/doc/trunk/media/os8/patches/patch_list.txt


## Review of Recommendations

`BRTS 31.11.2O` is an optional patch which disables 8th bit parity. It
is recommended because sometimes we may want to allow output that
does not force the 8th bit.

`BRTS 31.11.3O` is an optional patch that enables 132 column
output. It is recommended because it is expected that wide column
output is desirable.

`TECO 31.20.1O` is an optional patch that permanently forces no case
flagging.  It is not recommended because we want to allow the option
of case flagging.

`TECO 31.20.2O` is an optional patch that turns off verbose
errors. It was for slow terminals and experienced users who didn't
want to wait to see the long error messages they already knew.  It is
not recommended because we expect a majority of users to be on high
speed terminals needing the verbose errors.

`TECO 31.20.3O` turns off a warning that you are using the `YANK`
command to completely overwrite a buffer full of text.  Issuing the
command a second time succeeds.  It was again to avoid experienced
users.  It is not recommended because we expect fewer advanced users
who would be annoyed by the protection.

`TECO 31.20.4O` implements rubout support specifically and uniquely
for the `VT05` terminal in a way that breaks it for all other video
terminals.  It is not recommended because there are VERY few `VT05`
deployments that would use it.

It is at this point that I began to notice that in later years, patches
became less carefully produced, and more prone to errors. Some are not
correctable, even today.

`BASIC.UF-31.5.1M` shows:

    4044/4514 4556

changing location `4044` from `4514` to `4556`.  Such a change would be
consistent with the stated purpose of the patch, to correct references
to page zero literals that moved with the `V3D` version of `BRTS`.
The source around location '4044' looks like this:

    04043  4775          JMS I   (BUFCDF /SET UP USER BUF
    04044  1273          TAD     NSAM
    04045  7041          CIA
    04046  3276          DCA     NCTR    /-#OF BOARDS TO CLAR

In my judgment the `TAD NSAM` to get the subscript into the `AC`
should be retained, and the `4556` call to `UNSFIX` to truncate the
value of the Floating Point Accumulator should NOT be inserted.  I
modified the patch to leave out that change.  It remains to be seen if
calls to User Functions in OS/8 `BASIC` will ever be run to test this
code.  Here at least is an analysis to later explorers.

`EDIT 21.17.4 M` is supposedly a mandatory patch.  It fixes a problem
with line printer output through a specific parall interface card.
Unfortunately, the patch overwrites mandatory patch in 21.17.2 and is
NOT recommended.

`ABSLDR 21.29.1 M` is supposedly a mandatory patch that enables
`ABSLDR` to work with `SAVE` image files.  Normally `ABSLDR` only
loads `BIN` format files. The patch sequence number, `21.29`
identifies the patch as being for the OS/8 V3D version of `ABSLDR`.
But the patch changes locations that are not used by `ABSLDR.SV`.
Furthermore, the patch says it upgrades `ABSLDR` from version 6B to
version 6C.

Version 6 of `ABSLDR` was part of the OS/8 V3D Device Extensions kit.
See [our documention on the OS/8 V3D Device Extensions][os8ext].
Verification of this now seems within reach, with the expectation that
it is mis-labeled, and is properly applied to the version with the
Extensions kit. Until it is verified, applying this patch is *not*
recommended.

`PAL8-21.22.4M` is broken and doubly mis-labeled. Mis-label #1: It is
an optional, not mandatory patch. Mis-label #2: It is for product
sequence `35.14`, the `V13` codeline of `PAL-8` that, like `ABSLDR
V6`, is in the Device Extensions kit.  The breakage: Source listing
quits working.  *Do not apply this patch!*

Patch `FRTS-51.3.3-O.patch8` is to enable 2-page system drivers like
`RL01`.  Except that the `RL01` driver is only available in the
Extensions kit.  The patch overwrites existing code that makes `FRTS`
able to function with the `TD8E` 2-page system handler.  I've read the
code but don't fully understand it. Perhaps it generalizes the `TD8E`
support.  But if you happen to be using this setup under `TD8E` and
`FRTS` doesn't work, then back out this patch.


## Patch Application Order

The `patch` routine in `mkos8` applies the patches in the order they
appear in `patch_list.txt`.  That list is currently in alphabetical
order.  However, there may in future emerge patches that impose an
order.

For example, if the `ABSLDR` patch actually did work, it needs the
`FUTIL 31.21.2 M` in order to patch into the `ABSLDR` overlay bits.

I was skeptical of `FUTIL 31.21.2M` because, when I
load `ABSLDR.SV` into core with GET, the contents of memory showed by
`ODT` are *DIFFERENT* from those shown by `FUTIL`. With deeper
understanding of the OS/8 Device Extensions kit, I see that the patch
was incorporated into the version 8 `FUTIL` source, and also that
`ODT` is expected to be updated in version 3S of the Keyboard Monitor.

## Then There's `MACREL`

I've gone into detail on the explorations and understandings with
regard to `MACREL` in a [sister document to this one][macreldoc].

Originally I reviewed the patches for `MACREL` v1, because that's all
we had.  But the version numbers of the patches did not match the
version numbers of the executables.  A little diversion into the guess
work surrounding patch verification:

Version number mismatches sometimes do occur with patches. For
example, `TECO 31.20.11 M` says that it upgrades `TECO` to version
`5.06`, but got the bits wrong.  Instead of changing contents from
`0771` to `0772`, it looked to change from `0772` to `0773`.  `772`
octal is `506` decimal, and the `TECO` version number is represented
with a 12 bit number.  It's called "5.06" but it's represented as
`0772` octal, or `506` decimal.

With that TECO patch, I simply changed the version amendment line in
that `TECO` patch, because the rest was correct.  Whoever published
the patch got the version number wrong, and nobody complained.

With no `MACREL` v1 source verification was not really possible, so
applying those patches was postponed.  But then we found both binary
and source of `MACREL` v2!

In the interests of shipping out system packs in finite time, we will
integrate `MACREL` v2 into the system packs, and verify/apply `MACREL`
v2 patches as follow-on work.

After further testing of 'MACREL' I have concluded that integrating
the source-level patch `41.5.1M` will reduce uncertainty.  So I have
hand-integrated that patch into the `MACREL` tu56 image as well.

[macreldoc]:https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-macrel.md

## `FUTIL`:

I was dubious of some of the `FUTIL` patches, but with finding source
to version 8A, I gained confidence in the version 7 patches, and
understood how seriously important the first patch was to version 8.

The `MACREL` v2 tape shipped with version 8A of `FUTIL`. That was
necessary because V2 of `MACREL` supported the latest memory expansion,
and so the OS/8 Core Control Block needed to change.

Unfortunately, the `FUTIL.SV` distributed as version 8A had the wrong
starting address and Job Status Word settings. It *hangs* when run
under `BATCH`.  Our automated pack builder and patcher `mkos8` run
`FUTIL` under `BATCH`.

The `MACREL` v2 DECtape image we use with `mkos8` contains a
hand-applied patch `35.13.1M` that fixes this problem.

Currently if you opt in to having `MACREL` on the system packs, you
get `FUTIL` version 8B. If not, you get `FUTIL` version 7 and `mkos8`
applies the relevant patches. If `FUTIL` version 8 is installed, the
automated patch applier recognizes the version 7 patches don't fit and
fails to install them.

## One-off Patches

Most of the patches are parsed and applied in an automated manner
by mkos8.  However some are one-offs.

See the `FUTIL` section above with regards to patch `35.13.1M`.

`FORLIB 51.10.1 M` is a one line source change to `DLOG.RA`. The patch
file provides that line. It also provides instructions on how to use
`RALF` to assemble the source and on how to to use `LIBRA` to replace
the old version of `DLOG` with the new one in `FORLIB.RL`.  I followed
the instructions to hand-tool a patched `FORLIB.RL` which I then put
in the `local.tu56` DECtape image along with the other local hacks.
The `patch` routine `mkos8` has in-line code to replace `FORLIB.RL` on
`SYS:` if installation of FORTRAN IV is enabled.


## Unfinished Business

There remain the following patches that are still under development,
because they are not simple binary overlays on executables that could
be applied with simple scripts driving `ODT` or `FUTIL`.  Instead they
are either batch scripts, or are applied to source code that is
rebuilt either with an assembler or high level language compiler.

`LQP 21.49.1 M` patches a device driver `.BN` file, then using `BUILD`
to insert it into the system.  At the present time the OS/8 V3D packs
we build do not use the `LPQ` driver.  (We ran out of device ID space
and so we don't have anywhere to put an active `LPQ` driver.)


## The Tracking Spreadsheet

Below is the latest snapshot of the tracking spreadsheet.

Status column key:

| **A** | Patch Applies Successfully                                   |
| **V** | Patch Source Verified                                        |
| **K** | Patch Source Probably OK. Weaker confidence than "Verified". |
| **P** | Patch Source Plausible. Weaker confidence than "OK".         |
| **N** | Not recommended                                              |
| **O** | OCR Cleaned up. No other verification or application done.   |
| **D** | Does not apply.                                              |
| **B** | Bad patch. DO NOT APPLY.                                     |


### OS/8 V3D Patches

| Component | Issue | Sequence | Mon/Yr | Notes | Status |
| ------ | ------ | ------ | ------ | ------ | ------ |
|  `HANDLER` | `CTRL/Z` and `NULL` | `01 O *` | Oct-77 | Optional. Not going to apply. |  |
|  `CREF` | Bug with `FIXTAB` | `21.15.1M` | Apr/May-78 | `CREF-21.15.1-v2B.patch8` Corrects bad patch | AV |
|   | Input and output file specifications | `21.15.2M` | Feb/Mar-80 | `CREF-21.15.2-v2C.patch8` | AK |
|  `EDIT` | `EDIT` Problem with no `FORMFEED` at end of the input file | `21.17.1M` | Mar-78 | `EDIT-21.17.1M-v12B.patch8` | AV |
|   | `EDIT` `Q` command after `L` command | `21.17.2M` | Jun/Jul-79 | `EDIT-21.17.2M-v12C.patch8` | AV |
|   | `EDIT` `Q` command patch | `21.17.3M` | Jun/Jul-79 | `EDIT-21.17.3M-v12D.patch8` | AV |
|   | `EDIT.SV` `V` option will not work with `LPT DKC8-AA` | `21.17.4M` | Feb/Mar-80 | `EDIT-21.17.4M-v12C.patch8` Overwrites patch `21.12.2M` | AVB |
|  `FOTP` | Incorrect directory validation | `21.19.1M` | Jun/Jul-79 | `FOTP-21.19.1M-v9B.patch8` (Corrected from Aug/Sep 1978, Detailed in Apr/May 79) | AV |
|  `MCPIP` | `DATE-78` Patch for `MCPIP` | `21.21.1M` | Mar-78 | `MCPIP-21.21.1M-v6B.patch8` | AV |
|  `PAL8` | Incorrect core size routine | `21.22.1M` | Aug/Sep-78 | `PAL8-21.22.1M-v10B.patch8` | AV |
|   | Erroneous `LINK` generation noted on `PAGE` directive | `21.22.2M` | Aug/Sep-78 | `PAL8-21.22.2M-v10C.patch8` | AV |
|   | `EXPUNGE` patch to `PAL8` | `21.22.3M` | Feb/Mar-80 | `PAL8-21.22.3M-v10D.patch8` | AK |
|   | `TAB`s are translated incorrectly | `21.22.4M` | Oct/Nov-80 | `PAL8-21.22.4M` (Supercedes June/July 1980 (which had wrong contents of memory.)) Bad! Wrong version of `PAL8`! Breaks list output. | AB |
|  `PIP` | `PIP` `/Y` option does not work properly when transferring a system | `21.23-1M` | Aug/Sep-78 | `PIP-21.23.1M-V12B.patch8` | AK |
|  `PIP10` | `DATE-78` Patch to `PIP 10` | `21.24.1M` | Jun/Jul-79 | `PIP10-21.24.1M-V3B.patch8` (Corrected from Dec 78/Jan 79) | AV |
|  `SET` | Using `SET` with two-page system handlers | `21.26.1M` | Apr/May-78 | `SET-21.26.1M-v1C.patch8` | AV |
|   | `SCOPE` `RUBOUT`s fail in `SET` | `21.26.2M` | Apr/May-78 | `SET-21.26.2M-v1D.patch8` | AV |
|   | Parsing of `=` in `TTY WIDTH` option | `21.26.3M` | Aug/Sep-78 | `SET-21.26.3M-v1E.patch8` | AV |
|  `LPQ` | `LDP01` Handler fails to recognize `TAB`s | `21.49.1M` | Dec/Jan-80 | `LQP-21.49.1M-vB.patch8` (supercedes Mar 1978) | O |
|  `TM8E` | Write protect patch to `TM8E.PA` | `21.61.1H` | Feb/Mar-80 | New `TM8E` Source.  Too hard to correct. |  |


### OS/8 Extension Kit V3D Patches

| Component | Issue | Sequence | Mon/Yr | Notes | Status |
| ------ | ------ | ------ | ------ | ------ | ------ |
|  `SABR` | Line buffer problem in `SABR` | `21.91.1M` | Oct/Nov-79 | `SABR-21.91.1M-v18B.patch8` | AV |
|  `BASIC.UF` | `BASIC.UF` Incompatible from OS/8 V3C | `31.5.1M` | Aug/Sep-78 | `BASIC.UF-31.5.1M-V5B.patch8` Source also in _DSN_. | AV |
|  `BLOAD` | `BLOAD` Will not build `CCB` properly | `31.10.1M` | Feb/Mar-80 | `BLOAD-31.10.1M-v5B.patch8` | AV |
|  `BRTS` | `IOTABLE` Overflow | `31.11.1M` | Mar-78 | `BRTS-31.11.1-M-v5b.patch8` | AV |
|   | `BASIC` `PNT` Function | `31.11.2O` | Jun/Jul-78 | `BRTS-31.11.2-O.patch8` (superceds/corrects Mar 1978) | AV |
|   | Line size on output of `BASIC` | `31.11.3O` | Jun/Jul-78 | `BRTS-31.11.3-O.patch8` | AV |
|   | Change line printer width | `31.11.4F` | Oct/Nov-79 | Optional change of width to 132 columns |  |
|   | Patch to `BRTS` for addressing `LAB 8/E` functions | `31.11.5M` | Oct/Nov-79 | `BRTS-31.11.5-x.patch8` (`BASIC.UF` patch is a prerequisite.) | AV |
|  `TECO` | Changing the default `EU` value for no `case` flagging | `31.20.1O` | Mar-78 | `TECO-31.20.01O.patch8` | AVN |
|   | Changing the default `EH` value for one line error printouts | `31.20.2O` | Mar-78 | `TECO-31.20.02O.patch8` | AVN |
|   | Removing `YANK` protection | `31.20.3O` | Mar-78 | `TECO-31.20.03O.patch8` | AVN |
|   | `SCOPE` Support for `VT05` users | `31.20.4O` | Mar-78 | `TECO-31.20.04O.patch8` | AP N |
|   | Problem with `AY` command | `31.20.5M` | Mar-78 | `TECO-31.20.05M-v5A.patch8` | AV |
|   | Conditionals inside iterations | `31.20.6M` | Mar-78 | `TECO-31.20.06M-v5B.patch8` | AV |
|   | Echoing of warning bells | `31.20.7M` | Mar-78 | `TECO-31.20.07M-v5B.patch8` | AV |
|   | `CTRL/U` Sometimes fails after `*` | `31.20.8M` | Apr/May-78 | `TECO-31.20.08M-v5.04.patch8` | AK |
|   | Multiplying by `0` in `TECO` | `31.20.10M` | Apr/May-78 | `TECO-31.20.10M-v5.05.patch8` | AV |
|   | `Q` registers don't work in 8K | `31.20.11M` | Apr/May-78 | `TECO-31.20.11M-v5.06.patch8` | AV |
|   | Can't skip over `W` | `31.20.12M` | Apr/May-78 | `TECO-31.20.12M-v5.07.patch8` | AV |
|   | Unspecified iterations after inserts | `31.20.13M` | Oct/Nov-78 | `TECO-31.20.13M-v5.08.patch8` (Corrected from Jun/Jul 78) | AV |
|   | New features in `TECO V5` | `31.20.14` N | Aug/Sep-78 | Documentation Only |  |
|  `FUTIL` | `FUTIL` Patch | `31.21.1M` | Apr/May-78 | `FUTIL-31.21.1M-v7B.patch8` | AV |
|   | Fix `SHOW CCB` and mapping of `CD` modules | `31.21.2M` | Oct/Nov-78 | `FUTIL-31.21.2M-v7D.patch8` (Corrected from Aug/Sep 78) | AV |
|   | Optional: change `XS` format from `excess-240` to `excess-237`. Useful for viewing `COS` data files. | `31.21.3O` | Aug/Sep-78 | `FUTIL-31.21.3O.patch8` | AVN |
|   | `FUTIL` Patch to `MACREL`/`LINK` overlays | `31.21.4 N` | Jun/Jul-79 | Documentation Only |  |
|  `MSBAT` | `DIM` Statement not working in `MSBAT` | `31.22.1M` | Dec 78/Jan-79 | `MSBAT-31.22.1M-v3B.patch8` | AV |
|  `BATCH` | `MANUAL INTERVENTION REQUIRED` Erroneously | `31.23.1M` | Aug/Sep-78 | `BATCH-31.23.1M-v7B.patch8` | AV |


### OS/8 FORTRAN IV V3D Patches

| Component | Issue | Sequence | Mon/Yr | Notes | Status |
| ------ | ------ | ------ | ------ | ------ | ------ |
|  `F4` | `EQUIVALENCE` Statement | `02M` / `21.1.2M` | Dec/Jan-80 | `F4-21.1.2M-v4B.patch8` (Revised, Oct 77: `F4` and `PASS3` not `FRTS` patched.) | AP |
|   | `FORTRAN` Compiler fails to recognize `"` as an error | `51.3.1M` | Jun/Jul-78 | `F4-51.3.1M-v4C.patch8` (Corrects March 1978) | AP |
|   | `FORTRAN` Compiler not recognizing syntax error | `51.3.2M` | Jun/Jul-78 | `F4-51.3.2M-v4x.patch8` | AP |
|   | `FORTRAN` runtime system 2-page handler | `51.3.3O` | Oct/Nov-78 | `FRTS-51.3.3-O.patch8` Needed for RL02. (Corrected from Aug/Sep 78) | A |
|   | Restriction with subscripted variables | `51.3.4R` | Aug/Sep-80 | Documentation: `FIV` `FORTRAN IV` will not allow subscripting to be used on both sides of an arithmetic expression. |  |
|  `FORLIB` | `FORTRAN IV` `DLOG` Patch | `51.10.1M` | Feb/Mar-80 | `FORLIB-51.10.1M.patch8` (apply to `DLOG.RA`) | AV |


### OS/8 MACREL/LINKER V1A Patches

These patches are listed for completeness. The version numbers don't
match.  We lack source so we cannot verify them. we've moved on to
`MACREL` v2 as canon.  

| Component | Issue | Sequence | Mon/Yr | Notes | Status |
| ------ | ------ | ------ | ------ | ------ | ------ |
|  `LINK` | Patch `V1D` to `LINK` | `40.2.1M` | Apr/May-78 | `LINK-40.2.1M-v1D.patch8` | O |
|   | Patch `VIE` to `LINK` | `40.2.2M` | Apr/May-78 | `LINK-40.2.2M-v1E.patch8` | O |
|   | `LINK` Corrections | `40.2.3M` | Apr/May-78 | `LINK-40.2.3M-v1F.patch8` | O |
|  `MACREL` | Patch `V1D` to `MACREL` | `40.5.1M` | Apr/May-78 | `MACREL-40.5.1M-v1D.patch8` | OD |
|   | Patch `V1E` to `MACREL` | `40.5.2M` | Apr/May-78 | `MACREL-40.5.2M-v1E.patch8` | OD |
|  `OVRDRV` | Patch `V1B` to `OVRDRV.MA` | `40.6.1M` | Apr/May-78 | `OVRDRV-40.6.1M-v1B-8srccom` | O |


### OS/8 V3D Device Extensions December 1978 Patches

**WARNING**: Do not use this kit without first consulting _DSN_  Apr/May 1979.
See also: [Our OS/8 Device Extensions documentation][os8ext]

| Component | Issue | Sequence | Mon/Yr | Notes | Status |
| ------ | ------ | ------ | ------ | ------ | ------ |
|  `FRTS` | `FRTS` Patch | `35.1.3M` | Apr/May-79 |  |  |
|  `MONITOR` | `MONITOR` `V3S` Patch | `35.2.1M` | Apr/May-79 |  |  |
|  `FUTIL` | `FUTIL` hangs under `BATCH` | `35.13.1M` CRITICAL! | Apr/May-79 |  | AV |
|  `PAL8` | `EXPUNGE` Patch to `PAL8` | `35.14.1M` | Feb/Mar-80 | `PAL8-35.14.1M-v13B.patch8` | AN |
|  `ABSLDR` | Loader problem with `SAVE` image files | `21.29.1M` | Oct/Nov-80 | `ABSLDR-21.29.1M-v6C.patch8` (Supercedes June/July 1980) Bad: v6B was with OS/8 Device Extensions. | OB |
|  `ABSLDR` | `ABSLDR` Patch | `35.18.1M` | Apr/May-79 |  |  |
|  `BLOAD` | `BLOAD` Will not build `CCB` properly | `35.51.1M` | Feb/Mar-80 | `BLOAD-35.51.1M-v5C.patch8` | ON |


### OS/8 MACREL/LINKER V2A Patches

These patches have not been turned into files.  Armed with newly
discovered sources verification is possible.  Work on these will begin
soon.

| Component | Issue | Sequence | Mon/Yr | Notes | Status |
| ------ | ------ | ------ | ------ | ------ | ------ |
|  User's |`EXPUNGE` Documentation error | `41.1.1N` | Jun/Jul-79 |  |  |
|  Guide  | `MACREL` Version numbers: `MACREL` is `V2C` not `V2D`; `LINK` is `V2A` not `V2B`. | `41.1.2N` | Jun/Jul-79 |  |  |
|   | Macro restriction in `MACREL` | `41.1.3N` | Aug/Sep-79 |  |  |
|   | Error in `.MCALL` macro example | `41.1.4N` | Feb/Mar-80 |  |  |
|  `KREF` | Correct printing of numeric local symbols | `41.3.1M` | Apr/May-80 |  |  |
|  `MACREL` | `EXPUNGE` Patch to `MACREL` | `41.4.1F` | Jun/Jul-79 |  |  |
|   | Inconsistencies in `MACREL` error reporting | `41.4.2N` | Aug/Sep-79 |  |  |
|   | Forward reference patch to `MACREL` | `41.4.3M` | Aug/Sep-79 |  |  |
|   | Correct macro substring problem | `41.4.4M` | Apr/May-80 |  |  |
|   | Correct printing of numeric local symbols | `41.4.5M` | Apr/May-80 |  |  |
|  `OVRDRV` | Correct `CDF` problem | `41.5.1M` | Dec/Jan-80 | Source change applied by hand. | AV |
|  `FUTIL` | `FUTIL` hangs under `BATCH` | `35.13.1M` | Apr/May-79 | Critical to proper operation of our automated builder. Applied by hand to the `MACREL` v2 integration.  | AV |



### <a id="license"></a>License

Copyright © 2017 by Bill Cattey. Licensed under the terms of
[the SIMH license][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md
[os8ext]: https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-v3d-device-extenaions.md

# OS/8 V3D Device Extensions

The _OS/8 V3D Device Extensions_ kit (product code `QF026`) was released
in December 1978. It was created to support the newest PDP-8 hardware:

*   The `KT8A` Memory Management option which enables addressing by a
    factor of four beyond the previous maximum of 32K to a whopping
    128K of memory. The highest memory field for a PDP-8a goes up from
    7 to 37 (octal).

*   The `RL01` disk supporting 4 times the previous usual disk capacity,
    now up to nearly 5 Meg.

*   The `RX02` double-density floppy disks.

* Device drivers `VXSY` and `VXNS` enables use of `KT8A` extended
    memory as a file oriented system or non-system device.

This distribution contains software updates:

*   A version of `BUILD`, the system builder that could run under
    `BATCH`.  The previous version would just hang.

*   An update to the OS/8 system including `Keybord Monitor` version
    3S, and a version of `ODT` that works with memory fields greater
    than 7.

*   `ABSLDR` version 6A supports loading into memory fields greater
    than 7.

*   `PAL8` version 13A allows code to specify memory fields greater
    than 7.

*   `CCL` version 7A updates the 'MEMORY' command to recognize up
    to 128K words of memory.

*   `PIP` version 14A knows the sizes of the new devices, and has
    updated how it copies in the monitor system head.

*   `RESORC` version 5A includes new devices.

*   `BOOT` version 5A boots new devices.

*   `RXCOPY` version 4B formats and copies single and double density
    floppies.

*   `FUTIL` version 8A recognizes new core control block format that
    can represent extended above field 7.

The _OS/8 V3D Device Extensions User's Guide_ can be found
in [Willem van der Mark's PDP-8 doc archive][vdmdoc], under
[OS/8 - Device Extensions - User's Guide - December 1978 AA-D319A-TA.pdf][vdmextensions].
or on the [ftp.dbit.com pdp8 doc archive][dbitdoc] at [devextug.doc --
OS/8 Device Extensions User's Guide][dbitug]

The release notes can be found on ftp.dbit.com at [devextrn.doc	OS/8
Device Extensions Release Notes ][dbitrn].

Details on how the `KT8A` Memory Extension hardware works, physically
and programatically, can also be found at Willem van der Mark's site:
[vandermark.ch ... Emulator.128KMemory/EK-KT08A-UG_jul78-ocr.pdf][kt8adoc].

When reference is made to `PAL8` version 13, that version originally came
from this kit.

The distribution DECtape for this kit, part number `AL-H525A-BA` has
not yet been found.  The PDP-8 Software Components Catalog July 1979
gives no part number for a Source DECtape distribution of this kit.
There is an RK05 source distribution, part number
`AN-H529A-SA`. However, plausable source and binary have recently been
found!

The binaries were on someone's local hard disk and not published to
the net anywhere I could find.  Sadly those binaries did not include
the DECtape's system area, and so the updated version of the OS/8
Keyboard Monitor, Command Decoder and `ODT` seemed lost until a tape
could be found. It appears that the original source of these .en files
is Johnny Billingquist's site, [ftp.update.uu.se ... dectape1][uuseext1].

Then, however, a self-extracting archive called, `os8v3f.exe` was
found on a mirror site of ibiblio.org, [rtk.mirrors.pdp-11.ru
... fromhichols][rtknicnols]. Mainline ibiblio.org didn't have it, perhaps it was
purged because of its `.exe` extension.  The archive is also available
directly from [ftp.update.uu.se ... fromnichols][uusenichols], but at slow speed.

When that archive was extracted, the manifest of source files
corresponds exactly to the manifest of binaries in the Extensions Kit
file archive are present.  This looks quite promising for a future
project to upgrade to OS/8 V3D with the Device Extensions software,
and to create system packs useful even on PDP-8a hardware with 128K
words of memory!

After comparing sources found for OS/78, and OS/278, as well as Willem
van der Mark's locally modified sources labeled OS/8 version 4, I have
moderate confidence that these sources will enable validation and
integration of most, if not all the OS/8 V3D Device Extensions
functionality.

[rtknichols]: http://rtk.mirrors.pdp-11.ru/ftp.update.uu.se/pdp8/pdp-8/fromnichols/
[uuseext1]: ftp://ftp.update.uu.se/pub/pdp8/pdp-8/os8/os8.v3d/binaries/devext/dectapes/dectape1/
[uusenichols]: ftp://ftp.update.uu.se/pub/pdp8/pdp-8/fromnichols/

## FUTIL

This validation has been done with regards to `FUTIL`.

The `MACREL` v2 tape shipped with version 8A of `FUTIL`. That was
necessary because V2 of `MACREL` supported the latest memory
expansion, and so the OS/8 Core Control Block format needed to change.

`FUTIL` version 8A integrated patches for `FUTIL` version 7 into the
source.  Finding those patches in the version 8A source strongly
increased my confidence in those patches.

Unfortunately the `FUTIL.SV` verson 8A executable was saved
incorrectly and then shipped. The Core Control Block setting and
starting address were mis-specified. So `FUTIL` version 8A *hangs*
when run under `BATCH`.

The [April-May 1979][dsn1979apr] issue of _PDP-8 Digital Software
News_ contained patch `35.13.1M` which fixed this problem and upgraded
`FUTIL` to version 8B.  I've confirmed both the problem and the fix.

Currently if you opt in to having `MACREL` on the system packs, you
get `MACREL` v2 and `FUTIL` version 8B. If leave `MACREL` out, you get
`FUTIL` version 7. The automated pack builder recognizes that the
version 7 patches won't apply to version 8, and fails to apply them.
The research I did on the OS/8 Device Extensions kit and on
`MACREL` increased my confidence about the `FUTIL` version 7 patches.

See also [our documentation on the `MACREL` integration][macreldoc]
and [our documentation on applying OS/8 patches][patchdoc].

### <a id="license"></a>License

Copyright © 2017 by Bill Cattey. Licensed under the terms of
[the SIMH license][sl].

[vdmdoc]: http://vandermark.ch/pdp8/index.php?n=PDP8.Manuals
[vdmextensions]: http://vandermark.ch/pdp8/uploads/PDP8/PDP8.Manuals/AA-D319A-TA.pdf
[dbitdoc]: ftp://ftp.dbit.com/pub/pdp8/doc/
[dbitug]: ftp://ftp.dbit.com/pub/pdp8/doc/devextug.doc
[dbitrn]: ftp://ftp.dbit.com/pub/pdp8/doc/devextrn.doc
[kt8adoc]: http://www.vandermark.ch/pdp8/uploads/Emulator/Emulator.128KMemory/EK-KT08A-UG_jul78-ocr.pdf
[dsn1979apr]: http://bitsavers.org/pdf/dec/pdp8/softwarenews/198010_PDP8swNews_AA-K629A-BA.pdf
[macreldoc]:https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-macrel.md
[macreldoc]:https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-patching.md
[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md