AtariSIO driver and utilities V0.30 installation instructions

1. Installation requirements

   The following packages are required to build AtariSIO:

   * common build tools (gcc, make, ...)
   * libncurses 5.2 or newer
   * zlib
   * kernel headers if you want to build the AtariSIO kernel driver

   On Debian / Ubuntu you can install these with

   apt-get install build-essential libncurses5-dev zlib1g-dev

   plus, optionally, 

   apt-get install linux-headers-XXX

   where XXX matches the kernel version you are using (eg linux-headers-amd64)

2. Quick install guide

   Building AtariSIO tools plus kernel driver:

   make
   sudo make install

   Building only the tools, without the kernel driver:

   make tools
   sudo make tools-install

   This will install the AtariSIO tools in /usr/local/bin and
   (optionally) the kernel driver in /lib/modules/....

   Note: by default atariserver and atarixfer are installed 
   setuid root (so they ran run with realtime scheduling priorities)
   and accessible only to members of the group "users". So make
   sure your user is a member of that group or change the
   permissions manually after installation.

3. Changing build / installation options

   The provided Makefile should work out of the box on most
   Linux distributions and will pick up header and library
   locations automatically via pkg-config.

   Several common options can be tweaked by setting make variables.
   Make sure to pass those variables both to "make" and "make install".

   For example:
   make tools DEFAULT_DEVICE=/dev/ttyAMA0
   sudo make tools-install DEFAULT_DEVICE=/dev/ttyAMA0

   DEFAULT_DEVICE: atarisio / serial device to use in atariserver/atarixfer
   Default is /dev/atarisio0.
   Change it to eg /dev/ttyUSB0 if you intend to use atariserver/atarixfer
   mainly with a USB serial adapter.

   INST_DIR: Installation directory prefix
   Default is /usr/local

   KDIR: Location of the kernel headers / source.
   Default is  /lib/modules/KERNELVERSION/build

   USE_KBUILD: Use kernel build system to build kernel driver
   Default is 1 (enabled), set it to 0 to enable manual compilation
   of the kernel driver for ancient 2.2/2.4 kernels.

   KERNEL_CC: compiler to use for kernel 2.2/2.4 compilation
   Default is to use gcc.

4. Activate the kernel driver

   Due to the design of the linux kernel, the serial port chip can
   only be accessed when the built-in linux serial driver for that
   port is disabled. Until AtariSIO V0.20 this had to be done
   manually by calling "setserial /dev/ttySx uart none".

   Since AtariSIO V0.30 this can be handeled automatically by the
   kernel driver.

   In general this means: if your serial port(s) are properly
   configured, you only have set the "port=" module parameter of
   atarisio (eg "port=/dev/ttyS0") and the kernel module will
   disable the serial driver for that port, read the IO and IRQ
   settings from the serial configuration, and will also re-enable
   the serial port when the atarisio kernel module is unloaded.

   If you have a non-standard setup (or if your serial ports are not
   configured properly yet) you may use the "io=" and "irq=" module
   parameters to override the IO/IRQ configuration obtained
   from the serial driver.

   UARTs with memory-mapped IO ports (MMIO) are supported as well,
   use the "mmio=" module parameter (instead of "io=") to specify the
   MMIO address.

   Please note: if you don't pass a "port=" parameter to atarisio,
   you are responsible to disable the serial driver and properly
   set the "io="/"mmio=" and "irq=" parameters!

   The atarisio-modprobe.conf file contains a ready-to-use configuration
   that will use the first serial port (/dev/ttyS0) plus several
   other examples. Change that to your needs and copy it to
   /etc/modprobe.d/atarisio.conf

   A template udev configuration file, to setup permissions of
   the /dev/atarisioX device(s), is provided in atarisio-udev.rules.
   Change that to your needs and copy it to
   /etc/udev/rules.d/90-atarisio.rules

   Now load the module with "modprobe atarisio". It should load fine
   and a line similar this should be added to dmesg:

   atarisio0: minor=240 port=/dev/ttyS0 io=0x03f8 irq=4

   If you get a line saying:

   atarisio: please supply port or io and irq parameters

   then you stored the configuration in the wrong place. In this case
   please consult the documentation of your Linux distribution about
   the proper location.
   
   In case of troubles have a look at atarisio lines in dmesg.
   Loading atarisio will usually fail in one of the following cases:
   - if you passed a non-existant serial port device
   - if it could not disable the linux serial driver
   - if you don't have a 16550(A) (compatible) UART
   - if the IO port region is used by another driver

   If you want support for more than one SIO2PC / 1050-2-PC interface
   just pass a comma separated list of serial devices / io-ports / irqs
   to the kernel driver. For example:

   options atarisio port=/dev/ttyS0,/dev/ttyS1

   (in your /etc/modprobe.d/atarisio.conf file) or on the command line:

   modprobe atarisio port=/dev/ttyS0,/dev/ttyS1

   This will enable /dev/atarisio0 on your first serial port and
   /dev/atarisio1 on your second serial port.
   
5. Troubleshooting

   If you didn't install the kernel module correctly, the utilities
   will most likely bail out with an error message saying
   "unable to open /dev/atarisioX". If that's the case, look into
   dmesg if you can find some error messages from atarisio, and
   re­check the last  steps.

   You'll also get "unable to open /dev/atarisioX" if another
   program is using /dev/atarisioX.

   If you run "make clean" all object files and executables will
   be deleted, but not the 6502 binary files (*.bin). To remove
   these files, too, run "make allclean". Note: you need to have
   ATasm 1.08 (or newer) installed to assemble the 6502 code.
