|
Z80 Space-Time Productions Single Board Computer
Technical Support Information - BASIC 4.7A For those of you looking for a programming language to run on your Space-Time Productions Single Board Computer - look no further! I have sucessfully ported over BASIC for the Nascom Computer! This version of BASIC takes up nearly 8K bytes of memory, so you'll need to burn it onto the appropriate EPROMS for your system. If you are using this with your Space-Time Productions board, you will need to split your assembled file into two files and burn them onto 2732 type (4K Bytes x 8 Bits) Eproms and install them into the sockets for Roms 2 and 3. Also, you'll need to set the jumpers on your board for these roms [See Hardware page for more info]. BASIC utilizes program 'calls' for the Monitor rom which you most likely purchased along with the other IC's when you got your board. If you don't have a Monitor rom, you'll need to download it as well. For those of you who have expanded the RAM memory on this board [or may be porting this over to another Z80 system], I have included a version for you as well. The BASIC Language This BASIC uses old style line numbers and commands, and is one of the earlier simplified variants of the language. COMMAND WORDS:
Uses standard BASIC language conventions, including line numbers:
10 FOR A=1 TO 10 Line numbers may run in any increments but are limited from 0 to 65529 (yes, you may use "0" as a legitimate line number). Variables:
DOWNLOAD BASIC
Both versions require Ron Weiss' Monitor Rom in the ROM0 Socket. However, those of you porting this over to your system will no doubt want to create your own RS-232 Serial port system calls, but I have endeavored to make this as easy as possible. Installation Tips: If you are going to burn this to ROM for the Space-Time Productions board, you will have to split the file in half from $1000-$1FFF, and then create a second file for $2000-$2FFF. You should burn each file onto a 2732 ROM, place ROM1 in the socket for IC-22, ROM2 in the socket for IC-23. You will need to set the jumpers in the jumper boxes below the roms (near the PCB edge) to accomodate the 4K x 8 EPROM. See the Hardware page if you need help with this. To start BASIC, the original Ron Weiss Monitor command "NI" vectors the Z80 over to $1000. If this seems weird, you my simply use a "G1000" to Goto $1000 from the monitor prompt.
For you hackers and do-it-yourself-ers: This BASIC assumes a TTY data terminal interface; most of you are using your Z-80 computer with a PC running Hyperterminal. This interface makes it inviting because there is little to change to make it work with most any Z-80 system. There are 3 routines in the .ASM file you'll have to change:
The routine CKSIOA loads the Transmit Buffer status bit into the Z flag and the Receive Ready flag into the CY flag. This routine is called several times througout BASIC to test for "ESC/BRK", so you will want to make sure either your routine sets the flags accordingly, or modify the rest of the code so it responds better to your UART. What it took to port over from Nascom Computer to the Space-Time Productions Computer:
What follows is a lengthy discussion of the development of this rendition of BASIC: Background and Research After I got my Space-Time Z80 built and hooked up to the D-9 RS232 terminal port on my PC so I could communicate with it, I soon made a discovery: Machine code was fun, but in order to build a program that was elaborate enough to do some bigger jobs, one needed some help from beyond the borders of Assembly language. Assembly is great as far as speed is concerned, but it is cumbersome. If you are working with I/O and hardware and need to experiment with changes 'on-the-fly'; machine language is NOT the way to go. You have to code the program in a text editor, save it as an .ASM file, convert it to Intel Hex with the assembler (I use TASM - it's great), check the program .LST file for errors that occured during compilation. THEN you get to load it on the Z80, and then hope it works when you Goto it. I needed something live that I could change a few lines inside the Z80 program instantly and retry the program. [ I still have the memory of my first days in 1983 with my shining new Commodore VIC-20 and it's amazing on-screen BASIC editor playing around in my head - it's a good dream]. Also, if you need some better math than 16-bit integer, you'd better be prepared to embark into floating point stuff. Also, you have to build up some pretty good libraries of routines to call in order to handle the more repeated and mundane tasks and make system calls to those routines in order to save some time. Sooo... ...I started searching for a language interpreter. It would have to be burned onto EPROMS and reside on the S-T Z80 board. It would need to handle floating point math, and be listed in a form that I could text-edit for modification. I was familiar with BASIC; it's been like an old comfortable friend, having written a little in Visual Basic, miles of QBASIC 7.0 (Compiler) applications at Brownwood Regional Medical Center, and a ton of other stuff on my old Commodore 64 and even the VIC-20 back in the day, as well as a few hardware-specific test programs on the Tandy TRS-80 (affectionately called the "Trash Eighty" even by the management) when I was with them (see HISTORY). So I decided that BASIC was probably the way to go, for me anyway. Along the way I had also done some short investigation into a few other languages: PASCAL (obscure, data structure oriented in purpose), the wholly muck-driven FORTH ("Program in FORTH, backwards to think must you, my young Jedi. Mmmm."). [By the way, I - after being a little humbled here - have included a FORTH interpreter for this computer on another menu selection, but it definitely requires a Memory Expansion.] TINY-blah blah whatever I located several variations of "TINY"-(put your favorite language name here), easy to find and source code is well-documented. Most of which were ok for what they were designed for, but just didn't have a lot of horsepower (16-bit math only) or I/O control to mention a few of their shortcomings. Normal BASIC has nice, generic OUT port,data and IN port commands. Just to be certain, I took an Intel 8080 version Tiny-BASIC and converted the instructions over to the Z80 TASM assembler. As with any program you try and hand-enter, it had several bugs, the best of which caused the SP to overwrite every available address in a matter of milliseconds. I decided I had wasted enough time on that, and it wasn't going to be much good to me anyhow. Ron Weiss had emailed me a file which he thought was TinyBASIC specifically for his computer - from what I could disassemble from the .BIN file, it was sure enough a version of TinyBASIC, it also took the place of the monitor in Rom 1, having all the RST calls configured for the ST hardware. The problem with this was that the code mysteriously trails off as if it were only part of the whole program (maybe it was supposed to run on two separate 2716 ROMS, and the .BIN file was only the first half). It was all that he had available, and I wasn't too crazy about a BASIC with only 16-bit math anyway, so I decided to file that in my folder and to forge on with what else I could find. [Ron was also kind enough to send me the 8279 version of the system monitor in .BIN format, which I disassembled and fully commented for future use. This is posted over on the hardware page and download section if you care to see it. Some great stuff in there for the 8279 - I even figured out which bits he had hooked to what data pin on the 8279 to drive the 7-segment displays to approximate ascii text. Nice compact coding, whomever created that.] So, at this point it was decided: BASIC was in, everything else was out - the quest was begun. Searching the Internet for lunch-hours on end, I rambled through tons of CP/M code, various breakdowns of Tandy's Z80 BASIC from 4K ( 16-bit math only, with 3 whole error codes "WHAT?", "HOW?", and "SORRY" ) to 16K versions (very convoluted coding, too hardware specific because of video control to be of any use to me). Tandy Level II BASIC was about as close as I could get to something usable. TIMEX (Sinclair), it takes a licking, and keeps on ticking! The Timex-Sinclair is a cool computer, so small and yet a big genie inside. The coding is a little too weird for me (Timex-Sinclair above 4K ROM uses the RST function plus a following pseudo-command byte series to do all math calcs, was a very odd way to code things, very difficult to pick up anything useful there, how anything really works. To worsen matters, they used non-ASCII standard keyboard and video codes, and strongly affected the method used to drive this computer, zero bytes are tested for often). It's not a bad computer at all - especially for the size and during the era it was created - it was a work of art, and a lot of people did some really interesting things with it. I still remember taking all afternoon to load Star Trek from cassette and played it for 10 minutes before it crashed and I thought it was fantastic [1983]. As close as two years ago I actually printed the entire source code for both the 4K and 8K versions; couldn't get very much use out of it, [ but located the 16-bit integer math code in the 4K - it looks a lot like the Intel 8080 Tiny-BASIC's math routines. ] so the wasted reem of printouts reside in a huge binder on my shelf at home. Make me an offer... CP/M is everywhere on the Internet these days. You can read source code for and download whole software packages that cost users what still constitutes a fortune in greenbacks when they first released. Now they are floating free in cyberspace for the asking. I have and continue to read a lot of code, and I'm not sure I'm entirely done with CP/M yet, but the configuration of having rom from $0000 to $00FF and then reconfiguring the hardware so the ROM appears again in the upper memory blocks ($D000-onward or thereabouts) just seems ludicrous to me. Why didn't they put the entire op system in the lower 32K and just bank switch ram in the upper 32K all day long? So simple a solution. No one ever consulted me. So CP/M has a huge library of routines, codes, the infamous 'patches', and whole applications, probably bigger then anything else that has come along to date. I keep that in the back of my mind, but no version of BASIC ever surfaced that I could easily ported over to the Space-Time Productions Z-80. I liked the ASM program, but it was geared to the 8080. Onward I searched... NASCOM Arrives on the Scene I finally stumbled over a couple of websites devoted to the British product: The NASCOM computer. This is a wonderful product, and still provides a lot of people with many hours of usefulness and entertainment. [See, I understand this obsession better than you know.] There are even quite a few good emulators for the Windows-based PC for this computer, so it lives on well into the PC age. It had several advantages over the other hardware forms I had seen, it was a pure source code driven device, that is; there were only a few funky RST/with function byte things to look at, and everything else was super-well commented to follow along. There seemed to be a natural order to the software this computer could run. I liked it. On one of these sites, I found the 4.7 Version of Microsoft BASIC, written especially for the NASCOM. I was intrigued at first, then I got really excited - I had found just what I needed. It had the most wonderfully documented and commented .ASM file that I had found to date. It was the right size (8K), it had routines that were designed to handle pure ASCII input and output, just right for communicating with the rest of the known universe. So I downloaded the ASM file. Grabbing a (another) reem of paper, I printed the entire 100 plus pages of source code (but at 8-pt Courier font this time), and started to work. First thing was to realize that many of the routines for the cassette tape recorder, CRT screen and keyboard were hardware-specific to the NASCOM computer, quite useless for the Space-Time Computer machine. There were also routines in that that check to see which machine it is running on, and makes the appropriate system calls to that machine's 'bios' rom. One NASCOM varation uses the RST plus data byte to perform system calls, much like CP/M. So I get the red pen in hand, and scratch all that out. Leave anything that referred to the TTY. Bear in mind that any place in the code called by a proper name had to be checked against the entire program to make sure it wasn't being called from elsewhere as well. Many hours of using Wordpad to search this file. Next I noticed the tables for the BASIC instructions, routine addresses, error codes, and token tabless were pasted up at the front of the program, or right smack in the middle of the code, and that some of the routines were just jammed in the middle of two unrelated pieces of code. Continuity was poor (and I'm a stickler about that). I tried to re-arrange all this in a way that makes sense, combining the floating-point math routines into one modular area, placing all the Space-Time specific stuff that I had to add at the end of the assembly (before the lookup tables I had placed at the end), and making better documentation marks or clarification as I went and discovered (from the line-by-line comments) what that particular subroutine was up to. There were some other odd routines in there that looked like the original programmers left a few things lying around to experiment with, but weren't called from any command or any place in particular. Redlined those out, too. On the NASCOM there is a 'BRB' (Big Red Button) that is tied directly to the NMI on the Z-80. This is the Non-Maskable Interrupt. When it is ascerted, the processor must stop whatever it is doing, PUSH the next instruction address on the stack, and JP to $0066. In the case of the NASCOM, this vector points to another JP in RAM; and when BASIC initializes, it sets the vector to a routine in the BASIC rom that simply sets an internal variable to $00 or $FF, then RETN's from the NMI. When BASIC is executing, at the end of each line, it would glance at the variable to see if the NMI had been inserted during that line's execution. If it had, BASIC stopped execution and returned to the prompt. Personally, I'd have skipped the variable and just revectored the NMI to clean up the stack and JP to the "Ok" prompt. But there was quite a few lines used to set/reset the NMI variable and to read the variable and interact with it. I chose to X these routines all out, since the S-T uses the NMI to 'break' back to the Monitor Rom. I do have a switch wired to the NMI, but I use it to break out of assembly programs careening out of control. Next up there were some things that just didn't cut if for me. The main thing being the terse Error codes.
This was a message that I figured would come out anytime during the program if it was written badly enough; but it actually stands for "Bad Subscript". There were a few others that just didn't help a lot, like "/0 error", "FN" which could have been Function or File Name. It was just a little too lack-luster for my tastes, and I have seen plenty better. There was a lot of room left in the 8K space after removing the NASCOM-specific hardware routines, so I re-coded the Error Handling routine, and provided a code number and a full text string for each error. Now, when you have a problem, you get the Full Meal Deal:
There were also some stack and memory related errors I noticed that would crop up and they were all vectored to called the same ambiguous "OM" error, so I broke those out, gave them a new error code of their own, and continued onward. Things were on the upswing already. One of the biggest hurdles to overcome was the memory mapping layout. In fact, I had to code the Stack, System Variables, BASIC Variable and Program Text Storage, plus Array and String storage in the same order it was on the NASCOM, or the coding just wouldn't work. It is coded that way in a couple of places (to see if a string appears in the BASIC text as part of the program, or before as in a directly typed command i.e.- A$="Blah blah". Part of this hurdle is that the Space-Time Productions machine is woefully short on ram from the get-go (2K total onboard). I think this board was designed originally as an industrial controller, for very specific devices - most of the code was placed on specific ROMs and there was need for only a little scratch-pad ram to perform calcs and keep readings in. Mr. Simon probably never imagined someone would be running a full-blown programming language off this board. Since memory is so small, I built my own memory expansion PCB that uses two Dallas Semiconductor 32K Non-Volatile Static Rams, one with a built-in time-keeping set of registers. I feel like other people who own this board have probably felt the same need as I, so I have posted the schematic and technical blah blah in a separate page (see menu bar). I created a second version of BASIC to accomodate those who have expanded the ram on their systems, and for those vintage electronics gurus that enjoy a good hacking experience. I've added a memory test for BASIC that scans anything from $4300 upward to see if it is a valid, writeable ram location. If it can write and read the location, it continues checking upward until it hits a bad spot or until HL rolls over to address $0000 (this would indicate a full complement of ram from $4000 through $FFFF). If it hits a bad spot prior to $FFFF, say at $8000 for instance, it simply sets that location -1 (i.e. $7FFF) up as the RAMTOP and continues setting up house for BASIC to operate from. For those of you who don't know a soldering iron from a clothing iron, and could care less about building a circuit board, wirewrapping or anything else for that matter, and hey, if you don't want to add any memory, I have built a version of BASIC just for you. It doesn't waste any time scanning for RAM or any of that, it runs fast, but 2K just isn't enough RAM to do much more than a small simplified program. Notes below on how to conserve space when writing your BASIC programs.
You will probably discover the limitations of this BASIC pretty quickly. For teaching and running small hardware experiments (like driving a stepper motor or something) it will work just fine. Try writing a program that DIM's a lot of string space or something, and you'll see very quickly the end of the road. My best suggestion to you is to find yourself an electronics nerd friend to build you a memory expansion, or to figure out how to wirewrap a Radio Shack circuit board and get busy buying parts. Probably the easiest vendor I have found for connectors and other electronic doobobbers is Mouser Electronics - www.mouser.com ; they have no minimum order and their latest catalog is always online. Good to work with. Back to BASIC... This smaller version of BASIC sets up house as follows:
$3000-$30FF The machine stack runs probably too much room, whatever. I don't want to be accused of running out and crashing BASIC. As I noted above, when you type a line in at the BASIC "Ok" prompt, that line goes character-by-character into the INBUFF buffer starting at $3160 (small version, $4160 big version). This is filled by a routine inside BASIC called TTYLIN which gathers characters from the keyboard, accounting for backspacing (in which is repeats the typed characters on that line in reverse order. Once a CR (ENTER key) is hit, the program hands off to a routine called CRUNCH which detects any BASIC keywords or command words that appear in the line, and converts them to tokens, thus saving a lot of memory space for programs as well as speeding up the execution of a BASIC program at run-time. To see how BASIC stores and reads tokens to its keyword list you may look at this token table [Click Here]. Notice the original DEEK,DOKE, etc are still listed; they have been altered into new commands as noted below. A note about Tandy Level II BASIC After comparing this to the Tandy BASIC (yes, it was also created by Microsoft programmers) it became very apparent from reading their old operating manual that the NASCOM BASIC is similar to Tandy Level II BASIC in a number of very uncanny ways (error message formats, command syntaxes, etc). In fact the Level II Users Manual reads better than the Nascom manual for how to use their respective BASIC's. I have to assume that one of them was ported over to be used by the other; it's just too darn close. The code all fits into 8K worth of Rom on the NASCOM, but requires 12K on the Tandy because of all their video handling, and drivers to recognize a hard drive for DOS operations, as well as the addition of several BASIC commands, so I am guessing the NASCOM chicken came before the Tandy egg, but I wouldn't swear to it. There were countless versions of BASIC that were developed during the mid to late 1970's (most of them in violation of Microsoft's original copyright) for a whole sea of different little computers that were being jammed out to the marketplace. A lot of programmers felt Microsoft (and Digital Research) was trying to do something analogous to JIF placing a copyright on all peanut butter, and went ahead with their work. Other programmers who didn't care for BASIC nor to tangle with the legal juggernaut, took this opportunity to create languages of their own, a few of which are still floating around today in small, dark closets and websites across the world. Things you will want to make note of: LOAD/SAVE I wrote the Intel Hex Save routine, which saves everything from PROGST to PROGND. You have to capture this text into a file while using HyperTerminal or whatever, as it sends it right across the TTY (right along with the rest of the BASIC LISTs, PRINT results, and so on), and save it into a file of your own. LOAD will require that you use Hyperterminal to "Send Text File" and specify the filename you wish to load up. This is set to input from the same RS232 channel as the TTY is hooked to. SAVE* , LOAD* - Saving and loading arrays from BASIC The NASCOM version of BASIC appears to only be able to cassette-save (SAVE*) or load (LOAD*) numeric array variables - not string variables or standard number variables. This didn't seem like a function I needed to preserve. If it were to function at all, it really needs to be able to pass all types of variables to be of any use to anyone. The routines NASCOM BASIC had to perform this actually had their own routines that would direct-drive the hardware (UART) which they connect to the cassette tape ports. This was a little unusual, and put a strain on my porting over this version, because it wanted to speak directly to a particular UART port and IC type. I feel if this is going to be implemented the user needs to be able to pick which serial RS232 channel he/she wishes to use because it depends strictly upon your particular hardware configuration. The board, as is, comes with interfacing only for Channel A, as a TTY. The second channel signals come out to the edge connector, but no signal processing (i.e. for tape, etc) are there. Finally, I decided to ditch this function. I may at some point rig the Load/Save so you can select the second RS232 port on the SIO as a storage device. If that happens, I may re-instate the code for SAVE* and LOAD* for array passing, but it will also have to be able to select any variable from the pile before it gets my blessing... String storage area Although not an actual BUG; In this version of BASIC, String variable space size is not dynamic. BASIC's internal workings do not try to shift the pointers for string space once set. You must know aforehand just how much string space your program is planning on using. If you are using more than the default 100 bytes, you must start your program with a CLEAR command. Garbage collection (performed during a FRE command) will loosen up some of the wasted string space used by processing. It's best to set up the largest possible string space (with the CLEAR command) and to use as few actual string variables as possible. A note about CLEAR: "CLEAR 250" sets the string space to 250 bytes. Something done in their code that was not documented in the instruction manual was that CLEAR also can have a second parameter "CLEAR 100, 16283". The first parameter create a string space of 100 bytes, the second undocumented parameter sets the LSTRAM internal variable address at 16283 ($3F9B). This gives 100 additional bytes from $3F9C to $3FFF for storing your own machine language routine, for use with USR(x). Then it takes the 100 bytes of String space out below this new ceiling (16283). The second parameter directly sets LSTRAM in the BASIC internal variables, and resets all the other memory pointers for it. The LSTRAM parameter is what BASIC uses to see where the top limits for it's reach into ram are for storing strings. They do not necessarily reflect the actual ram in the machine. Since you can move LSTRAM with the CLEAR command, it is possible to 'clear' memory above BASIC for your own use. Nascom BASIC came with several commands that just didn't make the cut. DOKE and DEEK (a double byte POKE and PEEK) used that same crappy signed 16-bit integer format that required you get out your calculator to figure out the actual address or data. DOKE is replaced with VECTOR nnnnn, which sets the location for the next USR(x) jump. DEEK is one of those buggy problems you will read about in just a moment. SET, RESET, and POINT all dealt directly with the graphic screen of the Nascom computer - I have left those commands intact so they may be used later on with a graphic LCD display, etc. but for now they simply collect the parameters and place them into BASIC's internal variable storage, and returns back to BASIC. A function I added allows the use of hexadecimal values in calcs - Very Handy! If you want to set a VECTOR for the next USR(x) command, you can give it directly in hex (e.g. - VECTOR $0283). Most commands that involve calculations can use this, I have noticed it seems to function without error if you put the hex values in parenthesis for processing [ e.g. - PRINT ($34)+128 , or A=5*($8B) ]. Especially useful for use with the following commands:
KNOWN BUGS: I am very happy to announce that as of February 6, 2007 a fine gentleman named Grant Searle fixed both the known bugs I had in BASIC as easily as if he was stirring his coffee. Many, many thanks Grant. The updated versions of BASIC are now posted at the top of this page for download. Click HERE if you do not see a menu frame to the left. This page created September 18, 2004.
All information contained herein that is generated by J.Owens ©2007. |