-----------------------------------------------------------------------------
	SOLO - Generation Startup Info
-----------------------------------------------------------------------------

This document has the general information you should need to get started
with using SOLO, including system requirements, and source and binary
installation and uninstallation instructions.

Certainly it could use a lot more detail and more examples, and in the
future I will be expanding it.  In the meantime, feel free to email
me with questions about any part that is unclear.  (but try to look 
at the other documentation and some of the shell scripts first, or
experiment a little bit to see if you can figure it out yourself...
then still email me to let me know it's unclear so I can update it, but
let me know when I don't need to respond with a full answer)


-----------------------------------------------------------------------------
System Requirements:

	For binary release:
		libg++.so.27
		libstdc++.so.27
		libm.so.5
		libc.so.5

		NOTE:  I *have* made a binary release, and tested it,
		which is why this documentation was written, but I'm
		afraid I can't release it without legal problems 
		with GNU, because it would be linked with their libraries.
		If anyone knows a way around this, please let me know.
		Or, if anyone can point me to information that clearly
		states that shared libraries (as opposed to static)
		are free from their licensing, let me know that too.
		Otherwise, I'm going to have to either release a binary
		form that still needs linking to the libraries, or
		include lots of extra GNU license stuff with the binary
		release, and people using the binary release will 
		have to follow their restrictions, which is something
		I was trying to avoid.


	For source release:
		Linux (or some fairly compatible OS)
		gcc 2.7.2 (may work with some older ones... but I know
			for sure that it won't build with gcc 2.7.0
			due to an internal compiler error.  gcc 2.7.0 is
			full of other bugs and should be upgraded anyways...)
		gmake
		as86/ld86

	To run SOLO:
		At least 32K of RAM.
	To run SOLO and load 32-bit protected mode binaries:
		At least 32K + total memory usage of binary program.

	(in other words, small enough to be embedded, and it should
	run on any PC with a 32-bit processor (386 and up))


	If you try SOLO on any system that is configured differently
	from the requirements listed above, please mail me to let me
	know whether or not it works, (and if it doesn't work, why)
	so that I can fix minor problems, and make a more accurate
	list of what configurations it will run under.

-----------------------------------------------------------------------------
General Information about this document:

	-  $SRC means the root of the source tree... so wherever you see
		it, substitute it with the relative path from where you are
		to the root of the source tree
			i.e.:  if you're in '/u2/me/sos/build',
			and your source area is '/u2/me/sos/solo-0.96'
			and one of the instructions says to run '$SRC/config',
			then run '../solo-0.96/config'

	-  $BASE means the root of the build area, or the root of
		the binary distribution (which is created from a build area),
		so wherever you see it, substitute it with the relative
		path from where you are to the root of the source tree
-----------------------------------------------------------------------------
Source Installation:

	-  Make a build area.  Basically, create a directory somewhere
		that has lots of space (10Mb to be safe, but 5 should do).
		You might want to name this directory 'build' or 'solo',
		or the name of your target machine.  You probably want
		to put this build area in a place that is outside
		of the source tree, to avoid conflicts and to keep
		everything separate.  This makes it very easy to delete
		the entire build area when you want to without touching
		the source area.

	-  Go to your build area, and run 'config' from the source area
		to set up your new build area.  (See the note about $SRC
		in "General Information" above)

		Config takes two arguments, the name of the target machine,
		and the machine description type.  You can also run
			$SRC/config -l
		for a list of machine types.  For building SOLO, the
		type doesn't need to be very exact (as long as it's a PC),
		so don't worry about the fact that no Pentiums are listed
		yet.

		Then configure it with a command like the following:
			
			$SRC/config snail pc-i386sx

	-  Now set up the rest of the build area with:
			make setup
		During this process, some directories (such as io, cparse,
		object, and a bunch of .C, .h, and Make files) will show
		up as missing.  Don't worry about it.  The configuration
		is trying to set up things needed by the full Shag/OS
		distribution, and these parts aren't included with SOLO
		because you don't need them.

	-  Now go to the boot area, 
			cd sys/boot
		And prepare all the binaries needed for booting:
			make bootprep

	        Note: if all of the default configuration in sys/boot/Make
		is already set up the way you need to build a floppy disk,
		you could just skip the last several steps and just
		type 'make sys/boot/bootdisk' to do the whole process
		after 'make setup'

	-  Now, to build a boot disk, follow the instructions for
		"binary installation" below, using your build area

-----------------------------------------------------------------------------
Binary Installation:

	VERY IMPORTANT NOTE:
		Before doing any of this, back up all important information
		on your hard drive, and make sure you have the necessary
		resources to re-install your system if something gets 
		messed up.   Although this software has been tested on
		some machines, lots of system variations exist, and there
		is always the chance for bugs, or for a misinterpretation
		of the instructions to really cause a lot of damage, since
		this program will change your boot records.  Make sure
		you know what you are doing, and play it safe.  The author
		is not responsible for any damages, so do this at your
		own risk (see the 'NO WARRANTY' info in the 'readme'
		file in the '/doc' directory) 

		The SOLO install process *does* save a copy of the bootsector
		before it writes to it, to allow for booting from the original
		bootsector, and for uninstalling, but there's always a chance
		that this could fail.  If it does, please notify me so I can
		fix it--- but make sure you saved your own copy first.


	-  Important Recommendation:
		It is very strongly recommended that you first make
		a bootable floppy disk, and verify that it works.
		Then, before even considering making SOLO boot from the
		hard disk, make sure you have a way to boot 
		your standard operating system (Linux, etc) from
		a floppy disk.  There are instructions below on putting
		Linux on a disk with SOLO, and loading it from there.
		You might want to try this and make sure that you can
		boot Linux from this disk before you risk making your
		hard disk temporarily unbootable (if something goes wrong)
		If this works, then try putting SOLO on a partition 
		that you can boot from first, just to test it out.
		If this works for you, and you want it for your main
		boot loader, then go ahead and add it to the master
		boot record of your hard drive.	 

	-  To make a bootable floppy disk:

		It is first recommended that you add an entry to your
		'/etc/fstab' file that has a special mount point 
		(probably type 'noauto') for the floppy disk, along 
		with a filesystem type for it.   If you will be using
		different filesystems on floppies frequently, you can
		add multiple entries with different mount point names.

		I have entries that look like this on my system: 

			/dev/fd0	/a	msdos	user,noauto
			/dev/fd0	/fd0	minix	user,noauto

		Now, go into the boot part of the build area:
			cd $BASE/sys/boot
	
		Make sure you have floppy in the drive which is formatted
		for the filesystem you intend to use, and then
		run the 'mkboot' script to create a bootable floppy.
		It takes the name of the mount point, followed by the
		name of the raw device.  (mkboot <dir> <device>)
		For instance, using my '/etc/fstab' example from above,
		if I wanted to put SOLO on an MSDOS-formatted floppy
		in the first floppy drive, I would type:

			./mkboot /a /dev/fd0

		Of course, you can also specify to mount a disk at
		any arbitrary mount point, for instance with:
			./mkboot /mnt /dev/fd0
		
		Since the entry isn't in '/etc/fstab', 'mount' won't be
		able to figure out the filesystem type automatically, so
		'mkboot' will try to mount it as 'msdos', 'minix', and 'ext2'
		If your filesystem is none of those, then you will have
		to customize 'mkboot' or add an entry to '/etc/fstab'
		
	
		If this works correctly, 'mkboot' will put all of the
		files needed for SOLO on the disk, using the 'solo.cnf'
		file in the current directory to configure it.  Any files
		listed in 'solo.cnf' which cannot be found will be
		commented out in the 'solo.cnf' file on the destination disk.


	-  To create a bootable partition, or a bootable hard drive:
		
		Assuming you want the 'solo' software installed in
		'/sys', to put SOLO on the master boot record, type:

			./mkboot / /dev/hda

		To put it on a partition, type:

			./mkboot / /dev/hda2
		(replace /dev/hda2 with the partition you want to use)

		(If you want to put it somewhere other than '/sys',
		you will have to modify all references to '/sys' that
		are in 'solo.cnf' and 'solo.cmd' first.)

		After installing, modify the new 'solo.cnf' file
		(probably in /sys/solo.cnf'), and add a line near
		the top (above 'bootblock=')  that says 
			boot=/dev/hda2
		(replace /dev/hda2 with the device you installed the 
		bootblock on...)

		Without this line, if you run 'mksolo' by itself in the
		future, it will find the device by just looking for the
		device that the '/sys' directory is on, which might mean
		that it will update your master boot record when you
		only meant to put it on a partition.  So, to be safe,
		put an explicit line in that says what device you
		want the bootblock on.	

 
	-  To uninstall from a floppy:

		Remember the options you gave to 'mkboot' to install
		it, and run it again with the '-u' option.  For instance,
		if you installed SOLO with:

			./mkboot /a /dev/fd0

		Uninstall with:

			./mkboot -u /a /dev/fd0

		Note:  This will only work if the 'solo.cnf' file contains
		a 'saveboot=' line which has not been changed between the
		install and the uninstall.  This line specified a file
		to which the original bootsector is saved.  

	-  To uninstall from a hard-drive:
		
		This is the same as uninstalling from a floppy (see the
		instructions above)  Just specify the parameters you used
		to install on the harddrive.
	
	
-----------------------------------------------------------------------------
Creating your own standalone programs or operating systems:

	See the document 'doc/solo/solo.txt'


-----------------------------------------------------------------------------
Running SOLO:

	-  Boot the floppy (or hard drive, partition, etc...)

	-  If 'solo.cmd' was specified as a mapped image file in 'solo.cnf',
		then the commands in it will be run first, probably 
		presenting you with a customized menu.  From there, you
		should be able to run a variety of commands, or exit
		to the shell.

	-  If 'solo.cmd' is missing, you'll end up directly in the shell.
		From here, you can type 'help' for a list 
		of commands, and you can type help followed by a command
		name (or a topic, or disk error code) to get information
		about it.  Most of the documentation for SOLO is 
		currently in the help file (which can be read directly,
		without running SOLO, by reading 'solo.hlp'
		This file can also be edited to add new customized help
		to SOLO.  Just make sure 'mksolo' or 'mkboot' is run
		again after customizing the file.

	-  You can type the name of any file to try to run it directly,
		but for now only script files (such as 'solo.cmd') and
		32-bit executables (in ELF or a.out format) can be 
		run, and they will be loaded at whatever virtual address
		their header says to load them at.

		To test a few of them, you can try running
		'sys/solotest', 'sys/fdisk', or 'sys/hello'

	-  To boot Linux from SOLO:

		First see "Running SOLO" below...

		Make sure that a line of the form 
			image=vmlinuz
		exists in your 'solo.cnf' file, and that the path
		refers to the correct location for your kernel.
		Then run 'mksolo' (or 'mkboot', which runs 'mksolo')
		as you would for a normal installation to map out the
		kernel file.

		Now from SOLO, use the 'lboot' command as follows:

			lboot vmlinuz

		You can follow this command with any kernel 
		parameters to pass,

			lboot vmlinuz hd=1046,16,63
		
		or with commands prefixed with '@'
		to modify root parameters.  See the file 'solo.cmd'
		for an example of the lboot command that does this.

	-  To boot DOS (or other operating systems) from SOLO:

		First see "Running SOLO" below...

	 	If DOS, or another operating system, already existed on
		the drive/partition/floppy where you have installed SOLO,
		the bootsector, by default, will be saved to a file called
		'dos' (this can be changed in the 'saveboot=' line in 
		'solo.cnf'. Just make sure you supply an 'image=' line
		to correspond with the new name, or you will save it,
		but it won't show up to SOLO).
		You can run this old bootsector from SOLO by typing:
			boot dos
		(instead of 'dos', use whatever name you have changed the
		 'saveboot=' line to)

		To put from operating systems that are still installed
		directly on any partition, hard disk, or floppy,
		just type:
			boot /dev/hd0a
		(substitute '/dev/hd0a'	with the device name where
		the bootsector is located.   See the file 'notes' for
		details about device names)

		Note that you can boot any partition from either 
		hard drive using this technique.  Therefore, 
		even if your master boot record gets messed up on
		your hard disk, you can still boot your system 
		directly from a partition by first booting SOLO,
		and using it to boot from a specified partition.

	-  Changing video modes and testing modes
		The 'vmode' command by itself tells you what mode you 
		are currently using, and the resolution.  'vmode' followed
		by a two-digit hexadecimal mode number will switch to that
		mode.

		You can get a list of all available (BIOS supported) video
		modes by typing 'vtest'.  

		This test will probably take a few seconds, during which time
		your monitor will probably do all kinds of strange things,
		as your video board outputs all the possible video modes
		it supports, in rapid succession.
		IF THIS WORRIES YOU, THEN DON'T RUN IT, but for the couple
		seconds that it runs, it probably shouldn't cause any
		permanent damage, so just run it once, and then write down
		all the mode numbers that it prints, so you don't have 
		to run it again.  DO THIS AT YOUR OWN RISK.

		'vtest' will scan all possible video modes, and list all
		the valid ones, along with their resolutions, and an
		'm' for monochrome modes, and a 'g' for graphics modes.
		Graphics modes will probably not work with most software
		which you boot from SOLO, unless it is specifically 
		designed to handle arbitrary graphics modes.  (Most
		software assumes that you are initially in a text mode)
		However, SOLO itself, and any programs that just use
		the SOLO console interface, will use any mode that the
		BIOS supports. 

		Note that not all video modes supported by your Video BIOS
		and video board will work with your monitor, unless you
		have a multisync monitor with a wide range of supported
		horizontal and vertical frequencies.
	
-----------------------------------------------------------------------------
Debugging in SOLO:
	
	(See 'solo.hlp' in the boot directory for more commands,
		and more details on the commands)

	File specifications in SOLO can be either an actual full
	filename (such as 'sys/solotest'), or a device (such as '/dev/fd0').
	Optionally, the file name can be followed by an '@' symbol
	and an offset, and/or a comma, and a size.
	For instance, 
		/dev/mem@200
	specifies the memory at offset 0x200, and
		/dev/hd0,100
	specifies the first 0x100 bytes of hard drive 0.  Together, such as
		/dev/mem@7c00,200
	both an offset and a size are specified.  
	If an offset is given with no name first, then the default
	is '/dev/mem'.  Also, if no size is specified, the default is
	the default block size for the device, or the full length
	of a file.  Thus, the command
		dump @40
	displays the absolute offset, relative offset, and single byte
	value at address 40.

	- the 'reg' command dumps the current values of all registers

	- the 'dump' command (abbreviated 'd') will dump, in hex/ascii
		format, all specified parts of a file.   The display
		has the absolute and relative offsets on each
		line, followed by up to sixteen hex digits, and sixteen
		printable characters.
		Example:  dump sys/shagboot.bin

	- the 'write' command (abbreviated 'w') will write to the
		specified file/device, using all hexadecimal bytes
		that follow. 
		Example:  write @b8000 41 42 43 44

	- the 'dmsg' command will show the current contents of the
		circular message buffer.  Use 'msg on' or 'msg off'
		to turn on or off the message capture.

-----------------------------------------------------------------------------
Using 'mksolo':

	'mkboot' is just a shell script provided for convenience.
	It is not really necessary, and for setting up boot areas
	on the hard disk, should not really be used except for the
	initial setup, to avoid messing up customized configurations.
	(since it will write over all the boot files)
	'mksolo' should be used directly after that, and any new
	files should probably be copied by hand.
	(after a new release or build, you usually just
	need 'solo.bin', and 'shagboot.bin', along with any 32-bit
	programs you are planning on running)

	After using 'mkboot' to set up a boot area,
	you can use use 'mksolo' directly to the mapfile and
	boot sector by first making sure the boot disk you are
	updating is mounted, and then typing:
		mksolo -d -r /a

	Where '/a' should be replaced by the directory where the boot
	area is mounted.   If you're updating an area on your hard disk,
	such as '/sys', then the '-r' option can be omitted.
	The '-d' option can also be omitted, since it just tells 'mksolo'	
	to output debugging information.  (only errors will be printed
	if this is omitted)

	Important note:  if you are using 'mksolo' to update your hard
	disk, make sure that you have added a 'boot=/dev/xxx' line to your
	'solo.cnf' file, because otherwise it will default to your 
	root partition, which may not be where you want it to be. 
	You can specifically override this with the '-b' flag,
	such as:
		mksolo -d -b /dev/hda4

	See the 'mksolo(8)' manpage for more details.
	Formatted copies can be found in 'mksolo.8.txt' and 'mksolo.8.ps'.

-----------------------------------------------------------------------------
Errors and such:

	-  I've found that the 'mksolo' binary (if you haven't built it 
		yourself) actually fails on some systems because of
		strange library problems.   Specifically, on a machine
		with libc.so.5.0.9, it caused a segmentation fault
		(although the fault occurred in part of "cout")
		Upgrading to libc.so.5.2.16 fixed this problem,
		and hopefully newer libs should also be good.



