This package contains tools and diskette images for working with the
NorthStar disk system. It has two primary purposes:

1)  To provide a bootstrap platform so that the disk images can be
    configured on the PC and transferred to a target system wishing
    to run NorthStar software.

2)  Provide a simulation so that people without a NorthStar compatible
    system can experience what it is like to use this machine.

Files included in this archive are:

    README.TXT      <-  This file.
    HORIZON.COM     <-  Simulator for NorthStar Horizon, including
                        console I/O and both Single and Double density
                        diskette controllers. Allows you to mount and
                        boot NorthStar disks as images contained in PC
                        files, and provides facilities for importing and
                        exporting drivers etc. directly to/from memory.
    HORIZON.HLP     <-  Help file for simulator.
    USECOM1.CMD     <-  Command-option file to put AUX serial on COM1
    SERIAL.CMD      <-  Command-option file to put console in COM1
    SAMPLEIO.TXT    <-  Sample simulator I/O definitions
    NSI.COM         <-  NorthStar Image utility - provides access to
                        individual files within a NorthStar Image (NSI)
                        disk image.
    NST.COM         <-  NorthStar Transfer utility - to assist in moving
                        disk images to and from the physical N* system.
    NST.ASM         <-  Client stub used by NST - this may be modified
                        for other I/O systems.
    VIO.ASM         <-  Sample non-standard I/O drivers
    NSTXD.ASM       <-  NST client stub with double-density DOS
    NSTXS.ASM       <-  NST client stub with single-density DOS
    ASM.TXT         <-  Documentation for assemblers
    DIS80.TXT       <-  Documentation for disassembler
    ASM80.EXE       <-  8080 cross assembler
    ASMZ80.EXE      <-  Z80  cross assembler
    DIS80.EXE       <-  8080 cross disassembler
    MACRO.EXE       <-  Macro pre-processor (needed for HDM80)
    HDM80.MAC       <-  Source file to bootstrap monitor
    ZPBJMP.COM      <-  Utility to help set ZPB cpu jumpers
    NSTAR.TXT       <-  Quick reference to NorthStar DOS 5.x
    NSDOS50D.NSI    <-  Basic DoubleDensity N*DOS boot disk image
    NSDOS51S.NSI    <-  Basic SingleDensity N*DOS boot disk image   (*1)
    CPM.COM         <-  Utility to import files into CP/M via the simulator
    SIMHFIX.COM     <-  Repair utility for SIMH .NSO files          (*2)
    APN0014.TXT     <-  Notes on running my tools under Windows

*1: To boot a single-density disk, you *MUST* run the simulator with the
    single-density contoller (/S) option.

*2: The SIMH project has added a NorthStar Horizon simulation, however it
    creates and expects incorrect .NSI image files. Run SIMHFIX with no
    options for more details.

*3: Some disks (NorthStar CP/M for example) attempt to output a character
    to the AUX serial port when they boot. If you have an I/O configuration
    which prevents this from occuring (eg: file I/O where "output file
    mounted" is indicated by TX-ready), the simulator will appear to "hang"
    (in this case until you mount an output file). The default simulator I/O
    configuration indicates "output file mounted" via the DSR bit in the
    virtual uart - TX-ready is always 1, meaning you can always write to
    the port, even if no file is mounted (in which case the output is lost).

---------------------------- THE SIMULATOR -----------------------------
The simulator has little documentation, however there is adaquate online
help and on-screen prompts. Here are some sample sessions showing how to
use the simulator:

Boot Double-Density DOS:
------------------------
1- Run the simulator> HORIZON
2- Press F7 to mount a disk, and pick "Drive 1 - RO"
3- Select the image file: NSDOS50D   (N*DOS 5.0 Double)
4- Press 'G' - disk will boot and you will see DOS prompt
5- Use N*DOS as you wish.
6- Press F3 to halt the simulator, then F10 to exit

NOTE: NSDOS50D *requires* upper-case input at the console, use the
      PC "caps lock" key.

Boot Single-Density DOS:
------------------------
1- Run the simulator with Single-Density controller> HORIZON /S
2- Press F7 to mount a disk, and pick "Drive 1 - RO"
3- Select the image file: NSDOS51S   (N*DOS 5.1 Single)
4- Press 'G' - disk will boot and you will see DOS prompt
5- Use N*DOS as you wish.
6- Press F3 to halt the simulator, then F10 to exit

- You may mount additional disk images on other drives by selecting
  the desired drive under the F7 (mount) prompt.
- Press F1 for online help.

------------------------ EXAMPLE CONFIG SESSION -------------------------
I have included my VECTOR 1+ in the HORIZON simulation - this machine has
a NorthStar controller, but non-standard console I/O functions. The
standard Horizon boot disks will NOT work on this machine until they have
been customized for it's I/O requirements.

I have already written the needed I/O function in the file VIO.ASM

Here are the steps to create a boot disk using my modified I/O:

1)  Read the comments in VIO.ASM and make sure you understand exactly
    how the I/O drivers work.

2)  Assemble the VIO file: ASMZ80 VIO   -> This produces VIO.HEX

3)  Copy the appropriate boot disk (NSDOS50D or NSDOS51S to a working copy)

3)  Run the Vector simulator: HORIZON /V  [/S if single-density needed]

4)  Mount the working copy of the boot disk on "Drive 1 - R/W".

5)  Press F5 and set a breakpoint at 2013 - this is the call to TINIT
    within the operating system, which is called before any other of
    the I/O functions.

6)  Press 'G' the simulator will boot DOS into memory and then halt
    at the breakpoint.

7)  Press 'L', and then select VIO.HEX from the list - VIO.HEX will
    be loaded into memory, automatically patching the freshly booted
    DOS image.

8)  Press 'G', you should see the DOS prompt - you are now running a
    patched DOS in memory with the new I/O functions.

9)  Execute the command: LF DOS 5000    -> This loads a static copy
    of DOS into unused memory.

10) Execute the NorthStar monitor with one of these commands:
        GO M2D00            <- for Double Density system
        GO M2A00            <- for Single Density system
    You should see the monitor prompt.

11) Execute the command: MM 200D-2018 500D
    This copies the patched jump table into the static copy

12) Execute one of these commands:
        MM 2900-29FF 5800       <- For Double Density DOS
        MM 2900-29FF 5900       <- For Single Density DOS
    This copies the I/O functions into the static copy of DOS.

13) Exit back to the DOS prompt> OS

14) Execute the command: SF DOS 5000
    This saves the updated DOS image back to the working copy of the
    boot disk.

15) When the disk access is complete, press F3 to halt the simulator,
    and remove the breakpoint (F5 - 'EA00'). Then press 'R' to reset
    the CPU, and 'G' to execute - the new disk should boot!

You can use this procedure to test and configure the I/O for virtually
any I/O device - use the simulators P= command line option to create a
virtual I/O device which will work with the desired drivers.

Once you have the boot disk working under the simulator, you can use the
NST utility to transfer it into your target system.

--------------------------- THE NST UTILITY ----------------------------
NST is a NorthStar Transfer utility, which is used to transfer NorthStar
DOS 10-sector disk images to and from a PC via the serial port.

NST can also bootstrap software into a NorthStar DOS system by "typing"
it in via the NorthStar monitor program.

NST does NOT currently handle mixed density disks - the disk must be
either all single-density or all double-density. If you have data to
backup from mixed density disks, you will have to copy it to a uniform
density disk first.

NST requires a small resident "stub" program which runs on the North-
Star system, and performs disk reads and writes under control of the
PC - this stub is provided in the source file NST.ASM, and may require
customization to your system:

  You must supply host I/O functions to perform raw 8-bit serial
  data transfer with your console I/O hardware - please refer to
  the "Host I/O functions" section at the end of this file.

  NST permits comms parameters which are NOT 8-bit, however this
  is only for use with the UB and UH functions (if required) - all
  disk image transfer function (RS, RD, WS, WD) *REQUIRE* 8-bit
  serial I/O.

  As delivered, the NST resident stub occupies memory from 2D00-2DFF and
  places a 32k disk I/O buffer at 3000 - this is compatible with all
  versions of NorthStar DOS, which have free memory at:
     old single-density: $2A00 and higher
     old double-density: $2D00 and higher
     new relocatable   : $1000 and higher

  If you do not have enough memory in your NorthStar system for the 32k
  disk I/O buffer, you can use the NST B=<sectors> option to force NST
  to use a smaller buffer.

Once you have NST.ASM configured, you can assemble it with my Z80 cross
assembler (included) and upload it to the system:
  ..> ASMZ80 NST            <= Assemble NST.ASM
  ..> NST UH NST [c=n]      <= Connect to NorthStar System
  + GO Mxxxx                <= Execute NorthStar monitor
  Monitor x.x
  > DS 2D00                 <= Begin entering data (See NST.ASM: CODE equ)
  2D00 xx-                  <= Press F1 to send file

When the upload stops, press ENTER to return to the monitor prompt,
then:
  > JP 2D00                 <= See NST.ASM: CODE equ

The stub is now active, press F10 to exit the upload terminal
function - you may now use NST to read and write disk images.

If you prefer, you can save the NST stub to disk, instead of
'JP' above, use:
   > OS                     <= Return to NS DOS prompt
   + CR NST 2               <= Create NST file
   + TY NST 1 2D00          <= Set executable & address (see NST.ASM: CODE equ)
   + SF NST 2D00            <= Save downloaded image to disk
  Now you can execute the stub with:
   + GO NST
You can EXIT from the stub back to DOS by typing: $Q (quickly)


The syntax of the PC NST command is: NST <command> [options]

<command> can be any one of:

   RS <filename>[.NSI]      - Read  SingleDensity disk into image file
   RD <filename>[.NSI]      - Read  DoubleDensity disk into image file
   WS <filename>[.NSI]      - Write SingleDensity disk from image file
   WD <filename>[.NSI]      - Write DoubleDensity disk from image file
   UB <filename>[.BIN]      - Upload binary format file to memory    *
   UH <filename>[.HEX]      - Upload Intel/Motorola HEX format file  *
       * UB and UH provide a simple terminal function, use this to get
         the monitor into input mode at the right address,  then press
         F1 to start the transfer.

<options> are:

   B=<sectors>
     Sets the size of the disk tranfer buffer (in sectors) - this is
     most useful to insure a transfer buffer of less than 32k. If not
     specified, NST will choose an "optimal" transfer size which is
     the most integral tracks which can fit in 32k.

   C=<com>[:<databits><stopbits><parity><speed>]
     <com>      = COM port (1-4)
     <databits> = 5,6,7,8
     <stopbits> = 1,2
     <parity>   = N,O,E,M,S (None/Odd/Even/Mark/Space)
     <speed>    = 50-57600 bps
     Default is: Com1, 8-data, 1-stop, No-parity, 9600-bps : C=1:81N9600

   D=1-4
     Sets the NorthStar system drive number to use (only 1-3 are valid
     on a single density system).

   F=xx
     If the input file does not contain enough data to fill all of the
     tracks requested, NST will fill the remainder of the disk sectors
     with this value. The default value is 20 (hex) which is the value
     in freshly initialized NorthStar DOS sectors (CP/M uses a "fill"
     value of E5).

   R=n
     Sets the number of times that NST will retry an operation which
     fails. Default is three retries.

   T=1-80
     Sets the number of tracks that NST will try to transfer.
     Default when writing an image is the number of tracks in the image.
     Default when reading is 35 for SingleDensity systems/DoubleDensity
     systems which report a single-sided drive, and 70 for DoubleDensity
     systems which report a double-sided drive.

   U=[012]<delim>prompt<delim>enter
     Controls the interaction between NST and the monitor memory
     modification command, which is used for UB and UH functions.

      '012' controls characters outstanding in serial data stream:
        2   = Fastest : 2 outstanding characters (one in RX, one in transit)
        1   = Moderate: 1 outstanding character
        0   = Slowest : Each character must be echoed before next is sent.

     <delim> is any delimiter character which is not contained in 'prompt'.

     prompt = String that monitor prompts with for next input character.

     enter  = String that must be entered after two byte value is "typed".

     The following special characters may be used in the 'prompt' and
     'enter' strings:
        ~R  = Carriage return   (0D hex)
        ~L  = Line-Feed         (0A hex)
        ~S  = Space             (20 hex)
        ~~  = '~' character     (7E hex)
        ~xx = Hex value 'xx'    (xx hex)

    The default value which works with the NorthStar monitor (Mxxxx)
    is: U=2'='~S
    which means:
    - 2 outstanding serial characters are allowed.
    - The monitor sends '=' when ready for another byte.
    - A space character is sent after "typing" the byte value.

    Another example, for the DDS "TEST" debugger: U=2"-"~R
    - This example demonstrates using different delimiter characters.
    - 2 outstanding serial characters are allowed
    - The monitor sends '-' (only) when ready for another byte.
    - A carriage-return is sent after "typing" the byte value.


   W=n
     Sets the number of milliseconds which represent one second.
     This is normally 1000, which translates to one "real" second, however
     newer version of "windows" have broken comms drivers for the DOS
     box, and you may need to increase this number to get longer timeouts.


   /Y   = Auto-answer 'Y' to warning prompts.

Complete example:

Assumptions:
  + NST.ASM has already been modified and assembled to NST.HEX
  + NST.HEX loads at 2D00 - change addresses as required if otherwise.
  + COM1 @ 9600 - Add appropriate C= option to NST commands if otherwise.
  + NorthStar DOS at 0100 and monitor M1000 - Change Monitor name for other
    versions/memory addresses.

   ...> NST UH NST
   + GO M1000
   Monitor x.x
   > DS 2D00
   2D00 xx=<Press F1>
   .... Several lines ....
   .... of monitor output .... <Press ENTER when it stops>
   >JP 2D00
   <Press F10 to return to PC command prompt>
   >NST RD MYDISK             <= Read disk into image file MYDISK.NSI
   .... Several lines of output ....
   >NST WD MYDISK             <= Write disk from image file MYDISK.NSI

*** NOTE *** If you are running NST under windows, especially later
versions (2000, XP), then please refer to the file APN0014.TXT which
is included in this package for information regarding issues with
running my tools under windows.

------------------------ BOOTSTRAPPING THE TARGET ----------------------
One disadvantage of NST is that it needs NorthStar DOS to run - this is
because I wanted to keep it compatible with both disk controllers, and
not overly complicate it -- But.. if you need N*DOS to run it, then you
can't load N*DOS unto your system until you have N*DOS running on your
system (and then you wouldn't need it would you)....

The good news is that there is a way around this - you can save an "in
memory" copy of N*DOS, then load it in via a serial port etc. and start
it running - just as if it had booted from disk.

I have provided NSTXS.ASM (single-density) and NSTXD.ASM (double-density)
files which contain a N*DOS image, as well as the NST client stub. See
the comments in these files for details on how to use them.
See section '4' below for hints on how to get the code into the system.
Once loaded, execute at 2900 to launch the NST client.

If required, you can also use the simulator to create a downloadable copy of
N*DOS. It has to be an in-memory copy of DOS, that is because the system does
move some things around so that what is running in memory is NOT exactly the
same as the content of the DOS file on the boot disk.

1)  Configure the simulator to match your I/O, and build a working boot
    disk as described above.

2)  Boot the disk on the simulator, and then press F3 to stop the
    simulation.

3)  Press 'W' - this will prompt for a memory range, enter:
        2000-2CFF           <- Double Density System
        2000-29FF           <- Single Density system
    When prompted for a file, enter DOS.HEX (If you are given a
    list of .HEX files, press F2 for manual entry first).

4)  The next step depends on your system. If you have a ROM monitor
    capable of loading Intel HEX files, you can simply download DOS.HEX
    via the monitor.

4a) If you have a ROM monitor with memory edit capability, you can
    use NST UH to upload DOS by "typing" the code into the memory
    editor.

4b) If you have only a front-panel, then you will need to write and "toggle
    in" a small loader to read the code from a serial port.

4c) If you have a NorthStar Horizon, or any other system which has neither
    a ROM monitor or a Front panel,  you will need to add a ROM monitor.
    I've provided HDM80.MAC which is a tiny ROM monitor that needs no RAM
    - see the comments in HDM80.MAC for more information
    - once you have the monitor running, see '4a'

5)  Once you have DOS loaded, make your computer execute at 2028.
    If everything was done correctly, you should see the DOS prompt appear
    on the console terminal (This will be just the prompt, NOT the entire
    startup message).

6)  Once you have DOS running, you can then load the NST stub and activate
    it - now you can run NST and transfer disk images to and from your
    system (I would suggest transferring your boot disk first!).

7)  If you wish, you can download DOS and NST all at once - assuming
    that you have NST.ASM modified for your system and assembled to
    run at 2D00
    - After pressing F3 in step-2 above, press 'L' and select NST.HEX
      this will load the NST stub into memory just above DOS at 2D00
    - Press 'W' and select the memory range 2000-2EFF (Single or
      Double Density)
    - After executing at 2028 and getting the DOS prompt, type: JP 2D00
      to activate the NST stub.

------------------------------------------------------------------------
Dave dunfield - Feb 2005 / last updated Apr 2010


Dunfield Development Services (DDS) offers software and firmware
development services specializing in systems and embedded applications.
For more information, visit: http://www.dunfield.com
