Specifications

The "Sparky" computer system will be the ultimate 8 bit computer system that we all wanted when the 8 bit machines ruled, but never could afford.  It is designed as a system to experiment with as well as have fun with.  It is not intended to be one of those lame "trainer" boards with an LED display and keypad, boring!

The system is designed around the much advanced eZ80 by ZiLOG.  This processor is like a Z80 on steroids and most certainly would have been the processor of choice in the 80's had it existed.  It is marketed now days as an embedded "webserver" / Microcontroller, but we know it can do much more than serve web pages and be a brain to an Internet appliance.  The eZ80 can directly address 16 megabytes of memory without special hardware or software.  It is also compatible with "older" Z80 code (some minor changes may have to be made).  It also has just about every peripheral interface built right into it!  Great!  That will save a lot on the chip count.

There is only one drawback for the eZ80.  It only comes in a VQFP package that renders it near impossible for a human to solder it to a PC board.  Therefore, the ZiLOG eZ80 evaluation board will be used as a base for the rest of the system.

Those of you without the cash to shuck out for the evaluation board, don't despair.  Zilog now sells the eZ80 on a so-called "Network Module" which has all of the necessary CPU signals on its interface.  Using this module is a cheap way to assemble your own Sparky board.

Sparky's specifications are as follows:

  • The hardware will initially start with an eZ80 (eZ80190) evaluation board from ZiLOG.
  • It will run a custom operating system with BASIC that is loosely based upon the ZX Spectrum BASIC.
  • Keyboard entry via RS232 on the console port.  At first I considered emulating a PS/2 AT keyboard port via two PIO pins on the eZ80, but why do that when there is already a perfectly good RS232 console built in?  There is already a second RS232 port for modems etc.  So I don't see a problem.  Nevertheless, I think I'll program a couple of PS/2 ports in there anyway, as the OS becomes stable.
  • Generalized file system using streams for data transfer.  This will be a major expansion to the original ZX design as it must work for any I/O design, including display and keyboards.  The OS will not differentiate between peripherals as all will look the same to the OS.  It's up to the specific driver code to determine how to handle commands from the OS.
  • The graphical display will utilize high speed serial data to and from the CPU.
  • The system will depend highly on streams for its I/O, including files loading and saving.  It would be a good idea to have a Flash card interface for mass storage.
  • The token table will be increased by removing them from the upper 128 of the character set and expand the character set to the full 255.  The token table will be separated by a 256 command table and a 256 function table, with a special control character indicating which table to use.  This means each token is two bytes long, a special 16 bit character.
The Sparky eZX BASIC Memory Map
Start End Title Description
200000 FFFFFF Available for expansion and memory mapped hardware This is top memory space where RAM can be expanded from the bottom up.  The top 4 megabytes of memory is bank selected to accommodate memory mapped devices without losing 4 megabytes of RAM.  Normally bank 0, RAM, is mapped to the top 4 meg region.  Device drivers are responsible for banking out the RAM and banking in the device and then banking back in the RAM before it returns.  Thus memory mapped hardware is invisible to software.  This design also keeps speed at its maximum as memory mapped devices are not slowing down the CPU due to bus asrbitration.
110000 1FFFFF 1 MB SRAM This is where the system RAM starts for program and variables.
10E000 10FFFF System Variables There is 8K of high speed SRAM available in the eZ80 for use.  This is perfect for the system variables.
10D00 10DFFF Multiply Accumulator RAM I decided to leave this 1K RAM available for the user.  You can use it for the MACC device or you can use it as spare buffer RAM.
100000 10CFFF Available for expansion Because the internal 9K of RAM of the eZ80 is mapped at the top of a 64K page, this lower space in the page is blank.  It could be used for extra memory mapped hardware if you wish.
008000 0FFFFF Sparky ROM Code This is where the heart of the ZX BASIC code is located, and is the location with which must be flashed to once assembled.  Don't worry about the restarts as the boot block code traps them and redirects them to their $0080xx counterparts.  In other words, RST 20 will be directed to address $008020.  Always remember that the interrupt index table must be in page 00 ($000000 - $00FFFF)!  Placing it immediately after the "restarts" would be wise.
004000 007FFF Boot Block Parameter Block This block is used for the boot block flasher and by the C based OS code, which is not used, but resides in protected memory anyway.
003FFA 003FFF MAC Address The MAC address for the EMAC interface.  It also resides in protected memory.
000000 003FF9 Boot Block Flasher This is specific to the ZiLOG eZ80 evaluation board and is required if you want to flash the ROM.  This is write protected memory thanks to jumper J2.
The Sparky eZX BASIC I/O Port Map
0000 0095 Sparky Hardware Reserved These ports are reserved for Sparky hardware incorporated into the eventual design or future designs.
0096 00FF CPU Reserved These ports are reserved by the eZ80 processor for its internal peripherals.
0100 FFFF User Expansion The rest of the ports are given to the user for expansion.  Remember, the eZ80 uses 16 bit port addresses.  The "OUT0" eZ80 assembly instruction is reserved for the operating system and internal Sparky hardware.  Use only the standard "OUT" assembly pneumonic for user hardware.

For development purposes the console RS232 port is hard coded for (now at) 230400 baud 8/N/1 on the console port.  The emulation is ANSI.  You can lower the initial baud rate within the source file "rs232.inc".

ZX Spectrum

What is a ZX Spectrum??  Well it was the original design from which the Timex/Sinclair 2068 was based.  It was the top computer in Europe in the 1980's.  The TS2068 did not fair so well here in the USA as it was not compatible with the Spectrum (unless you had a special ROM or cartridge).

I actually owned a TS2068 in the early 80's and enjoyed it immensely.  My first hardware project was a 64K RAM expansion mapped in the DOCK bank and I experimented with modifying the OS by dumping the OS to the RAM and using a battery backup to retain the data.  I also wrote a BBS program in BASIC and had coded modem drivers in machine code.  The BASIC code was stored in the expanded 32K of RAM in the DOCK bank which left the majority of RAM in the HOME bank for message storage.  The BBS was so popular that it was featured in an issue of BYTE magazine when BBS' had their hay-day.

Go here if you would like to learn more about the ZX Spectrum, or here if you want to know more about the TS2068.

Detailed Specifications

This section is far from complete.

eZX BASIC is not intended to be Spectrum compatible, but only a superset of the original ZX BASIC.  Its basic syntax and functionality is the only thing to remain.

eZX BASIC is a highly streams oriented interpreter.  This facilitates the ability to use custom drivers for any peripheral or display device.  Anything related to I/O will most likely have its own control character to make it easy for a driver to intercept.

LOWER ASCII CONTROL TABLE
Decimal Value Description Full Details
0 Reserved  
1 Command Token start byte This is followed by the command token.  Which is from 0 to 255 for a total of 256 possible command tokens.
2 Function Token start byte This is followed by the function token.  Which is from 0 to 255 for a total of 256 possible function tokens.
3 Reserved Reserved for drivers to define
4 Reserved Reserved for drivers to define
5 Reserved Reserved for drivers to define
6 TAB  
7 BELL  
8 BACKSPACE  
9 Reserved Reserved for drivers to define
10 LINE FEED  
11 Reserved Reserved for drivers to define
12 FORM FEED  
13 ENTER  
14 Number Token Start Byte This is followed by a floating point representation of a number
15 Reserved  
16 INK Control Start Byte This is followed by a 16 bit two byte value
17 PAPER Control Start Byte This is followed by a 16 bit two byte value
18 ELLIPSE Control Start Byte This is followed by a 16 bit signed value for X, a 16 bit signed value for Y, a 16 bit unsigned value for XRadius, a 16 bit unsigned value for YRadius and a 8 bit value for filled.
19 DRAWTO Control Start Byte This is followed by a 16 bit signed value for X, and a 16 bit signed value for Y
20 PLOT Control Start Byte This is followed by a 16 bit signed value for X and a 16 bit signed value for Y.
21 FONT ADDRESS Control Start This is followed by a 24 bit unsigned value for the address of a font table.
22 FONT SIZE Control Start This is followed by an 8 bit width value and an 8 bit height value.
23 TEXT MODE An 8 bit encoded value indicated below for the text output mode.
 
Bit 0 Bit 1 Bit 2 Bit 3 Bit 4 Bit 5 Bit 6 Bit 7
Bold Italic Underlined Inverse Outlined Crossed Out Greyed Reserved
24 Reserved Reserved for drivers to define
25 Reserved Reserved for drivers to define
26 Reserved Reserved for drivers to define
27 Reserved Reserved for drivers to define
28 Cursor Left Moves the cursor one position to the left.  Does nothing if at the left edge of the output device.
29 Cursor Right Moves the cursor one position to the right.  Does nothing if at the right edge of the output device.
30 Cursor Up Moves the cursor one line up.  Does nothing if at the top edge of the output device.
31 Cursor Down Moves the cursor one line down.  Does nothing if at the bottom edge of the output device.

CHARACTER SET

The balance of the character set is the standard ASCII set with those above 128 undefined at the moment.

TOKENS

This is a preliminary (incomplete) list.  Many may be moved to different index positions to give the ability to group by type.

COMMANDS
Index Name Syntax
Description
0 ARC ARC X,Y,S_Angle,E_Angle,Radius,Mode
Draws a portion of a circle at center point X,Y with Radius starting from S_Angle to E_Angle.  Mode = 0 - Arc only, Mode =1 - Filled pie section, Mode = 2 - Outlined pie section, Mode > 2 - Error
1 BEEP BEEP Frequency,Length
Generates a square wave note at a specific frequency and a length in 100ths of a second.
2 BLIT WRITE BLIT WRITE X,Y,String
Blits a graphic stored in String at point X,Y.  The string holds the width and height.  Draws using the mode set by MODE
3 BLIT COPY BLIT COPY Xs,Ys,W,H,Xd,Yd
Does a direct Blit Read from point Xs,Ys with a Width W and Height H, and Blit Writes to point Xd,Yd
4 BOX BOX X,Y,W,H,Filled
Draws a box from point X,Y with Width W and Height H.  Draws a filled box if Filled is non-zero.
5 CASE CASE value
Used with SELECT
6 CD # CD #stream,"Directory name"
Changes the current directory on the specified stream.
7 CIRCLE CIRCLE X,Y,Radius,Filled
Draws a circle at center point X,Y with Radius either as an outline or filled if Filled is non-zero.
8 CLEAR CLEAR [Memory Address]
Clears all variables.  Sets a new Ramtop if a valid address is given.
9 CLS CLS
Clears the screen
10 CONTINUE CONTINUE
Continues execution of a program after an error, break or STOP
11 COPY # COPY #stream,"Source","Destination"
Copies a file from opened stream from Source to Destination
12 DATA DATA followed by comma separated string and numeric values
Provides a method for storing a table of string and numeric values.
13 DEFINE FUNCTION  
 
14 DELETE DELETE From,To
Deletes program lines.
15 DIM DIM variable[$],value[,.value][,value]
Dimensions an array.
16 DRAWTO DRAWTO X,Y
Draws a line from the last point plotted to X,Y
17 ELLIPSE ELLIPSE X,Y,Rx,Ry,Filled
Draws a filled or unfilled ellipse at center point X,Y with x-radius Rx and y-radius Ry.  Filled if non-zero
18 ENDSELECT ENDSELECT
Ends a SELECT CASE series
19 EXIT IF EXIT IF condition
Exits from any loop if condition is met
20 FORMAT # FORMAT #stream[,command]
Sends the format command to the specified stream.  For storage devices it formats it.  For serial devices it sets the speed and other parameters, only for streams already opened, as OPEN # typically does this.
21 FOR FOR variable=Start_value TO End_value [STEP value]
Starts a loop and continues looping as long as the variable does not equal or exceed End_value
22 GOSUB GOSUB number [or variable]
Calls a subroutine
23 GOTO GOTO number [or variable]
Transfers program control to a specific line number
24 IF IF condition THEN command [ELSE command]
Executes commands if condition is met
25 INK INK value
Sets the drawing color.
26 INPUT INPUT [#stream]  variable[$][,"prompt"]
Retrieves the value from the stream for a numeric or string variable, and will prompt the user with the given string if applicable.
27 LET LET variable[$]=["]value["]
Assigns a value to a string or numeric variable.  Value can be a number or numeric expression, or a quoted string.
28 LIST LIST [#stream] [start][,end]
Sends a program listing to the default or given stream.  If no start or end line is given, then the whole program is dumped to the stream, otherwise only the range given.
29 LOAD LOAD [#stream,]"filename' [CODE] [address]
Loads a BASIC program from the default or specified stream if no "CODE" specification is passed.  Otherwise it loads the file as binary data.  If an address is passed, then the data is loaded at that address, otherwise it's loaded at the address it was saved from.
30 LOCATE LOCATE [#stream,]column,row
Locates the cursor or drawing point to column,row.  For graphical streams it moves the plotting point as row=y and column=x.
31 MKDIR # MKDIR #stream,"dirname"
Only works for mass storage streams.  Creates a directory with the given "dirname"
32 DRAWMODE DRAWMODE value
Sets the drawing mode to the specific mode:

0 = Overwrite mode.
1 = XOR mode
2 = AND mode
3 = MASK mode (draw only if original pixel is set to the PAPER color)

33 MOVE # MOVE #stream,"source","destination"
Moves a file from one path to another.
34 NEW NEW [type]
Performs a system reboot.  If no type is given, it is a warm boot.  If type is used, then the following are the possible values:

0 = Cold Boot.  All memory is cleared and all peripherals reset to default values, just like at power on.
1 = Warm Boot.  All memory below RAMTOP is cleared and all peripherals set to their default values.
2 = Lukewarm Boot.  All memory below RAMTOP is cleared, but peripherals are not reset.
3 = Peripheral Boot.  Only peripherals are reset to default values, memory and system remains intact.
35 NEXT NEXT variable
identifies the ending portion of a FOR-NEXT loop by identifying the conditional variable identified in the FOR command.
36 ON ERROR ON ERROR GOTO line
ON ERROR GOSUB line
GOTO - If an error is triggered, the execution jumps to an error handler.

GOSUB - If an error is triggered, the error handler is called and execution can be returned to the main routine via a RETURN at the end of the error handler.  Execution begins immediately after the problem statement or line.
37 ON ON value GOTO line[,line etc.]
ON value GOSUB line[,line etc.]
GOTO - program execution jumps to the line index indicated by the value.  Value is an expression result or variable value that acts as an index into the list of line numbers at the end of the statement.

GOSUB - A specific routine is called at the line number indexed by the expression or variable indicated by "value."

38 OPEN # OPEN #stream[,parameters]
The method for opening and initial configuration of a stream.  The parameters can be numeric or string and should be comma separated.  It is up to the driver to determine how to parse.
39 OUT OUT port,value
Sends an 8 bit value to the I/O port.  Port is identified by a 16 bit value.
40 PAPER PAPER value
Sets the background color to value.
41 PAUSE PAUSE [value]
Waits for a keypress indefinitely if no value given, or for a specific number of seconds.
42 POKE POKE address,value
Sets an 8 bit value to the specified 24 bit address
43 DPOKE DPOKE address,value
Sets a 16 bit value starting at the 24 bit address given, in little endian format.
44 LPOKE LPOKE address,value
Sets a 24 bit value starting at the 24 bit address given, in little endian format.
45 PLOT PLOT x,y
Sets a pixel at position x,y for a graphical screen.  Otherwise it prints a solid square at column,row for text streams.
46 PRINT PRINT [#stream;] expression[,][;]expression][,][;]
Prints either a string or numeric expression separated by commas or semi-colons.  Commas insert tabs and semi-colons are just dividers.  If no semi-colon or comma ends the statement, then a CR/LF is sent to the stream as well.
47 READ READ variable[$]
reads the next value from the DATA tree.
48 REM REM Descriptive text
Is completely ignored by BASIC and execution immediately jumps to the next line or statement.
49 RESTORE RESTORE [line]
Sets the READ index at the beginning of the DATA tree, if no line given, otherwise at the line given.
50 RETURN RETURN
Returns from a routine called by GOSUB or ON ERROR GOSUB, immediately after the GOSUB call statement.
51 RUN RUN [line]
Clears all variables and begins program execution at the beginning or at the line number given by "line."
52 SAVE # SAVE #stream,"filename" [LINE start]
SAVE #stream,"filename" [CODE start,length]
Saves a file to the mass storage device stream.  If "CODE" is given, it dumps memory starting at address "start" with a length of "length".  Otherwise the BASIC program is saved.  If "LINE" is given, BASIC is told to start execution at the given line number when loaded.
53 SELECT SELECT value
Part of the SELECT-CASE-ENDSELECT commands.  Sets the conditional value which is either a variable or expression.  It must be numeric though!
54 STOP STOP
Ends program execution with the message "STOP Received at Line xxxx".  Helpful with debugging.
55 WHILE WHILE (expression result is true)
Executes the loop only if the expression is true.
56 WEND WEND
Indicates the end of the WHILE-WEND loop.
FUNCTIONS
Index Name Syntax
Description
0 <= expression <= expression
Boolean, returns true if expression is true.
1 >= expression >= expression
Boolean, returns true if expression is true.
2 <> expression <> expression
Boolean, returns true if expression is true.
3 ABS ABS value
returns the absolute value of "value" which can be a constant, variable, or expression.
4 ACS  
 
5 AND expression AND expression
Boolean, returns true if expression is true.
6 ASN  
 
7 ATN  
 
8 BDEC BDEC "binary string"
Converts the binary value to an integer value
9 BIN BIN integer
Converts a numeric integer into a binary string value.
10 CHR$ CHR$ value
assigns or returns the an ASCII character defined by "value"
11 CODE Only used in stream commands
 
12 COS  
 
13 DATE DATE
Returns the date in a string.
14 ELSE IF expression THEN statement ELSE statement
The statement is only executed if the "IF" expression was false.
15 EXP value EXP exponent
Returns the value of "value" to the "exponent" power.
16 FREE Returns the amount of FREE RAM available.
 
17 FUNC  
 
18 HDEC HDEC "hexadecimal string"
Converts a hexadecimal value given in the string to a numeric integer.
19 HEX HEX integer
Returns a hexadecimal string value for the numeric integer.
20 IN IN port
returns the 8 bit value from 16 bit port address
21 INKEY$ variable$=INKEY$
Non-blocking keyboard scanning.  Returns the ASCII value of the last key pressed, else an empty string if no keys in the keyboard buffer.
22 ROUND ROUND value
Rounds the decimal "value" to the nearest integer.
23 INT INT value
Returns only the integer portion of a number.  It does NOT round, but only truncates the value of the decimal.
24 LEFT$ LEFT$ string,length
Returns a portion of a string starting from the left and for the given length.
25 LEN LEN string
Returns the length of a string
26 MID$ MID$ string,start,length
Returns a portion of a string beginning at the index "start" and with the length of "length".
27 XMOUSE XMOUSE
Returns the X location of the mouse.
28 YMOUSE YMOUSE
Returns the Y location of the mouse.
29 NAT  
 
30 NOT NOT expression
Reverses the boolean value of the expression.  Changes true to false and false to true.
31 OCTAL OCTAL value
Returns a string representation of an octal number translated from value.
32 ODEC ODEC "octal number"
Returns an integer value of the octal value.
33 OR expression OR expression
Boolean, returns true if either expression is true, otherwise false.
34 PEEK PEEK address
Returns an 8 bit value of the memory address.
35 DPEEK DPEEK address
Returns the little endian 16 bit value starting at "address."
36 LPEEK LPEEK address
Returns the little endian 24 bit starting at "address."
37 PI PI
Returns the floating point value of Pi.  It uses the highest value of accuracy the floating point method can represent.
38 PIXEL PIXEL [#stream,]x,y
Returns the color value of the pixel at x,y.
39 RIGHT$ RIGHT$ string,length
Returns a string with the length of "length" starting from the end of "string" and going backwards the length of "length."
40 RND RND
Returns a random decimal value generated by the random number generator which is seeded by the system counter.
41 SIN SIN value
 
42 SNAP  
 
43 STEP FOR variable=start TO end STEP value
Is the increment value for the FOR loop.  Can be integer, decimal, positive or negative.
44 STR$  
 
45 TAN  
 
46 THEN IF expression THEN statement
Prefixes the statement that runs if the IF expression is true.
47 TIMER TIMER
Returns the value of the system timer.
48 XTOUCH XTOUCH
Returns the X position of the touch screen when touched.
49 YTOUCH YTOUCH
Returns the Y position of the touch screen when touched.
50 VAL VAL string
Returns the decimal value indicated in the string.  If none is given, then 0.
51 VAL$ VAL$ decimal
Returns a string representation of a decimal value.
52 BLIT READ string=BLIT READ x,y,w,h
Dumps a blot portion of the display into a string.  The block is given as X,Y with a width of "w" and a height of "H".