MARC4 User's Guide qFORTH Compiler 1 qFORTH Compiler By using the MARC4 qFORTH compiler, embedded-system designers no longer have to stick to assembly language; the compiler generates a highly optimized object code. The smart qFORTH compiler translates your high-level qFORTH program into the MARC4 processors native code. The compiler system selects the right assembly-language instruction sequences and addressing modes for optimal operation. The intermediate code passes through rule-based expert systems at different optimization stages. This code is optimized for local centers of reference (colon definitions, macros, loops) to minimize stack operations and register references; it actually scoreboards register references to eliminate redundancies. The qFORTH compiler supports standard FORTH constructs such as: BEGIN .. AGAIN, BEGIN .. UNTIL, CASE .. ENDCASE, DO .. LOOP, IF .. THEN, IF .. ELSE .. THEN, BEGIN .. WHILE .. REPEAT, and the following 4-bit and 8-bit data types: constants, variables, arrays and 8-bit ROM look-up tables. qFORTH extensions are interrupt functions, direct I/O port access, in-line assembly language and direct register access. The compiler also generates a line-number reference file to support sourcecode debugging in the MARC4 simulator and emulator. The compiler is available in two versions. The fully integrated version is run by selecting 'Compile' in the menu bar of the MARC4 integrated environment menu and the command-line version is run by typing QFORTH2, followed by options and the name of the file to be compiled at the DOS command line. 1.1 The qFORTH Program Structure In order to compile your qFORTH program correctly, the compiler expects the program to be composed of directives, definitions and statements. Most qFORTH programs will contain at least a group of statements which will perform computational operations. These statments are edited according to the guidelines outlined in the qFORTH Programmer's Guide. Whether or not you add compiler directives and CONSTANT definitions is dependant on the requirements of your program. They are more or less optional when compiling a qFORTH program. Parameters are expected by the compiler, but not defined by the programmer. The compiler will substitute default values such as for stack size allocation. At the end of this chapter you will find a section which lists the default values used by the qFORTH compiler. But 05.01 first it is necessary to re-examine what the three sections are which make up a qFORTH program. 1.1.1 Compiler Directives The directives are compiler switches used to control the way in which your program is compiled and to specify the format of your compiler generated file(s). The majority of the directives can be implemented as in-line commands appearing at the beginning of your program code. 1.1.2 Definitions The CONSTANT and VARIABLE definitions which are values referenced by your program via names. They should be assigned before the CONSTANT or VARIABLE is referenced within the program. 1.1.3 Statements A qFORTH program is composed of various statements grouped together to perform a particular task which your program invokes via a word. These words are called colon definitions because they appear in your qFORTH program as starting with a colon (`:'), followed by a space and the name assigned to these group of statements. A statement group is a sequential list of MARC4 instructions, words found in the qFORTH system library or words which have been defined in your program before invoking this subroutine. Note: All colon-definitions end with a semi-colon (`;'). Sequences of functionally grouped words are called modules. Modules used to perform the underlying computational tasks of the MARC4 are often caused by interrupt service routines. These are predefined names according to the naming conventions described in the qFORTH Programmer's Guide and are identified by `: INT', whereby is replaced by the priority number 0 to 7. The program entry point is identified as the $RESET service routine since it is the first word which the MARC4 processor will execute after power-on reset. Normally, this colon definition is located at the end of your source program and consists of two parts: the register and the application initialization section. After the initialization of the stack pointers, the on-chip peripherals and the RAM variables of the application have to be put in a welldefined state. 1.1.4 Kicking the Assembler Habit This short description has been intended as an overview to program composition as required by the qFORTH compiler. 1 MARC4 User's Guide qFORTH Compiler To achieve a tighter code with your high-level language, remember the following rules and apply them more or less in order. Stick to these approaches and you will be writing applications that will keep your competition awake at night, not you. D Rethink your approach to problems to see if you can't find a more elegant solution. 1.2 D Make sure you are storing and manipulating your data efficiently. Accessing data using a pointer requires almost three times the number of instructions required to access the same information using array indexing. Check that the correct directory path for qFORTH has been entered in the setting window 'Directories' (see installation guide). D Make your code less abstract and take advantage of hardware-specific shortcuts wherever possible, always weighing the tradeoffs between speed and development time. D Setup the project's file name Using the Compiler D Edit your program file(s) D Setup the compiler options D Invoke the compiler D Optimize your algorithms, eliminating all redundant and unnecessary operations. Use the address activity profiler in the emulator or simulator and optimize where it will do the most good. To set the project's filename use the pull-down menu 'Compile' and select 'Set project file'. The project's filename means the leading filename of the project which will be compiled (see figure 1). D To maximize the limited on-chip RAM, minimize the usage of local variables and too much nested subroutine calls. To invoke the compiler, use the pull-down menu 'Compile' and select 'Built Project' or press the key . This occurence will compile the whole project. D To reduce the stack usage, check your parameter passing and subroutine nesting as well as the number of concurrent interrupt service routines. D Use assembler instructions for the time-critical code but do not fall back on writing whole modules in assembler. The 'Compile' pull-down menu is shown in figure 2. If you wish to compile the currently edited file then either press followed by the carriage return key or simply enter from within the editor. This will automatically start the compiler using the active file as its input filename. 12518 Figure 1. Setup of project file to be selected first 2 05.01 MARC4 User's Guide qFORTH Compiler 12519 Figure 2. Selection of the compiler within the environment 1.2.1 Compiler Generated Messages If the compiler detects a code which can not compile correctly, a warning or an error message will be displayed. The occurence of a warning is an indication to you that your program will still compile and is executable, however, it may not produce a code with the desired kind of execution. If an error is found, the compiler will terminate since it is unable to generate executable code. A complete list of all warning and error messages can be found in the Appendix. D The optimizer passes, because a `.' is written to the screen for each step during optimization and a `,' when macro expansion takes place. D The compilation result: If no errors were found, the amount of ROM (in bytes) required and the calculated CRC checksum stored in the last two bytes of the ROM is displayed. If errors occur during the compilation, the error and/or warning messages will be reported instead. They will be attached at the end of your source code within the list file. The information given during any compilation is the following: Note: D The qFORTH compiler version and the date of creation with the qFORTH system library used with their date of creation 1.2.2 D The name, drive and directory path of the compiled source file The compiler generates various files which are normally directed to the same filename, drive and directory path as the project's source file (see table 1). A complete list of all warnings and error messages can be found in chapter 4.6 "Error and Warning Messages". Compiler Generated Files Table 1 List of all compiler generated files Extension HEX SYM LST CRF ASS HLL LIB RPT 05.01 File Type & Contents Object code Symbol table Complete list and statistics Cross reference file Assembly code list file of compiler generated object code Line number reference file for high level language orientated debugging User generated library for often used routines Compilation success/error report file within SDS Format Binary Internal Text Text Text Internal Internal Internal 3 MARC4 User's Guide qFORTH Compiler 1.2.3 Compiler Switches 12520 Figure 3. Default setting for compiler switches within the option menu To set the compiler switches for different compiler options, use the pull-down menu "Options" and select "Compiler" within the SDS2 environment. software simulator or emulator, you can view the symbol table data. Warnings Compiler Options Assembler This controls, whether an assembler list file is generated. The default extension is "ASS", the default filename is that of the source file. This output file may be used to check the efficiency of the generated object code. List This controls whether a source listing has to be generated. The default extension is "LST", the default filename and path is that of the source file. This generated file contains all events during compilation, depending on additional compiler switches. Object Default setting This controls whether a binary object code file has to be generated. The default ectension is "HEX" and default filename is that of the source file. By default, an object and symbol file with full optimization is created. Symbols Default setting This controls whether a symbol file has to be generated. The default extension is "SYM" and the default filename is that of the source code. This file is necessary if you want to check your code with all defined symbols (subroutines and variables). By pressing the function key at the 4 Default setting This controls whether warnings are written onto the screen and with the setting of the additional switch "List" into the list file too. HLL linkage This controls whether a high-level-language debugger link file has to be generated. The default extension is "HLL", the default filename and path is that of the source file. This generated file enables source level debugging (see chapter 5 "Software Simulator"). Cross reference This controls, whether a cross reference file has to be generated. The default extension is "CRF", the default filename and path is that of the source file. The cross reference file shows the correlations of all used symbols (subroutines, variables and constants) with regard to their definition and their use for different source files. New Library This controls whether a new user library has to be generated. The default extension is "LIB", the default filename is that of the first source file. When a user library is generated, no object, symbol and assemblerfile will be created. A user library contains all codes generated during this compilation or all codes read from other user libraries (see input line "LIBRARIES"). 05.01 MARC4 User's Guide qFORTH Compiler Compiler Statistics List of conditional compilation directives: None $DEFINE By setting this switch, all statistical information is suppressed in the list file. Brief Generates a summary of all errors, all defined words and all defined variables at the end of the list file. Normal Default setting Additionally lists the return and expression stack usage of all routines, the addresses of all words placed in ROM, a summary of left ROM holes, unused RAM nibbles and unused short call address entries, an overview of bytes saved during the optimization steps and information about the compiler's memory usage. To define a symbol, insert this directive into your program. follows the usual rules for identifiers as far as length, characters allowed, and other specifications are concerned. Example: $DEFINE Debug This defines the symbol `Debug' used for the remainder of your program which is to be compiled. $IFDEF Compiles the following code if is defined $ELSE Compiles the following code if the previous $IFDEF is not true, i.e., the is not defined. $ENDIF Marks the end of $IFDEF and/or $ELSE section. Full Additional information about the subroutine placement algorithm, the CPU time for the different compilation steps, statistics on the usage of the internal symbol table data base, summary of created files and used compiler switch settings. Example: Libraries This input line controls whether one or more user libraries have to be read after the system library has been read. By default, no additional user library is read. The list may consist of up to 7 user libraries, their names must be separated by a comma. The default extension is "LIB". 1.3 Compiler Directives A compiler directive may occur anywhere in the source file(s), the first character of a compiler directive is always an "$". In general, a directive is used to control the compilers behavior when processing the source code. Compiler directives can not be abbreviated. 1.3.1 Conditional Compilation To make your job easier, qForth offers conditional compilation. This means that you can decide what portions of your program to compile based on defined symbols. The conditional directives are similar in format to the compiler directives you are accustomed to. In other words, they have the format. $directive Where directive is the directive (such as DEFINE, IFDEF, and so on), and is the argument, if any. Note: There must be a blank as seperator between directive and . 05.01 Defines symbol for other directives $IFDEF $ELSE $ENDIF Where $IFDEF is followed by the appropriate argument, and is any amount of qFORTH statements. If the is not defined, the is ignored as if it had been commented out of your program. Within a skipped conditional block only $IFDEF, $ELSE and $ENDIF are processed. All other words (including directives) are ignored. Skipped conditional blocks are marked with a hash sign `#' in the listing file. Often you have alternate chunks of source code. If the symbol is defined, you need to compile one chunk, and if it's false, you need to compile the other chunk. The qFORTH compiler enables you to do this with the $ELSE directive. Note: All $IFDEF directives must be completed within the same source file, which means they cannot start in one source file and end in another. However, an $IFDEF directive can encompass an include file. Example: $IFDEF MUX4-LCD $INCLUDE LCD-MUX4.SCR $ELSE \ otherwise 3:1 MUX $INCLUDE LCD-MUX3.SCR $ENDIF 5 MARC4 User's Guide qFORTH Compiler In this way, you can select alternate include files based on the same condition. You can nest $IFDEF .. $ENDIF constructs to achieve the following results: $IFDEF Version-2 $IFDEF Debug $ENDIF \ end of debugging output $ENDIF \ Version-2 1.3.2 Compilation Control Index Checking $I+ $I- Default setting Normally the index checking for the array indices is on. When the default setting $I+ is active during compilation, the constant array indices must be kept in the range 0 to . By using $I- for a section of code, the index checking is switched off, i.e., any constant array index may be specified. For example, specifying the DataArray [-1] could be useful while writing to the array using [+Y]! or [+X]! instructions within a loop. Macro Expansion Control $EXPAND Default setting $NOEXPAND $BRA_STRIP ALL All branches are stripped, regardless of whether short branches could become long branches. This kind of branch stripping may result in an increase in code length, but will minimize the execution speed. ROM CRC-Algorithm $CRC The $CRC directive (Cyclic Redundance Check) checks the contents of ROM. The check sum will be stored after compilation at the last two ROM bytes of the last physical ROM bank. The following arguments are available: DEFAULT SIMPLE HARDWARE 1.3.3 16-bit software CRC 8-bit software CRC (optimized code size) 16-bit hardware CRC (for MARC4 variants with built-in selftest) List-File Directives The list file directives will only have an effect, if /LIST was specified in the command line or as one of the compiler options in the integrated environment. $NOLIST $LIST Default setting The source listing is suspended by $NOLIST until $LIST is found again in the source code. $PAGE To modify the time of the macro expansion and thereby the amount of optimization done by the compiler, the $EXPAND and $NOEXPAND directives may be used. The use of the directives $EXPAND or $NOEXPAND on the outside of a CODE definition sets this directive globally. This means that the macro expansion mode influences all following CODE definitions. By default all macros are expanded before the optimization process is started. The directive $NOEXPAND means that CODE definitions are expanded after the optimization process has finished. Branch Stripping Algorithm $PAGE will force a form feed in the print output file, if the list output is active. $DEBUG_STACKS The compiler directive $DEBUG_STACKS, when included in one of the source files, writes the calculated expression and return stack effects of all code and colon definitions into the print file. The four columns following the source line number contain stack depth values that are relative to the beginning of this source line. The sequence of the columns is as follows : - current number of nibbles on the expression stack, $BRA_STRIP NOTALL Default setting Unconditional branches are stripped so that short branches will stay short branches, i.e., if a short branch leads to a second unconditional short or long branch, the first short branch could be stripped. If this results in a long branch, stripping is suppressed. 6 - current number of used return stack entries, - maximum expression stack depth reached within this routine (nibbles), - maximum return stack depth reached within this routine. 05.01 MARC4 User's Guide qFORTH Compiler 27 $DEBUG_STACKS 28 29 | 5| 1| 5| 1| 30 | 31 | 6| 5| 1| 1| 7| 7| 1| 1| : INT7 PortData @ Port0 OUT ; 32 33 34 35 $NOEXPAND $OPTIMIZE -XYTRACE 36 37 | 38 | CODE X- 0| 0| 0| 0| 0| 1| 0| 0| 39 40 [X-]@ DROP END-CODE $OPTIMIZE +XYTRACE an unexpected expression stack under-/overflows or i.e., different stack effects of IF .. ELSE .. THEN parts. On the other hand, the programmer may be aware of the fact that i.e. a LOOP block eats up a specified number of elements from the stack. Therefore, if the programmer is sure that this particular code works perfectly, the compiler warnings can be turned OFF. These compiler directives will be placed at the end of each `block' of qFORTH words (i.e., a DO .. LOOP). They always start with `[ ' and end with the symbol ` ]'. In between those two symbols each combination of the following directives are allowed: E Define expected expression stack effect, R Define expected return stack effect, Ex Define maximum expression stack effect, Rx Define maximum return stack effect, ? Return and expression stack effects of the previous block are unknown, the corresponding WARNING message will be turned OFF. 41 42 | 0| 0| 0| 0| >SP S0 43 | 44 | 0| 0| 0| 0| 0| 0| 0| 0| >RP NoRAM 45 | 46 | 0| 0| 0| 0| 0| 2| 0| 0| Port0 IN 0 = IF RAM_TEST 47 | 48 | 0| 0| 0| 0| 0| 7| 0| 3| ROM_TEST THEN Example: 49 | 50 | 0| 0| 0| 0| 7| 7| 3| 3| 0 0 Timer_A 2 ! $I : BCD@ 51 | 0| 0| 7| 3| 52 | 53 | 0| 0| 0| 0| 7| 7| 3| 3| PortData X! X- 8 #DO 54 | 55 | 0| 0| 1| 1| 0| 7| 1| 1| 0 [+X] ! #LOOP 56 | 57 | 0| 0| 0| 0| 7| 7| 3| 3| 2_Hz Prescaler OUT 58 | 0| 0| 7| 3| ; All values related to the return stack are counted as 16-bit or 4 nibbles entries. The MARC4 core uses 12-bit words on each return stack entry. The address space of the fourth nibble, not used by the return stack, will be assigned by the compiler for single 4-bit variables. All calculated values are relative to the start of the CODE or colon definition. The expression stack values always start with 0. The return stack value starts with 0 in CODE definitions. In colon definitions it starts with 1 because of the return address which is already saved on the return stack. 1.3.4 Stack Effect Directives The following directives have no effect if the compiler switch WARNINGS is turned OFF. The warning messages of the compiler are very helpful when looking for 05.01 ; $I+ \ \ \ Multiplier [ -1 ] Y! \ 8 #DO [ +Y ]@ \ \ [E0] \ \ #LOOP [E8] \ \ 1.3.5 Turn index checking OFF Push a number of digits onto the stack Setup array pointer Push an array element onto the stack Turn the compiler warning message OFF Set correct number pushed onto stack Optimization Control The amount of optimization done during the compilation process can be controlled by the $OPTIMIZE control switch. By default all optimization steps will be performed. $OPTIMIZE , The ABSOLUTE range of optimizations to be performed is set by qualifying the control switch $OPTIMIZE. The only types of optimization performed furthermore are those, that are listed after $OPTIMIZE. $OPTIMIZE {+-}, {+-} The optimization qualifiers can also be used in conjunction with the $OPTIMIZE control switch for a 7 MARC4 User's Guide qFORTH Compiler RELATIVE setting in the source files. The kind of optimizations performed is determined by adding (+) or removing (-) the listed types from the current optimization set. A CALL instruction is replaced by a SCALL, whenever possible. SAVECONTXT $OPTIMIZE ? The current optimization control settings are written into the print output file. $NOOPTIMIZE $OPTIMIZE CALL Default setting All kinds of optimization are inhibited when the $NOOPTIMIZE is specified. Whereas $OPTIMIZE will cancel a previous $NOOPTIMIZE directive, i.e., the optimization set is the same as before the $NOOPTIMIZE directive. It is possible to control the optimization process in such a way that some specific subroutines or macros will not be optimized. For example, no register tracing in a handoptimized memory block MOVE routine. $OPTIMIZE Qualifieres The user may parameterize the $OPTIMIZE directive with the following qualifieres: CALL optimizer pass [ CALL SCALL ], Branch optimizer pass [ BRA SBRA ], Comparison optimizer, DUP .. DROP optimizer, SWAP .. SWAP optimizer, Register load optimizer, Register load with memory fetch/store operation, XYTRACE Register scoreboarding, preincrement /postdecrement XYLOAD CALL BRANCH CMP DROP SWAP XYLOAD XY@! Sequences like LIT_p LIT_q .. X! will be optimized to a >X $pq instruction. XY@! Sequences like >X $pq .. [X]! will be optimized to a [>X]! $pq instruction. XYTRACE By reloading the X or Y register sequences like [>X]@ or [>Y]! $pq will be replaced by [+X]@ or [Y-]! operations, whenever possible. The INTx prefix and postfix register save macro (X@ Y@ CCR@ .. CCR! Y! X!) is reduced, whenever possible. If INT5 does not change the register, X@ and X! are removed from the routine's prefix and postfix sequence. The lowest priority interrupt routine may be compiled with: $OPTIMIZE -SAVECONTXT : INT0 Calculate_On_Off Update_LCD ; $OPTIMIZE +SAVECONTXT BRANCH A long branch instruction is optimized to a short branch instruction within a code page whenever possible. BRA_EXIT Unconditional branches to an EXIT instruction are replaced by an EXIT, also unconditional branches to an instruction that is placed directly before an EXIT are replaced by this instruction followed by an EXIT. BRA_STRIP A branch to a second unconditional branch will be changed so that the first branch goes directly to the target of the second branch. This will not save any code, but result in a faster execution speed. See also the compiler directive $BRA_STRIP, which allows you to control the amount of branch stripping being performed. DROP Any sequence .. DROP will be removed from the code if this nibble is not used anywhere else and results in no side effects. Note: Because [+Y]@ DROP will change the Y register, it is not optimizable. SWAP Any sequence SWAP .. SWAP will be removed whenever possible. Furthermore, any sequence LIT_x .. LIT_y .. SWAP will be optimized to LIT_y .. LIT_x. CMP Sequences like CMP_cc .. TOG_BF .. BRA are optimized to the sequence CMP_cc .. BRA, where cc is the opposite condition of cc. Also TOG_BF .. TOG_BF sequences are omitted which may result from macro expansions. 8 1.4 Compiler Optimization Steps The previous section described how to use the compilers optimization directives. The code optimizations implemented are reviewed in this section. 05.01 MARC4 User's Guide qFORTH Compiler 1.4.1 Branch Optimizer Short branches are used whenever the address is achieveable within the present 64-byte page, otherwise full branches are used. The programmer does not need to be aware of any page boundaries. 1.4.2 Call Optimizer Short calls can only be used for colon definitions in the Zero Page (the first 512 bytes). These definitions are automatically selected to be placed in the Zero Page as a result of their size and static usage. The programmer can force a Zero Page placement by appending either AT

or `[ Z ]' compiler directives at the end of a colon definition. 1.4.3 Example 1: Compile time constant folding Source Assembly code FRED @ Lit_3 Lit_4 [>X]@ $FRED X! [X]@ Optimized code Example 2: DUP DROP optimizing resulting from the MARC4 implementation of the compare instructions, where only one of the top two elements is dropped. Source Assembly code Optimized code DUP 3 = DUP Lit_3 IF Lit_3 CMP_NE .. CMP_EQ SBRA $THEN THEN DROP TOG_BF BRA $THEN Register Tracking While a good assembly code programmer may never write code with redundant DUP and DROP instructions, 05.01 Example 1: Variables FRED and BERT are in consecutive RAM locations Source Assembly code FRED@ BERT +! Peephole Optimizer The peephole optimizer replaces a sequence of instructions with a shorter, more efficient sequence. In general, a stack architecture allows a much wider peephole than normal, as stack effects within a `basic block' may be evaluated at compile time. This means that a given code sequence does not need to be consecutive. Currently eight separate peephole sequences are checked. The following example shows the two sequences which were found to occur most frequently. 1.4.4 it is often the case that he may forget exactly which variables and addresses are cached in registers. A good compiler however, can keep track of which register contains are variable. This is especially true in qFORTH since the programmer's model of the machine has no additional registers. Lit_3 Lit_4 X! [X]@ Lit_3 Lit_5 Y! [Y]@ ADD [Y]! Optimized [>X]@ $FRED [>Y]@ $BERT ADD [Y]! Final code [>X]@ $FRED [+X]@ ADD [X]! (+! macro) Sometimes register tracking may also eliminate redundant address register loads across an IF statement. Example 2: FRED @ DUP 5 <> IF BERT ! ELSE DROP 0 FRED ! THEN 1.5 The Command-Line Compiler Compiling qFORTH programs can also be done by using the command-line approach common to most computers where each step in program generation occurs from the command line. On your PC this means from the DOS command line indicated by the prompt, such as the drive indicator. C:\MARC4 > qFORTH2 [/] [/] To invoke the compiler, enter the program name qFORTH2 followed by the filename to be compiled. Normally, a file extension is not required since `SCR` is default when compiling a main program. As an example, to compile a file called `MYFILE.SCR' with the generation of a list and object code file, the following command-line sequences would be accepted as valid by the compiler: QFORTH2/LIST/NOSTAT MYFILE QFORTH2 MYFILE/LIST/STAT=NO QFORTH2/LIST/SYM MYFILE/STAT=FULL 9 MARC4 User's Guide qFORTH Compiler An overview of the various compiler switches, options and directives accepted by the command-line compiler is listed in the subsequent sections of this chapter. After the compilation of your program is completed, the DOS drive indicator will appear on the screen permitting you to either enter the simulator or emulator (in command-line mode) or to go back to your program editor to correct any possible errors which may have occured. 1.5.1 depending on additional compiler switches. /NOWARNING /WARNING This controls whether warnings will be written onto the screen and - with the setting of the additional switch "$List" - in the list file, too. Compiler Generated Messages /NOSTATISTICS The generated messages of the command-line compiler version are the same as the MARC4 environment integrated version. 1.5.2 /STATISTICS[=] : Compiler Generated Files /STATISTICS=NO (is identical to NOSTATISTICS) A listing of all generated files is shown in table 1. 1.5.3 Default setting /STATISTICS=BRIEF Setting the Compiler Switches The compiler switches of the command-line version are the same as the integrated version. Default switch settings do not have to be called in the command line. For more detailed information, see the section 'Compiler Switches' of the integrated version. Object Code Generation /STATISTICS=FULL No By setting this switch, all statistical information is suppressed in the list file. Brief /NOOBJECT /OBJECT[=