This commit was generated by cvs2svn to compensate for changes in r2,HEADmaster

which included commits to RCS files with non-trunk default branches.

1 files changed, 149 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..46c77c0
--- /dev/null
+++ b/README
@@ -0,0 +1,149 @@
+------------------------------------------------------------------------------
+This version of the HARDSID driver is a small patch to the version available
+at Sourceforge.  I've not made any serious code changes -- just enough to make
+it compile with my kernel (2.6.20-16-generic in Ubuntiu 7.04).
+
+The original README for the patched version is below.
+
+Ian C <ianc@noddybox.co.uk>
+------------------------------------------------------------------------------
+
+
+HardSID device driver for Linux
+Version 0.16
+
+Copyright (c) 2000-2003 Jarno Paananen <jpaana@s2.org>
+Copyright (c) 2001-2003 Simon White    <s_a_white@email.com>
+
+*      This program is free software; you can redistribute it and/or
+*      modify it under the terms of the GNU General Public License
+*      as published by the Free Software Foundation; either version
+*      2 of the License, or (at your option) any later version.
+
+
+This is a small hackish device driver for the HardSID and HardSID Quattro
+cards (both ISA and PCI) by Hard Software and Catweasel MK3 card by
+Individual Computers.
+
+WARNING: before you read any further, please bear in mind that this is very
+experimental software. It could blow you and your machine to moon and back
+at any time. It hasn't done that to me though :)
+
+This version has been tested to work on 2.4.23 and 2.6.0 kernels It might or
+might not work for you, patches to get it working are happily accepted. SMP
+has been tested to work on 2.4.0-test12 and 2.2.18. It has also been tested
+on Alpha using kernel 2.4.0-ac10. Check the Makefile for necessary compiler
+options for Alpha. The driver has also been tested to work with 64-bit AMD64
+kernels, both 2.4 and 2.6.
+
+NOTE!
+-----
+If you are using 2.2.x kernel and SMP, you have to add -D__SMP__ to the
+command line in Makefile, otherwise your machine will lock up. 
+
+If you want to use 2.2.x kernel, it seems your need at least 2.2.18, earlier
+kernels don't have the 2.4 compatibility macros I'm using here.
+
+Due to the changes made to Makefiles between 2.4 and 2.6 kernels, I
+separated the them to two different files. Copy/symlink appropriate to
+Makefile before compiling.
+
+FOR OLD USERS
+-------------
+The device numbers have changed as of 0.11 version, read the information
+below on how to remake your /dev entries.
+
+
+Kernel driver
+-------------
+
+Currently the driver uses a character device called /dev/sid, which should
+be a symlink to sid0-15, with major number 60 and minor numbers 0-15. Each
+device maps to one SID.
+
+So before you get to use the driver, you need to make the device(s):
+
+mknod /dev/sid0 c 60 0
+mknod /dev/sid1 c 60 1
+(and so on...)
+ln -s /dev/sid0 /dev/sid
+
+Change the owner/group and permissions if you want non-root users to be able
+to use it as well.
+
+The device driver should compile with just "make", but check that it gets
+your kernel includes from the right place.
+
+At this point you should be ready for insmod hardsid.o. If this went well
+and you got message like:
+
+HardSID Driver v0.16
+HardSID card with 6581 detected @ 0x300
+
+in your dmesg, you should be set.
+
+
+User mode
+---------
+
+Sidplay2 supports this driver in the CVS version now. You need to get and
+build the Hardsid-builder. Use --hardsid switch with Sidplay2 to get it use
+Hardsid.
+
+If you have two SIDs, you can try playing stereo SIDs too.
+
+
+Miscellaneous
+-------------
+
+- the module accepts a few options:
+  io=0x300:      force the IO port base, not necessary
+  ioextent=8:    how many ports to allocate, not necessary
+  major=60:      the device major number to use, change if your
+                 system already uses that. Also change the /dev-nodes.
+  slowaccess=1:  use slow 8-bit access to the HardSID card if you have
+  		 problems with the default 16-bit. Shouldn't be necessary.
+  detecthack=1:  force the driver to load even if it doesn't find any SIDs.
+  		 Useful only for debugging.
+  quattrohack=1: play the first SID data with all SIDs in a Quattro. My
+                 personal hack, which might be useful to others too.
+  renice=-5:     set the renice value of the kernel thread. Improves timing
+                 when the machine is under heavy load.
+- increasing the kernel scheduling rate (HZ) from <asm/param.h> decreases
+  CPU usage and timing errors of the driver
+- there is also /proc/hardsid, which displays some statistics
+- to write stuff to the sid, you write commands with 32 bits each to the
+  device:
+        bits 31-16: 16 bit delay timer value in C64 clock cycles
+	bits 15-13: reserved, keep zero
+	bits 12-8:  SID register number
+	bits 7-0:   Data
+	
+This is in host byte order, ie. little endian in x86 case.
+
+Example:
+
+    unsigned char reg, val;
+    unsigned int temp;
+    temp = ( cycles << 16 )| (reg << 8) | val;
+    write(sidHandle, &temp, 4);
+
+Multiple commands can be written at once.
+
+Register 0x1f is considered dummy (it doesn't exist in real SID) and is used
+for delays longer than 0xffff.
+
+
+- to read stuff, you seek to the correct register and read one byte:
+
+    unsigned char reg, val;
+    lseek(sidHandle, reg, 0);
+    read(sidHandle, &val, 1);
+
+- there are a few ioctls you can use with the device, check the source for
+  those :)
+
+If you have any questions, patches or anything else in mind, feel free to
+mail me at jpaana@s2.org
+
+// Jarno