8bitfiles.net/archives

home *** CD-ROM | disk | FTP | other *** search

/ 8bitfiles.net/archives / archives.tar / archives / genie-commodore-file-library / Information / ACE-R11.DOC.ARC / ACE-R11.DOC

Wrap

Text File | 2019-04-13 | 62.7 KB | 1,243 lines

ACE-128/64 USER'S GUIDE for Release #11 [September 9, 1994] ------------------------------------------------------------------------------ 1. INTRODUCTION ACE is an operating system for the Commodore 128 and Commodore 64 that provides a Unix-like command shell environment. It is still in the development stage, but enough of it is complete to be useful. BTW, "ACE" means "Advanced Computing Environment" (well, advanced for the 128/64). This release contains a few new features over the previous release: - High performance built-in ramdisk (up to 1 meg/sec file reading) that you can use just like a regular disk device (file reading and writing). - Bitmap-implemented software 80-column screen for the C-64. - Scroll-back buffer for keyboard input line editing, allowing you to edit or re-execute previous commands. - Still even faster printing to screen (a la optional partially-implemented "pre-scrolling"). - And, of course, some minor bug fixes. This distribution consists of a boatload of files. System files: ace - the kernel bootstrapper; can be run from either 64 or 128 mode ace128 - the kernel for the 128 ace64 - the kernel for the 64 config - the configuration initializer sh - the command shell config.sys - the system configuration - this is data not an executable config.edit - configuration editor program (written in BASIC) ace-charset - character set - you can replace it with your own IYW ace-charset-4bit - character set - you can replace it with your own IYW Application programs (explained in Section 6.3): cp - copy files rm - remove files (scratch) mv - rename files (named for Unix "mv"=="move") mkdir - create a new directory (flat name) rmdir - remove an existing empty directory (flat name) xls - directory lister, displays dates uuencode - encode files into uuencoded format uudecode - decode files from uuencoded format bcode - encode files into BCODE format unbcode - decode files from BCODE format crc32 - display CRC-32 *B* values for files (new standard) crc32a - display CRC-32 *A* values for files (old standard) wc - count words, lines, characters of files grep - search for a substring in files (from Unix "grep") tr - translate from one character set to another sort - sort files wrap - wrap lines longer than 75 characters date - display current date and time forty - switch to 40-col screen, slow mode eighty - switch to 80-col screen, fast mode on 128 read - read files mem - display available dynamic and transient program area memory as - DEMO assembler: only tokenizer implemented vi - DEMO "Zed" text editor: displays screen, loads and prints file hello - dumb little "hello world" example program window - set the current window dimensions more - full-screen file displayer unkar - KAR (Kevin's ARchiver) file dearchiver These binary programs available in a uuencoded archive format. The uudecode program included here will decode this format of archive, but that is probably of no use to you unless you are able to Catch 22. You may have to use the uudecoder on your Unix system or use "uuxfer" for the C64. You may have to split the uuarchive up into separate files for uudecoding. Note that the "ace128" and "ace64" programs are functionally identical, except that one is set up for the 128 and the other for the 64. Thus, all of the appication binary programs will work with either "ace128" or "ace64". LOAD and RUN the "ace" program and it will load the correct "kernel" for your computer. The Buddy assembler source code files are not included here, but I will e-mail them to anyone who asks for them. They are getting a bit bulky, over 23,000 lines. For people wanting a little technical information, here is the memory map of ACE; it is subject to change at my whim: $0002-$007f = application zero-page storage (0.12K) $0080-$00ff = system zero-page storage (0.13K) $0100-$01ff = processor stack (0.25K) $0200-$0eff = system storage (3.25K) $0f00-$0fff = kernel interface variables (0.25K) $1000-$12ff = system storage (0.75K) $1300-$1fff = shell program (3.25K) $2000-$27ff = character set (2K) $2800-$6fff = ACE kernel and device drivers (18K) - unused space free $7000-$bfff = application area & stack (20K) $c000-$feff = ROM and I/O, RAM (15.75K) - free $ff00-$ffff = reserved for system (0.25K) or with a C64 with the soft-80 bitmap screen, high RAM usage: $d800-$dbff = soft-80 character set (1K) $dc00-$dfff = bitmap color matrix (1K) $e000-$ffbf = bitmap screen (7.81K) $ffc0-$ffff = reserved for system (0.19K) ------------------------------------------------------------------------------ 2. USING THE SYSTEM When ACE starts, it loads and executes the command shell (among other things), gives you a prompt and waits for you to give it a command. A command has the following format: programname arg1 arg2 ... argN The programname can be any of the following built-in commands (covered in Section 6.1): echo - print the given arguments to stdout clear - clear the screen cls - same as "clear" dir - clear the screen and give a long-form directory listing d - same as "directory", but no clear screen ls - give a multi-column short-form directory listing clsl - combination of "cls" and "ls" cd - change the current device/directory cat - display the named files to stdout exit - exit from the command shell back to BASIC x - same as "exit" dos - give a Commodore dos command to the current device (OPEN1,dv,15..) @ - same as "dos" path - set the path to search for external programs sh - invoke the shell again as a sub-shell or programname can be for any of the external programs provided with this distribution. You'll have to forgive my personal taste in command names and abbreviations (until the "alias" shell feature is finally implemented). 2.1. INPUT/OUTPUT REDIRECTION The three Unix standard files are supported: stdin - where the default input comes from (usually the keyboard) stdout - where the default output goes to (usually the screen) stderr - where error messages are sent to (usually the screen) To temporarally redirect these standard file streams for the execution of a command, you can use the following incantations on a command line: <infile - redirect stdin - input taken from "infile" >outfile - redirect stdout - output put into file "outfile" >>outfile - redirect stdout - same as ">" but the output is appended to file >&errfile - redirect stderr - error output is put into "errfile" >>&errfile - redirect stderr - error output is appended to file "errfile" Do not put a space between the redirection symbol(s) and the file name. 2.2. PATHNAMES Whenever you specify a file, you use a "pathname". Pathnames have the following optional parts: [device:][ramlink-directory:][filename] Device names are set by the user in the configuration file, but the factory defaults are: "k:" - Custom device driver: the keyboard "s:" - Custom device driver: the screen ("k:" and "s:" are exactly synonymous) "p:" - Commodore device #4 - the printer, with SecAddr 7 - output only "q:" - Commodore device #4 - the printer, with SecAddr 5 - transparent mode "n:" - Custom device driver: "null" device "a:" - Commodore device #8 - a disk drive - input/output "b:" - Commodore device #9 - a disk drive - if you have >1 drive ... "j:" - Commodore device #17 - a disk drive ".:" - the "current" disk device CMD RAMLink (or CMD HardDrive) directory names have the following formats: "//dir/:" - a subdirectory of the root directory "/dir/:" - a subdirectory of the current directory "4//dir/dir/ ... /dir/:" - a sub-path of the root directory of partition #4 "/dir/dir/ ... /dir/:" - a sub-path of the current directory And filenames have the usual Commodore format of 1 to 16 characters. Thus, the following are valid pathnames for files: k: - the keyboard for input p: - the printer for output b:file1 - "file1" on disk device #9 .:file1 - "file1" on the current disk device file1 - "file1" on the current disk device /dir1/file1 - "file1" in the RamLink subdirectory "dir1" a://dir1/dir2/:file1 - "file1" in the RamLink subdir "//dir1/dir2", device #8 And the following are valid pathnames for directories: a: - disk device #8 current directory .: - current disk device's current directory .://dir1/: - "dir1" off the root directory of the current RamLink device /dir1/dir2/: - subdirectory "/dir1/dir2" of the current RamLink device Note that a directory name always ends with a ":". You may append a ",p" or ",s" or ",u" to a filename to specify whether a PRG, SEQ, or USR file should be accessed/created. By default, ACE will create SEQ files. BTW, to generate an EOF for keyboard input, simply press Control-D. Only do this at the beginning of a blank line. 2.3. COMMAND SHELL ARGUMENTS Arguments that contain spaces must be put into quotes. Multiple quoted strings can be placed side-by-side to produce a longer string. The following are examples of valid command shell arguments: hello - hello 'hello' - hello "hello there" - hello there 'hello there' - hello there 'she said, "how'"'s that"'"'' to me.' - she said, "how's that" to me. Command shell arguments are separated by spaces or tab characters. 2.4. EXTERNAL COMMAND SEARCH PATH The "path" command sets or displays the current search pathnames for external programs. By default the paths to search are "a:" and ".:". The path consists of multiple directory names to be checked, in order, for each binary executable or shell script that you give that does not have a pathname prefix. 2.5. WILDCARDS Unix-style wildcard expansion is supported. When you enter an argument with an asterisk in the filename component of the pathname, the command shell will automatically expand that name into an argument for each file in the specified directory that matches that pattern. The expanded arguments are then passed onto the command you are invoking as if you had typed them all in yourself. For example: ARGUMENT EXPANSION -------- --------- * file1 prog1,p prog2,p ch* chess,p chinese_checkers,p *.bin main.bin,p data.bin anagram.bin a*n anagram.bin an another_plan b:a*.bin b:main.bin,p b:data.bin b:anagram.bin c://games/:a*.bin c://games/:acrobat.bin,p c://games/:acrodata.bin You'll note that program files are expanded to include a ",p". If a pattern does not expand to anything, an error message is displayed and the shell command is not executed. You'll have to cursor-up and change the command. Your filename pattern can include only one asterisk (anywhere in the name). Some example uses of wildcard expansion with the provided utilities follow: cp b:* a: cp //games/c64/:chess*.bin somefile b://games/: wc *.asm *.c ------------------------------------------------------------------------------ 3. SYSTEM CONFIGURATION The program entitled "config.edit" is used for editing the system configuration. The system will be configured according to the data in the file "config.sys" every time it starts up. Note that "config.sys" is a loadable binary PRG file; it is not in text format and is not meant to be edited with a text editor. The following data are included in the "config.sys" file: OFF SIZ DESC --- --- ---- $00 128 device descriptors, 32 entries of four bytes each. [For each entry, offsets: 0=device driver type, 1=device address, 2=secondary address, 3=flags. Described further below.] $80 1 ramlink device number [The kernel device number of your RAMLink. The default RL device number is 16.] $81 1 ramlink last logical bank allowed to use plus one (norm 255) [For the RAMLink memory partition (next section), the maximum number of 64K chunks that can be used for dynamic memory.] $82 4 real-time clock devices to check [4], $FF=unused [These are the kernel device numbers of CMD disk drive units that have a built-in real-time clock to check for the current time. If the first entry fails, then the second will be tried, etc., until the fourth entry is tried. If all devices fail to return a time, then the default date is used (next). A value of $FF in an entry means to try the next entry. ACE uses the TOD clock of CIA#1 to keep time. The date is stored in a regular memory field and is not rolled on a 24-hour TOD clock wrap-around.] $86 8 default date YY:YY:MM:DD:HH:MM:SS:TW [The default date to use if attempts to access the current time from CMD disk devices fail. Format is 24-hour BCD. All four digits of the year are given. The "TW" field means tenths of seconds in the high nybble and the day-of-week in the low nybble. For days of the week, 0 means "unknown", 1 means "Sunday", etc., and 7 means "Saturday". The factory-set value of this field is 12am, Friday, Jan 1, 1993.] $8E 1 screen saver activation time, in minutes (norm 10) [The screen will go black when the screen saver is activated, after a period where you have not pressed any key for the specified time, until you press a key (including the any of the shift keys). If you press any character key, that key will appear in your input. Normal processing will continue in the background, while the screen saver is active, including printing to the screen. This time is in minutes. A value of zero means to disable the screen saver. The screen saver is now active for the 40-column and 80-column displays.] $90 16 initial current directory string (default "a:") [Immediately after booting and before calling the shell, the kernel will do a change directory to the null-terminated string given here.] $A0 1 C128 bank1 start free page (norm $04) [This field and the next define the pages of RAM1 that ACE is allowed to use. This must include at least one page.] $A1 1 C128 bank1 last free page plus one (norm $ff) $A3 1 C128 bank0 last allowed free page plus one (norm $ff) [This is the highest page, plus one, on RAM0 that ACE is allowed to use. You can set this to protect a program that you wish to attempt to use with ACE (good luck). There is no minimum page that ACE is allowed to use; it takes whatever it wants below $6000.] $A5 1 C128 last internal bank allowed to use above 2, plus one (norm 8) [For expanded internal memory (a la TwinCities-128), this sets the high limit on the banks that ACE is allowed to use. A value of 2 means that ACE is not allowed to use it at all. There is no low limit on this because it caused too many programming problems.] $A6 1 C128 first REU bank allowed to use (norm 0) [This and the next field define the minimum and maximum (plus one) REU bank numbers that ACE is allowed to use. I included a minumum because of pleas about Zed having a minimum. If you set both min and max to $00, then ACE will leave the REU memory alone. Otherwise, ACE will auto-detect how much you have and will make use of as much REU memory as it can (note the default max is 255).] $A7 1 C128 last REU bank allowed to use plus one (norm 255) $A8 1 C128 top page of TPA (stack) (norm $c0) [This defines that page (plus one) of the top of the application program area (TPA). The bottom is $6000, so a top of $C000 gives apps 24K to play around in. $C0 is the maximum value this field can have, since the Commodore Kernal must (for this release) stay in context whenever ACE is in use. The top of this space is also used as the "argument stack" for applications.] $A9 1 C128 VDC default number of rows (norm 25) [Not currently supported] $AA 1 C128 VDC number of Kbytes of video RAM (norm 16) [Not currently supported] $AB 1 C64 soft-80 screen maximum prescroll for REU-supported scrolling [Currently, the number of rows to scroll the screen every time the screen needs to be scrolled.] $AC 1 C128 80-col screen maximum prescroll [Currently, the number of rows to scroll the screen every time the screen needs to be scrolled.] $AD 1 C128 40-col screen maximum prescroll [Currently, the number of rows to scroll the screen every time the screen needs to be scrolled.] $AE 1 C64 soft-80 screen maximum prescroll for software scrolling [Currently, the number of rows to scroll the screen every time the screen needs to be scrolled.] $AF 1 C64 40-col screen maximum prescroll [Currently, the number of rows to scroll the screen every time the screen needs to be scrolled.] $B0 8 C128 80-col screen color palette: table of eight RGBI codes. [This table gives the palette of colors to be used by C128 80-col applications. The meanings of the values stored at the offsets are: 0=char, 1=cursor, 2=status, 3=separator, 4=highlight, 5=alert, 6=border, 7=screen. The char, border, and screen colors are used when the screen driver is initialized. The border value for the 80-col screen is currently ignored. Note that RGBI codes are used, even for the VIC chip (for consistency). The factory defaults for char, screen, and border are light grey on black for 80 and light green on dark grey with a medium grey border for the 40 (perhaps a bit icky). The other values are chosen accordingly. The palettes for the other displays have the same structure as this one.] $B8 8 C128 40-col color palette $C0 1 C64 soft-80 enable mask (norm %10100000) [The 128-bit allows the soft-80 screen to be used. Allowing the soft-80 screen costs 10K of RAM0 memory on the C64. This software- implemented bitmap 80-column screen is supported only on the C64. On a C128, use the real 80-column screen. If the soft-80 screen is not allowed, then the 10K of memory is made available for far memory use (e.g., for ramdisks). The 64-bit specifies that the soft-80 screen is to be entered by default when ACE starts up, rather than the 40-col screen. You can switch between the two screens by using the "forty" and "eighty" programs. The 32-bit specifies that the REU is to be used to assist in scrolling the bitmap screen if an REU is present. The cost of doing this is 7.5K of REU memory. The benefit is that the screen will scroll several times faster than it will by just using the main processor, which is used otherwise.] $C1 1 C64 last allowed page free plus one (norm $ff) [This gives the top page, plus one, that ACE is allowed to use on the 64. Don't set this lower than the top of the TPA area.] $C2 1 C64 first REU bank allowed to use (norm $00) [Like the C128 settings, you can set the usage for the REU memory.] $C3 1 C64 last REU bank allowed to use (norm $ff) $C5 1 C64 end expanded internal memory banks plus one (norm $04) [This field is currently ignored.] $C6 1 C64 top page of TPA (stack) (norm $c0) [Top of the TPA for the 64. You can set this between $61 and $D0.] $C8 1 key repeat delay (norm 20) [The number of jiffies between when you press a key the first time and when it starts repeating.] $C9 1 key repeat rate (norm 3) [The number of jiffies between each repeat of a key while you are holding it down.] $CA 1 console color enable default (norm $80) [This is used to enable what is normally printed on the console screen: characters, colors, and/or attributes. This feature is not currently fully implemented. The default is for only characters because this allows it to operate twice as quickly as when both colors and characters are enabled.] $CB 1 input line scrollback buffer line count (norm 5) [The number of previous lines to save so that you can scroll back through previous input lines in order to edit them. Each line of buffer space requires 256 bytes of far memory to store. Specifying a value of zero disables the scrollback feature.] $CC 1 controller port 1 device [Not currently implemented.] $CD 1 controller port 2 device [Not currently implemented.] $D0 8 C64 80-col color palette [For the bitmapped hi-res 80-col screen, which is not yet implemented.] $D8 8 C64 40-col color palette $E0 32 initial shell path string (default "a:", ".:") [The paths to use to search for executable programs. Each directory name is a null-terminated string, and the list of paths is terminated by an empty string.] The offsets from $00 to $7F contain 32 four-byte fields, which are used to define the devices in the system. These fields will correspond to device names "@:", "A:", "B:", ..., "Z:", "[:", "\:", "]:", "^:", and "_:" (forgive the non-letter device names). The four fields will be defined as follows: 0 device driver type (0=Kernal non-disk, 1=Kernal disk, 2=console, 3=null) 1 device primary address / whatever 2 device secondary address / whatever 3 flags / whatever ($80 for a disk will means that it has a CMD Real-Time clock) The factory defaults are: devices "a" to "j" are Commodore disk devices 8 to 17, respectively, "p" is device number 4 with secondary address 7, "q" is device number 4 with secondary address 5 (which is transparent mode with many printer interfaces, with which you'd use the "tr" utility to translate files into Ascii-CrLf format), and devices "k" and "s" refer to the custom console (screen and keyboard) driver. To spare you the agony of editing this binary configuration manually, the BASIC program "config.edit" can be used instead. Run it from BASIC, not from inside of ACE. In fact, you should run this before running ACE the first time to set up the configuration. The program provides a full-screen interface. Move the cursor among the fields on each page and among the pages (10 of them) to set the values. All values are in decimal (except the strings). Then save the new configuration, exit, and run ACE. If you screw up the new "config.sys", the previous one will be available in "config.sys.bak". ------------------------------------------------------------------------------ 4. DYNAMIC MEMORY After you have configured ACE for your system, if you have a RAMLink, you will have to configure it for ACE if you want to use RAMLink RAM or indirect REU access. The way that ACE detects these types of memory is via the RL-DOS partition table. For RAMLink RAM, ACE will check for partition number 31 being a Foreign Mode (Direct Access) partition with the name "rl-ram". If it is, then ACE will get the information for that partition to determine the size and start address (in RL memory). It will then check the limit for usage of RL-RAM in the "config.sys" file, and adjust the size it can use accordingly, before initializing the memory. To set up this partition on your RAMLink in the first place, refer to your RAMLink documentation and use the tools program provided with it. Using REU (Ram Expansion Unit) memory with ACE is pretty easy; you just make sure it is plugged into the computer when ACE is started. ACE will auto- detect the size of the REU and then check the configuration for limitiations on REU usage. If you have your REU plugged into your RAMLink in the memory port (rather than the pass-through port), and you have the Normal/Direct switch thrown to the Normal position, then your machine cannot access REU memory in the usual way. The only way to access it is to go through the RAMLink. ACE will look for partition number 30 being Direct Access and named "indirect-reu" for this purpose. If your Normal/Direct switch is in the Direct position, then ACE will use the REU directly and will ignore the "indirect-reu" partition. Do not change the position of the Normal/Direct switch while ACE is in action. The tricky part here is in configuring your RAMLink. You have to make sure that the memory allocated to the "indirect-reu" partiton is the memory of the REU. RAMLink memory starts from $000000 and goes up to $FFFFFF. REU memory will be at the very front of this memory (from address $000000), and the internal RAMLink memory will follow immediately after this. For example, I have a 512K REU and an 8 Meg RAMLink, so my REU memory covers at RL addresses $000000-$07FFFF, and my internal RL memory covers RL addresses $080000-$87FFFF. When partitioning the device, partitions are assigned memory from lower addresses to higher addresses. So, starting with an empty RL (no partitions), you must create the "indirect-reu" partition first, followed by any RL-DOS partitions and the "rl-ram" partition. You must also make sure that the "indirect-reu" partition is the same size as your REU. 512K is 2048 blocks. A note for deleting RL partitions: delete the ones that were last allocated first. You have the option of installing or not installing either of these partitions. If either is missing, ACE will simply work without it. You'll want to be careful about throwing the Direct switch if you don't have your REU "protected" with an "indirect-reu" partition. (with other REU applications also). One note about using RAMLink memory: ACE can transfer data from it at a rate of 16 microseconds/byte (63,920 bytes/sec), but the cost of starting each transfer is 1 millisecond (which is absolutely terrible). Comparatively, an REU will transfer at a rate of 1 microsecond/byte (1 Meg/sec), with a setup cost of about 60 microseconds. So, you'll get the best performance out of your REU by accessing it directly, rather than indirectly through a RAMLink. For internal memory, the 64 has only one 64K internal bank, whereas your 128 can have either 2, 4, or 8 (128K, 256K, or 512K). The internal 128 memory above 128K are accessed according to the articles in TwinCities-128 Magazine. Since I don't have expanded internal memory for my 128, I haven't been able to test the expanded internal memory code. Hopefully, someone will let me know if it doesn't work. If it doesn't, then set your configuration to disallow the use of the expanded internal memory. When ACE starts, it determines the size of internal and REU memory by writing special values in the same locations of each bank and looking for readback failures or wrap-arounds. However, after testing a bank, the original contents of the test locations are restored. So, the testing process is completely non-destructive. ------------------------------------------------------------------------------ 5. DEVICES 5.1. COMMODORE CHARACTER DEVICES These are regular Commodore character-oriented devices, which really only includes the printer right now. The standard Kernal calls are made for all I/O. These devices will behave the same way they always have. 5.2. DISK DEVICES 5.2.1. COMMODORE DISK DEVICES Regular Commodore disk units are accessed in the same way as character- oriented Commodore devices, except that disk devices also support special operations such as directory listings. The standard Kernal calls are used and so are the standard Commodore-DOS incantations for operations such as deleting (scratching) a file. You can use the "dos" command of the command shell to send special Commodore-DOS commands directly to these devices. 5.2.2. CMD DISK DEVICES For CMD disk devices, support has been added to the kernel to request a "long-form" directory listing, including the date and time of last modification of all files. This allows ACE to pass this information onto application programs that request a directory listing from the CMD device. Special support is also included for interpreting directory and pathnames. The rest of accessing CMD disk devices is handled exactly the same as for regular Commodore disk devices. 5.2.2. RAMDISK DEVICE The Ramdisk, as currently implemented, has one major restriction: flat filenames. I.e., subdirectories are not currently supported. To make up for this deficiency, you can have as many ramdisks active in the system as you like. Setting a device to be a ramdisk in the system configuration is very easy: just change the device type code to the ramdisk type (code 4). When the system initializes, the kernel will scan the device configuration and initialize every ramdisk that you specify. Each initialized empty ramdisk costs 512 bytes of far memory storage. All of the standard disk device operations are supported for ramdisks, except, of course for "mkdir" and "rmdir", since subdirectories are not implemented. The operations include: open for read/write/append, read, write, binary-load (for loading programs), remove, rename, directory open & read, change directory (to device), "devinfo", and "isdir" (see the ACE-128/64 Programmer's Reference Guide for further descriptions of these operations). The factory-default configuration for ramdisks is to have two of them: devices "m:" and "z:". The intention is that you will use device "z:" for storing your often-used programs and "m:" for your general storage. You can store executables on a ramdisk and they will load very quickly. For this reason, the factory-default executable search path is "z:,a:", meaning that device "z:" will be checked before device "a:". To get good use out of the ramdisks, it is recommended that if you have a 64 then you also have an REU or some other memory expander. Without any memory expansion, if you have disabled the soft-80 screen you will have 16K of far memory for storing ramdisk data and if the soft-80 screen is enabled, you will only have 6K. With an REU, you can use all of the REU memory for a ramdisk if you wish. On an unexpanded 128 you will have 70K or so for ramdisks. Note that because of the "far memory" organization of ACE, the far memory can be used to store ramdisk data and any other type of far memory storage. Memory utilization is dynamic so you don't have to reserve large chunks of far memory exclusively for a particular purpose. As advertised at the top of this document, the ramdisk driver is capable of delivering a peak reading speed of about 1 megabyte per second. This is for reading a big file that was written to the ramdisk in large chunks, where the file is stored completely in REU memory. For a similar file stored completely in RAMLink memory, the reading speed will be around 56K/sec. The writing speed of files will be approximately the same as for reading files, because of the way the data is organized: the limiting factor is the data transfer speed rather than system overhead. The above figures are for a Fast-mode C128. You should get comparable REU performace from Slow-mode or a 64 and about half the performance in Slow mode from a RAMLink. I don't want to go into too many details, but to get such high performance, the ramdisk driver uses variable-sized disk blocks. Each block can be between 256 bytes and 64K in size and includes 6 bytes of control information. When you perform a write operation, the kernel will write the data out in the largest blocks possible without wasting space. This way, when the data is read back in using a large "read" operation, very little control overhead is needed and the data can be transferred to internal memory in large chunks, and the aggregrated per-byte accessing cost is minimized, almost to the raw hardware-accessing speed. Future expansion possibilites for this device include implementing subdirectories and implementing new types of memory which retain their contents between runs of ACE (but not power interruptions) so that you can have a "permanent" ramdisk similar to the way that RAMLink partitions work. As it is now, all ramdisks are erased when the system starts, so you have to copy necessary files to the ramdisks every time you reboot. 5.3. SCREEN 5.3.1. NORMAL SCREENS The screen has a custom device driver for the 40-column (VIC) screen of both the C128 and C64 and the 80-column (VDC) screen of the C128. Plans also call for a bitmap-eumulated 80-column screen for the C-64. Because of the way that the system has been designed, new screen drivers just easily slip into place. The custom screen driver includes support for the basic text output operation, as well as special full-screen accessing calls to allow for the simplified and standard implementation of full-screen programs, such as a text editor. Such a program would be able to work on the 40-column C64 screen as well as the 80-column C128 screen, with no modification. The Commodore Kernal includes very little support for full-screen applications (only numerous control character codes). For the regular output, only the screen characters and not the colors are used (normally), which allows scrolling to be twice as fast. Outputing characters is also faster because fewer control characters are supported, no translations between PETSCII and screen codes needs to take place, and operations are optimized for speed (rather than ROM size). The display character set has been rearranged to correspond to the PETSCII character codes, except for the "Commodore" characters. The graphics characters have been re-thought for applications. The screen driver also includes basic support for user-windows, which will be taken advantage of in future applications. A prescrolling feature will be implemented later that will cut down on the number of times that the screen needs to be scrolled in order to display text on the screen if the text is printed in one big system call. But, currently, this feature is not implemented. Instead, the screen will be scrolled by a fixed number of lines every time that characters are printed to it (by the "write" system call). For all screens but the soft-80 screen on the 64 with non-reu scrolling, the default for this is to scroll one line at a time. For that screen, the default is to scroll eight lines at a time, to make up for its slow scrolling speed. 5.3.2. BITMAPPED 80-COLUMN SCREEN FOR THE 64 This screen is implemented with a VIC bitmap and 4x8 pixel characters. The screen maps into memory under the Commodore Kernal ROM. The attribute bits of color values act as background color for color cells, and the color cells cover two character spaces, because of the VIC hardware. Also, to cut corners, the window-resizing feature is not implemented for the soft-80 screen. You can only use the entire 80x25 display as a window. There's not a whole lot else to say since it works pretty much like any other ACE screen. Er, I should mention about the character set. The one I have I came up with for a VIC-20 40-col screen program a long time ago but it may not be ideal for the smaller pixels of the 64. I have selected the default screen colors (black on gray) to display the characters clearly. It works best if you turn the brightness up on your monitor, to cut down on the pixel distortion of the 64 display. If you come up with a better character set or screen color combination, please let me know. The format of the character set in memory is a bit unusual. Each character takes four consecutive bytes and there are, of course 256 characters. The characters are in PETSCII order rather than screen-code order like on the regular 64 (the other character sets are in PETSCII order too). The first byte of the four used to represent a character includes the first and second pixel rows of the character in the high and low nybble, respectively. The other three bytes contain the pixel rows in a similar format. If you use a standard 8-bit-wide character set editor, you may wish to write a program to convert from a normal format into my format for your custom character set. I may change the format if I can find a different format that allows better performance. 5.4. KEYBOARD A custom keyboard scanner has been added also. It supports a three-key rollover as discussed in C= Hacking NetMagazine Issue #6. The key matricies will be extended to include a number of standard control characters for things like "page up," etc. Key scanning has been completely taken over to implement the three-key rollover, and to avoid interference with the joystick in port #1. There are a few new keyboard controls. To temporarily pause a listing going to the screen, press the CONTROL key. Output will resume when you release the key. For the C128, the NO SCROLL key is supported in the normal way. On the 64, to achieve the same effect, press the RUN/STOP key while holding down the CONTROL key to pause output until you explicitly re-enable it. To do this, just press NO SCROLL (128) or CONTROL-STOP (64) again. On the 128, the CAPS key is supported in the normal way (with CAPS-Q fixed), and to activate caps lock mode on the 64, press COMMODORE-STOP, and press it again to release caps lock mode. The key delay and repeat rates are not user- definable right now, but they will be. Also, function keys will be application-definable (where the command shell can be considered an application). Something that you may find odd is that the cursor color can be different from the character color. Deal with it. Full input line editing is supported. Lines may be up to 248 characters long, including the carriage return. You can delete the character before the cursor by typing DEL. You can use the cursor LEFT and RIGHT keys to move the cursor on the current input line and any characters you type will be inserted before the character that the cursor is on. CO-LEFT and CO-RIGHT (on the 128 with the upper cursor keys) move the cursor to the beginning and end of the current line. CT-J and CT-K do the same thing. When you wish to generate an EOF (end-of-file) signal from the keyboard, press CONTROL-D. This will only work on an empty line; otherwise, you will get the CT-D character. If you wish to edit and re-enter a previous line, press the cursor-UP key when the system prompts you for an input line. This will recall the previous line. You can press cursor-UP and DOWN to scan through all of the scroll buffer lines you have allocated in the configuration. Buffering each line will cost you 256 bytes of far memory. When you have selected a previous input line, you can edit it or re-enter it just like normal. The instant that you change or enter the line, it becomes the current line. Otherwise, if you don't change a previous line, then you can scroll back down to the current line you were working on before. This is useful for checking some item on a previous line and then continuing with the current line. When you scroll back to the end of the history buffer, the bell will ring if you try to scroll back any farther. Blank lines are not entered in the scrollback buffer. Also, all lines rather than just the command lines are saved (although I may reconsider this later). ------------------------------------------------------------------------------ 6. COMMANDS 6.1. BUILT-IN COMMANDS The following subsections give the low down on all of the executable programs provided with ACE, including the system programs and external user programs. For each command, a synopsis is given, followed by the description. -------- echo [arg ...] Print the given arguments to stdout, with a space between each and a carriage return at the end of the line. -------- clear cls Clear the screen. "cls" is the MS-DOS name and "clear" is the Unix name. This command simply emits a "form-feed" character to stdout. -------- dir [dirname] d [dirname] ls [dirname] clsl [dirname] Display a directory listing of the given directory or of the current directory if no "dirname" is given. This command has so many varients because it is so useful. "directory" and "dir" are synonymous and clear the screen before giving a long-form directory listing. "d" gives a long-form directory listing without clearing the screen. "ls" gives a short-form directory listing without clearing the screen, and "clsl" gives a short-form listing after clearing the screen. Short-form listings include only the filenames of the files in the directory, whereas long-form listings include directory name, file permissions, date and time of last modification, length (in blocks*254 bytes), file type, and filename. On 40-col displays, the date and time fields are omitted. For technical reasons (because they are built-in and space is limited), these commands will not actually display a real data and time. You must use the external program "xls" to see real dates and times. -------- cd [dirname] Change the current working device and directory to the given directory name. If no directory name is given, change to the "home" (initial) directory. -------- cat [file ...] Display the contents of the named files to stdout. If no files are named, then input is taken from stdin (normally the keyboard). -------- exit x Exit from the command shell. EOF on stdin (normally Control-D from the keyboard) has the same effect. If the current command shell is the initial one started by the system (process #2), then ACE will exit back to BASIC. Otherwise, the command shell will exit back to the program that invoked it. -------- dos command @ command Give a Commodore-DOS command to the current device (OPEN1,dv,15..). Both "dos" and "@" are exactly synonymous. -------- path path dirname ... Display or set the path to search for searching for external programs. "path" alone on a command line displays the current search path, and "path" followed by arguments will set the search path to the following arguments. -------- sh Invoke a sub-shell. Currently, arguments are not accepted. The subshell will accept its commands only from stdin. ------------------------------------------------------------------------------ 6.2. SYSTEM PROGRAMS ace This is the main loader. It determines whether it is running on a 128 or a 64 and then loads and runs either "ace128" or "ace64" below. -------- ace128 ace64 These are the kernel programs. -------- config The system configuration program. This is not a user-executable program; it is loaded and executed while the system is bootstrapping. This program loads the "config.sys" and "ace-charset" files, initializes the dynamically allocated memory, and sets the date. -------- config.edit The configuration editor written in BASIC. LOAD and RUN it directly from BASIC. Full-screen interface. Same program runs on either a 128 or 64. -------- sh The command shell. ------------------------------------------------------------------------------ 6.3. EXTERNAL PROGRAMS cp [-f] file destfile cp [-f] file ... directory A file copier. Operates like the Unix file-copier program. If you give two filenames, will copy the first file to the second name. If a number of file names are given and the last argument is a directory name is given, will copy all of the files, retaining their names, into the given directory. If a file that you want to copy to already exists, then you will be prompted for whether you want to overwrite the file: yes, no, all, or quit. Answering Yes will overwrite the file, and continue onto the next file. Answering No will abort copying the current file and continue onto the next file. Answering All will have the same action as Yes, except that it will never ask your permission again; it will always assume Yes. Answering Quit will abort the entire copy operation without disturbing any more files. If, on the other hand, you use the "-f" option (force), then the command will overwrite existing files without pestering you for permission. Or, if the stdin file stream is not connected to the console, then the "force" option will be presumed. I would really like to get a "-r" (recursive) option working. Maybe in an "xcp" variant. -------- rm file ... File remover (scratcher). All named files will be deleted. -------- mv oldfile1 newfile1 ... oldfileN newfileN File renamer. For each pair of names, the old name will be changed to the new name. If the new name already exists, then the program will report an error. This uses the crufty Commodore rename DOS command, so don't even think about renaming a file that is not in the current directory or "moving" a file between directories. -------- mkdir flatDirName Create a new subdirectory in the current directory. The given name must be "flat", i.e., it is just the name like "dirname", without any "/"s or ":"s. -------- rmdir flatDirName Remove an existing empty subdirectory in the current directory. -------- xls [-[c][l]] dirname ... Same as the built-in directory and ls commands, except this one will actually display real dates and times. Also, this will display the number of files, number of file bytes, and number of bytes free at the end of a long-form listing. The "-l" flag means to give a long-form listing; otherwise, a short-form listing will be given. The "-c" flag means to clear the screen before giving the listing. The built-in directory listing commands will be removed from the command shell and be replaced with this one after I do more fiddling with the command shell. Note that you can get a crude directory listing with "echo *". -------- uuencode file ... A uuencoder. The uuencode program sends its output to stdout, so you will usually want to redirect stdout to a disk file. This output will be in Petscii characters, to work with the other text utilities. If you wish to have the output in Ascii, then you must run it through the "tr" program (below). -------- uudecode file ... A uudecoder. The uudecode program will accept either Petscii or Ascii files and is able to extract multiple files from one input file. Extracted files are put into PRG files. -------- bcode [-help] [-v] [-u] [-m] [-l max_line_count] [filename ...] Encode the given files into BCODE format. This format, like uuencoded format, is used for transmitting binary information through a text-only medium. The "-help" flag is used to display "usage" information to stderr. The command will exit after encountering the flag, before doing any work. The "-v" flag means to give "verbose" information about what is going on. The "-u" and "-m" flags instruct bcode to output in either Unix (Ascii-Lf) or MESS-DOS (Ascii-CrLf) format. The default is good ole Petscii. The "-l" flag and value allows you to specify the maximum number of bcoded lines to include in each segment of the bcoded data. When this flag is used, output is sent to special output files rather than to stdout (where it is usually sent). One segment is sent to each special output file. These special output files are named after the file being encoded, appended with a ".b" followed by the at-least-two digit segment number. If the full name would exceed 16 characters, the "basename" is truncated. If the source file includes a path, the path is ignored and the special file is put in the current directory. For example, bcode -l 800 b:junkfile would put the bcoded segment data into "junkfile.b01", "junkfile.b02", ..., "junkfile.b99", "junkfile.b100", etc., in the current directory. Each line of bcoded data contains 72 characters (which represent 54 raw data bytes), so 800 lines will produce 59200 bytes of output (counting CR and LF at the end of each line), which is a good size for posting or for mailing to brain-damaged mailers (under 64K). The max_line_count does not include the two control lines in the bcode format. If you include filenames on the command line, then input will be taken from them in turn. Otherwise, input will NOT be taken from stdin and no work will be done. You may include many filenames (and associated aliases) on a command line to create a BCODE archive (which should be suffixed ".bca"). If you specify that a file is to be broken into multiple segments for encoding, then last segment may be of zero length. This is not an error and will be decoded correctly, although it may be a bit of a pain. -------- unbcode [-help] [-i] [-v] [-d] [filename ...] This is a full-blown BCODE decoder. It will read BCODE data from files named in any order and reconstruct the original binary files that were encoded using the BCODE program above. If the "-help" flag is specified, usage information will be given and the program will exit. The three other flags are used to request different levels of operational information: informative, verbose, and debugging. Informative messages include when a file is completely pieced back together, verbose information includes when a file is opened or closed, and debugging information includes a dump of the internal "have" table that keeps track of which segments of which files the decoder currently has. Currently, informative and verbose information is hard-wired on. Intermediate segments are decoded immediately and placed into temporary files in the current directory with names like "0BC00001", with different numbers. These files are created and deleted as needed. Between runs, if there are any files that have not yet been completely pieced together, the "have" information is saved into "0BC-STAT", which can be listed to see what is in the temporary files and which segments of the files are missing. An example of its contents would be: 00001-00001 beg 0000001223 0BC00002 filea 00001-00001 beg 0000540122 0BC00004 fileb 00003-00003 mid 0000002832 0BC00001 fileb 00005-00005 end 0000000023 0BC00003 fileb The first two columns with the dash between indicate the range of segment numbers that are contained in the temporary file. The next column gives the interpretation of the temporary file, indicating if it is the beginning, middle, or the end of the complete file being decoded. The next column gives the length of the temporary data (used for error recovery). The next column gives the name of the temporary file, and the final column gives the name of the file that the "fragment" belongs to. The fact that the status of decoding is kept between runs means that you don't have to have all of the segments of the final file(s) present at any one run. Error checking is performed on each segment as it is being decoded, and if an error is encoutered, the segment will be ignored. Because of the "incremental decode" feature, you can obtain correct copies of the segments that were found to be in error before and run them through again. This program will recover from all errors in the input data, including one tricky case that the C unbcode program released earlier before could not. The only ways that things can get fowled up are if unbcode has access problems to the temporary files, or if you STOP the program at an inopportune time. To recover from all errors, you just have to delete all of the "0BC" temporary files, including "0BC-STAT". During decoding, this program will overwrite existing "0BC" files or files being decoded. -------- crc32 file ... CRC32 *B* generator. The numbers generated by this program match CRC32 value generated by other programs, such as PKZIP and ZMODEM. This program is used to verify that files have been transported from place to place correctly. The program uses a table-driven byte-oriented algorithm, so it executes faster than the older (crc32a) program. -------- crc32a file ... CRC32 *A* generator. The numbers generated by this program DON'T match the CRC32 generated by other programs, such as PKZIP. However, it will always match itself. The program uses a brute-force bitwise algorithm, so it is relatively slow. The program is included for hysterical (er... historical) reasons. -------- wc file ... Word counter. Counts the lines, words, and characters in a file. To count lines, the program simply counts carriage returns (code 13 decimal). A word is any non-whitespace character(s) between whitespace characters. Whitespace is defined as the characters SPACE, TAB, and RETURN (codes 32, 9, and 13 decimal, respectively). If multiple files are specified, totals will be reported. -------- grep [-[i][v]] [^]substr[$] file ... The "i" and "v" flags are optional. "i" means to ignore the case of letters in comparisons and the "v" means to invert the search - display lines that do not match the pattern. The substring may begin with "^" which means only to check for the string at the beginning of a line, and may end with "$" which means only to check for the string at the end of a line. Both "^" and "$" may be used at the same time. There is no escape character, so you'll have problems trying to seach for the two anchor characters in the files. One or more files may be specified to be searched. If more than one file, then the name of the file will preceed each line printed that matches. Output goes to stdout. Some examples follow: grep hello hello_world.c grep -v '^$' file1 >file1.noblank grep -i crAiG Hack* grep -iv 'the$' file2 The first example simply searches for the string "hello". The second example removes all blank lines from the input file. The third example searches the Hack1, Hack2, Hack3, Hack4, and Hack5 files (for example) for the word "craig" which can be in any case (eg. "Craig" would match). The fourth example displays all lines that do not end with the word "the" in any case (eg. the second line of this paragraph would be omitted). Some limitations of the program are: only the first 2048 characters of a (really long) line will be considered, lines may not contain the character code $00, and the last line of the file must end with a RETURN (or it will be ignored). -------- tr [-fromset2toset] file ... Translate files from one character set to another. Character sets supported are: Petscii, Ascii-CrLf (MS-DOS), Ascii-Lf (Unix), Ascii-Cr, and SpeedScript. "fromset" and "toset" in the synopsis above may be any of: "p" (Petscii), "a" (Ascii-CrLf), "al" (Ascii-Lf), "ac" (Ascii-Cr), "s" (SpeedScript), "c" (Commodore == Petscii), "u" (Unix == Ascii-Lf), or "m" (MS-DOS == Ascii-CrLf). The the character set specifiers are separated by the character "2" (meaning "translate to"). If the translation specification argument is missing, the default of translating from Ascii-CrLf to Petscii is used. Input is taken from the files and all output goes to stdout in order. Example: tr -s2u file1 >file1.unix Translate from SpeedScript format to Ascii-Lf (Unix) format the contents of "file1" and put into file "file1.unix". The name "tr" is used (a Unix utility) because the functionality of this program will grow to include that of the Unix "tr" utilitiy. -------- sort [-[i][v]] [+column] file ... Sort utility. Currently uses a sucked-out insertion sort algorithm. Will be extended to use the "Approximation Sort" algorithm, which has between O(N) and O(N^2) performance (close to O(N) for random data). Makes use of dynamically allocated memory to store large files internally. The "i" and "v" flags are optional. "i" means to ignore case of letter characters in comparisons to determine order. The "v" flag means to inverse the order of sorting (put into descending order rather then the usual ascending order). The +col field is optional, and if present, gives the character position of the start of the sorting key. The default starting position is 1 (the beginning of the line). A TAB character will be interpreted as any other character. If multiple files are specified, they will all be merged together and then sorted as a group. Sorted output goes to stdout. If the program dies in the middle of its operation (eg. out of memory), all files owned by the program (process) will be closed and all memory allocated to the program will be reclaimed. This is also true for all other external programs, since this is implemented in the kernel. -------- wrap file ... This is like the cat command, except that lines longer than 75 characters will be word-wrapped into multiple lines. -------- date Display the current date. The format is: "YYYY/MM/DD-HH:MM:SS.T", in 24-hour time format. This command will be extended to display in "human mode" (eg. "Tue-13-Jul-1993 05:49:53 pm") and to allow you to set the date. Currently, the date will only be set when the system starts up. -------- forty Switch to the 40-column (VIC) screen on the 128. This also switches the processor into slow mode. -------- eighty Switch to the 80-column (VDC) screen on the 128. This also switches the processor into fast mode. This command will also be used to switch to the soft 80-col screen of the 64 when that feature is implemented. -------- read file ... File reader. Useful only for testing how long it takes to read a file. No output is generated. -------- mem Display bytes of dynamically allocated memory that are still free. Also displays a map of the pages allocated on the most recently used bank and the process number of the mem program. -------- as file DEMO assembler still under development. Only the tokenizer is implemented. It will scan through the given file and spit out reams of tokens in the example formats: i:hello,= c:= n:87125 s:Now is the time where the "i" line gives an identifier and the character following it, the "c" line gives an uninterpreted character, the "n" line gives an interpreted number (it accepts 32-bit numbers in decimal, hexadecimal, and binary), and the "s" line gives a character string that was enclosed in quotes. The tokenizer is designed to be very efficient (although it currently can only operate as fast as the Commodore Kernal CHRIN function). Plans for this project include a one-pass assembler that will use dynamic memory to be able to do very large assembles, with full support for 32-bit quantities, conditional assembly, macros, and eventually linkable code. -------- vi [file ...] DEMO of ZED: displays the main screen, reads the named file into memory, and prints it, soft-wrapped to the screen length, to stdout. It is called "vi" here (to use a grotesque misnomer) to avoid name conflicts since you may already have a file named "zed" in your ACE directory (like I do). The new ACE-Zed will have more fundamental features than the original Zed-128 program, including auto-wrap lines, unlimited line length, horizontal scrolling to 240 characters, character-oriented commands rather than line-oriented, and multiple file buffers with split-screen disply. Plus, it will also work on the 40-col screen of the 128 and on the C-64. Big plans. -------- hello This is just a dippy little program that prints out a "hello world" message. It is included so programmers may examine it and its source file to see how simple ACE programs are organized. -------- window [columns [rows [startColumn [startRow]]]] Sets the window size. If no arguments are give, it will report the current window dimensions. If one or more arguments are given, they will be used as window arguments as above. Missing arguments will be taken from the current window's settings. Screen coordinates start at column 0 of row 0 and go to the full size of the screen. You will get an error message if you try to set up an illegally sized window and the current window will remain unchanged. After successfully setting a window, it will be filled with a checkerboard pattern to indicate the size of the window. Just clear the screen to get rid of this. -------- more file ... Full-screen file viewer. At the prompt, press SPACE to view the next screenful of a file, RETURN or cursor-DOWN to view the next line, N to go onto the next file to be viewed, or STOP or Q to exit the viewer. Future expansion possibilities include a "go back" command and an ASCII-translation mode. -------- unkar file ... KAR (Kevin's ARchiver) dearchiver, intended to be used for extracting the ACE source code, although you may find this archiver format useful for your own purposes. Gotta put together a "kar" encoder. Unfortunately, encoding will be a two-pass operation. ------------------------------------------------------------------------------ 7. LATER, DUDE To-Do List: - Get the ACE version of Zed going. - Re-organize the RAM0 memory to make more free for applications. - Fix up the shell-script features of the command shell, autoexec feature. - Allow optional "permanent" ramdisk data with specially reserved REU and expanded-internal memory and RAMLink partition. - Add hierarchical directories to the ramdisk and complete its implementation. - Add windowing to the soft-80 screen. - Complete the prescrolling feature. - Incorporate limited 128-mode burst support & adapt Little Red Reader for ACE. - Put limited graphics support into the kernel & adapt VBM bitmap viewer. - More work on the assembler ("aceSembler ?"). - Trim down the kernel size. It has acquired a bit of "software bloat". This system is Public Domain Software. It is not required, but it would be appreciated if people who use this software regularly would send a postcard featuring a picture of some local attraction/scene to the following snail-mail address. You only have to do this once. You can send me money too, if you want, but this is strictly optional. My new semi-permanent address is: Craig Bruce 4-249 Cedarbrae Ave. Waterloo, Ontario Canada, N2L 4S8 If you have questions, comments, suggestions, or bug reports, you can contact me at the following e-mail address. Keep on Hackin'! -Craig Bruce csbruce@ccnga.uwaterloo.ca "Mental Inertia: A mind in motion will tend to stay in motion, and a mind at rest will tend to stay at rest, unless acted upon by some outside kick in the ass." ------------------------------------------------------------------------END---