--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/myram.doc	Sat Apr 05 00:55:28 2014 +0200
@@ -0,0 +1,203 @@
+level2/modules/myram.asm
+level2/modules/mr0.asm
+
+RAM disk driver for NitrOS-9 Level 2
+Copyright (C) 2014  Gene Heskett
+
+                   See update message near bottom of file
+
+These docs describe a new mram.dr for OS-9 level 2 systems. With a bit of
+further editing, and the help of the conditional assembly commands in xsm,
+this should now run on either cpu. Although the object grew a few bytes in
+the conversion, the megaread times are very similar, averaging 10.5 seconds
+on this 6309 native system. On a regular 6809 system, the os9 call F$Move
+hasn't been optimized, so expect the megaread times to be at least doubled.
+
+As there have been at least 70 people who downloaded the 6309 only version
+which apparently worked well enough that I have NOT had any "I can't make it
+work" messages (none, nada, zip), either nobody is using it, or it works
+just fine which is exactly what its done for me here. This 6809 version
+didn't work in its previous, missing one "y register restore" version on my
+plain 512k machine at work earlier today. With that command added it is
+currently running as a 1 megabyte drive on this machine as I type this.
+
+1. In my experience, trying to format "rammer" seemed to be an exercice in
+futility as it was the most blob sensitive util I've tried to use. In fairness
+to rammer, this machine historicly has been a great blob detector.
+
+2. The only ram driver I could make run reliably was the developers pack
+version after it had been patched for a couple of bugs.
+
+3. That driver served as the model for this one in that I didn't change the
+method used to size the device. Having only one variable to control how big it
+is sure simplifies things. That variable is of course "sct" in the dmode
+report, meaning sectors per track. Its a one track device, just a variable
+length of track.
+
+4. Several things in the devpack ram.dr were hard coded. This prevented
+it from being used at equivalent sizes above the 504k mark. At that point,
+the FAT was a full sector, and above that required another sector.
+Unforch, the position of the FD and root dirs was fixed.  Asking for memory
+above that point also seemed to write rather willy-nilly to other, not owned
+by ram, memory. Crashes, while not the order, did happen from time to time.
+
+5. The really major effort in this was a total, start from scratch, re-write
+of the init routine.  Wholesale hunks of code got moved around, lots more
+smarts added, etc. Yes, its bigger, and yes with effort I could in all
+probablility shrink it some. However this works reasonably well for sct=1b00
+sized ramdisks. Thats 1.7 something megabytes in a 2 meg machine! With mfree
+reporting 96k free, I can still do about everything except run umuse3. That
+needs at least 128k plus a few more pages of system ram than most programs.
+
+6. The reason RBF apparently ignores any and all error codes that I'd built
+into the InitChecker routine is that OS9 in fact does call the Init function
+first!  This means that you can copy or move anything you want to to /r0
+without any errors.
+
+However . . .
+
+OS9 keeps a link count of users of the device, and if the aformentioned
+copy operation was the only link, then when the copy is done and the link
+count is reduced to zero, the "Term"inate routine is then called.
+So /r0 was dynamicly initialized for the duration of the copy operation,
+gave no errors because of that, and then was de-initialized at the end of
+the copy by the closing of the only open path! By-by file!  I've been bit at
+least 1000 times, probably more, many more!
+
+Verified by setting the priority down to zip, initiating a copy while the
+descriptor had been dmoded to about 1.5 megs, and running mmap repeatedly
+while the copy was being done.  And by putting a call to F$regdmp (os9p4) in
+the Term routine. It did execute.
+
+Now there are folks out there who no doubt knew all this, so please bear with
+me as I prevent this zero open paths automatic deinit of /r0.
+
+I have been able to do the "autoinit" in a manner that doesn't deinit the
+device after the write path is closed. And it doesn't prevent it from being
+deinit'ed if and when you want to return the ramdisk memory to the machine 
+memory pool.
+
+Despite the statement in Kevins "Inside OS9 Level II" book to the effect
+that the device table is not available to the programmer, it is in fact
+available IF you are a device driver loaded in the os9boot file as it loads.
+Otherwise the address returned from a load of the direct page offset $80-81
+will be in some other block of memory instead of in the system's memory. And
+while the exact offset of our entry may be available from some other var in
+the direct page, I haven't found that define yet. So I searched to find our
+assigned V$STAT memory assignment instead. It searches each 9 byte entry in
+the device table till it either finds it and then incs the associated V$USRS
+count, or reads a $0000, in which case BIG trouble. It will do an F$Exit and
+report. I used E$DevOvf as the error in that event. You should NEVER see
+that error unless something else has badly corrupted the system vars in
+which case its reboot time, RIGHT NOW!
+
+The major problem with attempts to locate our own entry in the device table
+during the init routine is that our entry in the device table does not exist
+until the Init routine of a device driver has been exec'd and has returned
+to OS-9. This meant that the "stay resident" code had to be split up, a
+single instruction setting a flag during the initialization, a quick, one
+line test of the flag is done at every read or write function. If set, it
+finds its own entry in the now valid device table and increments the link
+(V$USRS) count in the table, one time only as that same piece of code then
+clears the tested flag. Once done, the additional read/write overhead is
+only the flag test which if zero, jumps immediately to the read or write it
+came here to do. I'd guess not more than a 2% slowdown averaged over a 100k
+write or read.
+
+The current size is coded into your device descriptor as "sct", so if you want
+it to survive a big file thru the C compiler, be sure to dmode it big enough
+to handle the expected files before running the compiler. I'd suggest patching
+the descriptor right on the disk so you can even afford to forget that most of
+the time. You do have 2 megs don't you? I have set mine for "sct=1000", giving
+a 1,024 kilobyte ramdisk when it does do the automatic initialization.
+
+In the event of an overflow or "device full", it really does return an error
+#248! The devpack one didn't as you all know well. Attempts to format it using
+"format /r0" will get an illegal service request error exit when format
+attempts to access it for recovering the device parms. It does not support any
+getstt or setstt calls.
+
+Speedwise, megaread is 10.5 seconds from /r0, 13 seconds from my Maxtor 7120s.
+Both obviously limited by machine speed, not the drives. That would be mainly
+in the OS-9 call "F$Move", the linkage between memory we own and some other
+memory not currently in our process map.
+
+My own megaread was redone in Basic09 early on because the drive I had at that
+time had a couple of bad sectors in the first megabyte, so I had to re-read
+the first 256k 4 times. That adds a couple of millisecs for seek time of
+course.
+
+There is one other item that caused me to go back and make the initial
+allocation for the root directory another 8 sectors longer, seems that dcheck
+didn't like the extended root directory caused by my stuffing about 700k worth
+of small files into it. So now the allocation for the sector zero, FAT, root
+FD, and root dir is $10 sectors total. And dcheck can't find anything at all
+to fuss about with that same long list of small files copied to ram, without
+pre"iniz"ing it.  I've been doing this on my hard drives for years, modifying
+it with ded before I write anything else to the drive, it sure cuts down on
+dchecks useless (but confusing to the newcomer) caterwalling and mewling
+about extended root directories (not associated with a file type msgs) that
+dcheck is truely famous for. Its only bug possibly. One I've been fussing
+about, and wishing the author would fix for years!
+
+If you do a "free /r0" on it, you'll find the volume name is "Gene's RamDisk",
+I had to get my name in there someplace! And for those who have a copy of
+"dtype", a kludge I wrote years ago to help me identify the 100's of disks I
+had in various flavors of drive styles and os-9 levels/versions, it will ident
+it as a floppy of course, but the rest of its report is accurate. That was a
+last minute addition that didn't run it back above $300 bytes in 6309
+versions.
+
+UPDATE MESSAGE
+
+The earlier version didn't attempt to set its "creation date" in the sector
+zero information, and in fact due to a foible of os9, couldn't use the
+regular F$Time call as it returned nothing. This one does, but the method
+used requires it to be in the os9boot file to work, (the second reason in
+fact) else it will copy garbage to that area of sector zero. That reason is
+that in order to make the method recommended work, I must convince the
+system that ram is indeed a system module for the approximatly 100
+microseconds it takes the I$Attach call now used to execute.
+
+Alan Dekok and company (of  Nitros9 fame) have, if a message I received is
+correct, rendered my auto linking routine null and void, and possibly made a
+crash, by expanding the format of the device table for additional data
+entries. When that is confirmed, I'll release this newer, fixed version that
+now also sets the create date correctly. It has to jump thru a few more hoops
+than the older version in order to do the linking in a way that won't be
+broken by newer versions of Nitros9 (1.21+). So of course it gained a couple
+of bytes sizewise.  While I haven't tryed it yet, from messages I've
+received, this new method won't break. I also did some tweeking of the
+allocation mapping, and the required 8k blocks of memory which effects those
+with only 128k will notice right away, memory usage is 1 256 byte page less
+than it was when sct was an even $x800 or $x000, and the read errors because
+it didn't get enough blocks of memory to hold the last $1f sectors when sct
+was less than the above should be gone also. Setting sct=170 will cause it
+to aquire enough blocks to hold $180 sectors instead of chopping it off at
+$15F under those conditions like it did before. The fat will however reflect
+the $170 you asked for. (Putting on my Jimmy Stewart hat here) So ya might
+as well ask for the whole block!
+
+END of UPDATE message
+
+I hope this is of some help to the OS-9 community.
+Cheers All, Gene Heskett, WDTV5@delphi.com
+
+ 
+RAM disk driver for NitrOS-9 Level 2
+Copyright (C) 2014  Gene Heskett
+
+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 program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+