readme.txt  (c) Copyright Mike Noel, 2001-2023 	  10/11/2023


PREFACE

This software is an emulator for the Alpha-Micro AM-100 computer.  
It is copyright by Michael Noel and licensed for non-commercial hobbyist 
use under terms of the "Q public license", an open source certified license.

There exist known serious discrepancies between this software's internal
functioning and that of a real AM-100, as well as between it and the WD-1600
manual describing the functionality of a real AM-100, and even between it and
the comments in the code describing what it is intended to do!  Use it at your
own risk!

Reliability aside, it is not the intent of the copyright holder to use this
software to compete with current or future Alpha-Micro products, and no such
competing application of the software will be supported.

Alpha-Micro and other software that may be run on this emulator are not covered
by the above copyright or license and must be legally obtained from an authorized
source.  

As this is written I have permission from Alpha-Micro to distribute AMOS 5.0
with the emulator so you can get that from me too - but it is subject to their
terms and conditions.


INSTALLATION

Preferred installation is to compile the source on the target machine.

Tested targets include Fedora Linux (37, 38).  I use them native under
Microsoft Windows 10 with VMware and WSL. I also use them on Android phones
and tablets using Termux.

Step Zero.	
      You have at least 600 megs free disk space - right?

      We will assume you have downloaded the source and amos 
      distributions into a directory on your system; those files being

      am100-1.2.tgz
      HD1_wd16amos.hda.gz

Step One.
      Untar the source, uncompress the amos distributions, move the
      uncompressed distributions to the new am100 folder and change
      to that folder

		tar -zxf am100-1.2.tgz
		gunzip HD1_wd16amos.hda.gz
		mv HD1_wd16amos.hda am100
		cd am100
		
Step Two.	
      Compile the source.

		make

Step Three.	
      Run it!

		./am100

Step Four.	
      What's this message...

	"boot failed! Problem with 'dsk0-container' ?"

	dsk0-container is the name of the file that represents DSK0
	(potentially thru DSK31) in the emulator.  Since you might already
	have a dsk0-container, I've packaged the AMOS releases (4.6 & 5.0)
	as HD1_wd16amos.hda.  You can either copy it, rename it, 
	or create a link...

	Then run it again!

		ln -s   HD1_wd16amos.hda   dsk0-container
		./am100

Step Five.
	It booted - right?

	If not contact me & I'll try to help you figure out why...

	One feature that may help is the POST (Power On Self Test) option.
	Specify it like this

		./am100 -P

Step Six:
	Shutdown

	Press ALT H to get a list of ALT commands.  Note that ALT F will
	get you to the front panel.  At the front panel you can use tab or arrow
	keys to select the reset or power switches.  Press enter with one
	selected and the indicated operation will be performed (after a
	confirming dialog).

	So to shutdown press ALT-F, enter, Y


OPERATION

The system you run this in needs to have relatively good NCURSES support.  

Within AMOS all the control keys should work.  Esc should work.  The Arrow keys,
Insert, Delete, Home, End, PgUp, and PgDn should work.

Watch out for ALT keys.  ALT T toggles instruction tracing.  ALT S toggles
instruction stepping.  ALT R resumes from stepping.  ALT 0 (zero) shows the
"front panel".  ALT 1 shows the first terminal screen, ALT 2 the second terminal
screens, ... Up to 9 terminal screens can be defined.  ALT Z repaints the screen
if it gets messed up (like with trace/step info).  ALT M means mount (or unmount)
files associated with the DSK, LPR and MTU devices.

Things are defined in the am100.ini file.  See that file for further instructions.
Also note am100.ini is only the default initialization file, if you want to use
another (for example if you have several different configurations you want to be
able to start) you use the -f statup flag: for example, to startup using a warm
boot configuration (that you create) you could type

	./am100 -f warm.ini

Console output is to one of the NCURSES panels associated with a terminal (ie,
the ALT 0-9 screens discussed above).  Traces go to STDERR.  If you want to try
a trace but don't want it mixed with your screen, start the emulator with 

	./am100 2>am100.log

Then all the trace output goes into a file.  Watch out - it gets huge very very
fast.  It "wraps" at a certain point but that’s an "undocumented" feature, and
there is also a "user" trace facility, but I'm not ready to try and document that
yet either.

CUT and PASTE works with the console windows iff the console or xterm the emulator
is running in supports it. Be careful of PASTEing more than a few lines; AMOS may not
be able to process characters so fast which can cause a crash (in AMOS, not VAM).


WHAT DO I KNOW DOES NOT WORK?

All 1400+ known diagnostics run as expected with the five exceptions noted and
explained in the “CPU test exception excuses.txt” file.



HOW TO REPORT A NEW BUG

Send me an email (mikenoel37@gmail.com) telling me what you did, what happened,
and why you don't think that should have happened.  For example: "I compiled and
ran xyz.bas and it crashed saying it couldn't open file aaa.bbb, but  aaa.bbb was
there like it was supposed to be and this program and file work  on my real AM-100".
So far I'm pretty prompt getting back to people who tell me about problems,
hopefully that will continue...


SOFTWARE DONATIONS

Were you a software developer in the AM-100 heydays?  Still have a copy of your
pride and joy laying around?  Why not let others remember with you!   Let me post
a copy for use with the emulator.  All donations welcome!


CREDITS

Special thanks to Alex Begin at Alpha-Micro who provided permission to distribute
AMOS to users of this emulator.

README.pdf  (c) Copyright Mike Noel, 2001-2023 	  10/11/2023	  page 1 of 7