-------------------------------------------------------------------------------- INFO -------------------------------------------------------------------------------- For all listed email addresses : >d.t< to be substituted by a dot '.' >a.t< to be substituted by an at sign '@' These are unique strings in the text, a global search and replace would work. File : Manual.txt Program : x4th, 4th compiler, x4th target libraries. Version : 2011.11.5.1 Author : Jan Punter j>d.ta.td.td.ta.td.ta.td.ta.td.t or <#aname arg1=value1 arg2= ... =valuen>. These constructs can be moved around freely or they can be removed at will, but no new names can be used without modifying the Pascal sources. There is no coupling mechanism currently with the x4th system. Dump ... -------- Dumps the complete current interpreter state to a text file. When you have a bug you can't resolve I might ask you for a dump to see if I can make sense of the system state. Run --- Starts interpretation on the selected top level source file. Interpretation can be suspendeded by using Break. This will change the Run button into a Continue button. On each new run the console window will be cleared. Continue -------- Resumes suspended interpretation. Step ---- When interpretation is suspended clicking Step will execute the next word to be excecuted stepping over any sub words. Into ---- When interpretation is suspended clicking Into will execute the next word to be excecuted going into any sub words. Reset ----- Clears the interpreter. After clearing continuation is no longer possible and the Continue button will turn into a Run button agin. Break ----- Break the current interpretation. Animate ------- Automatically perform Into clicks at regular time intervals. -------------------------------------------------------------------------------- Tabsheet Compiler ----------------- Compiler settings ----------------- Create output file as readonly ------------------------------ When checked it create the generated assembler file as a read only file to protect it from modification by MPLAB. Use asm macro post processor ---------------------------- When set macro post processing will be applied to the generated target assembly file. This post processing will expand all assembly macros it sees. This eases debugging in some versions of the MPLAB development environment. List asm macros --------------- When post processing has been turned on checking this option will result in listing the assembly level macros as comment in the final output file. Generate debug info ------------------- When checked this setting will include extra debug information into the generated assembler file. This setting needs support from a macro called (debug-info-func) in the processor dependent include file. For the PIC 24 it is currently defined as : macro (debug-info-func) ( aName ) ( -- ) // Debug info for function // definitions .ifdef __C30ELF .type $aName$, @function .endif endMacro It will make the function known to the debugger, when the ELF format is used for object files. Warn for possibly invalid numbers --------------------------------- Special modifiers can be used to specify numbers to be of a certain type. Single numbers do not use a modifier, double numbers use a dot (.) tripple numbers use a tilde (~) and quad numbers use an underscore (_). When this setting is selected to be on warnings will be genrated on numbers containing morethan one modifier. Another modifier type is the ' (single quote) this will start the base to be set to ASCII. For example 'I can be used to get a numerical representation of the character I. When converting numbers in ASCII base there will be warnings (when enabled) on strings longer than two characters (like 'AB for instance). Clip target identifiers ----------------------- When checked target identifiers will be clipped to the number of characters specified with the Characters spin edit. Such clipping is performed after name mangling has been applied. Warn for long identifiers ------------------------- When checked identifier lengths will be checked to not exceed the number of characters speciefied in the Characters spin edit. When they do exceed that length a woarning is typed on in the console window. Warnings are checked on identifiers before clipping has been performed. So when clipping is turned on and warning is turned on as well the identifiers will be clipped and any item that was clipped will still generate a warning message. Compile 4th valus as -------------------- address constants ----------------- In this mode the compiler will bind values to addresses and it will generate initialization code for those values. The user will have to use the word InitValues ( -- ) to actually perform this initialization. This isn the mode I've always used for PIC 18 and smaller processors, it can be used when direct linkerless assembly is used. initialized variables --------------------- In this mode the compiler will compile values into the .data section leaving initialization to the C startup code. This mechanism will not be set up by the compiler but it left to the linker instead. This is the mode I started using for the PIC 24, it needs the assembly and linker process to be separated. This allows for 4th code to be mixed with unrelated assembly code and C code. Type checking ------------- Check stack pictures -------------------- When checked all words defined should have a proper stack picture, and when thay do not have a proper stack picture a warning message will be typed to the conole. When not checked definitions are not checked to have a proper stack picture definition. Validate colon pictures ----------------------- Not implemented, value is a don't care currently. When this gets implemented colon words ( : aWord ( -- ) ... ; will be checked to see if the stack contract specified could match with the words used in the definition. For this to work the sizes of some standard objects have to be known to the compiler. These are : Integer size ------------ Data cell size, 8 bits for PIC 18 and lower, 16 bits for PIC 24. $ram size --------- Size of a RAM string, 2 or 3 bytes for PIC 18 or smaller, 3 bytes for PIC 24. $rom size --------- Size of a ROM string, 3 bytes for PICs 17 and smaller, 3 or 4 bytes for PIC 18 and 5 bytes for PIC 24. A ROM string is a size and a ROM pointer. RAM ptr size ------------ The size in bytes of a RAM pointer, 1 or 2 bytes for PIC 18 and before, 2 bytes for PIC 24. ROM ptr size ------------ The size in bytes of a ROM pointer. 2 or 3 bytes for PIC 18 and bbefore, 4 bytes for PIC 24. Set size -------- The size of a small set. A small set is a Pascal like set that can hold elements having ordinal values 0 .. , this is mapped to a bitmap. All current implemetaions use 4 bytes, but the library files determine what it will actually be. Debug ----- Show Progress ------------- When checked compiler progress will be shown on the console window. Show file enters ---------------- Type a file inclusion message when interpretation is started on an include file. Show file resumes ----------------- Type a file leave message when interpretation of an include file is ended (and the file using the include is being resumed). Show todos ---------- When checked todo' xxxx' items found in the source code will be typed to the console window. Show dones ---------- When checked done' xxxx' items found in the source code will be typed to the console window. It is assumed that todo' xxxx' items will be modified to done' xxxx' when they are dealth with. Show return stack ----------------- When set show a return stack picture in debug mode. Show data stack --------------- When set show a data stack picture in debug mode. Show instruction pointer ------------------------ When set show the instruction pointer in debug mode. The instruction pointer points into the x4th dictionary. Displays of the dictionary's contents can be obtained with the documetation system, with the dump facility or by using some of the debug dump features as listed in example make.4th files. Show word class --------------- Show the word class of the word being interpreted in debug mode. This is the name of the Pascall class implementing the word type (leaving out the first character of that name (which is presumed to be a 'T')) -------------------------------------------------------------------------------- Tabsheet Settings ----------------- Documentation settings ---------------------- Document unused words --------------------- In the generated documentation do include words that do not lead to target code generation. Document meta words ------------------- In the generated documentation do include words that have the Meta attribute set (words that were compiled in Meta mode). Docuiment Pascal words ---------------------- In the generated documentation do include words of the class Pascal.these words form the user accesible part of the x4th interpreter. A listing of these words is present in this document. General settings ---------------- Allow system.execute -------------------- x4th can run executable files through a shell interface when this setting is enabled. On top ------ When checked the x4th compiler window will keep itself on top of windows not having their on top feature set. Show hints ---------- When turned on mouse hovers over display elements will show a hint text. Hide some hints --------------- The most irritating hints will not be shown. Colors used in console view --------------------------- Colors for information typed to the console window. Default - the default output color to use when no other rules apply ------- Help - the color to use for help text ---- Debug - the color to use for debugger output ----- Info - the color to use for general information ---- Message - the color to use for text generated by the words message ------- and message' Warning - the color to use for text generated by the words warning ------- and warning' Error - the color to use for text generated by the words error and ----- error' Todo - the color used for todo' text' ---- Done - the color used for todo' text' ---- Return Stack - the color used for return stack dumps (in debug mode). ------------ -------------------------------------------------------------------------------- Tabsheet Tools -------------- Translate processor specific include file ----------------------------------------- Can be used to translate MicroChip processor specific include files into an x4th module. Tabsheet About -------------- Shows general information about the program, version info mainly but my website and email address as they once were are listed as well. -------------------------------------------------------------------------------- GENERAL SYSTEM INFO -------------------------------------------------------------------------------- The x4th compiler takes a 4th file for input and will try to translate it into an assembly file suitable to be assembled by the Microchip development environment (I currently use MPLAB IDE v8.10). The x4th compiler is based upon a forth like system, and it is not ANSI compatible. It might not even be Forth in some people's views. x4th can be considered to be a meta compiler, being a system that takes a forth like input file and tries to translate that into code to be run on another processor type. The compilation process is largly controlled by macro and code definitions in a procesor dependent library file. By changing the library file a different processor can be targeted. The forth system implemented by x4th differs from the target forth system in some important ways. Most important things to know are : x4th : A forth like language implemented in Delphi Object Pascal. Uses a CELL size of 32 bits and the address unit is 32 bits. The dictionary space is implemented as a list of CELLs with a theoretical capacity of 2^31 - 1 CELLS. CELLs can either hold numbers or object Delphi references. Pointers to anything really ... All target words are compiled into object pascal objects for which pointers are compiled into the dictionary. The target objects are macro like objects that can only be manipulated through the built in macro languages. The stacks used by x4th can hold 32 bit entries, and these can hold nearly anything, just like the dictionary. Run time type information about the stack elements is present. This means that strings can be on stack, or Delphi objects. Mostly x4th will know how to handle these through a partially automated type casting mechanism. Sometimes this will cause cryptic error messages when stack errors were made. All stacks have a capacity of 4096 entries. There are three stacks a data stack, a return stack and a control stack. A size change would mean a compiler recompile. Some type checking is present through the automated typecasting mechanism. A direct threading model is used, but the code is not native machine code but invocation of Pascal procedures encapsulated in Pascal objects rather. The possibiliy to have arbitrary objects on the stack comes at a cost regarding the create .. does> mechanism. Some special trickery is used to make this usable. The target forth : Has no text or outer interpreter, unless defined by the user. Has a non uniform CELL size dependent on the target processor. For instance for the PIC18 family a data CELL holds 8 bits (in RAM) but a memory CELL (in ROM, FLASH or EEPROM) holds 8 .. 24 bits depending on what memory space is used and on what exact processor model is selected. For the PIC 24 16 bit data cells are used. A native code compilation model is used (subroutine threading and inlining of simple words). No optimization has been implemented, only used words will be compiled. The target word set is determined by both the compiler builtin words and the supplied library files. Some words, and all immediate words (mainly used for control structures, but also for words that can be used by both the x4th and target systems) need compiler support in order to be able to use them. The implementation details are determind by the library files. Look for words with names that are enclosed in parenthesis (like in '(dup)' for instance). The target system uses three stacks as well. There is a data stack that works the usual way and this one has a CELL size of 8 bits (or 16 for the PIC 24). The maximum depth is set in the processor dependent include file. There is a return stack, which is implemented in the processor hardware (the PIC 24 has it in RAM though) and that one has a CELL size and a maximum depth which depends upon the target processor being used. There is a third stack on which words like >r operate, this is not actually the return stack although it is called so. This one uses a CELL size of 8 bits (16 for PIC 24) and it's maximum depth is set in the processor specific include file. -------------------------------------------------------------------------------- PROJECT SETUP -------------------------------------------------------------------------------- I usually use the folowing folder layout for a PIC project : | +- "[controller]" embedded controller code | | | +- "[work]" the current version to work on | | | | | +- "make.4th" the project's make file | | ~ ... | | ~ ... | | +- "work.4th" the file containing the word "main" | | | | | +- "make.ini" project specific x4th ini file | | | | | +- "program.asm" x4th compiler output | | | | | +- "[lib]" x4th code libraries | | | | | +- "18f452.inc" Microchip processor include file | | | | | +- "18xxx2.4th" The processor dependent library file | | | | | +- "i2c.4th" i2c library | | | ... The file make.4th is the top level project file, it is the file x4th is pointed to for compilation. This file will reference all other files used and it will tell the compiler what to do. The name make.4th is arbitrary, but there must be one top level file that determines what other files will be used. make.4th generally looks something like: ------------------------------------------------------------------------------ xVersion" 2007.5.21.1" // Requires x4th 2007.5.21.1 OutputFile' program.asm' // Output file to be generated by x4th #Define 18f452 // Intended processor #define UseInterrupts // This program uses interrupts LibraryPath' .\lib\' // Specify a common library path CodeLibrary' 18xxx2.4th' // Target specific library file Title // Define a title for the list file HexFormat INHX32 // Define the hex format to use for the assembler. AsmConfig 0 0 DEC // Confi assembler ( errorLevel LinesPerPage Radix ) // don't change radix, the library wants it to be // DECimal. include' hwconfig.4th' // Hardware configuration definitions include' hardware.4th' // Hardware definitions and register setup. include' fatal.4th' // Fatal error handling codeLibrary' timers.4th' // Generic timer support codeLibrary' queues.4th' // Generic queue support codeLibrary' utils.4th' // Various utils include' interrupt.4th' // Interrupt handlers codeLibrary' i2c.4th' // i2c eeprom drivers codeLibrary' strings.4th' // String support include' work.4th' // The application, defining Main as public. mainword main // Set 'main' to be the top level word uses Work endUses // Import the Work Module for the word Main Build // Generate target code ------------------------------------------------------------------------------ First the 'xVersion' word is issued. All x4th files need this definition to be present, it needs not be at the top of the file, but that seems the most logical position for it. The version is compared by x4th to it's own version number and it then determines whether it will use the file or not. Minor version differences will result in a warning message, major differences will cause x4th to stop with an error message. It is always possible of course to edit the source file version. This then may result in some incompatability issues having to be resolved. The compiler is set to generate it's output into a file 'program.asm' (by 'OutputFile'') that resides in the same folder as make.4th. The target processor is a PIC 18f452, and the library file to be used is 18xxx2.4th loaded from the folder '.\lib\' relative to the folder that make.4th is in. The 'hexformat' directive is intended to be used by MPASM, it determines the hex file format to use when translating 'program.asm'. This depends on the programmer that later will be used to program the actual device. Not used for PIC 24. Also there is a list of files to include for compiliation ('include'' and 'codeLibrary'' words). Include files are loaded relative to the the folder where make.4th resides. CodeLibrary files are loaded relative to the folder where the LibraryPath points to. It is also possible to add items to the search path by using '" string " addToSearchParh' or 'addToSearchPath' string''. The construct 'uses Work endUses' tells x4th to make the public words of the module work visible for the remaining part of make.4th. This is used to make the word 'main' visible. Main must be a public word in the module work.4th in this case. The word 'main' is the top level compilation target and it needs to be visible before 'build' can be executed. Another top levelword can be set with the word 'mainword', in the code above it merely restates the default behaviour of 'main' being the main word. Instead of 'uses xxx endUses' the construction 'import xxx' can be used as well. Finally the word 'build' will write the output file ('program.asm') from all the information gathered before. This is the actual target compilation process, everything before has actually been x4th interpretation and compilation. -------------------------------------------------------------------------------- MODULE LAYOUT -------------------------------------------------------------------------------- Most x4th files other than make.4th will be written as modules. The module mechanism uses the x4th vocabulary mechanism to make certain words visible to the outer world while hiding other definitions. Words in a module must explicitly be made visible before they can be used in other source files. And those other source files must import the modules it wants to use the public words from. The general module layout is as follows : ------------------------------------------------------------------------------ xVersion" 2007.5.21.1" module Demo1 private uses import-module-1 .. import-modulen endUses : private-word1 ( -- ) ; : prvate-word2 ( -- ) ; public uses import-module-1 .. import-modulen endUses : public-word ( -- ) ; export private-word1 ( -- ) endModule ------------------------------------------------------------------------------ This defines a module called Demo1. Usually the file this module is in will be called Demo1.4th, but matching file / module names are not enforced. Also there is no need to have just one module in a source file; you can list as many or as few (including zero) as you want. The module Demo1 has one Private and one Public section, but you can have as many private or public secions as you want and they can be in any order. The 'uses .. endUses' construct will import public words from the modules named within the construct. Usually such a list will occur just after the words 'private' or 'public', but it can be used anywhere to defining a new search order. Note : the usual forth mechanism using words like 'only', 'also', 'definitions', 'vocabulary' etc. can also be used. The 'uses .. endUses' construct is in fact built on top of the standard forth vocabulary mechanism. Words defined in a Private section of a module can only be used inside that module, either in Public or in Private sections. Words defined in Public sections have that same visibility but in addition can be used in other modules as well (privided that the module is listed in a 'uses .. endUses' list in the importing module). The word 'export' removes a word from the vocabulary it was found in and puts it into the current compilation vocabulary (definitions). This can be used to make private words public. Note : The normal forth rules where a word has to be defined before it can be used are in effect in x4th as well. So the module export list has to be at the end the file. Finally modules must be ended with the word 'endModule'. EndModule will check the x4th stacks to be empty, it is not normally possible to transfer values into or out of modules over any of the stacks. Meta variables can be used to transfer values into or out of a module. -------------------------------------------------------------------------------- WORD TYPES -------------------------------------------------------------------------------- Macros and code words are used throughout the system and they contain target code snippets. The difference between a code word an a macro word is that a macro is compiled as inline code and a code word is compiled as a call to that code. This does not always hold exactly as macros are also suitable for target high level forth code paramterization. Special provisions were made to be able to run x4th code from within macro and code definitions at the time they get written out to the output file. Another way to define target code is by using colon definitions in the normal forth way. Both Colon definitions and code definitions are translated into calls to code. A macro definition looks like : macro aMacroName ( arg1 arg2 ) ( stack-in -- stack-out ) // Documentation Macro body using $arg1$ and $arg2$ for parameter substitution. endMacro A code definition : code aCodeName ( stack-in -- stack-out ) // Documentation machine code ; // Execute some code return ; // ----> return to caller endCode And a high level colon definition : : aHighLevelName ( stack-in -- stack-out ) #// Documentation forth words here ; Apart from this there are words to deal with constants and variables on the target system. These are the usual words like 'constant' and 'variable', but also strings and arrays can be defined (as well as multi cell constants and variables). Constants and variables always have a dual identity in that they can be used both for x4th and in target code. For x4th use they can hold 32 bit values and strings, for the target system they have to be restricted to the target data CELL size. X4th itself can also use Pascal words. These are words implemented as Delphi code in the x4th program itself. Pascal words can not be compiled into target code, but they can cause target code compilation to be performed. It is also possible to write colon definitions that are to be seen as compiler extensions. Such words can not result in target code to be generated directly. It has to be noted that not all combinations of constructions mentioned above will always work, or will always work as expected. I made what I saw fit and usable in arather ad-hoc manner, and although I try to make things complete and symetrical I may have missed a couple of issues that I've never thought of to use. Forth code can use arbitrary character sequences separated by spaces as names for words. The target system however has some pretty strict rules for what names are acceptable (as the code generted will be an assembly file to be further translated by an assembler). To match x4th names to target names a mangling algorithm is used. All names are prefixed wit the character 'C' (or another user defined prefix, Like '_' for PIC 24 code, when it has to be C callable) and all occurances of characters assumed to be not allowed are changed into a numerical equivalent. The original x4th name will be used in automatically generated comments where useful and or possible. Target identifiers will always start with a letter or an underscore and then they can have letters, underscores or decimal digits. All other characters (including the @ character) will be translated. A maximum length can be set for target identifiers and anything longer will be truncated (this feature can be turned off). Target names have to be unique identifiers, this is always enforced by the compiler (but mostly so) and violations may result in assembly time errors. By using macro or code words target assembly code can be used directly. To make it possible to have references from such code to x4th names a special embedded forth syntax is used : <@" Forth.Name"> This in facrt is an example of using the embedded x4th evaluator from within macro and code definitions. This special form will evaluate a forth symbol into a target symbol, mangling and truncating it when needed. In this case the construct would evaluate to : CForth2eName which is (assumed to be) an acceptable name for the target system. Another form of embedded x4th is : Such arbitrary forth code will be evaluated by the 4th compiler when the macro or code word the the embedding is in gets written out to the destination file (compiled). A temporary data stack frame will be used in the normal data stack during embedded code evaluation. Any stack results resulting from evaluation will be concatenated as if they formed a list of strings. That concatenation will then be the result of the embedding and it will be written to the destination file. Often the stack will be empty after evaluation, resulting in an empty string being returned. In that case it is the side effects of the evaluation that makes the construct interesting. It should not be possible to consume more elements from the temporary stack than are produced. The arbitrary forth code mentioned above could not contain some special caracters normally so an escapement mechanism was implemented for it. Also by making a level counting mechanism it is possible to use and <@" ..."> constructs nested within each other and themselves. Escapment is introduced by a single '\' and the following applies : \ -> So to use the characters '<', '>' and '\' (or possibly ''' and '"') they must be written as '\<', '\>' and '\\' (or '\'' and '\"'). BTW actually '<@ .... >' is equivalent to '' where mangle translates the the top stack entry into a target acceptable identifier. The form '<@" string">' is equivalent to '' and this starts the x4th evaluator with '" string" mangle' in the input stream. Strings are a first class data type for the x4th system (but not for the target system), and the string will be pushed onto the data stack for mangle to mangle it. The macro mechanism can also used for parameterized x4th high level definitions. In the following example code this is used to define counting objects. macro Counter ( aName ) ( bIniValue -- ) endMacro This then can be used like : '1 Counter aCounter' Which defines a Counter called MyCounter with an initial value of 1. 'aCounter++' will increment the counter 'aCounter@' will get it's current value 'aCounter.reset' will reset the counter to it's initial value This mechanism can not be used with code words, but there still is a way to use the mechanism for assembly code as well. for an example of this look at the library files 'queues.4th' or 'timers.4th' . Some more details .. before I forget ... x4th itself is case insensitive. It will use the user casing in the generated assembly file and this may make it necessary to set the assembler used to case insesitivity (not in all library files the Microchip 'standard' casing is used ... the GNU assembler used for the PIC 24 seems pretty anal on casing). Numbers are interpreted in the current number base, which can be set by storing a value into the 'base' variable, or by using the words 'binary', 'decimal' or 'hex'. Additionaly the number base can be overruled in the following way : %digits - binary numbers &digits - decimal numbers $digits - hex numbers There can be more than one number base modifier in a number, but this is confusing. By prefixing a character with a single quote that characters ASCII value will en up on the stack, as in : 'a The character modifier can not be mixed with the base modifiers, and a character value can not be signed. the standard? word '[char]' is not supported. Double numbers are defined by using a dot in the number, tripple numbers by using a tilde and quad numbers are defined by using an underscore, like : 100.0 - a double number 100~0 - a tripple number 100_0 - a quad nmber Not all processor dependent x4th files support all of the number types, number type support requires some macros. E.g. the PCIC 24 library currently has no support for quad numbers and only limited support for tripple numbers. Negative nummbers must start with a dash (or minus sign) as in : -%1010 - which is equal to minus 10 decimal. The x4th system has some special string support stuff mainly for use as macro actual parameters. When there is a macro defined as : macro aMacro ( anArg ) ( -- ) Do something with $anArg$ endMacro it can be invokded as aMacro anArg Or when the actual argument value to be used would have spaces in it : aMacro This same syntax can be used for strings to be read from the input stream by using the word 'token' ( bSeparator -- ). It is not a general mechanism for strings though. Double quoted string tokens use a C like escape mechanism using the '\' character. The complete specs for the token scanner are : - If extended scanning is on : if aSeparator = ' ' and the token to scan starts with '<' then use '>' as the separator and treat everything between '<' and '>' as a single token, even when spaces are contained within this string. - If aSeparator = '"' (the double quote character) then scan for a string in the following way : Process '\' characters in a C like manner : \\ - treat as a single '\' character \" - treat as a single '"' character \nnn - treat as a decimal - 3 digits must be present \$xx - treat as a hex number - 2 digits must be present \%bbbbbbbb - treat as a binary number - 8 difits must be present Extended scanning will be off for normal x4th token scanning (to allow for words like '<' to be scanned correctly). -------------------------------------------------------------------------------- WORD HELP -------------------------------------------------------------------------------- Not too much actual word help here I'm affraid. All I had was borrowed from Michael but it didn't make sense anymore after some eight years of organic growth. I erased it all and started anew, the task is not completed though. The automatic glossary generator is not finished yet, but a DIY HTML glossary can be made in the following way. Make a file glossary.4th (it might be present already in the x4th application folder) with the following contents (leave out the two lines of dashes) : -------------------------------------------------------------------------------- xVersion" 2007.5.21.1" MarkAllUsed // Turn of un-used word elimination outputFile' glossary.asm' #define 18f452 codeLibrary' 18xxx2.4th' title glossary hexFormat INHX32 asmConfig 0 0 DEC : main ( -- ) ; Build -------------------------------------------------------------------------------- Compile that file with x4th and ignore the warnings about unfound resources. Next, make sure to have all of the following options checked in the settings tab : - document unused words - document meta words - document pascal words Then generate a doc file named glossary.htm (from the Work tab). Keep the generated html file for reference, the generated file glossary.asm can be deleted, or it can be inspected as to see how target code is generated (all unused words will be present due to the use of MarkAllUsed in glossary.4th). (glossary.htm might already be present in the x4th application folder). This will give you an overview of the words used in the x4th compiler and the words present in the processor dependent library. The layout of HTML documentation can be controlled through a couple of template files. These are present in a subfolder called 'templates' in the x4th application folder. One of the templates used holds a stylesheet section that controls most colors and fonts (x4th_doc_template.html). -------------------------------------------------------------------------------- Still ... here is a list of all the compiler built ins (Pascal words) with some short comments. No particular order. // ------------------------------------------------------------------------- Only Definitions // Compile a few words to the system pseudo vocabulary 'only'. system.reset ( -- ) Clear complete x4th system and go on interpreting in the current file, all definitions made before will be forgotten. system.ShowResults ( -- ) Dump the current console contents to a file. The name is being popped from the data stack. system.Execute (

-- ) " Program" " args" system.Execute Executes an external program called Program with a commandline " args". Any results from that program written to stdout or stderr will be copied to the console window afterwards. Only ( -- ) Pseudo Vocabulary containing basic vocabulary control words like: 'Also', 'Vocabulary', 'Definitions', 'ShowVocs', 'DropVocabulary', 'XVersion'. Sets 'Only' as the only vocabulary to be searched (context). Also ( -- ) Duplicates the toplevel search vocabulary (context). Vocabulary ( -- ) To be able to define new vocs, used as : Vocabulary VocName When VocName is later executed it will set itself as the top level search vocabulary (context). Definitions ( -- ) To set the current compile voc (current) equal to the top level search vocabulary (context). ShowVocs ( -- ) Show a list of all defined vocabularies. DropVocabulary ( -- ) Removes the top of the search order (context). XVersion" ( -- ) To check versions. #eof ( -- ) Special token to denote 'end of file', used to stop interpretation on 'end of file', can be used to break out of a source file as well. // ------------------------------------------------------------------------- Only Forth Definitions // Compile the rest to the Forth vocabulary // These are for the meta compiler. // The meta helpers are used in meta compiled x4th definitions, mainly for // control structures. They are not used to generate target code from in the // target compilation process. The processor specific include file has a set // of target specific helper words that are used to implement the same sort // of structures for the target platform. Those words will usually be // enclosed in parenthesis (like : (begin) or (loop) etc.). Those words // are not listed here though. _Begin ( -- ) meta helper _Until ( n -- ) meta helper _While ( n -- ) meta helper _Again ( -- ) meta helper _Repeat ( -- ) meta helper _Do ( n1 n2 -- ) meta helper _?Do ( n1 n2 -- ) meta helper _Loop ( -- ) meta helper _PLoop ( n -- ) meta helper _Leave ( -- ) meta helper _I ( -- n ) meta helper _J ( -- n ) meta helper _K ( -- n ) meta helper _>R ( n -- ) meta helper _R> ( -- n ) meta helper _If ( f -- ) meta helper _Else ( -- ) meta helper _Then ( -- ) meta helper _Case ( -- ) meta helper _default ( -- ) meta helper _EndCase ( -- ) meta helper _Of ( n1 n2 -- n1 | ) meta helper _EndOf ( -- ) meta helper _Exit ( -- ) meta helper _Try ( -- ) meta helper _Except ( -- ) meta helper _Finally ( -- ) meta helper _EndTry ( -- ) meta helper _Raise ( -- ) meta helper // ------------------------------------------------------------------------- // This is normal stuff, the usual words, and some less usual maybe. NewLabel ( -- ) Create a new and unique label name Module ( -- ) Module start tag. Module Private Public Export EndModule EndModule ( -- ) Module end tag. Module Private Public Uses Export EndModule Public ( -- ) Creates a ModuleName.Public vocabulary and sets it as curent. Module Private Uses Public Export EndModule Private ( -- ) Creates a ModuleName.Private vocabulary; sets it as curent. Module Private Public Uses Export EndModule Uses ( -- ) Uses modulenames EndUses. Module Private Public Uses Export EndModule Export ( -- ) Find/remove word from Context and link it into Current. Module Private Public Uses Export EndModule Defer ( -- ) Defer XXXX ' ( -- ExecutionToken ) ' XXXX Search next word in input stream and return it's execution token. Also see ['] ['] ( -- ExecutionToken ) immediate ['] XXXX Search next word in input stream and return it's execution token, see ' Compile ( -- ) Compile XXXX Compile next inline token, also see [Compile] [Compile] ( -- ) immediate [Compile] XXXX Compile next inline token, also see Compile Postpone ( -- ) immediate Postpone XXXX Compile next inline token, also see [Compile] and Compile >c ( n -- ) Move n from data stack to control stack, see c> c> ( -- n ) Move n from control stack to data stack, see >c Is ( -- ) immediate Resolve a deferred XXXX ' aWord is aDeferredWord Defers have compile time binding. lastDefined ( -- ExecutionToken ) Get the execution token for the last defined word Implements ( -- ) LastDefind Is XXXX : aWord ( -- ) ... ; implements aDeferredWord Defers have compile time binding. Execute ( -- ) execute exec-token ' aWord Execute Enum ( -- ) Enum x y z endEnum, start enumeration at 0. See InitEnum InitEnum ( n -- ) InitEnum x y z EndEnum, start enumeration at n. See Enum EndEnum ( -- ) Ends Enum or InitEnum section " ( -- ) immediate " a string" String or Data or RawData ... '' ( -- ) immediate '' a string' String or Data or RawData ... Same as " but can be used inside double quoted strings. Deprecated I guess now that there is string escaping. ( ( -- ) immediate Comment till ) :: does :: ')' Token ( this is comment ) Type ( string-token -- ) Type string token to console " a string" Type String ( string-token -- ) Define a string constant XXXX, also see 'Data', 'RawData', '"' and '''' " a string" String XXXX Data ( string-token -- ) Define a data constant XXXX, also see 'String', 'RawData', '"' and '''' " a string" Data XXXX RawData ( string-token -- ) Define a raw data constant XXXX, also see 'String', 'Data', '"' and '''' " a string" RawData XXXX \ ( -- ) immediate Comment till end of line, same as // \ This is commnet // ( -- ) immediate Comment till end of line, same as \ // Thiis is comment RamBank ( n -- ) n RamBank #1 #2 ... End Make a series of RAM addresses of the target system usable for target code. RomBank ( n -- ) n RomBank #1 #2 ... End Make a series of ROM addresses of the target system usable for target code. : ( -- ) Start a colon definition : name ... ; Alias ( -- ) Defines an alias for a 4th word Alias aWord aNewName ; ( -- ) immediate End a colon definition : name ... ; noreturn; ( -- ) immediate End a colon definition without return, see : and ; : Main ( -- ) begin ... again noreturn; [ ( -- ) immediate Switch compiler off, also see ] : aWord ( -- 2 ) [ 2 literal ] ; ] ( -- ) Switch compiler on, see [ MetaOn ( -- ) Switch on meta compiler, also see MetaOff, { and } { ( -- ) Switch on meta compiler, also see MetaOn, MetaOff and } { : MetaDefinition ( -- ) .... ; } MetaOff ( -- ) Switch off meta compiler, also see MetaOn, { and } } ( -- ) Switch off meta compiler, also see MetaOn, MetaOff, { Literal ( n -- ) immediate Compile TOS as a single byte literal : aWord ( -- 2 ) [ $20 literal ] ; DLiteral ( n -- ) immediate Compile TOS as a double byte literal : aWord ( -- $202 ) [ $2020 dliteral ] ; TLiteral ( n -- ) immediate Compile TOS as a tripple byte literal : aWord ( -- $2020202 ) [ $202020 tliteral ] ; QLiteral ( n -- ) immediate Compile TOS as a quad byte literal : aWord ( -- $2020202 ) [ $20202020 qliteral ] ; SearchPath ( -- ) Get the x4th current search path ClearSearchPath ( -- ) Clear the x4th search path AddToSearchPath ( -- ) Add text on stack to x4th search path AddToSearchPath' ( -- ) Add inline text to x4th search path LibraryPath' ( -- ) Alternate path for library - overrides the setting from the GUI OutputPath' ( -- ) Alternate path for generated output file - overrides the setting from the GUI OutputPath ( -- ) Alternate path for generated output file - overrides the setting from the GUI CodeLibrary ( -- ) Include a code library from the lib folder CodeLibrary' ( -- ) Include a code library from the lib folder Include ( -- ) Include a 4th file from the source folder Include' ( -- ) Include a 4th file from the source folder OutputFile' ( -- ) Define the file into which to generate code RunError ( -- ) Generate a runtime error with text on stack, also see RunError'. RunError' ( -- ) immediate Generate a runtime error with inline specified text, also see RunError. warning ( -- ) Generate a warning with text on stack, also see Warning'. Warning' ( -- ) immediate Generate a runtime error with inline specified text, also see Warning. message ( -- ) Generate a warning with text on stack, also see Message'. Message' ( -- ) immediate Generate a runtime error with inline specified text, also see Message. todo' ( -- ) immediate Generate a runtime todo msg with inline specified text. done' ( -- ) immediate Generate a runtime done msg with inline specified text. CommentSymbol' ( -- ) Define the comment symbol for the output file. The default is " ; " LabelPrefix' ( -- ) Define prefix to use for assembly labels The default is " L" ManglePrefix' ( -- ) Define prefix to use for assembly symbols other than labels The default is " C", use " _" when some of the code neest to be C callable. GenerateCode ( -- ) Generate the output file GenerateDebug ( -- ) Include some debug stuff in the output file Code ( -- ) Start a code definition, ended with EndCodce code aName ( -- ) // Documentation ; assembly code return endCode EndCode ( -- ) End a Code definition Macro ( -- ) Start a macro definition to be ended with EndMacro Macro ( arg1 arg2 ) ( -- ) // Documentation ; Assembly code using $arg1$ and $arg2$ endMacro or Macro ( arg1 arg2 ) ( -- ) // Documentation : HighLevelWord ( -- ) // Using $arg1$ and $arg2$ ; : AnotherHLword ( -- ) ; endMacro EndMacro ( -- ) End a Macro definition to be ended with EndMacro >" ( n -- ) Convert number to string acccording to 'Base' (or for type casting). &10 >" Type It is not always necessary to convert numbers to strings as there is an automatic typecasting mechanism, however sometimes that gets confused giving incorrect results. Especially the number zero is usually interpreted as a zero length string and that one sometimes must explicitly be casted to a number. Also when numbers should be printed in a non decimal number base this word can be used for conversion. hex &10 >" would yield ( " a" ) as a () result. >$ ( n -- ) Convert number to string acccording to 'Base', same as '>"' (see above) >f ( n -- ) Convert n to a floating point string. #f ( -- r ) Scan for float, leave on stack when interpreting, compile as fLiteral when compiling. When compiling the float will be in the format specified by the FloatMode system setting, when interpreting it'll be in IEEE format. . ( n -- ) Print a number in the current base, also see .b, .d, .h &10 . Print a string " a string" . .b ( n -- ) print a number in base &2, also see . &10 .b .d ( n -- ) print a number in base &10, also see . &10 .d .h ( n -- ) print a number in base &16, also see . &10 .h ." ( -- ) immediate Copy a string (up to ") to the output file, also see .' ." copy this to the output file" .' ( -- ) immediate Copy a string (u[ to ') to the output file, also see ." .' copy this to the output file' .\ ( -- ) immediate Comment (to EOL) that is copied to the output file, also see .//. .\ Copy this to the output file This will use the user defined comment prefix string .// ( -- ) immediate Comment (to EOL) that is copied to the output file, also see .\. .// Copy this to the output file This will use the user defined comment prefix string "cr ( -- ) Push crlf as a string, also see cr cr ( -- ) type a crlf to the console, also see "cr. token ( bSep -- ) // Read bSep separated token from input stream untoken ( bSep -- ) // Push back string token separated by bSep into input stream bl token dup bl untoken will duplicate the space separated token at the head of the input file. >Mark ( -- n ) Forward jump (for if .. endif etc), also see Resolve and Resolve ( n -- ) Resolve >Mark, also see | n ) Backward jump (for begin ... again etc, also see >Mark | n -- ) resolve Mark and >Resolve branch ( -- ) unconditional branch ?branch ( f -- ) branch if TOS is zero Create ( -- ) : joop create ... does> ... ; The possibility to have arbitrary objects on the data stack and code space comes with a cost penalty for the create .. does> mechanism. examples : : const create , does> @ ; // (1) This will NOT work as expected and it has to be rewritten into : : const create , does> pfa@ @ ; // (2) explanation: All data is internally stored as a pascal TData object and not as a number. The advantage is that a TData object can hold arbitrary data like strings for instance. The code/data space holds pointers to such objects and not the data itself. Likewise, The word ',' (comma) will encapsulate data popped from the stack into a TData object for which a reference gets enclosed into the code space. So an extra level of indirection is needed, the word (does>) (which is compiled into the code by the word does>) could automatically perform this dereference operation, however that would make it impossible to reach anything betond the first data field compiled in the code after Create. So the compiled bit of Create just leaves a regular PFA to be used by the words after does>. This PFA can simply be incremented to reach following data fields, but in order to be able to reach the actual data a manual extra dereference operation using the word pfa@ is needed. (Does>) ( -- ) Meta helper for Does> Does> ( -- ) immediate see Create pfa@ ( n -- n ) See Create , ( n -- ) Allot's in meta data space, not in the target system Allot ( n -- ) Allot's in meta data space, not in the target system. Here ( -- n ) Location in meta data space Begin ( -- n ) immediate Begin .. Again, Begin .. 0 Until, Begin .. (f) While .. Repeat. Can be used for target and for meta definitions. Again ( n -- ) immediate Begin .. Again Can be used for target and for meta definitions. Until ( n -- ) immediate Begin .. ( f ) Until Can be used for target and for meta definitions. While ( n -- ) immediate Begin .. While .. Repeat Can be used for target and for meta definitions. Repeat ( -- ) immediate Begin .. While .. Repeat Can be used for target and for meta definitions. Do ( -- n ) immediate n1 n2 Do .. Leave .. Loop or n +Loop Can be used for target and for meta definitions. ?Do ( -- n ) immediate n1 n2 ?Do .. Leave .. Loop or n +Loop Can be used for target and for meta definitions. Loop ( n -- ) immediate n1 n2 Do .. Leave .. Loop Can be used for target and for meta definitions. +Loop ( n -- ) immediate n1 n2 Do .. n +Loop Can be used for target and for meta definitions. Leave ( -- ) immediate Leave a do .. Leave .. loop Can be used for target and for meta definitions. I ( -- n ) immediate Get inner most loop index Can be used for target and for meta definitions. J ( -- n ) immediate Get 2nd level loop index Can be used for target and for meta definitions. K ( -- n ) immediate Get 3rd level loop index Can be used for target and for meta definitions. >R ( n -- ) immediate Move a value from the data to the loop stack Can be used for target and for meta definitions. R> ( -- n ) immediate Move a value from the loop to the data stack Can be used for target and for meta definitions. If ( -- n ) immediate n If .. Else .. Then or endIf Can be used for target and for meta definitions. Else ( n -- n ) immediate n If .. Else .. Then or endIf Can be used for target and for meta definitions. Then ( n -- ) immediate n If .. Else .. Then or endIf Can be used for target and for meta definitions. EndIf ( n -- ) immediate n If .. Else .. Then or endIf Can be used for target and for meta definitions. Case ( -- 4 0 ) immediate ( n ) Case .. of .. endOf .. default .. endCase Can be used for target and for meta definitions. Default ( -- ) immediate ( n ) Case .. of .. endOf .. default .. endCase Can be used for target and for meta definitions. EndCase ( n0 n1 .. nn-1 0 4 -- ) immediate ( n ) Case .. of .. endOf .. default .. endCase Can be used for target and for meta definitions. Of ( -- n 5 ) immediate ( n ) Case .. of .. endOf .. default .. endCase Can be used for target and for meta definitions. EndOf ( n1 5 -- n1 n2 ) immediate ( n ) Case .. of .. endOf .. default .. endCase Can be used for target and for meta definitions. Exit ( -- ) immediate Immediately leave the current colon word returning to the caller Can be used for target and for meta definitions. Try ( -- ) immediate try .. except, catch or finally .. endTry Can not be used in the meta system yet. Raise ( n -- ) immediate Raise an exception, same as throw Can not be used in the meta system yet. Throw ( n -- ) immediate Throw an exception, same as raise Can not be used in the meta system yet. Except ( -- n ) immediate try .. except .. endTry Can not be used in the meta system yet. Catch ( -- n ) immediate try .. catch .. endTry Can not be used in the meta system yet. Finally ( -- ) immediate try .. finally .. endTry Can not be used in the meta system yet. EndTry ( -- ) immediate try .. except, catch or finally .. endTry Can not be used in the meta system yet. Immediate ( -- ) Toggle the immediate bit for the last defined word Used ( -- ) Set the used bit for the last defined word Deprecated ( -- ) Set the deprecated bit for the last defined word SetUsed ( -- ) Set the used bit for the token following inline SetUnUsed ( -- ) Clear the used bit for the token following inline Meta ( -- ) Set the meta bit for the last defined word SetMeta ( -- ) Set the meta bit for the token following inline SetUnMeta ( -- ) Clear the meta bit for the token following inline Hide ( -- ) Clear the visible bit for the last defined word Reveal ( -- ) Set the visible bit for the last defined word #If ( f -- ) immediate Conditional compilation : n1 #If .. #Else .. #Then or #endIf #Else ( -- ) immediate Conditional compilation : n1 #If .. #Else .. #Then or #endIf #Then ( -- ) immediate Conditional compilation : n1 #If .. #Else .. #Then or #endIf #EndIf ( -- ) immediate Conditional compilation : n1 #If .. #Else .. #Then or #endIf #Define ( -- ) immediate Define a symbol that does nothing. #Defined ( -- f ) immediate Check if a word is defined, result goes to data stack #IfDef ( -- ) immediate Combination : #defined SomeWord #if #IfNdef ( -- ) immediate same as #IfDef but inverted condition Constant ( n -- ) Define a constant :: 12 Constant Joop Both for target and meta, meta constants cna hold strings as well as numbers. later target execution yields ( -- b ) later host execution yields ( -- n ) 2Constant ( n -- ) Define a 2 byte constant :: 1234 2Constant Joop later execution yields ( -- d ) Target only 3Constant ( n -- ) Define a 3 byte constant :: 123456 3Constant Joop later execution yields ( -- t ) Target only 4Constant ( n -- ) Define a 4 byte constant :: 12345678 4Constant Joop later execution yields ( -- q ) Target only Variable ( -- ) Define a variable :: Variable Truus Target and meta, meta variables can both hold strings and numbers. 2Variable ( -- ) Define a 2 byte variable :: 2Variable Truus Target only 3Variable ( -- ) Define a 3 byte variable :: 3Variable Truus Target only 4Variable ( -- ) Define a 4 byte variable :: 4Variable Truus Target only Array ( n -- ) Define an array :: 7 Array Data Target only [] ( -- n ) immediate Index into an array :: [] 4 SomeArray Target only $[] ( n -- c ) immediate Index into a string " a string" 3 $[] // ( " a string" 3 -- 't' ) Meta only $left ( n -- n ) immediate Take a left slice of a string " a string" 3 $left // ( " a string" 3 -- " a s" ) Meta only $right ( n -- n ) immediate Take a right slice of a string " a string" 3 $right // ( " a string" 3 -- " ing" ) Meta only $mid ( n-low n-len -- n ) immediate Take a mid slice of a string " a string" 3 2 $mid // ( " a string" 3 2 -- " tr" ) Meta only LocVar ( -- ) immediate Define a local variable Target only Loc2Var ( -- ) immediate Define a local 2Variable Target only Loc3Var ( -- ) immediate Define a local 3Variable Target only Loc4Var ( -- ) immediate Define a local 4Variable Target only Value ( n -- ) Define a Value (using the To concept) Target only To ( n -- ) immediate Place a value into a Value word, same as =. Target only =: ( n -- ) immediate Alias for To Target only Struct ( -- 0 ) Define structure offsets Struct or extendStruct, Field or 2Field, EndStruct Target only ExtendStruct ( n -- n ) Extend structure offsets, see Struct Target only Field ( n m -- n+m ) Defines a field in a structure, see Struct Target only 2Field ( n m -- n+m ) Defines a 2field in a structure, see Struct Target only EndStruct ( n -- ) End structure offset defs, see Struct Target only Decimal ( -- ) &10 Base ! Meta only Hex ( -- ) &16 Base ! Meta only Binary ( -- ) &2 Base ! Meta only Base@ ( -- n ) Base @ Meta only Base! ( n -- ) Base ! Meta only ForceRomBank ( n -- ) n ForceRomBank :: selects rom bank n For banked targets only and the bank must have beem defined before LocalBank ( n -- ) n LocalBank :: selects target ram bank n for local variables. Target only, the meta system is not banked. ShowStatistics ( -- ) Show some compilation stastistics ShowCallTree ( -- ) Show some compile stastistics ShowCallCounts ( -- ) Show some compile stastistics SystemDump' ( -- ) Make a debug dump to a file, use as Dump' afile.ext' #doc ( -- ) immediate Add documentation to LastDefined, ended with #endDoc, also see #// and ##// #// ( -- ) immediate Add documentation to LastDefined, ended at end of current line, also see #Doc and #Document #document ( -- ) Add documentation to next token in input buffer, ended with #endDoc ##// ( -- ) Add documentation to next token in input buffer, ended at end of current line, also see #// and ##// #endDoc ( -- ) Ends a #Doc or #Document section MakeDocs' ( -- ) Generate html auto documentation, use as MakeDocs' afile.ext', also see #Doc etc. MakeDocs ( -- ) Generate html auto documentation, use as '" afile.ext" MakeDocs', also see #Doc etc. AddDoc ( -- ) Use as '" aName=aValue" AddDoc', is used in documentation output AddDoc' ( -- ) Use as 'AddDoc' aName=aValue'', is used in documentation output ShowAllocations ( -- ) Make a dump of all RAM allocations AddCallDepth ( n -- ) Helper word to better see true call depths. This was used for limited stack target processors like the PIC 16c54 MarkAllUsed ( -- ) Treat all defined words as if being used for the target code generation. RequestRamBank ( n -- ) n RequestRamBank :: Set a prefered ram bank for subsequent variable allocations. The rambank must have been defined before. RequestNoRamBank ( -- ) Clear Ram bank preference Group ( -- ) Start memory grouping for the allocations that follow, all grouped allocations will end up in the same RAM bank.When this would not fit an error is generated. EndGroup ( -- ) End memory grouping CompileTime ( -- n ) immediate Get compilation start date/time as Unix time - pseudo constant Unix time is seconds elapsed since 1970-01-01 00:00 Now ( -- n ) immediate Get current date/time as Unix time - pseudo constant Unix time is seconds elapsed since 1970-01-01 00:00 unix>str ( n -- ) Convert n to an ISO format date time string Now unix>str type .s ( -- ) Type a stack dump to the console window/ debug function [.s] ( -- ) immediate Type a stack dump to the console window / debug function Mangle ( -- ) Mangle string token to make a valid target identifier Evaluate ( -- ) evaluate string token as 4th code " 1 1 + . " evaluate will print the number 2 to the console. Resources ( -- ) resources endResources sets the words in to be used when gets used CodeSize! ( n -- ) Specify a code size for a target code or macro word. FbDecimation ( n -- ) n FbFecimation, feedback decimation. Number of file lines to process before the line counter in the user feedback will be updated. SetBreak ( -- ) Set a Pascal break (for compiler debuging) - not really implemented ClearBreak ( -- ) Pascal un-break (for compiler debuging) - not really implemented UnBug ( -- ) Stop debug processing (for compiler debugging) - not really implemented + ( n1 n2 -- n3 ) immediate adition For target and meta usage - ( n1 n2 -- n3 ) immediate subtraction of n2 from n1 For target and meta usage * ( n1 n2 -- n3 ) immediate multiplication For target and meta usage / ( n1 n2 -- n3 ) immediate division of n1 by n2 For target and meta usage /mod ( n1 n2 -- n3 n4 ) immediate division of n1 by n2 with result n3 and remainder n4 For target and meta usage and ( n1 n2 -- n3 ) immediate bitwise and For target and meta usage or ( n1 n2 -- n3 ) immediate bitwise or For target and meta usage xor ( n1 n2 -- n3 ) immediate bitwise xor For target and meta usage drop ( n1 -- ) immediate drop top stack element For target and meta usage dup ( n1 -- n1 n1 ) immediate duplicate top stack element For target and meta usage swap ( n1 n2 -- n2 n1 ) immediate swap top and sub top stack elements For target and meta usage True ( -- f ) immediate Push boolean true For target and meta usage False ( -- f ) immediate Push boolean false For target and meta usage Space ( -- n ) immediate Push a space character For target and meta usage Negate ( n1 -- n2 ) immediate Unary minus performed on top stack element For target and meta usage Not ( n1 -- n2 ) immediate Logic inversion performed on top stack element For target and meta usage = ( n1 n2 -- f ) immediate Push true when the top two stack elements are equal, false otherwise For target and meta usage <> ( n1 n2 -- f ) immediate Push true when the top two stack elements are un-equal, false otherwise For target and meta usage < ( n1 n2 -- f ) immediate Push true when u1 < u2, false otherwise For target and meta usage > ( n1 n2 -- f ) immediate Push true when u1 > u2, false otherwise For target and meta usage <= ( n1 n2 -- f ) immediate Push true when u1 <= u2, false otherwise For target and meta usage >= ( n1 n2 -- f ) immediate Push true when u1 >= u2, false otherwise For target and meta usage ?dup ( n1 -- n1 n1 | 0 -- 0 ) immediate Dup the top stack element when it is not equal to zero For target and meta usage 2drop ( n1 n2 -- ) immediate Drop the top two stack elements For target and meta usage Over ( n1 n2 -- n1 n2 n1 ) immediate Duplicate the second stack element and make it the top item For target and meta usage 2dup ( n1 n2 -- n1 n2 n1 n2 ) immediate Duplicate the top two stack elements For target and meta usage 2swap ( n1 n2 n3 n4 -- n3 n4 n1 n2 ) immediate Exchange the top two sets of two stack items For target and meta usage lshift ( n1 -- n2 ) immediate Shift the top stack item to the left, bit wise For target and meta usage rshift ( n1 -- n2 ) immediate Shift the top stack item to the right, bitwise For target and meta usage << ( n1 n2 -- n3 ) immediate Shift the second stack element left over the number of bits indicated by the top stack element For target and meta usage >> ( n1 n2 -- n3 ) immediate Shift the second stack element right over the number of bits indicated by the top stack element For target and meta usage 2over ( n1 n2 n3 n4 -- n1 n2 n3 n4 n1 n2 ) immediate Duplicate the seconds set of two stack elements For target and meta usage rot ( n1 n2 n3 -- n2 n3 n1 ) immediate rotate the 3rd stack element to the top For target and meta usage +rot ( n1 n2 n3 -- n2 n3 n1 ) immediate rotate the 3rd stack element to the top For target and meta usage -rot ( n1 n2 n3 -- n3 n1 n2 ) immediate rotate the top stack element to the 3rd position For target and meta usage pick ( n1 -- n2 ) immediate Duplicate the nth stack entry For target and meta usage put ( n1 n2 -- ) immediate Change the nth stack entry For target and meta usage abs ( n1 -- n2 ) immediate Get the absolute value of the top stack element For target and meta usage Max ( n1 n2 -- n3 ) immediate Get the maximum of the top two stack elements For target and meta usage Min ( n1 n2 -- n3 ) immediate Get the minimum of the top two stack elements For target and meta usage @ ( n1 -- n2 ) immediate Fetch a value from an address For target and meta usage ! ( n1 n2 -- ) immediate Store value n1 at address n2 For target and meta usage +! ( n1 n2 -- ) immediate Increment value at address n1 with n2 For target and meta usage -! ( n1 n2 -- ) immediate Decrement value at address n1 with n2 For target and meta usage -------------------------------------------------------------------------------- Assembly level macros -------------------------------------------------------------------------------- The processor dependent include file, and usually hardware configuration files make use of assembly level macros. These macros would normaly be handled by the PICASM assembler. Some version of the MPASM development environment have some less wanted behaviour in treating macros when single stepping through the code. This was the reason for building in an assembly level macro post processor that expands all assembly level macros into plain code. This feature can be turned on or off in the Compiler tab. When the post processor is used macro's can either be listed in the generated code (as comment) or not. Although all code in code and macro words is processor dependent a lot of dependancies are contained in assembly level macros. By recoding these macros the bulk of the work in porting to a new processor is done. By using these macros in your code and macro words the processor depencies are reduced. For PIC 18 the following macros are used for that purpose (the AsmHelper macros) : // ================================== // AsmHelpers ( ) Some helper macro's // fBranch macro aLabel bz aLabel ; // B/ zero flag set : fBranch endm // // =============================================== // // Parameter Stack macro's // =============================================== // PopReg macro Reg movwf (Reg) ; // PopReg ( b -- ) movf postdec0, w endm // // // =============================================== // Drop macro movf postdec0, w ; // drop ( b -- ) endm // // // =============================================== // SwapDrop macro decf fsr0l, f ; // SwapDrop ( b1 b2 -- b2 ) endm // // // =============================================== // PushLit macro Arg movwf preinc0 ; // Push Arg ( -- b ) movlw (Arg) endm // // // =============================================== // PushReg macro Reg movwf preinc0 ; // Push Reg ( -- b ) movf (Reg), w endm // // // =============================================== // PushNothing macro movwf preinc0 ; // Push nothing, free wreg endm // // // =============================================== // Dup macro movwf preinc0 ; // Dup ( b1 -- b1 b1 ) endm // // // =============================================== // Return (loop) Stack macro's // =============================================== // LsPushReg macro Reg decf fsr1l ; // Push Reg [ -- b ] movff (Reg), indf1 endm // // // =============================================== // LsPushLit macro Arg ; // LsPushLit (Arg) PushNothing ; // Free wreg to be used movlw (Arg) ; // Arg into wreg decf fsr1l ; // Push Arg [ -- b ] to loop stack movwf indf1 Drop ; // Restore wreg endm // // // =============================================== // LsDrop macro incf fsr1l ; // drop [ b -- ] from loop stack endm // // // =============================================== // LsFree macro item_count PushNothing movlw item_count addwf fsr1l, f ; // drop [ n1 .. nn -- ] from loop stack Drop endm // // // =============================================== // LsPopReg macro Reg movff postinc1, (Reg) ; // Pop Reg [ b -- ] endm // // // ; =============================================== // AddExceptionFrame macro ; // AddExceptionFrame : link in a new ; // exception frame LsPushReg ( EFP + 0) ; // Push Except Frame Pointer LsPushReg ( EFP + 1) movff fsr1l, EFP + 0 ; // And set up a new Except Frame Pointer movff fsr1h, EFP + 1 endm // // // =============================================== // RemoveExceptionFrame macro ; // RemoveExceptionFrame, unwind one ; // exception level movff EFP + 0, fsr1l ; // Set loop stack back to EFP movff EFP + 1, fsr1h LSPopReg ( EFP + 1) ; // Pop back old Exception Frame Pointer LsPopReg ( EFP + 0) endm // // =============================================== // Ram select macro's // =============================================== // SetBSR macro aRegister movlb (aRegister >> 8) & 0xff ; // SetBsr endm // // // =============================================== // SetBSRDefault macro movlb 0x00 ; // Select the default rambank endm // // // =============================================== // AddressToFsr0 macro aRegister movlw (aRegister >> 0) & 0xff ; // AddressToFsr0 movwf fsr0l movlw (aRegister >> 8) & 0xff movwf fsr0h endm // // // =============================================== // AddressToFsr1 macro aRegister movlw (aRegister >> 0) & 0xff ; // AddressToFsr1 movwf fsr1l movlw (aRegister >> 8) & 0xff movwf fsr1h endm // // // =============================================== // AddressToFsr2 macro aRegister movlw (aRegister >> 0) & 0xff ; // AddressToFsr2 movwf fsr2l movlw (aRegister >> 8) & 0xff movwf fsr2h endm // // // =============================================== // Utility macro's // =============================================== // PushNextRomAddress macro local BeyondMe ; // PushNextRomAddress ( -- wRomAddr ) PushLit (BeyondMe >> 0) & 0xff ; // Push low byte PushLit (BeyondMe >> 8) & 0xff ; // Push high byte return BeyondMe: endm // // // =============================================== // incf16 macro freg incf freg, f ; // incf16 btfsc Status, C incf freg + 1, f endm // // // =============================================== // incf32 macro freg incf freg + 0, f ; // incf32 btfsc Status, C incf freg + 1, f btfsc Status, C incf freg + 2, f btfsc Status, C incf freg + 3, f endm // // // =============================================== // incf24 macro freg incf freg + 0, f ; // incf24 btfsc Status, C incf freg + 1, f btfsc Status, C incf freg + 2, f endm // // // =============================================== // decf16 macro freg decf freg + 0, f ; // decf16 btfss Status, C decf freg + 1, f endm // // // =============================================== // decf16sz macro freg decf freg + 0, f ; // decf16sz S if Zero - kills wreg btfss Status, C decf freg + 1, f movf freg + 0, w iorwf freg + 1, w btfss Status, Z ; // S/ result was zero endm // // // =============================================== // addl16 macro dst16, lit16 movlw (lit16 >> 0) & 0xff ; // addl16 addwf dst16, f movlw (lit16 >> 8) & 0xff addwfc dst16 + 1, f endm // // // =============================================== // shl16 macro reg16 bcf Status, C ; // shl16 rlcf reg16 + 0, f rlcf reg16 + 1, f endm // // // =============================================== // rrc16 macro reg16 ; // Same as shrc16 rrcf reg16 + 1, f ; // rrc16 rrcf reg16 , f endm // // // =============================================== // shlc16 macro reg16 rlcf reg16 , f ; // shlc16 rlcf reg16 + 1, f endm // // // =============================================== // shr16 macro reg16 bcf Status, c ; // shr16 rrcf reg16 + 1, f rrcf reg16 + 0, f endm // // // =============================================== // shrc16 macro reg16 ; // Same as rrc16 rrcf reg16 + 1, f ; // shrc16 rrcf reg16, f endm // // // =============================================== // xorl16 macro dst16, lit16 movlw (lit16 >> 0) & 0xff ; // xorl16 xorwf dst16, f movlw (lit16 >> 8) & 0xff xorwf dst16 + 1, f endm // // =============================================== // shlc32 macro reg32 rlcf reg32 , f ; // shlc32 rlcf reg32 + 1, f rlcf reg32 + 2, f rlcf reg32 + 3, f endm // // // =============================================== // xorf16 macro dst16, src16 movf src16 , w ; // xorf16 xorwf dst16 , f movf src + 1, w xorwf dst + 1, f endm // // // =============================================== // xorf16d macro src16_1, src16_2, dst16 movf src16_1 + 0, w ; // xorf16d xorwf src16_2 + 0, w movwf dst16 + 0 movf src16_1 + 1, w xorwf src16_2 + 1, w movwf dst16 + 1 endm // // // =============================================== // clrf16 macro reg16 clrf reg16 ; // clrf16 clrf reg16 + 1 endm // // // =============================================== // clrf32 macro reg32 clrf reg32 ; // clrf32 clrf reg32 + 1 clrf reg32 + 2 clrf reg32 + 3 endm // // // =============================================== // cpfslt16 macro reg16_1, reg16_2 ; // Skip the next instruction if N1 < N2 (unsigned) ; // or skip if N1 - N2 < 0 local CheckHiUnEq, N1SmallerN2, N1NotSmallerN2 movwf <@" Quotient"> ; // Save wreg movf reg16_1 + 1, w subwf reg16_2 + 1, w bnz CheckHiUnEq ; // B/ N1 + 1 <> N2 + 1, test hi bytes ; // N1 + 1 == N2 + 1, test low bytes movf reg16_2, w ; // N2 to w subwf reg16_1, w ; // calc N1 - N2 :: negative -> ; // N1 - N2 < 0 -> N1 < N2 movff <@" Quotient">, WREG ; // Restore wreg || NOT affecting flags bc N1NotSmallerN2 ; // N1 < N2 bra N1SmallerN2 CheckHiUnEq ; // Hi bytes are not equal, test 'm movf reg16_2 + 1, w ; // N2 == reg16_2 + 1 subwf reg16_1 + 1, w ; // Sub N1:: negative -> N1 - N2 < 0 -> ; // N1 < N2 movff <@" Quotient">, WREG ; // Restore wreg || NOT affecting flags bc N1NotSmallerN2 N1SmallerN2 bra N1NotSmallerN2 + 2 ; // Skip next N1NotSmallerN2 endm // // // =============================================== // cpfseq16 macro reg16_1, reg16_2 ; // Skip the next instruction if N1 = N2 local N1NotEqualN2 movf reg16_2 + 1, w subwf reg16_1 + 1, w bnz N1NotEqualN2 ; // Hi bytes not equal ; // N1 + 1 equals N2 + 1 movf reg16_2, w subwf reg16_1, w btfss Status, Z ; // S/ N1 = N2 :: so skip next ; // instruction N1NotEqualN2 endm // // // =============================================== // // A delay utility, the argument should be in the range [6..860] // Delay is in microseconds. // // Must be tuned for processor speed ! // which it IS for project c\002\progger // Delay macro aMuSecs local _DlyLp if aMuSecs < 3 | aMuSecs > 307 error "Argument for delay (aMuSecs) : out of range [3..307]" endif movlw (1000 * (aMuSecs) / (3 * 408)) - 1 ; // 1 cycles movwf _Quotient ; // 1 cycles _DlyLp decfsz <@" Quotient">, f ; // 1 cycles total : ; // ( n * 3 + 3) * 102 ns goto _DlyLp ; // 2 cycles ; // 1 cycles endm // // // =============================================== // jr_f macro reg ; // jr_f local table movlw (table >> 8) & 0xff ; // Setup pclath with table address ; // high byte movwf pclath movlw table & 0xff ; // Table address low byte into wreg addwf reg, w ; // Add ofset for the first time to ; // pclath_w register pair btfsc status, c incf pclath, f addwf reg, w ; // Add offset again (table entries are ; // two bytes in size) btfsc status, c incf pclath, f movwf pcl ; // set new pc (dispatch) table endm // // End of AsmHelpers // ========================================= -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- LICENSE AGREEMENT -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- Blue Hell is a trade mark owned by Jan Punter Oogstplein 6 7545 HP Enschede the Netherlands http://www.iaf.nl/Users/BlueHell/ http://bluehell.electro-music.com/ j>d.ta.td.t