		Warren's Version of Xinu for the Apple ][
		-----------------------------------------

	Here is my rewrite of Xinu for the Apple ][. The Xinu I used came
out of a hardcover book with a tan cover and a picture of a rug with the
words `Xinu' on it -- I suspect the newer versions of Xinu have changed a bit.

	You should have received:

		- three 140K Apple ][ floppy disk images
		- this Readme
		- some Gifs of docs I have here

There is essentially no documentation other than the source code, the Gifs
and this Readme. I have some other handwritten stuff which is covered by the
source, but I could probably photocopy/scan it and send it to you if you
thought it might help.


Section 1: Disk images
----------------------

	Here is the list of main files on each disk image. The first two
are DOS 3.3 disks, and the last is a ProDOS disk. I used to use the ProDOS
FILER to move the .OBJ files from the DOS 3.3 disks to the last disk.


Xinu_1.dsk - Xinu OS assembly code

*B 002 LISA V2.5 		\
*B 050 ASM.CODE.1		 |	Lisa Assembler
*B 016 ASM.CODE.2		 |
*B 003 SORT			/
*B 008 WILLIAM TELL			plays William Tell on spkr
*B 014 KERNEL.CONFIG			Xinu kernel configuration
*B 006 SYSTEM.CONFIG 			Machine-dependent things
*B 006 SYSPTR.SRC			System call jump table
*B 016 CHAPTER3.SRC		\
*B 019 CHAPTER4.SRC		 |
*B 032 CHAPTER5.SRC 		 |
*B 020 CHAPTER6.SRC		 |
*B 011 CHAPTER7.SRC 		 |	Xinu source, per-chapter
*B 011 CHAPTER8.SRC		 |
*B 017 CHAPTER10.SRC		 |
*B 014 CHAPTER12.SRC 		 |
*B 012 CHAPTER13.SRC		 |
*B 023 CHAPTER15.SRC 		/
*B 003 TIME.SRC
*B 092 XINU.SRC1		\	Xinu src collected from above
*B 060 XINU.SRC2 		/
*T 003 KA 		Create XINU.SRC1 and XINU.SRC2 from components and
			assembles


Xinu_2.dsk - Xinu OS extensions: file system, mini-assembler, shell

*B 009 DDD2				ProDOS disk I/O routines
*B 014 FILE.CONFIG 			File system configuration
*B 020 FILE1.SRC		\
*B 022 FILE2.SRC 		 |	The file system code
*B 024 FILE3.SRC		 |
*B 004 FILE4.SRC 		/
*B 005 SUP.CONFIG			FS Support configuration
*B 024 SUP1.SRC 		\
*B 021 SUP2.SRC			 |	FS Support routines
*B 020 SUP3.SRC 		 |
*B 018 SUP4.SRC			/
*B 015 KERNEL.CONFIG 			As per last disk
*B 006 SYSTEM.CONFIG			As per last disk
*B 030 CONFIG.SRC 			Whole system configuration (see below)
*B 018 MINASM2.SRC 		\	Mini-Assembler and monitor extensions
*B 034 MONEXT.SRC 		/
*B 012 SHELL1.SRC 		\
*B 021 SHELL2.SRC		 |	Simple shell for Xinu
*B 025 SHELL3.SRC		/
*T 002 FA		Create FILE.SRC from components and assembles
*T 002 SA		Create SUP.SRC from components and assembles
*T 002 CA		Create CONFIG.SRC from components and assembles
*T 014 ZPG USE 		Diagram showing zero-page usage


Xinu_3.dsk - Disk with Xinu image

XINU		SYS	34		The Xinu OS image
XMAKER		BAS	03		Loads .OBJ files and creates OS image
WILLIAM.TELL	BIN	05	\
frogr		REL	03	 |	Misc. programs used to test that Xinu
frogb		BIN	03	 |	loads and runs programs, and multi-
jim		REL	01	 |	tasks as well.
GB		BIN	09	/


Section 2: Assembling the bits
------------------------------

	The assembler I used is Lisa 2.5, which is on disk 1. On the two
source disks there are text files which you can EXEC to create the output
.OBJ files. Once this is done, move the files over to the last disk, run
XMAKER and load all the files, then save the Xinu image to disk.

	The image parts are:

		XINU.OBJ		The XINU-specific stuff
		DDD2			ProDOS disk I/O routines
		FILE.OBJ		File system routines
		SUP.OBJ			FS support routines
		SHELL.OBJ		The shell
		BOOT2.OBJ		Xinu bootstrap code

The source for the last file, BOOT2.OBJ, is chapter13.src, from memory.

	To run Xinu, boot the 3rd disk, go to the BASIC prompt and type

		]-XINU

This didn't work on APL2EM here. I know I had to patch both the PRODOS
and BASIC.SYSTEM image to get them to work on the Apple clone I have.
Try using the real Apple ][ ones. If the thing still crashes, see below.
You'll need an upper/lowercase keyboard too!

	On the second source disk you'll also find some code for the
old Apple Mini-Assembler, and some other extensions to the monitor, such
as a program relocator. I'm not sure how I got these into the language card,
or how they were included into the Xinu image. However, they are not
essential for Xinu to work, but are handy things to have around.


Section 3: Warnings, Gotchas
----------------------------

	You need a 24Hz (I think) clock tick coming in on the IRQ line
so that Xinu can (try to) keep time and do multitasking. I never drew
a schematic for this -- consult the 6502 hardware docs to see how long
a pulse for IRQ should be, and if it should drop to 0V or raise to 1V.

	The biggest gotcha is that the code was written for an Apple
clone with a 16K bankswitchable RAM at $4000 (from memory). I used this
memory to store OS stuff like zero-pages/stack-pages when switching between
processes. You will have to rewrite a bit of the code to store this somewhere
else, and remove the bankswitching operations. I have scanned in some info
about the bankswitching in the clone -- it should give you an idea when you
find me STA'ing something into a weird I/O location.


Section 4: Scanned GIFs
-----------------------

	Most of the docs I have are either printouts of the source, which
you can produce, or a small quantity of handwritten notes, plus the docs
about the hardware of the Apple clone from its technical handbook. I've
scanned these in at 300dpi, and a quick description of each image is given
below:

Xinu1.gif	- A overview of the memory layout of Xinu. Note in particular
		  the two bankswitched areas - 4K in the language card and the
		  16K bankswitched area which is peculiar to the Apple clone I
		  have. With this setup, there is 47.5K of memory for user
		  processes. A more detailed view of the memory map is given in
		  the next two Gifs.

Xinu2.gif	- The top 16K memory map (i.e the language card). The main part
		  of Xinu is on the right, with each of the main Xinu chapters
		  from $D000 upwards. Above that is the shell, the support
		  routines, the Mini-Assembler and the monitor modifications,
		  and the monitor itself. In the 4K bankswitched part is the
		  disk I/O routines stolen from ProDOS, and the File System
		  code.

Xinu3.gif	- In the 16K bankswitched memory at $4000 Xinu stores its
		  system information; this is the `System Memory'. We have
		  the keyboard buffer, other buffers (unused?), the list of
		  processes, some system variables, the process names, the
		  queue of ready or waiting processes, a map of available
		  memory, and most importantly, the copies of the zero-page
		  and the stack for each process. We swap in/out a process'
		  zero-page/stack during every context switch.

Xinu4.gif	- Dates of when I started each Xinu Chapter. I basically wrote
		  most of the code in a year I had off from Uni after my 3rd
		  year and before Honours.

Xinu5.gif	- Summary of the commands for the Lisa Assembler, which is on
		  disk image 1. I have the full docs, about 40 pages if you
		  want.

Xinu6.gif	- A basic overview of the `bank' mapping of memory in the
		  Apple clone I have. My machine only had the standard 48K
		  (banks 0-2), plus 16K in bank 3 which was normally not
		  used, except for the System Memory in Xinu.

Xinu7.gif	- Here's how to select which physical bank of memory goes
		  into which logical bank. You write a number ($00 to $0F)
		  into locations $C07C, $C07D, $C07E or $C07F. I guess I
		  was normally writing either $01 or $03 into location $C07D,
		  to put either the `user memory' or the `System Memory' at
		  addresses $4000 -- $7FFF.
