undefined
The SIMP language was conceived for a single purpose, to implement the JoeBasic compiler with much of the code residing in ASCII files. It is a rather peculiar language to be sure but it does seem to run pretty well considering the simplicity of its implementation. This document endeavors to explain the commands available in the SIMP language and most of its rules of syntax.
A file coded in SIMP language should have a file extension of ".smp" and consist of a standard text format file. It cannot include any formatting information, just the standard ASCII characters.
One line of a SIMP language file may consist of any one of these 4 possibilities:
The format of a SIMP command line must comply with these rules:
There are 4 types of parameters possible after a SIMP command:
A <numeric variable> parameter must consist of the name of a SIMP numeric variable.
A <string variable> parameter must consist of the name of a SIMP string variable.
A <number> parameter may contain a SIMP numeric variable or it may consist of a literal number in decimal format or in hexadecimal format using "&H" as a prefix. All numbers are limited in range to 0-65535 (decimal). There are no negative numbers in SIMP language programs.
A <string> parameter may contain a SIMP string variable or it may consist of a literal string. A literal string consists of a series of characters enclosed in quotation marks(").
SIMP does not offer any direct means of executing a program loop. Therefore, it is necessary for the QBasic programs that call on SIMP files to provide the necessary loop actions externally. For example, at the main level of the compiler, each JoeBasic source statement is read into the OrigStmt variable and then the ProcStmt.smp file which is coded in SIMP code is executed to work on it. As soon as it exits, the main level program repeats its action and reads in the next JoeBasic source statement and executes the same ProcStmt.smp file. The management of the loop is carried out externally from the ProcStmt.smp file.
Each time a JoeBasic source code expression needed to produce a byte-size result is to be converted to assembly language statements, a looping process repeatedly executes BGetVal.smp, BDoOp.smp, and BGetOp.smp to do the real work. All three of these files rely on a variable called Lvl to indicate the nesting level of the calculations. A string list called Dst() contains operand names for each level and another string list called Op() holds stored operators.
A nearly identical set of operations surrounds the use of WGetVal.smp, WDoOp.smp, and WGetOp.smp to generate assembly language code to produce word-size results.
The Spit command routine includes nested loops that repeatedly execute the RulesA.smp and RulesB.smp files. Outside the control of the SIMP rules files themselves, the rules are made to be repeatedly tested starting at every step of the assembly language code. Any time any rule causes a change to be made by replacing a set of assembly language instructions with a more efficient set of instructions, the process repeats from the beginning until no rule can make any improvements despite every rule having been tried starting at every possible point in the code.
The rule files are nearly self contained and do not receive external information other than the assembly language code itself.
Again, all the loop management for the expression evaluating code and the rule code is conducted external from the SIMP files.
The compiler provides a fixed set of variables for the SIMP files to use. These are global variables. That is, if any of the SIMP files alters one, its new value is felt in any of the SIMP files that run.
SIMP variables come in two varieties, numbers and strings. In general, numbers are unsigned integers of 16-bits precision. Strings can have lengths up to thousands of characters.
Here is the set of number variables that SIMP files can access:
ListFlg
TraceFlg
SymIdx
Pntr
Status
Index
Lvl
PntrSv
PntrSv2
JJ
KK
Tmp
AssyFlg
Buck
PP
Tmp0I
Tmp0WI
DatV()
Here is the set of string variables that SIMP files can access:
OrigStmt
Stmt
SymNm
IfStk
UnkSymNm
SubFld
TmpStrg
Src
PPrd
DatN()
DatT()
Op()
Dst()
Many parts of the existing SIMP code rely on certain temporary variables being declared by the user in the run-time target system. Although they are not necessarily required to be stored in successive RAM memory cells, there needs to be 16 temporary variables of type Byte stored in Access memory. The names of these temporary variables must be:
Tmp0
Tmp1
Tmp2
Tmp3
Tmp4
Tmp5
Tmp6
Tmp7
Tmp8
Tmp9
TmpA
TmpB
TmpC
TmpD
TmpE
TmpF
There also must be 8 temporary variables of type Word stored in Access memory. The names of these temporary variables must be:
Tmp0W
Tmp1W
Tmp2W
Tmp3W
Tmp4W
Tmp5W
Tmp6W
Tmp7W
Note that it is perfectly acceptable to use the same storage space for both sets of temporary variables.
SIMP code that is involved in parsing JoeBasic source code statements must have a means of examining the source code text and making decisions about what it says. For that purpose, SIMP has a string variable called Stmt which stores the current JoeBasic statement while it is being processed.
In order to direct attention to a particular area of this statement buffer, the numeric variable Pntr serves as the current character position pointer. Setting it to 1 causes it to point to the 1st character in the Stmt buffer.
SIMP software tools that parse JoeBasic source statements test the characters in the Stmt buffer starting with the character position indicated by Pntr and advancing forward in search of characters that meet some desired condition such as a literal number, a symbol name, a math operator, etc. Generally, if characters that meet the desired condition are found, Pntr gets repositioned just past those characters. If the desired condition is not met, Pntr remains unchanged so that other tests may be performed on what comes next in the Stmt buffer.
Numbers in some parts of JoeBasic code are limited to an 8-bit range (0 to 255). In other places they are limited to a 16-bit range (0 to 65535). There are a few places where they can be no larger than one bit (0 or 1). For numbers expressed as a single bit, the appropriate syntax in JoeBasic is to preceded the 0 or 1 with a percent (%) character. That is, binary values are %0 or %1. All other numbers may be expressed as decimal values or hexadecimal values. For a decimal value, no special syntax is required and, of course, the number can contain nothing but the decimal digits (0 to 9). For numbers expressed in hexadecimal, the appropriate syntax is "0x" followed by the hexadecimal number using the appropriate digits (0 - 9, A - F). Case is unimportant.
There are no negative numbers in JoeBasic. If a large number is subtracted from a smaller one, the result rolls under and wraps around. That is, in an 8-bit computation, 10 - 30 will result in 236, not -20.
It might look like there can be a negative number in the first statement of a For/Next loop, but it is not so. For example, in this JoeBasic statement...
For I = 100 To 50 Step -5
... it looks like the step value is a negative 5. However, in reality, the step value is just 5 and the system knows that 5 is being subtracted in each cycle of the loop. It does not add -5.
Consider this JoeBasic statement:
X = Y
In general, we know that X represents some RAM memory, either a byte or a word depending on how X was created. The RAM cell(s) that X represents are being set equal to some value. If Y also represents a byte or word in RAM, the intention is for the contents of the RAM cell(s) represented by Y to be copied to the RAM cell(s) represented by X.
However, Y might not represent any RAM cells at all. Y may just be a symbol to which a value has been assigned such as a constant. For example, suppose this statement had created Y:
#Y = 7
If this is the case, the X = Y statement is equivalent to X = 7 and it means that X is to be set to 7.
Somehow, when JoeBasic encounters X = Y, it must know how to choose the appropriate meaning for Y.
To this end, the symbol table includes type codes. These are always 2-character codes. For most symbols, the first character of a type code indicates data size:
% bit-size data
B byte-size data
W word-size data
The second character indicates the nature of the symbol:
V a value
A data in Access memory
R data in other RAM memory, accessible only when BSR is set properly
Some examples are:
%V a bit value with a value equal either to 0 or to 1
BV a byte value with a value somewhere in the 0 to 255 range
WV a word value with a value somewhere in the 0 to 65535 range
BA a byte stored in Access memory
WR a word stored in other data memory, accessible only when BSR is set properly
The exception that relates to type codes in the symbol table is for subroutine names. These must be declared before the code for them appears or any references to them (such as subroutine calls) appear. The subroutine code may or may not appear in the same JoeBasic module. That is, the subroutine itself might be external. When a subroutine has been declared but its code has not yet been found, it has a type code of "D ". After its code has been found, the type code is changed to "S ".
Now back to the X = Y statement. To process the X, we would use either of the SIMP commands TDefSym or FDefSym. We would supply the command with a desired type of "BA", "BR", "WA", or "WR" or some combination of these. This would assure that we would only accept a variable stored in data memory.
After processing the equal sign (=), we could use another TDefSym or FDefSym to accept a second variable. As before, we would supply a desired type of "BA", "BR", "WA", or "WR" or some combination of them. This would assure that a symbol with an assigned value would not be accepted but a symbol representing data stored in data memory would.
Alternately, we could use either of the SIMP commands TNxtVal or FNxtVal. Supplying the command with a type code of "BV", "WV", or both, would permit either a number or a symbol with a matching type to be accepted, but not a symbol that represents a variable.
JoeBasic symbols are stored in a symbol table. SIMP has several commands that allow SIMP files to access and/or change the contents of the symbol table. All JoeBasic symbols must start with an alphabetic character and may include alphabetic characters, decimal digits, and underscore (_). Problems will develop if some symbols exceed 15 characters in length. Each symbol in the symbol table is stored with its name, an assigned value, and an assigned type. The type codes in use are:
| Type Code | Meaning |
|---|---|
| "%V" | Binary value |
| "%A" | (Reserved) |
| "%R" | (Reserved) |
| "BV" | Byte value |
| "BA" | Byte in RAM accessible via Access memory addressing |
| "BR" | Byte in RAM accessible only via bank switch addressing |
| "WV" | Word value |
| "WA" | Word in RAM accessible via Access memory addressing |
| "WR" | Word in RAM accessible only via bank switch addressing |
| "D " | Subroutine that has been declared but whose code not yet found |
| "S " | Subroutine that has been declared and then whose code was found |
Subroutine name entries also include a list of variables used for parameter passing.
The symbol table does not store information about every label in the assembly language output file. It does keep the name, type, and address of every declared byte or word variable in the target system's RAM. It keeps the name, type, and address of every SFR (special function register) in the target system so that if given an SFR's name, it can determine if the reference involves a byte or a word. It also stores some symbols that simply have a value such as a constant and that do not represent any variable in RAM.
The only symbols that it stores that reside in program memory are subroutine names. It does not even attempt to retain a subroutine's address. The reason it can do this is that the assembly language output file will subsequently be assembled by the assembler program and that program will be the one to keep track of all the details that JoeBasic can skip. On the other hand, JoeBasic keeps enough info about RAM-based variables that it can know when and when not to use Access memory to address them, something that the assembler does not do.
Branches in SIMP code are performed by forward-only searches for a line containing only an asterisk (hereafter called a star) immediately followed by a number. For example, suppose a SIMP command sets out to branch to the number 7. The SIMP interpreter will search forward in the current SIMP file looking for a line containing only *7 but is also sensitive to finding any line marked with *0. If *7 is found, execution resumes with the next line after the line containing *7. However, if *0 is found before *7, execution ends with an error as this is a fatal error in the SIMP system. In effect, *0 is used to mark the end of the routine within with a forward branch may be executed.
There is no facility for
reverse branching. Therefore, there is no way to code a loop in SIMP.
All necessary looping is accomplished outside a SIMP file.
SIMP provides three data lists containing 6 entries each. They are called DatV(), DatT(), and DatN(). The primary purpose for them is to hold numeric values (DatV()), type codes (DatT()), and variable names (DatN()). The indexes to these lists run from 0 to 5 in each list.
They are often used together. For an example (and using the number 1 as an example index), information about a symbol read from the symbol table might be stored as the symbol's value in DatV(1), its type code in DatT(1), and its name in DatN(1). However, SIMP provides only limited support for directly coded indexes as shown here. Specifically, in the case of DatV(),DatT(), and DatN(), it is permitted to code these with a literal digit inside the parentheses. For example, DatT(3) is permissible but DatT(03), DatT( 3), and DatT(Tmp) are not.
For occasions where it is desired to have an index into the list be provided by a variable, set the value into the SIMP variable Index and then use a reference with empty parentheses, such as DatT(). In fact, this use of the variable Index can be applied to every SIMP variable that is a list.
SIMP provides the Op() list which has a capacity for 10 entries (0 - 9). Each entry can store a string. It is generally used to store operators for JoeBasic statements. Op() and can use the Index variable to select a list entry in Op() but simpler and more direct access is provided for Op(0) and Op(1) only.
The JoeBasic compiler contains a set of three lists that accumulate the assembly language statements during the compilation of a single JoeBasic source statement. Although not accessible from SIMP code, their internal names are StepsL(), StepsC(), and StepsO(). They respectively store assembly language statement labels, assembly language commands (that is, opcodes), and assembly language operands.
After the ProcStmt.smp file processes a JoeBasic source statement and causes assembly language instruction elements to be stored in these three lists, a SIMP command called Spit is executed to cause the assembly language elements in these lists to be screened for improvements according to the SIMP files RulesA.smp and RulesB.smp. If the rules in those files find assembly language code patterns that can be improved, they edit the assembly language instruction elements in the step lists to reduce the number of instructions needed. Then the assembly language elements that remain in the lists are combined together to form complete assembly language statements and the statements are output to the assembly language output file, YourCode.asm.
The RulesA.smp and RulesB.smp files detect certain patterns of assembly language instructions that can be replaced with alternate but simpler equivalent assembly language instructions. There are two kinds of SIMP software tools that perform this function. The first kind tests for some particular code condition in the assembly language code stored in the Steps lists. After a series of such tests are performed and it is determined that an assembly language pattern exists that can be simplified, the second type of software tool causes the section of code in the tested pattern to be deleted and replaced with alternate code.
The SIMP code for any given optimization rule always starts with *0 followed on the next line by a Rule command to identify it. All SIMP commands of the kind that test for some part of a pattern of interest start with a question mark (?). For each of these testing commands, if the condition being tested is not met, execution automatically branches forward to the next occurrence of *0 and, therefore, to the test for the next rule in the file.
The commands that replace the tested code include Line commands and several commands that start with FLD. The first of these that occur cause the statement pattern that was successfully found to be automatically deleted so that the replacement assembly code lines are created in its place.
Many SIMP commands are provided in two variations, one that starts with T (for True) while the other starts with F (for False) instead. All such SIMP commands take at least one number parameter as the last parameter for the command. Along with performing whatever other operation is intended by the command, it also provides a conditional branch function based on a result returned by the action of the command.
If the command starts with T and the operation performed by the command returns a True condition, execution will then branch forward in the SIMP code to the number indicated by the last numeric parameter. If the operation returns a False condition, execution will instead continue with the next line of SIMP code.
If the command starts with F and the operation performed by the command returns a True condition, execution will continue with the next line of SIMP code. If the operation instead returns a False condition, execution will then branch forward in the SIMP code to the number indicated by the last numeric parameter.
A simple example is this SIMP command: T= <number> <number> <number>
Note that this command starts with T. This command's operation is to compare the 1st and 2nd number parameters to see if they are equal. If that is True, execution will branch forward in the SIMP code to the star with the number indicated by the 3rd number parameter. If 1st and 2nd number parameters are not equal, the comparison result will be Not True (False) and execution will continue with the next line of SIMP code.
In contrast, we have this counterpart SIMP command: F= <number> <number> <number>
This is essentially the same command except that it starts with F. This command's operation is also to compare the 1st and 2nd number parameters to see if they are equal. However, if that is True, execution will not branch forward in the SIMP code but will instead continue with the next line of SIMP code. Only if the comparison results in a not True (that is, a False) condition will execution branch forward in the SIMP code.
Note that some decision commands can be expressed in two ways. For example, while T= and F= indicate opposite actions being taken, T= and F<> are exactly equivalent.
The SIMP command set is divided into nine groups of commands.
I. Debugging tools
The commands in this small group were included to aid in debugging SIMP programs. They do not generally appear in finished SIMP program files.
Print$ <string>
Prints one line containing the string on the screen.
Print <number>
Prints one line containing the number on the screen.
Pause
Halts operation until the user taps a key on the keyboard.
II. General Decision Makers
See the description above about making decisions with T and F SIMP commands and the purpose of the numeric 3rd parameter in all these commands.
T< <number> <number> <number>
F< <number> <number> <number>
Returns True if 1st number is less than 2nd number.
T= <number> <number> <number>
F= <number> <number> <number>
Returns True if 1st number equals 2nd number.
T> <number> <number> <number>
F> <number> <number> <number>
Returns True if 1st number is greater than 2nd number.
T<=; <number> <number> <number>
F<=; <number> <number> <number>
Returns True if 1st number is less than or equal 2nd number.
T<> <number> <number> <number>
F<> <number> <number> <number>
Returns True if 1st number is not equal to 2nd number.
T>= <number> <number> <number>
F>= <number> <number> <number>
Returns True if 1st number is greater than or equal 2nd number.
T<$ <string> <string> <number>
F<$ <string> <string> <number>
Returns True if 1st string is less than 2nd string.
T=$ <string> <string> <number>
F=$ <string> <string> <number>
Returns True if 1st string equals 2nd string.
T>$ <string> <string> <number>
F>$ <string> <string> <number>
Returns True if 1st string is greater than 2nd string.
T<=$ <string> <string> <number>
F<=$ <string> <string> <number>
Returns True if 1st string is less than or equal 2nd string.
T<>$ <string> <string> <number>
F<>$ <string> <string> <number>
Returns True if 1st string is not equal to 2nd string.
T>=$ <string> <string> <number>
F>=$ <string> <string> <number>
Returns True if 1st string is greater than or equal 2nd string.
III. Source Code Parsing Tools
The commands in this group provide functions that enable the analysis of the syntax of the JoeBasic source code.
FS
This command takes no parameters. FS is short for "From the Start" and is used to initialize
facilities involved in the compilation process. Namely, it clears the internal step lists where assembly language steps are stored and it sets Pntr to 1.
AddDefntn <string>
There is an internal list where defined words and their definitions are stored. This command adds a new defined word and its definition. The string contains the word being defined. The current location of Pntr indicates the start of the definition within the Stmt buffer. All characters in the Stmt buffer from that location forward, excluding trailing spaces, constitute the definition to be stored.
PreProc
This command scans the Stmt buffer for any words that have definitions. Each such defined word is replaced with the definition previously assigned to that word by an AddDefntn command.
IgSp
If Pntr does not point to a non-space character in the Stmt buffer, this command advances Pntr until it does. That is, it allows the system to ignore spaces by skipping over them.
TDefSym <string> <number>
FDefSym <string> <number>
Starting with the current character in the Stmt buffer, this command reads a string of characters that could be a symbol (that is, the characters abide by the rules for a symbol). Then it searches for the symbol in the symbol table. The string parameter of this command may provide one or more type codes or it may be coded as an empty string. If the string is empty, if the symbol name is found in the symbol table, the search is considered a success. If the string is not empty, the search for the symbol in the symbol table will only be considered a success if the type of the symbol found in the symbol table appears in the string parameter.
If the symbol search is successful, the numeric index into the symbol table for that symbol is stored in SymIdx and the operation returns True. If the symbol search is not successful, False is returned.
TExpV <number> <string> <number>
FExpV <number> <string> <number>
This command evaluates an expression. It does not write assembly language code. It only computes an expression's value where all elements of the expression have an assigned value. That is, it must encounter one or more literal numbers or symbols with assigned values separated by math operators.
The number parameter in the command indicates which DatV() entry is to receive the expression's resulting value. The string in the command indicates if there are limitations to the type of resulting data that is permitted. An empty string indicates that any data type is acceptable. "BV" indicates a byte value. "WV" indicates a word value. "%V" indicates a binary bit value. The operation returns True only if an expression was successfully evaluated that complied with a data type requirement if there was one.
TMore <number>
FMore <number>
This command scans forward from the current character position to see if there are any other non-space characters in the Stmt buffer (excluding a possible JoeBasic comment which must start with semicolon (;)). If more info is found on the line, the operation returns True. Otherwise, it returns False.
TNxt <string> <number>
FNxt <string> <number>
This command looks to see if what comes next in the Stmt buffer matches the characters in the string parameter of the command. The comparison is not case sensitive but the string parameter itself must be coded in uppercase. The operation returns True if the sought characters are found. Otherwise, it returns False.
TNxtOpr <number> <string> <number>
FNxtOpr <number> <string> <number>
The only operators that JoeBasic can recognize are in the following list. When this command is executed, it scans forward in the Stmt buffer from the current character position to see if any of the operators from the following list comes next:
>>
>=
<>
>
<<
<=
<
=
+
-
*
\
AND
XOR
OR
If it finds one, it checks to see if the particular operator that was found appears in the string parameter in the command. If an operator is found in the Stmt buffer that also appears in the string parameter, Pntr is left just past the operator, the operator is set into the Op() entry indicated by the 1st number parameter, and the operation returns True. If none of the operators is found next in the Stmt buffer, or if one is found but it does not also appear in the string parameter, Pntr remains unchanged and the operation returns False.
The program allows a certain degree of lattitude with operator coding and that is accomplished here. For example, the standard character combination for "less than or equal" is <=. However, if TNxtOpr or FNxtOpr find =< instead, they still recognize the operator as if it were coded in the standard <= form. They translate it to the standard form before they look for it in the string parameter and store it into an Op() entry.
TNxtSym <number>
FNxtSym <number>
This command scans forward from the current character position in the Stmt buffer to see if what comes next conforms to the syntactic rules for a symbol. If a potential symbol is found, its name is stored into the variable SymNm and the operation returns True. If no potential symbol is found, SymNm is cleared and the operation returns False.
TNxtNbr <number> <string> <number>
FNxtNbr <number> <string> <number>
This command scans forward from the current character position of the Stmt buffer to see if a literal number comes next. The type of literal number that is permitted to be found may be limited by the string parameter in the command. If the string parameter is empty, there is no limitation. If the string parameter contains "%V", the number must be a binary value. If the string parameter contains "BV", the number may be any number from 0 to 255 (decimal). If the string parameter contains "WV", the number may be any number from 0 to 65535 (decimal). In JoeBasic source statements, a literal binary number must be expressed as %0 or %1. Other numbers may be expressed as a series of decimal digits or "0x" followed by a hexadecimal number.
If a literal number is found next that complies with any limitation expressed in the string parameter, the numeric value is stored into DatV() where the index is the 1st number parameter, DatT() (using the same index) will be set with "%V", "BV", or "WV" to indicate the type of data that was found, Pntr will be moved to the first character past the literal number, and the operation will return True. Otherwise, Pntr will remain unchanged and the operation will return False.
TNxtVal <number> <string> <number>
FNxtVal <number> <string> <number>
This command scans forward from the current character position of the Stmt buffer to see if either a number or a symbol with an assigned value comes next. The string parameter may be an empty string to permit any data types to be accepted or it may contain one or more type codes separated by commas. Acceptable type codes include "%V", "BV", and "WV". If a number or symbol complying with the type requirement is found next, the value of that number or symbol is placed in the DatV() entry indicated by the first numeric parameter, Pntr is left at the first character after the number or symbol, and True is returned by the operation. Otherwise, Pntr remains unchanged and False is returned.
TNxtW <string> <number>
FNxtW <string> <number>
This command looks to see if what comes next in the Stmt buffer matches the characters in the string parameter of the command. The comparison is not case sensitive but the string parameter must be coded in uppercase. What sets this command apart from TNxt and FNxt is that it also verifies that the next character after the located string in the Stmt buffer is not a character permitted in a symbol. That is, the character is not alphabetic, is not a numeric digit, and is not an underscore (_).
As an example, consider the following command:
TNxtW "FOR" 1
If the next text coming up is "For all good men...", the command will succeed in its test. However, if the next text coming up is "Form over function...", the command will not succeed in its test because the "m" that follows "For" can be part of a symbol whereas the space character that follows "For" in the first example cannot be part of a symbol.
If the test succeeds, Pntr is left just past the matching string and the operation returns True. Otherwise, Pntr remains unchanged and the operation returns False.
TUnkSym <number>
FUnkSym <number>
The intent of this command is to detect the presence of a symbol name that is not currently in the symbol table. Starting with the current character in the Stmt buffer, this command reads a string of characters that could be a symbol (that is, the characters abide by the syntactic rules for a symbol). If it finds a possible symbol name in the Stmt buffer and then fails to find that symbol name in the symbol table, Pntr is left just past the apparent symbol name and the operation returns True. If it does not find a potential symbol name (because the characters coming next do not fit the syntactical rules for a symbol) or if it does find a potential symbol name but then discovers that the name is already in the symbol table, Pntr remains unchanged and the operation returns False.
SymScan <number>
This command is used when a symbol's name has been stored in one of the DatN() entries. The number parameter in this command specifies the particular DatN() entry that contains the symbol name. The command searches forward in the Stmt buffer from the current character position to determine if that particular symbol is referenced anywhere on the remainder of the line. It is designed to ignore portions of the line that are enclosed in quotation marks (") or that appear after a semicolon (;) which indicates the start of a JoeBasic program comment. If it finds any occurrences of the symbol, it sets the Status variable to 1. If it does not find any occurrences of the symbol, it sets Status to 0. In either case, Pntr remains unchanged.
IV. Assembly Language Code Creation Tools
The commands in this group are primarily intended to process JoeBasic source statements and to generate assembly language statements for the output file.
TBExpr <number> <number>
FBExpr <number> <number>
This command is used when an expression is allowed to appear next in a JoeBasic statement and the expression is limited to generating an 8-bit result, typically for storing in a byte-sized variable. If a valid expression is successfully found and processed, the series of assembly language instructions necessary to perform the equivalent calculation specified by the expression is added to the Steps buffers, Pntr is left pointing to the first character after the expression, and the operation returns True. If no valid expression is found next, no assembly language steps are added to the Steps buffers, Pntr is left unchanged, and False is returned.
There is a special feature which relies on the 1st number parameter in the command. If this number parameter is set to 99, the assembly language code is written such that at run time in the target system, the result of the expression's calculation will be left stored in the Tmp1 variable. However, if the 1st number parameter is in the range 0 to 5, the result of the expression's calculation will be stored in the byte variable whose name appears in the DatN() entry indicated by that number parameter. Other values of the 1st number parameter will likely cause a fatal error during compilation.
TWExpr <number> <number>
FWExpr <number> <number>
This command is used when an expression is allowed to appear next in a JoeBasic statement and the expression is permitted to generate a 16-bit result, typically for storing in a word-sized variable. If a valid expression is successfully found and processed, the series of assembly language instructions necessary to perform the equivalent calculation specified by the expression is added to the Steps buffers, Pntr is left pointing to the first character after the expression, and the operation returns True. If no valid expression is found next, no assembly language steps are added to the Steps buffers, Pntr is left unchanged, and False is returned.
There is a special feature which relies on the 1st number parameter in the command. If this number parameter is set to 99, the assembly language code is written such that at run time in the target system, the result of the expression's calculation will be left stored in the Tmp1W variable. However, if the 1st number parameter is in the range 0 to 5, the result of the expression's calculation will be stored in the byte variable whose name appears in the DatN() entry indicated by that number parameter. Other values of the 1st number parameter will likely cause a fatal error during compilation.
DeclArgs <number>
This command is called when JoeBasic encounters a Declare statement that declares the existence of a subroutine. The subroutine name should already have been added to the symbol table before invoking this command. The number parameter in the command indicates the index into the symbol table where the subroutine symbol is stored.
On entry, it is expected that Pntr is pointing to where the first passed variable name will appear although intervening spaces at that point are ignored. The command processes the list of variables to be passed to the subroutine.
If it is at a point where a variable name might be expected to appear and no variable name does appear, Pntr is left where a variable name would have been expected to start and the operation terminates with 1 stored in Status.
If a variable name that is in the symbol table does appear, the variable name is added to the subroutine's symbol table entry as a variable to be passed. If the variable name is followed by a comma (,), the action is repeated with the expectation that another variable name will then appear. If instead, a close parenthesis [)] appears, it is recognized as the end of the passed list of variables. Control returns with Pntr pointing at the first character after the close parenthesis and with 0 stored in Status.
If neither close parenthesis nor comma appear after a passed variable name, control returns with Pntr pointing to where a comma or close parenthesis would have been expected and with 2 stored in Status.
Extra space characters just before and just after each variable name are automatically ignored.
SubArgs <number>
This command is used when a subroutine is found in the JoeBasic code. The subroutine will include the list of variables in which parameters are passed when the subroutine is called. This list must match the list of variables in the subroutine's Declare statement. Executing this command with the number parameter set to the symbol index for the entry containing the subroutine's symbol assures that the two lists match. The outcome of this test is revealed in the Status variable:
| Status | Meaning |
|---|---|
| 0 | The list of variables at the subroutine matches the list at the declaration. Pntr is left positioned just past the close parenthesis [)]. |
| 1 | A defined symbol is not found at some point where it is expected. Pntr remains at the point where the error was discovered. |
| 2 | There is a mismatched variable name or the wrong number of variables. Pntr remains at the point where the error was discovered. |
PassArgs <number> <string>
This command should be called when generating the assembly language code for calling a subroutine. If the subroutine needs no arguments, the call to the subroutine can be completed without the need for this command. However, if one or more arguments are to be passed, execute this command to cause assembly language code to be generated sufficient to load the passed arguments into the argument variables.
This command should be executed with Pntr pointing just past the open parenthesis [(] following the subroutine name. The number parameter must indicate the number of args to be passed. The string parameter must provide a copy of the symbol table SymN() entry for the subroutine being called. This string will contain the subroutine's name plus the name of each variable to receive data prior to the transfer of control to the subroutine's code.
When finished, the command returns with a value in Status to indicate the outcome. The returned values are:
| Status | Meaning |
|---|---|
| 0 | Normal return. Pntr is just past ) |
| 1 | Invalid argument specified |
| 2 | Missing or invalid byte arg |
| 3 | Missing or invalid word arg |
| 4 | Arg has invalid type |
| 5 | No comma where expected |
| 6 | No ) where expected |
MakeIf
This command is used to increment a 4-digit decimal "IF" number used in the assembly language labels for IF statements. When compilation begins, this counter starts at 0000. At the same time, a string variable, called IfStk, starts empty. This string variable serves as a simple stack for IF statement related labels. Each time the MakeIf command is executed, the 4-digit counter is incremented and then the previous contents of IfStk is shifted 9 characters to the right and a new 9-character string is inserted at its front. The 9 characters consist of "IFNOT" plus the new 4-digit number. The IfStk is needed because IF statements can be nested.
The current 4-digit "IF" number also replaces any occurrence of #0 in assembly language operands and labels during execution of a Spit command.
All other changing and use of the IfStk string variable is carried out by SIMP code in the .smp files.
MakeLbl
This command is used to increment a 4-digit decimal "Label" number used in the generation of unique assembly language labels. When compilation begins, this counter starts at 0000. The current "Label" number replaces any occurrence of #1 in assembly language operands and labels during execution of a Spit command.
MakeFor
This command is used to increment a 4-digit decimal "For" number used in the generation of unique assembly language labels for For/Next loops. When compilation begins, this counter starts at 0000. The current "For" number replaces any occurrence of #2 in assembly language operands and labels during execution of a Spit command.
Ref <string variable> <number>
This command uses the symbol table index provided in the number parameter to read information about a symbol in the symbol table. Then it generates an appropriate reference string for that symbol which it stores into the string variable named in the command. The reference string includes a code character followed by the name of the symbol in the symbol table.
If the symbol being referenced has a type code of "BA" or "WA", the code character placed in the string variable by the Ref command is "*" which indicates that when the variable is subsequently accessed in the assembly language program, Access memory addressing should be used. If the symbol being referenced has a type code of "BR" or "WR", the code character placed in the string variable by the Ref command is a single hexadecimal digit. The hexadecimal digit indicates the memory bank in which the referenced symbol exists in the target system. Further processing in the Spit command will translate these settings into appropriate addressing commands for the assembler. If the symbol being referenced has a type other than "BA", "BR", "WA", and "WR", a space character is inserted as the code character.
AddLbl <string>
PartStp <string>
HexStp <number>
CodeStp <number>
AddStp <string>
Spit
In general, an assembly language instruction (or step) is constructed by the compiler from several parts.
<label field> <opcode field> <code field> <operand field> <comment>
| Field | Description |
|---|---|
| <label field> | When present, this should be held to 10 characters max although can be longer. |
| <opcode field> | Must not exceed 10 characters but can be shorter. |
| <code field> | Always one character if operand field is not blank. See Ref command explanationfor more about this. |
| <operand field> | When present, this should be held to 10 characters max although can be longer. |
| <comment> | Always starts with semicolon if not blank. Automatically generated by Spit command. |
When ProcStmt.smp is executed to analyze the syntax of a single JoeBasic statement and generate the equivalent assembly language code, it produces one or more assembly language program steps which are buffered in the step lists. See the section on The Step Lists for more explanation about them. When a set of assembly language steps is complete, the Spit command is executed to process the stored steps into the YourCode.asm output file as finished assembly language code ready for the assembler.
The AddStp command is key in the creation of the assembly language steps. Each time an AddStp command is executed, one more step is added to the step lists. If no AddLbl, PartStp, HexStp, or CodeStp commands have been executed prior to the AddStp command, only the contents of the string parameter to the AddStp command will be stored into the step lists.
If an AddLbl command is executed prior to the AddStp command, its string parameter will provide a label field for the step subsequently added by the AddStp command. Sometimes it is appropriate to include a terminating colon (:) in the string parameter of the AddLblcommand so that the label is followed by a colon in the output file.
The string parameter of the AddStp command serves to load as many as three fields of the assembly language instruction info, depending on its length. It starts at the left end of the opcode field. If there are enough characters (that is, more than 10), it spills over into the single-character code field and then further into the operand field. If the string parameter is 10 or fewer characters in length, there will be no code field and no operand field derived from it.
If a PartStp command is executed prior to an AddStp command, it can provide a partial step. That is, it provides an early portion of the string info for the three fields. Each PartStp command string parameter can provide more of the opcode/code/operand data with each being appended to those that came previously. The AddStp command actually also works in this way, with its string parameter being appended to the end of any string elements accumulated previously. However, as stated before, the AddStp command marks the completion of a step. It's string parameter is the last part to be added.
During this process of building up an assembly language instruction a little at a time, there are two more commands that can contribute to it. The CodeStp command uses its number parameter as an index into the symbol table to select a symbol entry. It examines the type code of that symbol entry. In the same manner as a one character code is generated for the Ref command, the CodeStp command generates a single-character code and appends it to the accumulation of strings forming an assembly language instruction. Obviously, it is intended to provide the 11th character so that it lands in the code field.
Another command that can contribute to the instruction building process is HexStp. This command converts its number parameter to a hexadecimal number string and appends it to the assembly language instruction under construction.
The single character code field is only temporarily present. When the Spit command is executed, it endeavors to apply the optimization rules expressed in RulesA.smp and RulesB.smp to the set of steps generated from the JoeBasic source statement being processed. If improvements can be made in the coding of the steps for that JoeBasic source statement, the improvements are implemented and the number of steps required is reduced. The rules are applied time and time again until no further improvements can be made.
Then the Spit command continues by gathering together the various fields of each step and turning them into assembly language statements. The first assembly language statement of the generated group will bear a comment field consisting of a semicolon (;) and the original JoeBasic source code statement.
As each assembly language statement is being processed, the single character code field is removed and coding incorporated to perform the appropriate addressing. Also, any occurrence of #0, #1, or #2 in the label or operand fields will be replaced by the 4-digit IF number, the 4-digit Label number, or the 4-digit For number, respectively.
Note that if a label is added using an AddLbl command but then no step is actually completed using an AddStp command, the added label will be lost and not appear in the output. If an AddLbl command is used and then there are no more steps to be added, you can execute an AddStp command with an empty string to force the label to be output.
Output <string>
This command simply outputs the contents of the string parameter directly to the YourCode.asm output file without any processing at all.
V. Control
The commands in this group cause a certain change in execution.
Goto <number>
This command causes an unconditional branch to the star number indicated in the number parameter.
Exit
This command causes execution of the current SIMP file to cease. Control returns to the QBasic portion of the compiler.
VI. Symbol Table Tools
The commands in this group provide interaction with the system's symbol table.
AddSym <string> <string> <number>
This command adds an entry to the symbol table. The 1st string parameter provides the name of the symbol being added. The 2nd string parameter provides the 2-character type code. The number parameter provides the numeric value to be associated with the symbol in the symbol table. For a symbol that represents a memory variable, this should be the data memory address. For a symbol that is just assigned a numeric value, such as a constant, this should be the numeric value.
FindSym <numeric variable> <string> <string>
Given a symbol name and a list of acceptable type codes, FindSym searches the symbol table for a symbol entry that matches. The match is not case sensitive. The 1st string parameter supplies the symbol's name. The 2nd string parameter supplies a list of acceptable type codes. Each code consists of 2 characters. If more than one type is acceptable include all the acceptable types in the same string separated by commas. If the 2nd string parameter is an empty string, any type is considered acceptable.
If the search for the symbol is successful, the index into the symbol table where the symbol is located is stored into the numeric variable parameter. If the search is not successful, 0 is stored into the numeric variable parameter.
RdSymN <string variable> <number>
Given an index into the symbol table in the number parameter, this command fetches the symbol's name and stores it into the string variable indicated by the string variable parameter.
RdSymT <string variable> <number>
Given an index into the symbol table in the number parameter, this command fetches the symbol's 2-character type code and stores it into the string variable indicated by the string variable parameter.
RdSymV <number variable> <number>
Given an index into the symbol table in the number parameter, this command fetches the symbol's numeric value and stores it into the number variable indicated by the number variable parameter.
WrtSymN <number> <string>
Given an index in the number parameter into an existing symbol table entry, this command replaces the name in the symbol table with the contents of the string parameter.
WrtSymT <number> <string>
Given an index in the number parameter into an existing symbol table entry, this command replaces the 2-character type code in the symbol table with the contents of the string parameter.
WrtSymV <number> <number>
Given an index in the 1st number parameter into an existing symbol table entry, this command replaces the value in the symbol table with the value of the 2nd number parameter.
VII. General Processing
This group of commands perform general computational and string manipulation operations.
Insert$ <string variable> <number> <string>
This command inserts the contents of the string parameter into the string already in the named string variable. It inserts the string just before the character position indicated by the number parameter. If the existing string has fewer characters than the number in the number parameter, the inserted string is effectively concatenated to the end of the existing string.
ErrMsg <string>
This command causes an error message to be generated and inserted into the YourCode.asm output file. The description of the problem is produces from the contents of the string parameter in the command. This also increments the counter that tracks the number of errors that are detected during compilation. The total is included near the end of the output file as well as on the computer's screen at the end of the compilation run.
Set= <number variable> <number>
This command stores into the named number variable the value of the number parameter.
Set=$ <string variable> <string>
This command stores into the named string variable the contents of the string parameter.
Set+ <number variable> <number> <number>
This command stores into the named number variable the sum of the 1st and 2nd number parameters.
Set+$ <string variable> <string> <string>
This command stores into the named string variable the concatenation of the contents of the 1st and 2nd string parameters.
Set- <number variable> <number> <number>
This command stores into the named number variable the value of the 1st number parameter minus the value of the 2nd number parameter. Note that there are no negative numbers in SIMP. If a larger number is subtracted from a smaller one, the result will roll under. All numbers are processed as 16-bit integers.
Set* <number variable> <number> <number>
This command stores into the named number variable the product of the 1st number parameter times the 2nd number parameter.
Set\ <number variable> <number> <number>
This command stores into the named number variable the result of the 1st number parameter divided by the 2nd number parameter. Note that the division is integer divide. The result is not rounded.
Set<< <number variable> <number> <number>
This command copies the 1st number parameter into the named number variable then shifts it left the number of times indicated by the 2nd number parameter. With each shift, a zero bit is shifted into the least significant bit of the number variable. The operation is carried out with 16-bit precision.
Set>> <number variable> <number> <number>
This command copies the 1st number parameter into the named number variable then shifts it right the number of times indicated by the 2nd number parameter. With each shift, a zero bit is shifted into the most significant bit of the number variable. The operation is carried out with 16-bit precision.
SetAND <number variable> <number> <number>
This command stores into the named number variable the 1st number parameter bitwise ANDed with the 2nd number parameter.
SetOR <number variable> <number> <number>
This command stores into the named number variable the 1st number parameter bitwise ORed with the 2nd number parameter.
SetXOR <number variable> <number> <number>
This command stores into the named number variable the 1st number parameter bitwise Exclusive-ORed with the 2nd number parameter.
SetLt$ <string variable> <string> <number>
This command stores into the named string variable a number of characters taken from the left end of the string parameter. The number is of characters is dictated by the number variable.
SetLTrm$ <string variable> <string>
This command stores into the named string variable the contents of the string parameter that has had any space characters on its left end trimmed away.
SetMid2$ <string variable> <string> <number>
This command stores into the named string variable, characters from the string parameter starting with the character position indicated by the number parameter and continuing to the end of the string.
SetMid3$ <string variable> <string> <number>
<number>
This command stores into the named string variable, characters from the string parameter starting with the character position indicated by the 1st number parameter and continuing for the number of characters indicated by the 2nd number parameter.
SetRt$ <string variable> <string> <number>
This command stores into the named string variable a number of characters taken from the right end of the string parameter. The number is of characters is dictated by the number variable.
SetRTrm$ <string variable> <string>
This stores into the named string variable the contents of the string parameter that has had any space characters on its right end trimmed away.
UCase$ <string variable> <string>
This command stores into the named string variable the contents of the string parameter converted to upper case.
Hex$ <string variable> <number>
This command stores into the named string variable, the value of the number parameter expressed as a string of hexadecimal digit characters. There is no prefix such as 0X or &H. It is just the actual hexadecimal digits.
Dec$ <string variable> <number>
This command stores into the named string variable, the value of the number parameter expressed as a string of decimal digit characters.
VIII. Optimizing Rule Tools
This group of commands helps apply rules designed to improve the efficiency of the generated assembly language programs.
Here is how rules are implemented. Each rule applies to a particular coding pattern. There must be a way to detect that the significant elements of the pattern exist and then there must be some action the rule can take to improve the coding when it finds the pattern. For example, suppose a rule is intended to detect this simple assembly language situation:
LoadL 0x0
Sto Var
This code says to load the W register with zero. Then store the value in the W register into a memory location called Var. Since there is a single instruction available that can store zero into a memory location, we could substitute this for the original code:
Clr Var
The need is to detect that one assembly language step has LoadL for its opcode and 0x0 for its operand and that the next step has Sto for its opcode and some operand where it stores the zero. We also would permit a label on the first line which we should retain in the replacement code but if there is a label on the second line, we would have to disallow the rule from being applied since there is no equivalent place to put such a label in the replacement code. Also, the rule should verify that the instruction just prior to the LoadL is not an instruction capable of causing a skip action.
So, just as an example, here is how that rule might be coded in SIMP code:
*0
Rule 01
?Ck "~" "/S" "~" 01
?Ck "*" "LoadL" "0x0" 02
?Ck "" "Sto" "*" 03
FLDLsO 01 "Clr" 03
Rule <number>
This command indicates the start of the code that forms one of the rules. The value of the number parameter is not actually used in general but it does allow you to identify each rule with a number therefore it makes the code easier to read. The rule number has occasionally been used by some temporarily implemented debugging tools. Every Rule command should be preceded by a line containing *0.
There should always be a *0 followed by an Exit command at the end of the file.
?Ck <string> <string> <string> <number>
This command checks for a part of the pattern that must exist to cause the current rule to apply. It verifies that specified conditions exist in one line of a set of consecutive lines. The 1st, 2nd, and 3rd string parameters supply the specification about the condition of the step's label, command (that is, its opcode), and its operand, respectively. The number parameter at the end serves no purpose other than to allow the programmer to provide a line number to improve readability of the rule.
In each of the three string parameters, here is how the strings are interpreted:
If a string parameter contains "~", there is no requirement to be met by the associated field.
If a string parameter contains "", the associated field must contain no text (other than possibly spaces).
If a string parameter contains "*", the associated field must contain some kind of text and not be blank.
If a string parameter contains a string with text in it, the associated field must match that text (non-case sensitive).
One more special rule applies to the command field. If the 2nd string parameter contains "/S", the command opcode in that step must not be any type of skip instruction.
Starting after a Rule command, the first ?Ck command applies to the first step of a group of steps being tested by the rule. The next ?Ck command applies to the second step of the group of steps. A third ?Ck applies to the third step of the group, and so on. When the rule is being executed, if the conditions in an assembly language program step do not match the conditions set forth by any of the rule's ?Ck commands, an automatic branch is taken to the next occurrence of *0. This allows the system to move on to testing for the conditions of the next rule since the current rule does not apply. If execution continues through a series of ?Ck commands without branching out to the next *0, all the conditions expressed in those ?Ck commands must be met.
More condition testing can be done with the other commands in this group that start with a question mark (?).
?O=O <number> <number>
This command verifies that the operand of one assembly language step matches the operand of another assembly language step. The 1st and 2nd number parameters indicate which steps are to be tested in this way. If the two operands do not match, a branch is taken to the next *0.
?O=O+1 <number> <number>
This command is similar to the ?O=O command except that the operand indicated by the 2nd number parameter must be equal to the operand indicated by the 1st number parameter plus "+1". Here is an example:
*0
Rule 02
?Ck "~" "LoadL" "0x1" 01
?Ck "~" "Sto" "*" 02
?Ck "~" "LoadL" "0x0" 03
?Ck "~" "Sto" "*" 04
?O=O+1 02 04
.
.
.
Here is a body of code that would satisfy the conditions laid out in the rule segment example above:
LoadL 0x1
Sto Dat
LoadL 0x0
Sto Dat+1
?ODiff <number> <number> <number> <number>
This command examines the operands of up to 4 different assembly language steps and determines if every one is different from every other. The four number parameters specify the steps whose operands are to be tested. If fewer than 4 operands are to be tested, the last one or the last two may be programmed with 0 so they are not involved in the test. If any of the specified operands match, a branch is taken to the next *0.
?L=O <number> <number>
This command is used to verify that the label on the step indicated by the 1st number parameter matches the operand on the step indicated by the 2nd number parameter. If they do not match, a branch is taken to the next *0.
KeepNone
This command indicates that all the lines tested by the rule may simply be deleted.
Line <number>
This command indicates that the assembly language step indicated by the number parameter should be inserted into the body of code that replaces the steps tested by the rule. Often times, several lines from the original code need to be included into the replacement code without any changes. A series of Line commands would do that. There is a special rule concerning the use of 0 for a step number. This is described in the "FLD" commands below.
FLDsss <string> <string> <string>
FLDssO <string> <string> <number>
FLDsCs <string> <number> <string>
FLDsCO <string> <number> <number>
FLDLss <number> <string> <string>
FLDLsO <number> <string> <number>
FLDLCs <number> <number> <string>
FLDLCO <number> <number> <number>
These eight "field" commands are similar to one another but each performs a different combination of actions. In general, each of the "field" commands is capable of creating one assembly language instruction to be included in the replacement code block for a rule.
Looking at the commands themselves, you can see that each has 3 characters following the initial "FLD" identifier. The 1st of these 3 characters is always either "s" or "L" and determines the label for the assembly language instruction. The second is always "s" or "C" and determines the command (opcode) of the assembly language instruction. The third is always "s" or "O" and determines the operand of the assembly language instruction.
A "field" command assembles the three fields of information to create one line of assembly language code.
If the first of the three characters is an "s", the first parameter of the command is a string parameter and whatever appears in that parameter will appear as the label for the assembly language command. If instead of "s", it is "L", then the first parameter of the command is a number parameter and it indicates the step number from which an existing label should be copied.
If the second of the three characters is an "s", the second parameter of the command is a string parameter and whatever appears in that parameter will appear as the command for the assembly language command. If instead of "s", it is "C", then the second parameter of the command is a number parameter and it indicates the step number from which an existing command should be copied.
If the third of the three characters is an "s", the third parameter of the command is a string parameter and whatever appears in that parameter will appear as the operand for the assembly language command. If instead of "s", it is "O", then the third parameter of the command is a number parameter and it indicates the step number from which an existing operand should be copied.
In the process of constructing one assembly language instruction, the generated instruction is left in a buffer and can be used again and again by the Line command by using a step number of 0.
IX. Show Stopper
This one command group is true to its name.
End
This command causes the system to come to a screeching halt with all files closed. There is no real reason to stop unless a condition is detected that should be considered a fatal error.
Comments or questions? Send them to:
