MARC4 4-Bit Microcontroller Programmer's Guide I. Hardware Description II. Instruction Set III. Programming in qFORTH IV. qFORTH Language Dictionary V. Addresses MARC4 Programmer's Guide Table of Contents Contents I. 1 MARC4 Microcontroller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MARC4 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1 General Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 Components of MARC4 Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.1 Program Memory (ROM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.2 Data Memory (RAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.3 Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.4 ALU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.5 Instruction Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.6 I/O Bus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.7 Interrupt Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Software Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Hardware Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3 Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.4 Sleep Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.5 Peripheral Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.5.1 Port Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6 Emulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 12 12 13 13 13 14 16 17 17 18 19 20 21 21 21 21 22 II 2 Instruction Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MARC4 Instruction Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.1 Description of Used Identifiers and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . 2.1.2 Stack Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.3 MARC4 Instruction Set Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 25 25 27 27 32 III 3 Programming in qFORTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Programming in qFORTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1 Why Program in qFORTH ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Language Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 The qFORTH Vocabulary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.1 Word Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4 Stacks, RPN and Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.1 Reverse Polish Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.2 The qFORTH Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.3 Stack Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.4 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5 Constants and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.1 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.2 Look-up Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6 Variables and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1 Defining Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 37 37 38 40 40 40 40 41 41 41 42 42 42 42 43 43 MARC4 Programmer's Guide Table of Contents Contents (continued) 3.7 3.8 3.9 3.10 3.11 3.12 3.13 Stack Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.1 Stack Pointer Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stack Operations, Reading and Writing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.8.1 Stack Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Data Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SWAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DUP, OVER and DROP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ROT and <ROT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R>, >R, R@ and DROPR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other Useful Stack Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.8.2 Reading and Writing (@, !) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.8.3 Low-Level Memory Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RAM Address Registers X and Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bit Manipulations in RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MARC4 Condition Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.9.1 The CCR and the Control Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.10.1 Number Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Single- and Double-Length Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.10.2 Addition and Subtraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.10.3 Increment and Decrement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.10.4 Mixed-Length Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.10.5 BCD Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DAA and DAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.10.6 Summary of Arithmetic Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logicals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.11.1 Logical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOGGLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SHIFT and ROTATE Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.12.1 <,> ............................................................. 3.12.2 <= , >= . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.12.3 <> , = . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.12.4 Comparisons Using 8-bit Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.13.1 Selection Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IF .. THEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The CASE Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.13.2 Loops, Branches and Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definite Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Indefinite Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.13.3 Branches and Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 44 44 44 44 45 45 45 45 46 47 47 47 48 48 49 49 49 49 49 50 50 50 50 51 51 51 52 52 53 53 53 53 53 54 55 55 55 56 56 57 58 MARC4 Programmer's Guide Table of Contents Contents (continued) 3.13.4 4 V. Arrays and Look-up Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Array Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Initializing and Erasing an Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Array Filling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Looping in an Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Moving Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comparing Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.13.5 Look-up Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.13.6 TICK and EXECUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.14 Making the Best Use of Compiler Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.14.1 Controlling ROM Placement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.14.2 Macro Definitions, EXIT and ;; . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.14.3 Controlling Stack Side Effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.14.4 $INCLUDE Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.14.5 Conditional Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.14.6 Controlling XY Register Optimizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.15 Recommended Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.15.1 How to Pronounce the Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.16 Literature List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.16.1 Recommended Literature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.16.2 Literature of General Interest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . qFORTH Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1 Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 Stack-Related Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4 Flags and Condition Code Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.5 MARC4 Memory Addressing Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.6 The qFORTH Language - Quick Reference Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.6.1 Arithmetic/Logical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.6.2 Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.6.3 Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.6.4 Stack Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.6.5 Memory Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.6.6 Predefined Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.6.7 Assembler Mnemonics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.7 Short Form Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.8 Detailed Description of the qFORTH Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index of "Detailed Description of the qFORTH Language" . . . . . . . . . . . . . . . . . . . . . . . . . . 58 58 58 58 59 59 59 59 59 62 62 62 62 63 63 63 64 64 66 66 66 71 71 72 75 76 77 78 78 78 79 79 80 81 81 83 93 465 Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 I. Hardware Description II. Instruction Set III. Programming in qFORTH IV. qFORTH Language Dictionary V. Addresses MARC4 Programmer's Guide Hardware Description MARC4 Microcontroller Introduction The Atmel Wireless & Microcontrollers MARC4 microcontroller family is based on a low-power 4-bit CPU core. The modular MARC4 architecture is HARVARD like, high-level language oriented and well suitable to realize high integrated microcontrollers with a variety of application or customer-specific on-chip peripheral combinations. The MARC4 controller's low voltage and low power consumption is perfect for hand-held and battery-operated applications. The standard members of the family have selected peripheral combinations for a broad range of applications. Programming is supported by an easy-to-use PC based software development system with a high-level language qFORTH compiler and an emulator board. The stack-oriented microcontroller concept enables the qFORTH compiler to generate a compact and efficient MARC4 program code. Features D 4-bit HARVARD architecture D Low power consumption D High-level language oriented CPU D Power-down mode D 256 x 4 bit of RAM D Various on-chip peripheral combination available D Up to 9 KBytes of ROM D 8 vectored prioritized interrupt levels D Low voltage operating range 03.01 D High-level programming language qFORTH D Programming and testing is supported by an integrated software development system 11 MARC4 Programmer's Guide Hardware Description 1 1.1 MARC4 Architecture General Description The MARC4 microcontroller consists of an advanced stack-based 4-bit CPU core and application-specific, on-chip peripherals such as I/O ports, timers, counters, ADC, etc. The CPU is based on the HARVARD architecture with a physically separate program memory (ROM) and data memory (RAM). Three independent buses, the instruction-, the memory- and the I/O bus, are used for parallel communication between ROM, RAM and peripherals. This enhances program execution speed by allowing both instruction prefetching, and a simultaneous communication to the on-chip peripheral circuitry. The powerful integrated interrupt controller, with eight prioritized interrupt levels, supports fast processing of hardware events. The MARC4 is designed for the high-level programming language qFORTH. A lot of qFORTH instructions and two stacks, the Return Stack and the Expression Stack, are already implemented. The architecture allows high-level language programming without any loss of efficiency and code density. Sleep Clock Reset MARC4 CORE ROM X Y SP RP PC 256 x 4-bit II II Instruction bus Instruction decoder RAM Memory bus TOS CCR Interrupt controller ALU I/O bus I/O ports Timer Application -specific peripherals Interrupt inputs On-chip peripheral modules 94 8711 Figure 1. MARC4 core 12 03.01 MARC4 Programmer's Guide Hardware Description 1.2 Components of MARC4 Core The core contains the program memory (ROM), data memory (RAM), ALU, Program Counter, RAM Address Register, instruction decoder and interrupt controller. The following sections describe each of these parts. special subroutines accessible with single byte instructions (SCALL). The corresponding memory map is shown in figure 2. Look-up tables of constants are also stored in ROM and are accessed via the MARC4 built in TABLE instruction. 1.2.2 Program Memory (ROM) The MARC4's program memory contains the customer-application program. The 12-bit wide Program Counter can address up to 4 Kbytes of program memory. The access of program memory with more than 4 K is possible using the bank-switching method. One of 4 memory banks can be selected with bit 2 and 3 of the ROM bank register (RBR). Each ROM bank has a size of 2 Kbytes and is placed above the base bank in the upper 2 K (800h-FFFh) of the address space. This therefore enables program memory sizes of up to 10 Kbytes. 1 Kbyte of bank 3 is normally reserved for test software purposes. After any hardware reset, ROM Bank 1 is selected automatically. The program memory starts with a 512 byte segment (Zero Page) which contains predefined start addresses for interrupt service routines and MARC4 self test routines Bank 2 Bank 1 800h 7FFh 1FFh 000h Expression Stack The 4-bit wide Expression Stack is addressed with the Expression Stack Pointer (SP). All arithmetic, I/O and memory reference operations take their operands from, and return their result to the Expression Stack. The MARC4 performs the operations with the top of stack items (TOS and TOS-1). The TOS register contains the top element of the Expression Stack and works in the same way as an accumulator. This stack is also used for passing parameters between subroutines, and as a scratchpad area for temporary storage of data. 1F8h 1F0h 1E8h 1E0h Bank 4 Bank 3 FFFh The MARC4 contains a 256 x 4-bit wide static Random Access Memory (RAM). It is used for the Expression Stack, the Return Stack and as data memory for variables and arrays. The RAM is addressed by any of the four 8-bit wide RAM Address Registers SP, RP, X and Y. RBR: 11xxb RBR: 10xxb RBR: 01xxb RBR: 00xxb Basebank SCALL addresses 1.2.1 Data Memory (RAM) Zero page 020h 018h 010h 008h 000h Zero page 1E0h 1C0h 180h 140h 100h 0C0h 080h 040h INT7 INT6 INT5 INT4 INT3 INT2 INT1 INT0 008h 000h $RESET $AUTOSLEEP 94 8709 Figure 2. ROM map 03.01 13 MARC4 Programmer's Guide Hardware Description RAM (256 x 4-bit) Expression Stack 3 TOS FFh FCh 0 TOS-1 Global variables X SP TOS-2 4-bit RAM Address Register: Y Expression Stack SP TOS-1 Return Stack 11 0 RP Return Stack RP 04h 07h 00h 03h Global variables 12-bit 94 8710 Figure 3. RAM map Return Stack Program Counter (PC) The 12-bit wide Return Stack is addressed by the Return Stack Pointer (RP). It is used for storing return addresses of subroutines, interrupt routines and for keeping loop-index counters. The return stack can also be used as a temporary storage area. The MARC4 Return Stack starts with the AUTOSLEEP vector at the RAM location FCh and increases in the address direction 00h, 04h, 08h, ... to the top. The Program counter (PC) is a 12-bit register that contains the address of the next instruction to be fetched from the ROM. Instructions currently being executed are decoded in the instruction decoder to determine the internal micro-operations. The MARC4 instruction set supports the exchange of data between the top elements of the expression and the Return Stack. The two stacks within the RAM have a user-definable maximum depth. 1.2.3 Registers The MARC4 controller has six programmable registers and one condition code register. They are shown in the programming model in figure 4. 14 For linear code (no calls or branches), the program counter is incremented with every instruction cycle. If a branch, call, return instruction or an interrupt is executed, the program counter is loaded with a new address. The program counter is also used with the table instruction to fetch 8-bit wide ROM constants. RAM Address Register The RAM is addressed with the four 8-bit wide RAM address registers SP, RP, X and Y. These registers allow the access to any of the 256 RAM nibbles. 03.01 MARC4 Programmer's Guide Hardware Description 11 0 Program Counter PC 0 7 0 RP 0 Return Stack Pointer 0 7 Expression Stack Pointer SP 0 7 RAM Address Register (X) X 7 0 RAM Address Register (Y) Y 0 3 Top of Stack Register TOS 0 3 CCR C -- B I Condition Code Register Interrupt enable Branch unused Carry / Borrow 94 8707 Figure 4. Programming model Expression Stack Pointer (SP) The stack pointer (SP) contains the address of the next-to-top 4-bit item (TOS-1) of the Expression Stack. The pointer is automatically pre-incremented if a nibble is pushed onto the stack, or post-decremented if a nibble is removed from the stack. Every post-decrement operation moves the item (TOS-1) to the TOS register before the SP is decremented. After a reset, the stack pointer has to be initialized with the compiler variable S0 03.01 (" >SP S0 ") to allocate the start address of the Expression Stack area. Return Stack Pointer (RP) The Return Stack pointer points to the top element of the 12-bit wide Return Stack. The pointer automatically pre-increments if an element is moved onto the stack, or it post-decrements if an element is removed from the stack. The Return Stack Pointer increments and decrements in steps of 4. This means that every time a 12-bit element is stacked, a 4-bit RAM location is left unwritten. This location is 15 MARC4 Programmer's Guide Hardware Description used by the qFORTH compiler to allocate 4-bit variables. TOG_BF, CCR! and DI allow a direct manipulation of the Condition Code Register. To support the AUTOSLEEP feature, read and write operations to the RAM address FCh using the Return Stack Pointer are handled in a special way. Read operations will return the autosleep address 000h, whereby write operations have no effect.After a reset, the Return Stack Pointer has to be initialized with " >RP FCh ". Carry/Borrow (C) RAM Address Register (X and Y) Branch (B) The X and Y registers are used to address any 4-bit element in the RAM. A fetch operation moves the addressed nibble onto the TOS. A store operation moves the TOS to the addressed RAM location. The Branch flag controls the conditional program branching. When the Branch flag has been set by one of the previous instructions, a conditional branch is taken. This flag is affected by arithmetic, logic, shift, and rotate operations. By using either the pre-increment or post-decrement addressing mode, it is convenient to compare, fill or move arrays in the RAM. Interrupt Enable (I) Top of Stack (TOS) The Top of Stack Register is the accumulator of the MARC4. All arithmetic/logic, memory reference and I/O operations use this register. The TOS register gets the data from the ALU, the ROM, the RAM or via the I/O bus. Condition Code Register (CCR) The 4-bit wide Condition Code Register contains the branch, the carry and the interrupt enable flag. These bits indicate the current state of the CPU. The CCR flags are set or reset by ALU operations. The instructions SET_BCF, The Carry/Borrow flag indicates that the borrowing or carrying out of the Arithmetic Logic Unit (ALU) occurred during the last arithmetic operation. During shift and rotate operations, this bit is used as a fifth bit. Boolean operations have no effect on the Carry flag. The Interrupt Enable flag enables or disables the interrupt processing on a global basis. After a reset or by executing the DI instruction, the Interrupt Enable flag is cleared and all interrupts are disabled. The C does not process further interrupt requests until the Interrupt Enable flag is set again by either executing an EI, RTI or SLEEP instruction. 1.2.4 ALU The 4-bit ALU performs all the arithmetic, logical, shift and rotate operations with the top two elements of the Expression Stack (TOS and TOS-1) and returns their result to the TOS. The ALU operations affect the Carry/Borrow and Branch flag in the Condition Code Register (CCR). IIII IIIII IIII IIIII IIIII IIII IIII IIIIIII IIIII IIIII II IIIIIIII IIIIIII IIII IIIII IIIII II IIII IIIII IIIII III IIIIIIII II IIII IIIII III IIII IIIIIIII IIIII III IIIIIIII IIII IIIII RAM SP TOS-1 TOS-2 TOS-3 TOS-4 TOS ALU CCR 94 8977 Figure 5. ALU zero address operations 16 03.01 MARC4 Programmer's Guide Hardware Description 1.2.5 Instruction Set The MARC4 instruction set is optimized for the high-level programming language qFORTH. A lot of MARC4 instructions are qFORTH words. This enables the compiler to generate a fast and compact program code. The MARC4 is a zero address machine with a compact and efficient instruction set. The instructions contain only the operation to be performed but no source or destination address information. The operations are performed with the data placed on the stack. An instruction pipeline enables the controller to fetch the next instruction from ROM at the same time as the present instruction is being executed. One- and two-byte instructions are executed within 1 to 4 machine-cycles. Most of the instructions have a length of one byte and are executed in only one machine cycle. A complete overview of the MARC4 instruction set includes the table instruction set. MARC4 Instruction Timing The internal instruction timing and pipelining during the MARC4's instruction execution are shown in figure 6. The figure shows the timing for a sequence of three instructions. A machine cycle consists of two system-clock cycles. The first and second Cycle 1 Cycle 2 instruction needs one and the third two machine-cycles. 1.2.6 I/O Bus Communication between the core and the on-chip peripherals takes place via the I/O bus. This bus is used for read and write accesses, for interrupt requests, for peripheral reset and for the SLEEP mode. The operation mode of the 4-bit wide I/O bus is determined by the control signals N_Write, N_Read, N_Cycle and N_Hold. (see table I/O bus modes). During IN/OUT operations, the address and data and during an interrupt cycle the low and the high priority interrupts are multiplexed by using the N_Cycle signal. When N_Cycle is low the address respectively the low interrupts `0,1,2,3' are sent, when N_Cycle is high the data respectively the higher priority interrupts `4,5,6,7' are transfered (see figure 7). An IN operation transfers the port address from TOS (top of stack) onto the I/O bus and reads the data back on TOS. An OUT operation transfers both the port address from TOS and the data from TOS-1 onto the I/O bus. Note that the interrupt controller samples interrupt requests during the non-I/O cycles. Therefore, IN and OUT instructions may cause an interrupt delay. To minimize interrupt latency, avoid immediate consecutive IN and OUT instructions. Cycle 3 Cycle 4 Cycle 5 TCL/SYSCL ROM read Decode Execute Instr 1 Instr 2 Instr 1 Instr 3.1 Instr 2 Instr 1 Instr 3.2 Instr 4 Instr 3 Instr 2 Instr 3 94 8712 Figure 6. Instruction cycle (pipelining) 03.01 17 MARC4 Programmer's Guide Hardware Description Table 1. I/O bus modes AAAAAAAAAAA AAAAAA AAAAA AAAAA AAAAA AAAAA AAAAAAAAAAA AAAAAA AAAAA AAAAA AAAAA AAAAA AAAAAAAAAAA AAAAAA AAAAA AAAAA AAAAA AAAAA AAAAAAAAAAA AAAAAA AAAAA AAAAA AAAAA AAAAA AAAAAAAAAAA AAAAAA AAAAA AAAAA AAAAA AAAAA AAAAAAAAAAA AAAAAA AAAAA AAAAA AAAAA AAAAA AAAAAAAAAAA AAAAAA AAAAA AAAAA AAAAA AAAAA AAAAAAAAAAA AAAAAA AAAAA AAAAA AAAAA AAAAA AAAAAAAAAAA AAAAAA AAAAA AAAAA AAAAA AAAAA AAAAAAAAAAA AAAAAA AAAAA AAAAA AAAAA AAAAA Mode I/O read (address cycle) I/O read (data cycle) I/O write (address cycle) I/O write (data cycle) Interrupt 0 to 3 cycle Interrupt 4 to 7 cycle Sleep mode Reset mode N_Read 0 0 1 1 1 1 0 0 N_Write 1 1 0 0 1 1 0 0 N_Cycle 0 1 0 1 0 1 0 x N_Hold 1 x 1 1 1 1 1 0 I/O Bus x x x x x x 0 Fh TCL/SYSCL (N_Hold=1) N_Cycle OUT instruction cycle N_Write IN instruction cycle N_Read I/O bus Int0-3 Int4-7 III III III III Addr Data Int0-3 Int4-7 Figure 7. Timing for IN/OUT operations and interrupt requests The I/O bus is internal and therefore not accessible by the customer on the final microcontroller. 1.2.7 Interrupt Structure The MARC4 can handle interrupts with eight different priority levels. They can be generated from internal or external hardware interrupt sources or by a software interrupt from the CPU itself. Each interrupt level has a hard-wired priority and an associated vector for the service routine in the ROM (see table 2). The programmer can enable or disable all interrupts at once by setting or resetting the interrupt-enable flag (I) in the CCR. 18 III III IIIIII Addr Data 94 8713 Interrupt Processing To process the eight different interrupt levels, the MARC4 contains an interrupt controller with the 8-bit wide Interrupt Pending and Interrupt Active Register. The interrupt controller samples all interrupt requests on the I/O bus during every non-I/O instruction cycle and latches them in the Interrupt Pending Register. If no higher priority interrupt is present in the Interrupt Active Register, it signals the CPU to interrupt the current program execution. If the interrupt enable bit is set, the processor enters an interrupt acknowledge cycle. During this cycle, a SHORT CALL instruction to the service routine is executed and the 12-bit wide current PC is saved on the Return Stack automatically. 03.01 MARC4 Programmer's Guide Hardware Description INT7 7 INT7 active INT5 Priority level 6 5 4 3 2 AAAA AAAA AAAA AAA AAAA AAA RTI INT5 active INT3 AAA AAA INT3 active RTI AAAAA IIIIIII AAAA AAAAA IIIIIII AAAA INT2 RTI INT2 pending 1 SWI0 0 AAAAA AAAAA INT2 active RTI IIIIII AAAA IIIIII AAAA INT0 pending INT0 active RTI Main / Autosleep Main / Autosleep Time 94 8978 Figure 8. Interrupt handling An interrupt service routine is finished with the RTI instruction. This instruction sets the Interrupt Enable flag, resets the corresponding bits in the Interrupt Pending/Active Register and moves the return address from the Return Stack to the Program Counter. When the Interrupt Enable flag has been reset (interrupts are disabled), the execution of interrupts is inhibited, but not the logging of the interrupt requests in the Interrupt Pending Register. The execution of the interrupt will be delayed until the Interrupt Enable flag is set again. But note that interrupts are lost if an interrupt request occurs during the corresponding bit in the Pending Register is still set. After any hardware reset (power-on, external or watchdog reset), the Interrupt Enable flag, the Interrupt Pending and Interrupt Active Register are reset. 03.01 Interrupt Latency The interrupt latency is the time from the occurrence of the interrupt event to the interrupt service routine being activated. In the MARC4 this takes between three to five machine cycles depending on the state of the core. Software Interrupts The programmer can generate interrupts using the software interrupt instruction (SWI) which is supported in qFORTH by predefined macros named SWI0...SWI7. The software-triggered interrupt operates exactly in the same way as any hardware-triggered interrupt. The SWI instruction takes the top two elements from the Expression Stack and writes the corresponding bits via the I/O bus to the Interrupt Pending Register. Therefore, by using the SWI instruction, interrupts can be re-prioritized or lower priority processes scheduled for later execution. 19 MARC4 Programmer's Guide Hardware Description Hardware Interrupts automatically event-controlled program flow. The different vectored interrupts permit program dividing into different interrupt-controlled tasks. Hardware interrupt sources such as external interrupt inputs, timers etc. are used for fast Interrupt event INT3 TCL/SYSCL I I I I II III IIIIII IIIIII III IIIIII III III IIII III IIIIII III III IIIIII III III IIII III IIIIII IIIIII III III IIIIII III III IIII N_Cycle Interrupt request I/O bus 8 INT5 Instruction CCR! Interrupt acknowl. INT0 RTI AND LIT_5 Pending: 21h Active: 21h Interrupt register: 0 Pending: 01h Active: 01h ADD SCALL INT3 INT3 CCR@ LIT_5 LIT_E Pending: 09h Active: 01h Pending: 09h Active: 09h 94 8696 Figure 9. Interrupt request cycle Table 2. Interrupt priority table Interrupt Priority ROM Address INT0 INT1 INT2 INT3 INT4 INT5 INT6 INT7 lowest 040h 080h 0C0h 100h 140h 180h 1C0h 1E0h Interrupt Opcode (Acknowledge) C8h (SCALL 040h) D0h (SCALL 080h) D8h (SCALL 0C0h) E0h (SCALL 100h) E8h (SCALL 140h) F0h (SCALL 180h) F8h (SCALL 1C0h) FCh (SCALL 1E0h) Pending/ Active Bit 0 1 2 3 4 5 6 7 AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAAAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA highest INT5 TCL/SYSCL Instruction IIIII IIIII I/O control bus NOP SLEEP SET_BCF SBRA $Autosleep SCALL INT5 SLEEP mode Int0-3 Int4-7 I/O bus IIII IIIIIII IIII IIIIIII Interrupt acknowledge Int0-3 IIII IIII Int4-7 Int0-3 Int4-7 Int0-3 94 8703 Figure 10. Timing sleep mode 20 03.01 MARC4 Programmer's Guide Hardware Description 1.3 Reset The reset puts the CPU into a well-defined condition. The reset can be triggered by switching on the supply voltage, by a break-down of the supply voltage, by the watchdog timer or by pulling the NRST pad to low. After any reset, the Interrupt Enable flag in the Condition Code Register (CCR), the Interrupt Pending Register and the Interrupt Active Register are reset. During the reset cycle, the I/O bus control signals are set to `reset mode', thereby initializing all on-chip peripherals. The reset cycle is finished with a short call instruction (opcode C1h) to the ROM-address 008h. This activates the initialization routine $RESET. In this routine the stack pointers, variables in the RAM and the peripheral must be initialized. 1.4 Sleep Mode The sleep mode is a shutdown condition which is used to reduce the average system power consumption in applications where the C is not fully utilized. In this mode, the system clock is stopped. The sleep mode is entered with the SLEEP instruction. This instruction sets the Interrupt Enable bit (I) in the Condition Code Register to enable all interrupts and stops the core. During the sleep mode, the peripheral modules remain active and are able to generate interrupts. The C exits the SLEEP mode with any interrupt or a reset. The sleep mode can only be kept when none of the Interrupt Pending or Active Register bits are set. The application of $AUTOSLEEP routine ensures the correct function of the sleep mode. The total power consumption is directly proportional to the active time of the C. For a rough estimation of the expected average system current consumption, the following formula should be used: 03.01 Itotal = ISleep + (IDD Tactive / Ttotal) IDD depends on VDD and fSYSCL. 1.5 Peripheral Communication All communication to and from on-chip peripheral moduls takes place via the peripheral I/O-bus. In this way the I/O does not interfere with core internal operations. Data transfer is always mastered by the core CPU. A peripheral device, if necessary, can however draw attention to itself by means of an interrupt. 1.5.1 Port Communication The MARC4 peripheral modules are I/O-mapped by using an IN or OUT instruction which in turn either inputs or outputs a 4-bit data or from one of 16 direct accessible port addresses. Before an OUT instruction is executed the port destination address and the data to be transmitted must be pushed onto the Expression Stack. Example: : TurnLED_Off 8 Port4 OUT ; TOS TOS Data TOS Addr Data Figure 11. OUT instruction - Stack effects In the case of an IN instruction only the port address needs to be pushed onto the Expression Stack. Example: : KeyPressed? KeyIn IN ; 21 MARC4 Programmer's Guide Hardware Description TOS TOS Addr the internal CPU core is inactive and the I/O buses are available via Port 0 and Port 1 to allow an external access to the on-chip peripherals. The MARC4 emulator uses this mode to control the peripherals of any MARC4 controller (target chip) and emulates the lost ports for the application. Data Figure 12. IN instruction - Stack effects For more complex peripherals please refer to the corresponding data sheets and the supplied hardware programming routines. 1.6 Emulation The basic function of emulation is to test and evaluate the customer's program and hardware in real time. This therefore enables the analysis of any timing, hardware or software problem. For emulation puposes, all MARC4 controllers include a special emulation mode. In this mode, A special evaluation chip (EVC) with a MARC4 core, additional breakpoint logic and program memory interface takes over the core function and executes the program from an external RAM on the emulator board. The MARC4 emulator can stop and restart a program at specified points during execution, making it possible for the applications engineer to view the memory contents and those of various registers during program execution. The designer also gains the ability to analyze the executed instruction sequences and all the I/O activities. Emulator target board MARC4 emulator MARC4 emulation-CPU I/O bus Trace memory Port 0 MARC4 target chip CORE I/O control Port 1 Program memory CORE (inactive) Peripherals Port 0 Control logic Port 1 Emulation control SYSCL/ TCL, TE, NRST Application-specific hardware Personal computer Figure 13. MARC4 emulation 22 03.01 I. Hardware Description II. Instruction Set III. Programming in qFORTH IV. qFORTH Language Dictionary V. Addresses MARC4 Programmer's Guide Instruction Set 2 2.1 MARC4 Instruction Set Introduction Most of the MARC4 instructions are single-byte instructions. The MARC4 is a zero address machine where the instruction to be performed contains only the operation and not the source or destination addresses of the data. Altogether, there are five types of instruction formats for the MARC4 processor. A Literal is a 4-bit constant value which is placed on the data stack. In the MARC4 native code they are represented as LIT_<value>, where <value> is the hexadecimal representation from 0 to 15 (0..F). This range is a result of the MARC4's 4-bit data width. The long RAM address format is used by the four 8-bit RAM address registers which can be pre-incremented, post-decremented or loaded directly from the MARC4's internal bus. This results in a direct accessible RAM address space of up to 256 x 4 bit. The 6-bit short address and the 12-bit long address formats are both used to address the byte-wide ROM via call and conditional branch instructions. This results in a ROM address space of up to 4 K x 8-bit words. The MARC4 instruction set includes both short and long call instructions as well as conditional branch instructions. The short instructions are single-byte instructions with the jump address included in the instruction. On execution, the lower 6 bits from the instruction word are directly loaded into the PC. Short call (SCALL) and short branch (SBRA) instructions are handled in different ways. SCALL jumps to one of 64 evenly distributed addresses within the zero page (from 000 to 1FF hex). The short branch instruction allows a jump to one of 64 addresses contained within the current page. Long jump instructions can jump anywhere within the ROM area. The CALL and SCALL instructions write the incremented Program Counter contents to the Return Stack. This address is loaded back to the PC when the associated EXIT or RTI instruction is encountered. Table 1. MARC4 opcode formats opcode 1) Zero address operation (ADD, SUB, etc...) 2) Literal (4-bit data) 7 6 5 4 3 2 1 0 opcode 3 2 1 0 opcode 3) Short ROM address (6-bit address, 2 cycles) 4) Long ROM address (12-bit address, 2 cycles) 5) Long RAM address (8-bit address, 2 cycles) 03.01 1 0 data 3 2 1 0 address 5 4 3 2 1 0 opcode address 3 2 1 0 11 10 9 8 7 6 5 4 3 2 1 0 opcode 7 6 5 4 3 2 1 0 address 7 6 5 4 3 2 1 0 25 MARC4 Programmer's Guide Instruction Set Table 2. Instruction set overview 00 ADD 10 SHL 20 TABLE 30 [X]@ 01 ADDC 11 ROL 21 --- 31 [+X]@ 02 SUB 12 SHR 22 >R 32 [X-]@ 03 SUBB 13 ROR 23 I 33 [>X]@ $xx 04 XOR 14 INC 24 --- 34 [Y]@ 05 AND 15 DEC 25 EXIT 35 [+Y]@ 06 CMP_EQ 16 DAA 26 SWAP 36 [Y-]@ 07 CMP_NE 17 NOT 27 OVER 37 [>Y]@ $xx 08 CMP_LT 18 TOG_BF 28 2>R 38 [X]! 09 CMP_LE 19 SET_BCF 29 3>R 39 [+X]! 0A CMP_GT 1A DI 2A 2R@ 3A [X-]! 0B CMP_GE 1B IN 2B 3R@ 3B [>X]! $xx 0C OR 1C DECR 2C ROT 3C [Y]! 0D CCR@ 1D RTI 2D DUP 3D [+Y]! 0E CCR! 1E SWI 2E DROP 3E [Y-]! 0F SLEEP 1F OUT 2F DROPR 3F [>Y]! $xx 40 CALL $0xx 50 BRA $0xx 60 LIT_0 70 SP@ 41 CALL $1xx 51 BRA $1xx 61 LIT_1 71 RP@ 42 CALL $2xx 52 BRA $2xx 62 LIT_2 72 X@ 43 CALL $3xx 53 BRA $3xx 63 LIT_3 73 Y@ 44 CALL $4xx 54 BRA $4xx 64 LIT_4 74 SP! 45 CALL $5xx 55 BRA $5xx 65 LIT_5 75 RP! 46 CALL $6xx 56 BRA $6xx 66 LIT_6 76 X! 47 CALL $7xx 57 BRA $7xx 67 LIT_7 77 Y! 48 CALL $8xx 58 BRA $8xx 68 LIT_8 78 >SP $xx R@ 49 CALL $9xx 59 BRA $9xx 69 LIT_9 79 >RP $xx 4A CALL $Axx 5A BRA $Axx 6A LIT_A 7A >X $xx 4B CALL $Bxx 5B BRA $Bxx 6B LIT_B 7B >Y $xx 4C CALL $Cxx 5C BRA $Cxx 6C LIT_C 7C NOP 4D CALL $Dxx 5D BRA $Dxx 6D LIT_D 7D --- 4E CALL $Exx 5E BRA $Exx 6E LIT_E 7E --- 4F CALL $Fxx 5F BRA $Fxx 6F LIT_F 7F --- 80..BF SBRA $xxx Short branch inside current page C0..FF SCALL $xxx Short subroutine CALL into 'zero page' 26 03.01 MARC4 Programmer's Guide Instruction Set 2.1.1 Description of Used Identifiers and Abbreviations n1 n2 n3 Three nibbles on the Expression Stack n3n2n1 Three nibbles on the Return Stack which combine to form a 12-bit word un2n1 Two nibbles on the Return Stack (i.e. DO loop index and limit), `u' is an unused (undefined) nibble on the Return Stack RP Return Stack Pointer (8 bits), the RAM Address Register which points to the last entry on the return address stack X RAM Address Register (8 bits) Y RAM Address Register Y (8 bits) these registers can be used in 3 different addressing modes (direct, pre-incremented or postdecremented addressing) TOS Top of (Expression) Stack (4 bits) CCR Condition Code Register (4 bits) which contains: /n 1's complement of the 4-bit word n 3210 Numbered bits within a 4-bit word $xx 8-bit hexadecimal RAM address $xxx 12-bit hexadecimal ROM address PC Program Counter (12 bits) I [bit 0] Interrupt-Enable flag SP Expression Stack Pointer (8 bits), the RAM Address Register which points to the RAM location containing the second nibble (TOS-1) on the Expression Stack B [bit 1] Branch flag 2.1.2 % [bit 2] Reserved (currently unused) C [bit 3] Carry flag /C NOT Carry (Borrow)flag Stack Notation E ( n1 n2 -- n ) Expression Stack contents ( rightmost 4-bit digit is in TOS ) R ( n1n2n3 -- ) Return Stack contents ( rightmost 12-bit word is top entry ) RET ( -- ROMAddr ) Return Address Stack effects EXP ( -- ) Expression / Data Stack effects True condition = Branch flag set in CCR False condition = Branch flag reset in CCR n 4-bit data value (nibble) d 8-bit data value (byte) addr 8-bit RAM address ROMAddr 12-bit ROM address 03.01 27 MARC4 Programmer's Guide Instruction Set Code [hex] 28 Mnemonic Operation 00 ADD Add the top 2 stack digits 01 ADDC Add with carry the top 2 stack digits 02 SUB 2's complement subtraction of the top 2 digits 03 SUBB 1's complement subtraction of the top 2 digits 04 XOR Exclusive-OR top 2 stack digits 05 AND Bitwise-AND top 2 stack digits 0C OR Bitwise-OR top 2 stack digits 06 CMP_EQ Equality test for top 2 stack digits 07 CMP_NE Inequality test for top 2 stack digits 08 CMP_LT Less-than test for top 2 stack digits 09 CMP_LE Less-or-equal for top 2 stack digits 0A CMP_GT Greater-than for top 2 stack digits 0B CMP_GE Greater-or-equal for top 2 stack digits 0E CCR! 0F SLEEP 10 SHL Shift TOS left into carry 11 ROL Rotate TOS left through carry 12 SHR Shift TOS right into Carry Restore condition codes CPU in 'sleep mode',, interrupts enabled Symbolic Description [Stack Effects] E ( n1 n2 -- n1+n2 ) If overflow then B:=C:=1 else B:=C:=0 E ( n1 n2 -- n1+n2+C) If overflow then B:=C:=1 else B:=C:=0 E ( n1 n2 -- n1+/n2+1) If overflow then B:=C:=1 else B:=C:=0 E ( n1 n2 -- n1+/n2+/C) If overflow then B:=C:=1 else B:= C:=0 E ( n1 n2 -- n1 XOR n2) If result=0 then B:=1 else B:=0 E ( n1 n2 -- n1 AND n2) If result=0 then B:=1 else B:=0 E ( n1 n2 -- n1 OR n2) If result=0 then B:=1 else B:=0 E ( n1 n2 -- n1) If n1=n2 then B:=1 else B:=0 E ( n1 n2 -- n1) If n1<>n2 then B:=1 else B:=0 E ( n1 n2 -- n1) If n1<n2 then B:=1 else B:=0 E ( n1 n2 -- n1) If n1<<=n2 then B:=1 else B:=0 E ( n1 n2 -- n1) If n1>n2 then B:=1 else B:=0 E ( n1 n2 -- n1) If n1>=n2 then B:=1 else B:=0 E ( n -- ) R ( -- ) E ( -- ) R ( -- ) I:=1 C<--197>3210<--0 B:=C:=MSB ..<--C<--3210<--C<--.. B:=C:=MSB 0-->3210-->C B:=C:=LSB Instr. Cycles Flags C%BI 1 xxx- 1 xxx- 1 xxx- 1 xxx- 1 -xx- 1 -xx- 1 -xx- 1 xxx- 1 xxx- 1 xxx- 1 xxx- 1 xxx- 1 xxx- 1 xxxx 1 -x-1 1 xxx- 1 xxx- 1 xxx- 03.01 MARC4 Programmer's Guide Instruction Set Code [hex] Mnemonic Operation 13 ROR Rotate TOS right through carry 14 INC Increment TOS 15 DEC Decrement TOS 16 DAA Decimal adjust for addition (in BCD arithmetic) 17 NOT 1's complement of TOS 18 TOG_BF Toggle Branch flag 19 SET_BCF Set Branch and Carry flag 1A DI Disable all interrupts 1B IN Read data from 4-bit I/O port 1C DECR Decrement index on return stack 1D RTI Return from interrupt routine; enable all interrupts 1E SWI Software interrupt 1F OUT 20 21 TABLE 22 >R 23 I R@ 24 25 EXIT Write data to 4-bit I/O port Fetch an 8-bit ROM constant and performs an EXIT to RetPC Move (loop) index onto Return Stack Copy (loop) index from the Return Stack onto TOS Return from subroutine ( ' ; ' ) 26 SWAP 27 OVER 28 2>R 29 3>R 2A 2R@ 2B 3R@ 03.01 Exchange the top 2 digits Push a copy of TOS-1 onto TOS Move top 2 digits onto Return Stack Move top 3 digits onto Return Stack Copy 2 digits from Return to Expression Stack Copy 3 digits from Return to Expression Stack Symbolic Description [Stack Effects] ..-->C-->3210-->C-->.. B:=C:=LSB E ( n -- n+1) If result=0 then B:=1 else B:=0 E ( n -- n-1) If result=0 then B:=1 else B:=0 If TOS>9 OR C=1 then E ( n -- n+6 ) B:=C:=1 else E ( n -- n) R (--) B:=C:=0 E ( n -- /n) If result=0 then B:=1 else B:=0 If B = 1 then B:=0 else B:=1 B:=C:=1 E ( -- ) R ( -- ) I:=0 E ( port -- n) If port=0 then B:=1 else B:=0 R ( uun -- uun-1) If n-1=0 then B:=0 else B:=1 E (--) R ( $xxx -- ) PC := $xxx I:=1 E ( n1 n2 -- ) R ( -- ) [n1,n2 = 0,1,2,4,8] E ( n port -- ) R ( -- ) E ( -- nh nl ) R ( RetPC ROMaddr -- ) PC:= RetPC E ( n -- ) R ( -- uun) E ( -- n ) R ( uun -- uun) E ( -- ) R ( $xxx --) PC:=$xxx E ( n1 n2 -- n2 n1) R ( -- ) E ( n1 n2 -- n1 n2 n1) R ( -- ) E ( n1 n2 -- ) R ( -- un1n2) E ( n1 n2 n3 -- ) R ( -- n1n2n3) E ( -- n1 n2) R (un1n2 -- un1n2) E ( -- n1 n2 n3) R (n1n2n3 -- n1n2n3) Instr. Cycles Flags C%BI 1 xxx- 1 -xx- 1 -xx- 1 1x1- 0x0- 1 -xx- 1 -xx- 1 1x1- 1 -x-0 1 -xx- 2 -10- -01- 2 ---1 1 -x-- 1 -x-- 3 ---- 1 ---- 1 ---- 2 ---- 1 ---- 1 ---- 3 ---- 4 ---- 2 ---- 4 ---- 29 MARC4 Programmer's Guide Instruction Set Code [hex] Operation 2C ROT Move third digit onto TOS 2D DUP Duplicate the TOS digit 2E DROP Remove TOS digit from the Expression Stack 2F DROPR Remove one entry from the Return Stack 30 [X]@ Indirect fetch from RAM addressed by the X register 31 [+X]@ 32 [X-]@ Indirect fetch from RAM addressed by preincremented X register Indirect fetch from RAM addressed by the postdecremented X register [>X]@ $xx Direct fetch from RAM addressed by the X register 34 [Y]@ Indirect fetch from RAM addressed by the Y register 35 [+Y]@ 36 [Y-]@ 33 xx 37 xx [>Y]@ $xx 38 [X]! 39 [+X]! 3A [X-]! 3B xx 3C 30 Mnemonic Indirect fetch from RAM addressed by preincremented Y register Indirect fetch from RAM addressed by postdecremented Y register Direct fetch from RAM addressed by the Y register Indirect store into RAM addressed by the X register Indirect store into RAM addressed by pre-incremented X register Indirect store into RAM addressed by the postdecremented X reg. [>X]! $xx Direct store into RAM addressed by the X register [Y]! Indirect store into RAM addressed by the Y register Symbolic Description [Stack Effects] E (n1 n2 n3 -- n2 n3 n1) R ( -- ) E ( n -- n n) R ( -- ) E ( n -- ) R ( -- ) SP:=SP-1 E ( -- ) R( uuu -- ) RP:=RP-4 E ( -- n) R ( -- ) X:=X Y:=Y E ( -- n) R ( -- ) X:=X+1 Y:=Y E ( -- n) R ( -- ) X:=X-1 Y:=Y E ( -- n) R ( -- ) X:=$xx Y:=Y E ( -- n) R ( -- ) X:=X Y:=Y E ( -- n) R ( -- ) X:=X Y:=Y+1 E ( -- n) R ( -- ) X:=X Y:=Y-1 E ( -- n) R ( -- ) X:=X Y:=$xx E ( n -- ) R ( -- ) X:=X Y:=Y E ( n -- ) R ( -- ) X:=X+1 Y:=Y E ( n -- ) R ( -- ) X:=X-1 Y:=Y E ( n -- ) R ( -- ) X:=$xx Y:=Y E ( n -- ) R ( -- ) X:=X Y:=Y Instr. Cycles Flags C%BI 3 ---- 1 ---- 1 ---- 1 ---- 1 ---- 1 ---- 1 ---- 2 ---- 1 ---- 1 ---- 1 ---- 2 ---- 1 ---- 1 ---- 1 ---- 2 ---- 1 ---- 03.01 MARC4 Programmer's Guide Instruction Set Code [hex] Mnemonic Operation Symbolic Description [Stack Effects] Instr. Cycles Flags C%BI 3D [+Y]! Indirect store into RAM addressed by pre-incremented Y register E ( n -- ) R ( -- ) X:=X Y:=Y+1 1 ---- 3E [Y-]! Indirect store into RAM addressed by the post-decremented Y reg. E ( n -- ) R ( -- ) X:=X Y:=Y-1 1 ---- [>Y]! $xx Direct store into RAM addressed by the Y register E ( n -- ) R ( -- ) X:=X Y:=$xx 2 ---- 70 SP@ Fetch the current Expression Stack Pointer E ( -- SPh SPI+1) R ( -- ) SP:=SP+2 2 ---- 71 RP@ Fetch current Return Stack Pointer E ( -- RPh RPI) R ( -- ) 2 ---- 72 X@ Fetch current X register contents E ( -- Xh XI) R ( -- ) 2 ---- 73 Y@ Fetch current Y register contents E ( -- Yh YI) R ( -- ) 2 ---- 74 SP! Move address into the Expression Stack Pointer E ( dh dl -- ?) R ( -- ) SP:=dh_dl 2 ---- 75 RP! Move address into the Return Stack Pointer E ( dh dl -- ) R ( -- ?) RP:=dh_dl 2 ---- 76 X! Move address into the X register E ( dh dl -- ) R ( -- ) X:=dh_dl 2 ---- 77 Y! Move address into the Y register E ( dh dl -- ) R ( -- ) Y:=dh_dl 2 ---- 78 xx >SP $xx Set Expression Stack Pointer E ( -- ) R ( -- ) SP:=$xx 2 ---- 79 xx >RP $xx Set return Stack Pointer direct E ( -- ) R ( -- ) RP:=$xx 2 ---- 7A xx >X $xx Set RAM address register X direct E ( -- ) R ( -- ) X:=$xx 2 ---- 7B xx >Y $xx Set RAM address register Y direct E ( -- ) R ( -- ) Y:=$xx 2 ---- 7C NOP No operation PC:=PC+1 1 ---- 7D..7F NOP Illegal instruction PC:=PC+1 1 ---- 4x xx CALL $xxx Unconditional long CALL E ( -- ) R ( -- PC+2) PC:=$xxx 3 ---- 5x xx BRA $xxx Conditional long branch If B=1 then PC:=$xxx else PC:=PC+1 2 --1- --0- LIT_n Push literal/constant n onto TOS E ( -- n ) R ( -- ) 1 ---- 80..BF SBRA $xxx Conditional short branch in page If B=1 then PC:= $xxx else PC:=PC+1 2 ---- ---- C0..FF SCALL $xxx Unconditional short CALL E ( -- ) R ( -- PC+1) PC:= $xxx 2 ---- 3F xx 6n 03.01 31 MARC4 Programmer's Guide Instruction Set 2.1.3 MARC4 Instruction Set Overview Mnemonic Description Cycles/ Bytes AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAAAAAAAAAAA AAA AAAAAAAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAAAAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAA AAAAAAAAAAAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAAAAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAA AAAAAAAAAAAAAA AAAAAAAAA AAA Arithmetic operations: ADD Add ADDC Add with carry SUB Subtract SUBB Subtract with borrow DAA Decimal adjust INC Increment TOS DEC Decrement TOS DECR Decrement. 4-bit index on return stack Compare operations: CMP_EQ Compare equal CMP_NE Compare not equal CMP_LT Compare less than CMP_LE Compare less equal CMP_GT Compare greater than CMP_GE Compare greater equal Logical operations: XOR Exclusive OR AND AND OR OR NOT 1's complement SHL Shift left into carry SHR Shift right into carry ROL Rotate left through carry ROR Rotate right through carry Flag operations: TOG_BF Toggle branch flag SET_BFC Set branch flag DI Disable all interrupts CCR! Store TOS into CCR CCR@ Fetch CCR onto TOS Program branching: BRA $xxx Conditional long branch CALL $xxx Long call (current page) SBRA $xxx Conditional short branch SCALL$xxx Short call (zero page) EXIT Return from subroutine RTI Return from interrupt SWI Software interrupt SLEEP Activate sleep mode NOP No operation 32 1/1 1/1 1/1 1/1 1/1 1/1 1/1 2/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 1/1 2/2 3/2 2/1 2/1 2/1 2/1 1/1 1/1 1/1 Mnemonic Description Cycles/ Bytes AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAAAAAAAAA AAAAAAAA AAAA AAAAAAAAAAAAAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA AAAAA AAAAAAAA AAAA SP@ RP@ X@ Y@ SP! RP! X! Y! >SP $xx >RP $xx >X $xx >Y $xx SWAP OVER DUP ROT DROP >R 2>R 3>R R@ 2R@ 3R@ DROPR LIT_n Register operations: Fetch the current SP Fetch the current RP Fetch the contents of X Fetch the contents of Y Move the top 2 into SP Move the top 2 into RP Move the top 2 into X Move the top 2 into Y Store direct address to SP Store direct address to RP Store direct address into X Store direct address into Y Stack operations: Exchange the top 2 nibble Copy TOS-1 to the top Duplicate the top nibble Move TOS-2 to the top Remove the top nibble Move the top nibble onto the return stack Move the top 2 nibble onto the return stack Move the top 3 nibble onto the return stack Copy 1 nibble from the return stack Copy 2 nibbles from the return stack Copy 3 nibbles from the return stack Remove the top of return stack (12-Bit) Push immediate value 2/1 2/1 2/1 2/1 2/1 2/1 2/1 2/1 2/2 2/2 2/2 2/2 1/1 1/1 1/1 3/1 1/1 1/1 3/1 4/1 1/1 2/1 4/1 1/1 1/1 (1 nibble) onto TOS 03.01 MARC4 Programmer's Guide Instruction Set Instruction set overview (continued) Mnemonic Description Cycles/ Bytes AAAAAAAAAAAAAAA AAAAAAAAAAAAAAA AAAAA AAAAAAAAA AAA AAAAAAAAAAAAAAA AAAAA AAAAAAAAA AAA AAAAAAAAAAAAAAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAA AAAAA AAAAAAAAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAA AAAAA AAAAAAAAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAAAAA AAA AAAAA AAAAAAAAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAA AAAAA AAAAAAAAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAAAAA AAAAAAAAAAAAAAA AAAAAAAAAAAAAAA AAAAA AAAAAAAAA AAA AAAAA AAAAAAAAA AAA TABLE [X]@ [Y]@ [+X]@ [+Y]@ [X-]@ [Y-]@ [>X]@ $xx [>Y]@ $xx [X]! [Y]! [+X]! [+Y]! [X-]! [Y-]! [>X]! $xx [>Y]! $xx IN OUT 03.01 ROM data operations: Fetch 8-bit constant from ROM Memory operations: Fetch 1 nibble from RAM indirect addressed by Xor Y-register Fetch 1 nibble from RAM indirect addr. by pre-increm. X- or Y-register Fetch 1 nibble from RAM indirect addr. by post-dejcrem. X- or Y-register Fetch 1 nibble from RAM direct addressed by X- or Y-register Store 1 nibble into RAM indirect addressed by [X] Store 1 nibble into RAM indirect addressed by preincremented [X] Store 1 nibble into RAM indirect addr. by post-decrem. X- or Y-register Store 1 nibble into RAM direct addressed by X- or Y-register I/O operations: Read I/O-Port onto TOS Write TOS to I/O port 3 1/1 1/1 1/1 2/2 1/1 1/1 1/1 2/2 1/1 1/1 33 I. Hardware Description II. Instruction Set III. Programming in qFORTH IV. qFORTH Language Dictionary V. Addresses MARC4 Programmer's Guide Programming in qFORTH 3 3.1 Programming in qFORTH Why Program in qFORTH ? Programming in qFORTH reduces the software development time ! Atmel Wireless & Microcontrollers' strategy in developing an integrated programming environment for qFORTH was to free the programmer from restrictions imposed by many FORTH environments (e.g. screen, fixed file block sizes), and at the same time to maintain an interactive approach to program development. The MARC4 software development system enables the MARC4 programmer to edit, compile, simulate and/or evaluate a program code using an integrated package with predefined key codes and pull-down menus. The compiler-generated MARC4 code is optimized for demanding application requirements, such as the efficient usage of available program memory. One can be assured that the generated code only uses the amount of on-chip memory that is required, and that no additional overhead is attached to the program at the compilation phase. What other reasons are there for programming in qFORTH ? Subroutines that are kept short increase the modularity and program maintainability. Both are related to the development cost. Programs that are developed using the Brute Force approach (where the program is realized in software using a sequential code) tend to be considerably larger in memory consumption, and are extremely difficult to maintain. A qFORTH program, engineered using the building block modular approach is compact in size, easy to understand and thus, easier to maintain. The added benefit for the user is a library of software routines which can be interchanged with other MARC4 applications as long as the input and output conditions of your code block correspond. This toolbox of off-the-shelf qFORTH routines grows with each 03.01 new MARC4 application and reduces the amount of programming effort required. Programming in qFORTH results in a re-usable code. Re-usable for other applications which will be programmed at a later date. This is an important factor in ensuring that future software developement costs are kept to a minimum. Routines written by one qFORTH programmer can be easily incorporated by a different qFORTH user. Language Features: Expandability Many of the fundamental qFORTH operations are directly implemented in the MARC4 instruction set Stack Oriented All operations communicate with one another via the data stack and use the reverse polish form of notation (RPN) Structured Programming qFORTH supports programming structured Reentrant Different service routines can share the same code, as long as you do not modify global variables within this code Recursive qFORTH routines can call themselves Native Code Inclusion In qFORTH there is no separation of high level constructs from the native code mnemonics 37 MARC4 Programmer's Guide Programming in qFORTH 3.2 Language Overview qFORTH is based on the FORTH-83 language standard, the qFORTH compiler generates a native code for a 4-bit FORTH-architecture single-chip microcomputer - the Atmel Wireless & Microcontrollers MARC4. MARC4 applications are all programmed in qFORTH which is designed specifically for efficient real-time control. Since the qFORTH compiler generates highly optimized codes, there is no advantage or point in programming the MARC4 in assembly code. The high level of code efficiency generated by the qFORTH compiler is achieved by the use of modern optimization techniques such as branch-instruction size minimization, fast procedure calls, pointer tracking and peephole optimizations. IIIIII IIIIII IIIIII IIIIII IIIIII IIIIII IIIIII IIIIII IIIIIIIIIIIIIIIIII IIIIII IIIIII IIIIII IIIIII IIIIII IIIIII II APPLICATION SPECIFICATION PROGRAM SPECIFICATION HARDWARE REQUIREMENTS LEARN qFORTH LEARN DEVELOPMENT SYSTEM PSEUDO-CODE MODULES PROGRAMMER'S GUIDE CODE IN qFORTH MARC4 MARC4 qFORTH REFERENCE GUIDE II IIIIII II IIIIII IIIIII IIIIII II IIIIII IIIIII II IIIIII IIIIII IIIIII IIIIII IIIIII IIIIII IIIIII qFORTH qFORTH EDIT PROGRAM (MODULES) DEVELOPMENT SYSTEM USER'S GUIDE COMPILE MARC4 S.D.S. (TEST MODULES) SIMULATE EMULATE MAIL FLOPPY TO Atmel Wireless & mC MARC4 TARGET HARDWARE Figure 1. Program development with qFORTH 38 03.01 MARC4 Programmer's Guide Programming in qFORTH Standard FORTH operations which support string processing, formatting and disk I/O have been omitted from the qFORTH system library, since these instructions are not required in single-chip microcomputer applications. The following two tables highlight the basic constructs and compare qFORTH with the FORTH-83 language standard. Table 1. qFORTH's FORTH-83 language subset Arithmetic / Logical - D+ 1+ AND NEGATE + D- 1- NOT DNEGATE * 2* D2* OR / 2/ D2/ XOR Compiler ALLOT $INCLUDE CONSTANT 2CONSTANT CODE END-CODE VARIABLE 2VARIABLE Comparison < = <> <= >= 0= 0<> D> D0<> D< D0= D>= D= MIN MAX DMIN DMAX D<= D<> Stack Operations >R <ROT ?DUP OVER 2DUP I R> 2DROP DEPTH DUP PICK 2OVER DROP SWAP 2SWAP J ROT ROLL Control Structure ?DO DO IS ELSE THEN +LOOP LEAVE UNTIL AGAIN ENDCASE LOOP WHILE BEGIN ENDOF OF CASE EXIT REPEAT EXECUTE Memory Operations ! 2! @ 2@ ERASE MOVE MOVE > FILL TOGGLE Table 2. Differences between qFORTH and FORTH-83 qFORTH 4-bit Expression Stack 12-bit Return Stack The prefix "2" on a keyword (e.g. 2DUP refers to an 8-bit data type) Branch and Carry flag in the Condition Code Register Only predefined data types for handling untyped memory blocks, arrays or tables of constants 03.01 FORTH-83 16-bit Expression Stack 16-bit Return Stack The prefix "2" on a keyword (e.g. 2DUP refers to a 32-bit data type) Flag value on top of the Expression Stack CREATE, >BUILD .. DOES 39 MARC4 Programmer's Guide Programming in qFORTH 3.3 The qFORTH Vocabulary qFORTH is a compiled language with a dictionary of predefined words. Each qFORTH word contained in the system library has, as its basis, a set of core words which are very close to the machine-level instructions of the MARC4 (such as XOR, SWAP, DROP and ROT). Other instructions (such as D+ and D+!) are qFORTH word definitions. The qFORTH compiler parses the source code for words which have been defined in the system dictionary. Once located as being in the dictionary, the compiler then translates the qFORTH definition into MARC4 machine-level instructions. 3.3.1 Word Definitions A new word definition which i.e. contains three sub-words: WORD1, WORD2 and WORD3 in a colon definition called MASTER-WORD is written in qFORTH as: : MASTER-WORD WORD1 WORD2 WORD3 ; IIIII IIIII The colon `:' and the semicolon `;' are the start and stop declarations for the definition. A qFORTH programmer refers to a colon definition to specify a word name which follows the colon. The following diagram depicts the execution sequence of these three words: The sequential order shows the way the compiler (and the MARC4) will understand what the program is to do. 1st step Begin the word definition with a `:', followed by a space. 2nd step Specify the <name> of the colon definition. 3rd step List the names of the sequentially-organized words which will perform the definition. Remember that each word as shown above can itself be a colon or macro definition of other qFORTH words (such as D+ or 2DUP). 4th step Specify the end of the colon definition with a semicolon. II II ; : MASTER_WORD WORD1 WORD2 WORD3 Figure 2. Threaded qFORTH word definition 3.4 Stacks, RPN and Comments In this section, we will look at the qFORTH notation known as RPN. Other topics to be examined include qFORTH's stacks, constants and variables. 3.4.1 Reverse Polish Notation qFORTH is a Reverse Polish Notation language (RPN), which operates on a stack of data values. RPN is a stack based representation of a mathematical problem where the top two numbers on the stack are operated on by the operation to be performed. 40 Example: 4+2 Is spoken in the English language as '4 plus 2', resulting in the value 6. In our stack-based MARC4, we write this using qFORTH notation as: 42+ The first number, 4, must be placed onto the data stack, then the second number will follow it onto the data stack. The MARC4 then comes to the addition operator. Both the 4 and 2 are taken off the data stack and processed by the MARC4's arithmetic and logic unit, the result (in this case 6) will be deposited onto the top of the data stack. 03.01 MARC4 Programmer's Guide Programming in qFORTH 3.4.2 The qFORTH Stacks The MARC4 processor is a stack-based microcomputer. It uses a hardware-constructed storage area onto which data is placed in a last-in-first-out nature. The MARC4 has two stacks, the Expression Stack and the Return Stack. The Expression Stack, also known as the data stack, is 4 bits wide and is used for temporary storage during calculations or to pass parameters to words. The Return Stack is 12 bits wide and is used by the processor to hold the return addresses of subroutines, so that upon completion of the called word, program control is transferred back Before Side ( n3 n2 n1 TOS 3.4.4 After Side -- n3 n2 n1) TOS qFORTH Comment Definitions Type _ 2 : \ text Type_1 Comments begin and end with curved brackets while Type_2 comments require only a backslash at the beginning of the comment. Type_1 declarations do not require a blank space before closing the bracket. 03.01 Stack Notation The qFORTH stack notation shows the stack contents before and after the execution of a qFORTH word. The before and after operations are separated via two bars: -- . The left hand side of the stack shows the stack before execution of the operation. The right most element before the two bars on the left side is the top of stack before the operation and the right most on the right side is also the top of stack after the operation. Examine the following qFORTH stack notation: Stack Notation 4 2 1 + SWAP Comments in qFORTH are definitions which instruct the qFORTH compiler to ignore the text following the comment character. The comment is included in the source code of your program to aid the programmer in understanding what the code does. There are two types of comment declarations: ( text ) 3.4.3 Example Comments Type _ 1 : to the calling qFORTH word. The Return Stack is used by all colon definitions (i.e. CALLs), interrupts and to hold loop-control variables. ( -- 4 2 1 ) ( 4 2 1 -- 4 3 ) ( 4 3 -- 3 4 ) Type_2 Comments start at the second space following the backslash and go till the end of the line. Both types of declarations require a blank space to follow the comment declaration. Valid Invalid ( this is a valid comment ) (this is not a valid comment) \ this is a valid comment \\ this is not a valid comment 41 MARC4 Programmer's Guide Programming in qFORTH 3.5 Constants and Variables $EXTMEMSIZE In qFORTH, data is normally manipulated as unsigned integer values, either as memory addresses or as data values. Allows the programmer to define the size of an external memory. Only required if an external memory is used whereby the default value is set at 255 nibbles. 3.5.1 $EXTMEMPORT Constants A constant is an unalterable qFORTH definition. Once defined, the value of the constant cannot be altered. In qFORTH, 4-bit and 8-bit numerical data can be assigned to a more readable symbolic representation. Allows the definition of a port address via which the external memory is accessed. The default port address for external memory is Fh. $EXTMEMTYPE value CONSTANT <constant-name> ( 4-bit constant ) Allows the definition of the type of external memory used. The types RAM or EEPROM are valid, whereby RAM is default if an external memory is used. value 2CONSTANT <constant-name> ( 8-bit constant ) Example: qFORTH Constant Definitions Example: 7 42h CONSTANT 2CONSTANT : Load-Answer Set-Mode ROM_Okay ROM_Okay ; ( Places 42h on EXP stack) 6 CONSTANT RAM CONSTANT 95 2CONSTANT 16 2ARRAY : Check_Freq Freq [4] IF 0 0 THEN ; 3.5.2 $EXTMEMPORT $EXTMEMTYPE $EXTMEMSIZE Freq EXTERNAL 2@ 80h D> Frequency [5] 2! Look-up Tables In the qFORTH compiler a number of constants have a predefined function. Look-up tables of 8-bit bytes are defined by the word ROMCONST followed by the <table-name> and a list of single- or double-length constants each delimited by a space and a comma. $ROMSIZE 2CONSTANT to define the MARC4's actual ROM size. The values are 1.5K (default), 2.0K, 2.5K, 3.0K and 4.0Kbytes of ROM. The content of a table is not limited to literals such as 5 or 67h, but may also include user- or pre-defined constants such as Set-Mode or ROM_Okay. $RAMSIZE 2CONSTANT to define the MARC4's actual RAM size in nibbles. Possible values are 111 (default), 167 and 255 nibbles. In the examples below, the days of the month are placed into a look-up table called `Days_Of_Month', the month (converted to 0 ... 11) is used to access the table in order to return the BCD number of days in the given month. Predefined Constants 42 03.01 MARC4 Programmer's Guide Programming in qFORTH qFORTH Table Definition ROMCONST <table-name> Const , Const , Const , Const , Const , Const , Examples: ROMCONST DaysOfMonth 31h , 28h , 31h , 30h , 31h , 30h , 31h , 31h , 30h , 31h , 30h , 31h , ROMCONST DaysOfWeek SU , MO , TU , WE, TH , FR , SA , ROMCONST Message 11 , " Hello World " , Note 1:A comma must follow the last table item. Note 2:Since there is no end-of-table delimiter in qFORTH, only a colon definition, a VARIABLE or another ROMCONST may follow a table definition (i.e. the last comma). 3.6 Variables and Arrays A variable is a qFORTH word whose name is associated with a memory address. A value can be stored at the memory address by assigning a value to the named variable. The value at this address can be accessed by using the variable name, thereby placing the variable value onto the top of the stack. The VARIABLE definition has a 4-bit memory cell allocated to it. qFORTH also permits a double-length 8-bit value to be assigned as a 2VARIABLE. qFORTH Variable Definitions VARIABLE <variable- name> 4-bit variable 2VARIABLE <variable- name> 8-bit variable 03.01 Example: VARIABLE Relay# 2VARIABLEVoltage 3.6.1 Defining Arrays qFORTH arrays are declared differently from arrays in FORTH-83. In both implementations of FORTH an array is a collection of elements assigned to a common name. An array can either be defined as being a VARIABLE with 8 elements: VARIABLE DATA 7 ALLOT or using the qFORTH array implementation: 8 ARRAY DATA The array index is running from 0 to <length-1>. ARRAY and 2ARRAY may contain up to 16 elements (e.g. nibbles or bytes). LARRAY and 2LARRAY contain more than 16 elements. qFORTH Array Definitions ARRAY Allocates RAM space for a short 4-bit array LARRAY Allocates RAM space for a long 4-bit array 2ARRAY Allocates space for a short 8-bit array 2LARRAY Allocates space for a long 8-bit array 3.7 Stack Allocation Both the Expression and Return Stacks are located in RAM. The size of the stacks is variable and must be defined by the programmer by using the predefined variables R0 and S0. Figure 3 shows the location of the stacks in RAM. The Return Stack variable address R0 starts at RAM location 00h. The Expression Stack is located above the Return Stack, starting at the next location called S0. The depth of the Expression and Return Stacks is allocated using the ALLOT construct. While 43 MARC4 Programmer's Guide Programming in qFORTH the depth (in nibbles) of the Expression Stack is exactly the number allocated, the Return Stack depth is expressed by the following formula: : $RESET >RP FCh \ Initialize the two stack pointers >SP S0 RAM_Test ... RET_Value := (RET_Depth-2)4+1 ; Example: VARIABLE R0 20 ALLOT \ RET Depth of 7 VARIABLE S0 17 ALLOT \ EXP Depth of 17 3.7.1 Stack Pointer Initialization 2 3 S0 unused 0Ch 08h 04h 00h R0 FCh 0 0 0 Return Stack RP Expression Stack 15h (TOS-1) used SP used unused Global variables and arrays 1 3.8.1 Stack Operations, Reading and Writing Stack Operations A number of stack operators are available to the qFORTH programmer. An overview of all the predefined stack words can be found in the qFORTH Quick Reference Guide. Stack operators used most often and which manipulate the order of the elements on the data stack like DUP, DROP, SWAP, OVER and ROT are explained later on. The Data Stack RAM 0 3.8 The 4-bit wide Data Stack is called the Expression Stack. Arithmetic and data manipulation are performed on the Expression Stack. The Expression Stack serves as a holding device for the data and also as the interface link between words, so that all data passed between the qFORTH words can be located on the Expression Stack or in global variables. The qFORTH word : TEN 1 2 3 4 5 6 7 8 9 0 ; Auto-Sleep Figure 3. Stacks inside RAM 9 The two stack pointers must be initialized in the $RESET routine. Note: The Return Stack pointer RP must be set to FCh so that the AUTOSLEEP feature will work. 44 TOS-1 8 7 6 5 4 3 2 Example: VARIABLE R0 32 ALLOT VARIABLE S0 12 ALLOT TOS 0 1 \ RET stack depth = 10 \ EXP stack depth = 12 nibbles TOS-9 Figure 4. Push-down data stack 03.01 MARC4 Programmer's Guide Programming in qFORTH When executed, the value 0 at the top and the value 1 at the bottom of the Expression Stack will be the result. SWAP In many programming applications it is necessary to re-arrange the input data so that it can be handled properly. For example we will use a simple series of data and then SWAP them so that they appear in the reserve order. 4 2 SWAP ( 4 2--2 4) 2 4 4 2 TOS TOS-1 ROT and <ROT Stack values must frequently be arranged into a defined order. We have already been introduced to the SWAP operation. Apart from SWAP, qFORTH supports the stack rotation operators ROT and <ROT. The ROT operation moves the third value (TOS-2) to the TOS. The operation <ROT (which is the same as ROT ROT) does the opposite of ROT, moving the value from the TOS to the TOS-2 location on the Expression Stack. R>, >R, R@ and DROPR TOS-9 Expression Stack Expression Stack Figure 5. The SWAP operation DUP, OVER and DROP The qFORTH word to duplicate the TOS item is DUP. It will make a copy of the current TOS element on the Expression Stack. DUP is useful in retaining the TOS value before operations which implicitly DROP the TOS following their execution. For example, all of the comparison operations like >, >=, <= or < destroy the TOS. qFORTH also supports data transfers between the Expression and the Return Stack. The >R operation moves the top 4-bit value from the Expression Stack and pushes the value onto the Return Stack. R> removes the top 4-bit value from the Return Stack and puts the value onto the Expression Stack, while R@ (or I) copies the 4-bit value from the Return Stack and deposits the copied value onto the Expression Stack. DROPR removes the top entry from the Return Stack. R>, R@, I TOS TOS-1 The OVER operation makes a copy of the second element on the stack (TOS-1) and deposits it onto the top of the stack. The MARC4 stack operator DROP removes one 4-bit value from the TOS. For example, the qFORTH operation NIP will drop the TOS-1 element from the stack. This can be written in qFORTH as: : NIP SWAP DROP ; ( n1 n2 -- n2 ) 03.01 TOS-9 0 9 8 7 6 5 4 3 2 1 Expression Stack 0 >R, #DO Return Stack Figure 6. Return Stack data transfers 45 MARC4 Programmer's Guide Programming in qFORTH Other Useful Stack Operations The following list contains more useful stack operations. Note that for every 4-bit stack operation, there is almost always an 8-bit equivalent. A full list of all stack operations may be found in the qFORTH Quick Reference Guide. ' <name> EXP ( -- ROMAddr ) Places ROM address of colon-definition <name> on EXP stack <ROT EXP ( n1 n2 n -- n n1 n2 ) Move top value to 3rd stack pos ?DUP EXP ( n -- n n ) Duplicate top value if n <>0 I EXP ( -- I ) R@ RET ( u|u|I -- u|u|I ) Copy 4-bit loop index I from the return to the Expression Stack NIP EXP ( n1 n2 -- n2 ) Drop second to top 4-bit value TUCK EXP ( n1 n2 -- n2 n1 n2 ) Duplicate top value, move under second item 2>R EXP ( n1 n2 -- ) RET ( -- u|n2|n1 ) Move top two values from Expression to Return Stack 2DROP EXP ( n1 n2 -- ) Drop top 2 values from the stack 2DUP EXP ( d -- d d ) Duplicate top 8-bit value 2NIP EXP ( d1 d2 -- d2 ) Drop 2nd 8-bit value from stack 2OVER EXP ( d1 d2 -- d1 d2 d1 ) Copy 2nd 8-bit value over top value 2<ROT EXP ( d1 d2 d -- d d1 d2 ) Move top 8-bit value to 3rd pos'n 2R> EXP ( -- n1 n2 ) RET ( u|n2|n1 -- ) Move top 8 bits from Return to Expression Stack 2R@ EXP ( -- n1 n2 ) RET ( u|n2|n1 -- u|n2|n1 ) Copy top 8 bits from Return to Expression Stack 3>R EXP ( n1 n2 n3 -- ) RET ( -- n3|n2|n1 ) Move top 3 nibbles from the Expression onto the Return Stack 3DROP EXP ( n1 n2 n3 -- ) Remove top 12-bit value from stack 3DUP EXP ( t -- t t ) Duplicate top 12-bit value 3R> EXP ( -- n1 n2 n3 ) RET ( n3|n2|n1 -- ) Move top 3 nibbles from Return to the Expression Stack 3R@ EXP ( -- n1 n2 n3 ) Copy 3 nibbles (1 ROM address entry) from the RET ( n3|n2|n1 -- n3|n2|n1 ) Return Stack to the Expression Stack 46 03.01 MARC4 Programmer's Guide Programming in qFORTH 3.8.2 3.8.3 Reading and Writing (@, !) In the previous section it was mentioned that data can be placed onto, and taken off the Expression Stack. The reading and writing operations transfer data values between the data stack and the RAM. Writing a data value to a RAM location which has been specified by a variable name requires the TOS to contain the variables 8-bit RAM address and that the data to be stored in the RAM be contained at the TOS-2 location. The read operator is written in the qFORTH syntax with the @ symbol and is pronounced fetch. The write operator is written in qFORTH with the ! symbol and is pronounced store. Write two qFORTH colon definitions (words) that will store the numeric value 7 from the TOS to the variable named FRED and then fetch the contents its back onto the Expression Stack (TOS). Example: VARIABLE FRED : Store 7 FRED : Fetch FRED ! ; @ ; ( ( -- ) -- n ) For 8-bit values, stored at two consecutive locations, qFORTH has the Double-Fetch and Double-Store words: 2@ and 2!. To store 1Ah in the 8-bit 2VARIABLE BERT using the Double-Store, examine the following code: 2VARIABLE BERT : Double-Store 1Ah BERT RAM Address Registers X and Y The MARC4 processor can address any location in RAM indirectly via the 8-bit wide X and Y RAM Address Registers. These registers are used as pointer registers to organize arrays within the RAM. They can be pre-incremented or post-decremented by using CPU control. The X and Y registers are automatically used by the compiler during fetch (@) and store (!) operations. Hence, care should be taken when referencing these registers explicitly. If a default occurs, the compiler uses the Y register. Memory Operators which Use the X / Y Register @ D+! 2! ERASE ! D-! 2@ FILL +! TD+! 3! MOVE 1+! TD-! 3@ MOVE> -! T+! PICK TOGGLE 1-! T-! ROLL DTOGGLE Example: BERT 2! ; Storing the value 1Ah is a two-part operation: The high-order nibble 1 is stored in the first digit, while at the next 4-bit RAM location the hexadecimal value A will be stored. : Double-Fetch Low-Level Memory Operations 2@ ; (-- d) i.e., accesses the 8 bits at the memory address where BERT is placed and loads them onto Expression Stack. The lower-order nibble will always end up on TOS. The 4-bit value in TOS is added to an 8-bit RAM value and stored back into the 8-bit RAM variable. : M+! X! 0 ; ( n RAM_addr -- ) [+X]@ [X]@ + +C [X-]! [X]! 2VARIABLE Voltage 5 Voltage M+! Note: Hexadecimal values are represented by an h or H following the value. 03.01 47 MARC4 Programmer's Guide Programming in qFORTH X Register X@ X! Description Fetch current X (or Y) register contents Y@ Move 8-bit address from stack into X (or Y) reg. Y! >X xx Set register address of X (or Y) direct >Y yy [>X]@ xx Direct RAM fetch, X (or Y) addressed [>Y]@ yy [>X]! xx Direct RAL store, X (or Y) addressed [>Y]! yy [X]@ Indirect X (or Y) fetch of RAM contents [Y]@ [X]! Indirect X (or Y) store of RAM contents [Y]! [+X]@ Preincrement X (or Y) indirect RAM fetch [+Y]@ [X-]@ Postdecrement X (or Y) indirect RAM fetch [Y-]@ [+X]! Preincrement X (or Y) indirect RAM store [+Y]! [X-]! Postdecrement X (or Y) indirect RAM store [Y-]! Bit Manipulations in RAM By using the X or Y registers, it is possible to manipulate the content of the RAM on a bitwise basis. The following examples all have the same stack notation. : BitSet X! [X]@ OR [X]! ; ( mask RAM_addr -- [branch flag] ) ( get data from memory ) ( mask & store in memory ) 3.9 MARC4 Condition Codes The MARC4 processor has within its Arithmetic Logic Unit (ALU) a 4-bit wide Condition Code Register (CCR) which contains 4 flag bits. These are the Branch (B) flag, the Interrupt-Enable (I) flag and the Carry (C) flag. C : BitReset X! Fh XOR [X]@ AND [X]! ; ( mask RAM_addr -- [branch flag] ) ( Invert mask for AND ) ( get data from memory ) ( mask & store in memory ) : Test0= ( mask RAM_addr -- [branch flag] ) X! [X]@ AND DROP ; CODE Test0<> ( mask RAM_addr -- [branch flag] ) Test0= TOG_BF END-CODE 48 Y Register - B I CCR Interrupt enable Branch (reserved) Carry Figure 7. MARC4 Condition Code Register flags Most arithmetic/logical operations, for example, will have an effect on the CCR. If you try to add 12 and 5, the Carry and Branch flags will be set, since an arithmetic overflow has occured. 03.01 MARC4 Programmer's Guide Programming in qFORTH 3.9.1 The CCR and the Control Operations The Carry flag is set by ALU instructions such as the +, +C, -or -C whenever an arithmetic under/overflow occurs. The Carry flag is also used during shift/rotate instruction such as ROR and ROL. The Branch flag is set under CPU control, depending upon the current ALU instruction, and is a result of the logical combination of the carry flag and the TOS = 0 condition. The Branch flag is responsible for generating conditional branches. The conditional branch is performed when the Branch flag has been set by one of the previous qFORTH operations (e.g. comparison operations). The TOG_BF instruction will toggle the state of the Branch flag in the CCR. If the Branch flag is set before the TOG_BF instruction, it will be reset following the execution. The SET_BCF instruction will set the Branch and Carry on execution, while the CLR_BCF operation will reset both flags. 3.10 Arithmetic Operations The arithmetic operators presented here are similar to those described in most FORTH literature. The underlying difference, however, is that the qFORTH arithmetic operations are based on the 4-bit CPU architecture of the MARC4. 3.10.1 Number Systems When coding in qFORTH, standard numeric representations are decimal values. For other representations, it is necessary to append a single character for that representation. Examples have already been presented which perform operations on the TOS as a 4-bit (single-length) value or on both the TOS and TOS-1 values. By combining the TOS and TOS-1 locations, it is possible to handle the data as an 8-bit value. Note: In qFORTH, all operators which start with a 2 (e.g: 2SWAP or 2@) use double-length (8-bit) data. Other operators such as D+ and D= are also double-length operators. The qFORTH language also permits triple-length operators, which are defined with a 3 prefix (e.g: 3DROP). Examples for all qFORTH dictionary words are included in the qFORTH Language Reference Dictionary. 3.10.2 Addition and Subtraction The algebraic expression 4 + 2 is spoken in the English language as: 4 plus 2, and results in a value of 6. In qFORTH, this expression as 4 2 +. The 4 is deposited onto the Data Stack, followed by the 2. The operator gives a command to take the top two values from the Data Stack and add them together. The result is then placed back onto the Data Stack. Both the 4 and the 2 are dropped from the stack by the operation. The stack notation for the addition operator is: + EXP ( n1 n2 -- n1+n2 ) qFORTH performs the subtraction in a similar way to the addition operator. The operator is the common algebraic symbol with the stack notation: - EXP ( n1 n2 -- n1-n2 ) Examples: : TNEGATE Example: Bh --> bH --> 11 --> 1011b--> 1011B--> Single- and Double-Length Operators hexadecimal hexadecimal decimal binary binary ( 12-bit 2's complement on the TOS ) 0 SWAP - ( th tm tl -- th tm -tl ) 0 ROT -c ( th tm -tl -- th -tl -tm ) ROT 0 SWAP-c ( th -tl -tm -- tl -tm -th) SWAP ROT ( -tl -tm -th -- -t ) ( base 16 ) ( base 16 ) ( base 10 ) ( base 2 ) ( base 2 ) ; 03.01 49 MARC4 Programmer's Guide Programming in qFORTH : 3NEG! Voltage 2@ 5 M+ IF 2DROP 0 0 \ IF overflow, THEN reset Voltage ELSE 10 M- THEN Voltage 2! ; 3.10.5 ( 12-bit 2's complement in an array ) Y! 0 [+Y]@ 0 [+Y]@ ( addr -- 0 tm 0 tl ) -[Y-]! -c [Y-]! ( 0 tm 0 tl -- ) 0 [Y]@ -c [Y]! ( 0 tm -tl -- ) 3.10.3 DAA and DAS Increment and Decrement Increment and decrement instructions are common to most programming languages. qFORTH supports both with the standard syntax: 1+ 1- incrementnew-TOS: = old-TOS + 1 decrement new-TOS: = old-TOS -1 Decimal numbers are usually represented in 4-bit binary equivalents of each digit using the binary-coded-decimal coding scheme. The qFORTH instruction set includes the DAA and DAS operations for BCD arithmetic. DAA Example: : Inc-Dec Note: 3.10.4 10 1+ 1-1- ; ( -- Ah ( Ah -- Bh ( Bh -- 9h BCD Arithmetic ) ) ) Fh ( 1111 ) -> 5 ( 0101 ) and carry flag set Eh ( 1110 ) -> 4 ( 0100 ) Dh ( 1101 ) -> 3 ( 0011 ) Ch ( 1100 ) -> 2 ( 0010 ) Bh ( 1011 ) -> 1 ( 0001 ) Ah ( 1010 ) -> 0 ( 0000 ) The Carry flag in the CCR is not affected by these MARC4 instructions, whereby the Branch flag is set if the result of the operation becomes zero. Mixed-Length Arithmetic qFORTH supports mixed-length operators such as M+, M-, M* and M/MOD. In the examples below, a 4-bit value is added/subtracted to/from an 8-bit value (generating an 8-bit result) using the M+ and M-operators. Decimal adjust for BCD arithmetic, adds 6 to values between 10 and 15. It will also add 6 to the TOS, if the carry flag is set. DAS Decimal arithmetic for BCD subtraction, builds a 9's complement for DAA and ADDC, the branch and carry flags will be changed. Examples: : DIG- Y! SWAP DAS SWAP #DO [Y]@ + DAA [Y-]! 10 -?LEAVE #LOOP DROP ; : BCD_1+! Y! [Y]@ 1 + DAA [Y]! ; : Array_1+ Y! SET_BCF BEGIN [Y]@ 0 +C DAA [Y-]! 1- UNTIL DROP ; 50 \ Digit count LSD_Addr -- \ Generate 9's complement \ Digit count -- Digit \ Transfer carry on stack \ Exit LOOP, if NO carry \ Repeat until index = 0 \ Skip TOS overflow digit \ RAM_Addr -- \ Increments BCD digit \ in RAM array element \ Inc BCD array by 1 ( n array[n] -- ) ( Start with carry = 1 ) 03.01 MARC4 Programmer's Guide Programming in qFORTH 3.10.6 Summary of Arithmetic Words The following list contain more useful arithmetic words. The full list and implementation may be found in the MATHUTIL.INC file D+ D- D+! D-! M+ M- M+! M-! M/ M* M/MOD D/MOD TD+! TD-! TD+ TD- D->BCD ( d1 d2 -- d_sum ( d1 d2 -- d2-d1 ( nh nl addr -- ( nh nl addr -- ( d1 n -- d2 ( d1 n -- d2 ( n addr -- ( n addr -- ( d n -- d_quotient ( d n -- d_product ( d n -- n_quot n_rem ( d n -- d_quot n_rem ( d addr -- ( d addr -- ( d addr -- t ( d addr -- t ( d -- n_100 n_10 n_1 ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) Add top two 8-bit elements Subtract top two 8-bit elements Add 8-bit TOS to memory Subtract 8-bit TOS from memory Add 4-bit TOS to an 8-bit value Sub 4-bit TOS from 8-bit value Add n to an 8-bit RAM byte Subtract n from 8-bit RAM byte Divide n from d Multiply d by n Div n from d giving 4-bit results Div 8-bit value &4-bit remainder Add 8-bit TOS to 12-bit RAM var. Sub 8-bit from 12-bit RAM var. Add 8-bit to 12-bit RAM var. Sub 8-bit from 12-bit RAM var. Convert 8-bit binary to BCD 3.11 Logicals The logical operators in qFORTH permit bit manipulation. The programmer can input a bit stream from the input port, transfer it onto the expression stack and then shift branches and the bit pattern left or right, or the bit pattern can be rotated onto the TOS. The Branch and Carry flag in the CCR are used by many of the qFORTH logical operators. used to represent the effects of the logical operators on two data values (n1 and n2). These qFORTH operators take the top values off of the expression stack and perform the desired logical operation. The resultant flag setting and the stack conditions are described in the qFORTH Language Reference Dictionary. The stack notation for all logical qFORTH words is: EXP ( n1 n2 -- n3 ) 3.11.1 Logical Operators The truth table shown below is the standard table NOT OR AND XOR n1 n1' n1 n2 n1 v n2 n1 n2 n1 ^ n2 n1 n2 n1 XOR n2 1 0 0 0 0 0 0 0 0 0 0 0 1 0 1 1 0 1 0 0 1 1 1 0 1 1 0 0 1 0 1 1 1 1 1 1 1 1 1 0 03.01 51 MARC4 Programmer's Guide Programming in qFORTH As an example, examine the logical AND operation with the data values 3 and 5. Representing these values in 4-bit binary, and performing the AND operator: 0101b 0011b AND ( -- 0101b 0011b ( 0101b 0011b -- 0001b ) ) results in a value of 1 appearing on the TOS. The Branch flag will be reset, since the result of the logical operation is non-zero. value located at the specified memory location will be exclusive-ORed. Example: VARIABLE LED_Status : Toggle-LED 0001b LED_Status TOGGLE ( toggles bit 0 only ) ; SHIFT and ROTATE Operations Example: : Logicals 3 7 OR 3 7 AND 5 XOR NOT 2DROP ; ( -- 7 ) ( 7 -- 7 3 ) ( 7 3 -- 7 6 ) ( 7 6 -- 7 9 ) ( 7 9 -- ) TOGGLE The TOGGLE operation is classified in the qFORTH Language Reference Dictionary as belonging to the set of memory operations. Although this is true, the TOGGLE and its relative, the DTOGGLE, are both used to change bit patterns at a specified memory address. For the TOGGLE operation the 4-bit Mnemonic SHR 2/ The MARC4 instruction set contains two shift and two rotate instructions which are shown in figure 2.8. The shift operators multiply (SHL) and divide (SHR) the TOS value by two. These instructions are identical to the qFORTH macros for 2* and 2/. The rotate instructions ROR and ROL shift the TOS value right/left through the Carry flag, and cause will the Carry and Branch flags to be altered. When using these instructions, it is advisable to set or reset the flags within your initialization routine, using either the SET_BCF or the CLR_BCF instructions. Description Shift TOS right into carry Function 3 2 1 0 0 C 3 2 1 0 ROR Rotate TOS right through carry SHL 2* Shift TOS left into carry C ROL Rotate TOS left through carry C C 0 Figure 8. Shift and rotate instructions 52 03.01 MARC4 Programmer's Guide Programming in qFORTH Example: Write the necessary qFORTH word definitions to flip a data byte (located on TOS) as shown below: Before flip: 3 2 1 0 After flip: 7 6 5 4 : FlipBits 0 4 #DO SWAP SHR SWAP ROL #LOOP NIP ; : FlipByte FlipBits SWAP 4 5 6 7 0 1 2 3 : GREATER-EQUAL 9 >= FlipBits ; 3.12 Comparisons The qFORTH comparison operations (such as > or <) will set the Branch flag in the CCR if the result of the comparison is true. The stack effects of a comparison operation is: EXP ( n1 n2 -- ) 3.12.1 <,> The qFORTH word < performs a 'less-than' comparison of the top two values on the stack. If the second value on the Expression Stack is less than the value on the TOS, then the Branch flag in the CCR will be set. Following the operation, the stack will contain neither of the two values which where checked, as they will be dropped from the Expression Stack. : Less-Example 9 5 < ; ( -- 9 5 ) ( 9 5 -- ) The > comparison operator determines if the second value on the stack is greater than the TOS value. If this condition is met, then the Branch flag will be set in the CCR. 3.12.2 <= , >= Using <= in your qFORTH program enables you to determine if the second item on the stack is less or equal to the TOS value. 03.01 In the GREATER-EQUAL example, the top two stack values 5 and 9 are removed from the stack and used as input values for the greater-or-equal operation. If the second value (TOS-1) is greater or equal the TOS value and subsequently the branch flag in the CCR will be set. After the comparison operation has been performed by the MARC4 processor, neither of the two input values will be contained on the Expression Stack. 3.12.3 5 ( -- 9 5 ) ; ( 9 5 -- [C-B-] ) <> , = These two qFORTH comparison operators can be used to determine the Boolean (true/false) value (e.g. setting/ resetting the Branch flag in the CCR). If the second value on the stack is not equal ( <> ) to the TOS value, then the Branch flag in the CCR will be set. The two values that were on the TOS before the operation, are dropped off the stack after the operation has been executed, except if one or both items on the Data Stack were duplicated before the operation. If, however, the equality test (=) is executed then the Branch flag will only be set, if both the TOS and the TOS-1 values are identical. Again, as with all the comparison operations presented so far, the contents of the TOS and TOS-1 previous to the operations are dropped from the stack. 3.12.4 Comparisons Using 8-bit Values Example: 68 2CONSTANT PAR-FOR-COURSE 2VARIABLE GROSS-SCORE : Check-golf-score GROSS-SCORE2@PAR-FOR-COURSE D0 8 D<= IF GOOD-SCORE THEN \ My Handicap is 8 ; Note: There is a space between the 0 and 8. This is required because literals less then 16 are assumed to be 4-bit values. 53 MARC4 Programmer's Guide Programming in qFORTH This problem may be improved if an additional 2CONSTANT is used, since 2CONSTANT assumes an 8-bit value, e.g. : 8 2CONSTANT My-Handicap : Check-Golf-score GROSS-SCORE2@PAR-FOR-COURSE DMy-Handicap D<= IF GOOD-SCORE THEN ; 3.13 Control Structures The control structures presented here can be divided into two categories: Selection and looping. The tables 3 and 4 compare qFORTH's control structures will those found in PASCAL. As the comparison of the two languages shows, qFORTH offers a rich variety of structures which enable your program to branch to different code segments within the program. Table 3. qFORTH selection control structures qFORTH <condition> IF <operation> THEN <condition> IF <operations> ELSE <operations> THEN <value> CASE .. <n> OF <operations> ENDOF .. ENDCASE PASCAL IF <condition> THEN <statements> ; IF <condition> THEN <statements> ELSE <statements> ; CASE <value> .. <n> OF <statements> ; .. END ; Table 4. qFORTH loop control structures qFORTH BEGIN <operations> <condition> UNTIL BEGIN <condition> WHILE <operations> REPEAT BEGIN <operations> AGAINb <limit> <start> DO <operations> LOOP <limit> <start> DO <operations> <offset> + LOOP <limit> <start> DO <operations> <condition> ?LEAVE <operations> LOOP <n-times> #DO <operations> #LOOP 54 PASCAL REPEAT <statements> UNTIL <condition> ; WHILE <condition> DO <statements> ; FOR i := <start> TO <limit> DO <statements> ; FOR i := <start> DOWNTO 0 DO <statements> ; 03.01 MARC4 Programmer's Guide Programming in qFORTH 3.13.1 Selection Control Structures The code to be executed is dependent on a specific condition. This condition can be indicated by setting the Branch flag in the CCR. The control operation sequences such as the IF .. THEN and the indefinite loop operations such as BEGIN .. UNTIL and BEGIN .. WHILE .. REPEAT will only be executed if the Branch flag has been set. IF .. THEN The IF .. THEN construct is a conditional phrase permitting the sequence of program statements to be executed dependent on the IF condition being valid. The qFORTH implementation of the IF .. THEN phrase requires that the <condition> computation appears before the IF word. IF .. THEN in PASCAL : IF <condition> THEN < True statements> ELSE <False statements> ; IF .. THEN in qFORTH : First the current TOS value is duplicated. Then, 9 is deposited onto the TOS so that the value to be compared to is now in the TOS-1 and TOS-2 location of our data stack. The TOS value is now compared with the TOS-1 value. IF TOS-1 is greater than 9, then the condition has been met. The qFORTH words following the IF will therefore be executed. In the first example the TOS value will be dropped and replaced by the value 1. The CASE Structure The CASE structure is equivalent to the IF .. ELSE .. THEN structure. The IF .. ELSE .. THEN permits nested combinations to be constructed in qFORTH. A nested IF .. ELSE .. THEN structure can look like this example: : 2BIT-TEST DUP 0 = DUP 1 = DUP 2 = BIT0OFF ELSE BIT0ON ELSE BIT1OFF ELSE BIT1ON THEN THEN THEN THEN <condition> IF <True operations> ELSE <False operations> THEN IF IF IF DROP ; Example: : ) GREATER-9 DUP (n -- n or 1, IF n > 9 9 > IF DROP 1 (THEN replace n -- 1 ) THEN (ELSE keep original n ) ; : $RESET >SP S0 (Power-on initialization entry) >RP FCh (Init both stack pointers first ) 10 Greater-9(Compare 10 > 9 ==> BF true ) 5 Greater-9(1 5 -- 1 5 ) 2DROP (1 5 -- ) ; The qFORTH word GREATER-9 checks if the values given on TOS as a parameter to the word are greater than 9. 03.01 In the word `2BIT-TEST', the TOS is checked to see if it contains one of three possible values. If either one of these three values is on the TOS, then the desired word definition will be executed. If none of these three conditions has been met, then a fourth word BIT1ON will be executed. Re-writing the `2BIT-TEST' word using the CASE .. ENDCASE structure results in a qFORTH code which is more readable and thus easier to understand: : 2BIT-CASE CASE 0 OF 1 OF 2 OF BIT0OFF BIT0ON BIT1OFF BIT1ON ENDOF ENDOF ENDOF ENDCASE ; 55 MARC4 Programmer's Guide Programming in qFORTH The CASE selectors are not limited to constants ( e.g. high-score @). 15 CONSTANT TILT : PIN-BALL CASE 0 OF HIGH-SCORE @ OF TILT OF ( ELSE ) ENDCASE ; ( BALL-CODE -- ) FREE-BALL ENDOF REPLAY ENDOF GAME-OVER ENDOF UPDATE-SCORE Note: Unlike Pascal, the case compares the index to the loop's limit to determine whether the loop should terminate or continue. In addition to the FORTH-83 looping construct, the MARC4 has special hardware support for the qFORTH #DO .. #LOOP. As a result of this, the #DO..#LOOP is the most code and speed efficient definite loop and is recommended for most loop constructs. Example: 5 #DO HELLO-WORLD #LOOP The DO .. LOOP control structure is an example of a definite loop. The number of times the loop is executed by the MARC4 must be specified by the qFORTH programmer. In this example, the loop control variable is set to 5, then decremented at the end of each iteration until 0. Hence, 5 #DO .. #LOOP will loop 5 times. #LOOPS may also be nested (to any depth). The outer loop control variable is called J when used inside the inner loop. Example: Example: 3.13.2 Loops, Branches and Labels Definite Loops : DO-Example 12 5 ( -- Ch 5 ) DO ( Ch 5 -- ) I 1 OUT ( Copy loop-index I onto TOS ) LOOP ( Write "5 6 7 8 9 Ah Bh" to port1 ) ; Here, the loop index I starts at the value 5 and is incremented until the value 12 is reached. This is an example where we have defined a definite looping range (from 5 to 11) for the statements between the DO and the LOOP to be repeated. On each iteration of a DO loop, the LOOP operator will increment the loop index. It then 56 : NESTED-LOOPS 7 #DO \ OUTER LOOP 5 #DO \ INNER LOOP IJ+ Port0 OUT #LOOP #LOOP ; Care should be taken when using loops to compute multi-nibble arithmetic (e.g. 16-bit shift right). This is because the standard FORTH-83 definite loops change the Carry flag after each iteration of the loop. In such cases, the #DO .. #LOOP is recommended since the Carry flag is not affected. 03.01 MARC4 Programmer's Guide Programming in qFORTH ?DO .. ?LEAVE LOOP, ( limit start -- ) (--) (--) IF start = limit THEN skip the loop exit loop if the Branch flag is true increment loop-index by 1 DO .. -?LEAVE LOOP ( limit start -- ) (--) (--) Init iterative DO..LOOP if Branch flag is false, then exit loop increment loop-index by 1 ?DO .. LOOP ( limit start -- ) (--) IF start = limit THEN skip the loop DO .. +LOOP ( limit start -- ) (n--) Iterative loop with steps by <n> increment loop-index by n #DO .. #LOOP (n--) (--) Execute #LOOP block n-times decrement loop-index until n = 0 Indefinite Loops BEGIN indicates the start of an indefinite loop-control structure. The sequence of words which are to be performed by the MARC4 processor will be repeated until a conditional repeat construct (such as UNTIL or WHILE .. REPEAT) is found. Write a counter value from 3 to 9 to Port 1, then finish the loop. The second conditional loops control structure BEGIN .. WHILE .. REPEAT repeats a sequence of qFORTH words as long as a condition (computed between BEGIN and WHILE) is still being met. qFORTH also provides an infinite loop sequence, the BEGIN .. AGAIN which can only be escaped by EXIT, -?LEAVE or ?LEAVE. Example: : UNTIL-Example 3 BEGIN DUP Port1 1+ DUP UNTIL DROP 9 OUT ( Write the current value to Port 1 ) ( Increment the TOS value 3 .. 9 ) > ( DUPlicate the current value .. ) ( the comparison will DROP it ) ( skip counter value from stack ) Example: : BinBCD Fh <ROT BEGIN OVER 0<> WHILE \ High order is zero 10 M- ROT 1- <ROT REPEAT \ Count 10th DUP 10 >= IF 10 - ROT 1- <ROT THEN NIP SWAP NOT SWAP ; The encapsulated BEGIN .. UNTIL loop block is then executed until the Branch flag is set (TRUE). The Branch flag is set when the desired condition (TOS > 9) is met. 03.01 \ Converts binary to 2 digit BCD ( d [<99] -- Dhi Dlo ) \ 1's comp of '0' ; 57 MARC4 Programmer's Guide Programming in qFORTH qFORTH - Indefinite Loops BEGIN <Condition> WHILE ... REPEAT Condition tested at start of loop BEGIN ... <Condition> UNTIL Condition tested at end of loop BEGIN ... AGAIN Unconditional loop 3.13.3 Branches and Labels While not recommended in normal programming, branches and labels have been included in qFORTH for completeness. Labels have the following format: <Label>: <instruction> | <Word> : NEXT-LIFE WAS-BAD? BRA HELL HEAVEN: TRA-LA-LA NOP SET_BCF BRA HEAVEN HELL: TEMPERATURE 1+! WORK SET_BCF BRA HELL ; The `NEXT-LIFE' word can also be written with high-level constructs as: : NEXT-LIFE WAS-BAD? TOG_BF IF BEGIN TRA-LA-LA NOP AGAIN ELSE BEGIN Temperature 1+! WORK AGAIN THEN ;; \ HEAVEN \ HELL Note: There is no space allowed between the label and the colon. 3.13.4 Example: INDEX is a predefined qFORTH word used to access array locations. The compiler translates INDEX into a run-time code definition, specific for the type of array being used (2ARRAY, LARRAY, etc.) Initializing and Erasing an Array My_Labl1: Only conditional branches are allowed in qFORTH, i.e., the branch will be taken if the Branch flag is set. If unconditional branches are required, then care must be taken to set the Branch flag before branching. Example: SET_BCF BRA My_Labl1 Note: The scope of labels is only within a colon definition. It is not possible to branch outside a colon definition. Example: VARIABLE SINS VARIABLE TEMPERATURE : WAS-BAD? SINS @ 3 >= ; 58 Arrays and Look-up Tables Array Indexing By using the qFORTH word ERASE, it is possible to erase an array's content to be filled with zeros. Array Filling A third way to initialize an array is using the word FILL. FILL requires that the beginning address of the array and the size of the array are placed onto the stack, followed by the value to be filled. : FillArray Y! DUP [Y]! SWAP 1- #DO DUP [+Y]! #LOOP DROP ; ( count n addr -- ) ( count n addr -- count n ) ( count n -- n count-1 ) 03.01 MARC4 Programmer's Guide Programming in qFORTH <> ?LEAVE 1- Looping in an Array The qFORTH words contained between the DO and LOOP words are repeated between the start element and the limit element. The element first deposited onto the stack will be decremented following the store instruction. Moving Arrays The words MOVE and MOVE> copy a specified number of digits from one address to another within the RAM. The difference between the two instructions is that MOVE copies the specified number of digits starting from the lowest address, while MOVE> starts from the highest address. : C-MOVE ( n Source Dest -- ) Y! X! [X]@ [Y]! BEGIN 1- TOG_BF WHILE [+X]@ [+Y]! REPEAT DROP ; Comparing Arrays The word '?Arrays=' compares two array fields, starting at the last field element in desending addresses. The maximum length permitted is 16 elements. The result, if the arrays are equal or not, is stored in the Branch flag. : ?Arrays= (n Array1[n] Array2[n] -- [BF=1, if equal]) X! Y! 0 SWAP #DO [X-]@ [Y-]@ - OR #LOOP 0= ; Another way of implementing the array-comparison function is to use the BEGIN .. UNTIL loop as shown below. : ?Arrays= (n Array1[n] Array2[n] -- [BF=1, if equal]) X! Y! BEGIN ( n is decremented in loop ) [Y-]@[X-]@ 03.01 UNTIL DROP TOG_BF ; Array examples are included in the qFORTH Language Reference Dictionary. 3.13.5 Look-up Tables Look-up tables are implemented in most microprocessors to hold data which can be easily accessed by means of an offset. qFORTH supports tables with the instructions: ROMCONST, ROMByte@, DTABLE@ and TABLE ;; . These instructions are described in the qFORTH Language Reference Dictionary. The basic principle of MARC4 tables is that the data to be referenced is placed into a contiguous ROM memory during compile time when defined as a ROMCONST. The ROMByte@ word fetches an 8-bit constant from ROM defined by the 12-bit ROM address which is on the top of the Expression Stack. The DTABLE@ word permits the user to access a particular 8-bit constant from the array via the array's address value and the 4-bit offset. In the program file `INCDATE.INC', found on the applications disk, the days of the month are placed into a look-up table called `DaysOfMonth'. The month is used to access the table in order to return the number of days in the month. 3.13.6 TICK and EXECUTE The word ' (pronounced TICK, represented in FORTH by the apostrophe symbol) locates a word definition in memory and returns its ROM address. EXECUTE takes the ROM address (located on the Expression Stack) of a colon definition and executes the word. TICK is useful for performing a vectored execution where a word definition is executed indirectly, this can be performed by 59 MARC4 Programmer's Guide Programming in qFORTH placing the address of a definition into a variable. The content of the variable is then EXECUTEd as desired. This gives the user increased flexibility as complicated pointer manipulations now be performed. Example: CODE BCD_+1! [Y]@ 1 + DAA [Y-]! END-CODE : Inc_Hrs Time [Hrs_1] Y! BCD_+1! IF Time [Hrs_10] 1+! THEN Time [Hrs_10] 2@ 2 4 D= IF 0 0 Time [Hrs_10] 2! THEN ; : Inc_Hour LAP_Timer [Hours] 1+! ; : Inc_Min BCD_+1! IF [Y]@ 1+ 6 CMP_EQ [Y]! IF 0 [Y-]! Hours_Inc 3@ EXECUTE [E0R0] THEN THEN ; : Inc_Secs BCD_+1! IF [Y]@ 1+ 6 CMP_EQ [Y]! IF 0 [Y-]! Inc_Min THEN THEN ; : Inc_1/100s BCD_+1! IF BCD_+1! IF Inc_Secs \ <Y> = ^Digit ----<Y-1> \ Incr. BCD digit in RAM \ x9:59 -> x+1 0:00 \ 0 -> 1 or 1 -> 2 \ 24:00:00 \ 23:59 -> 00.00 \ It's midnight ? \ Inc Hours binary by 1 \ Wrap around at 16:00.00 \ <Y> = ^Digit[Min_1] \ 18:29 -> 18:30 \ On overflow .. \ 18:59 -> 19:00 \ Reset Min_10 \ Computed Hrs_Inc ' \ <Y> = ^Digit[Sec_1] \ Increment seconds \ 8:25:19 -> 8:25:20 \ 8:30:59 -> 8:31:00 \ Reset Sec_10 \ Incr. Minutes \ Increment 10_ms \ 25.19.94 -> 25.19.95 \ Incr. 100_ms \ 30.49.99 -> 30.50.00 \ Incr. seconds .. THEN THEN ; : 60 IncTime ' Inc_Hrs Hours_Inc [2] 3! Time [Sec_1] Y! Inc_Secs \ Incr. T.O.D. \ Note use of Tick \ Increment seconds 03.01 MARC4 Programmer's Guide Programming in qFORTH ; : Inc_10ms ' Inc_Hour Hours_Inc [2] 3! LAP_Timer [10_ms] Y! Inc_1/100s \ Incr. LAP timer \ Note use of TICK \ Increment 1/100 sec ; \ Excerpts of program 'TEST_05' 9 6 7 3 2 which includes TICKTIME CONSTANT Seed ARRAY Time ARRAY LAP_Timer ARRAY Hours_Inc ARRAY C_INT6 VARIABLE RandomUpdate VARIABLE LAP_Mode VARIABLE TimeCount \ Random display update \ Current Time Of Day \ Stop Watch time \ Dest. of computed GOTO \ INT6 counter \ LAP_Timer or T.O.D. display \ Count RTC interrupts $INCLUDE LCD_3to1 $INCLUDE TickTime : StopWatch C_INT6 [1] D-1! IF 26 C_INT6 2! Inc_10ms RandomUpdate 1-! IF Seed RandomUpdate ! LAP_Timer [1] Show6Digits THEN THEN ; : INT5 1 TimeCount TOGGLE IF DI IncTime EI \ Real-Time Clock Interrupt every 1/2s THEN \ Be on the save side ; : INT6 LAP_Mode @ 0= IF StopWatch \Stop Watch Interrupt every 244.1 usec THEN ; : $RESET >SP S0 >RP Vars_Init ( etc. ); 03.01 FCh \ Init stack pointers first \ Setup arrays and prescaler 61 MARC4 Programmer's Guide Programming in qFORTH 3.14 Making the Best Use of Compiler Directives Compiler directives allow the programmer to have direct manual control of the generation and placement of program code and RAM variables. The qFORTH compiler will automatically generate an efficient code, so it is not necessary or recommended to manually optimize the application program at the beginning of the project. However, when the first version of the application is completed, the following compiler directives can be used to "fine tune" the program. Clearly `CODE' definitions have no implied EXIT (or subroutine return) on termination. Occasionally, a colon definition does not require an EXIT on termination. If this is the case, the `;;' statement is used instead of the `;'. Examples: 07 2CONSTANT Duff-Value nCODE : A complete list of all compiler directives may be found in the documentation shipped with the qFORTH2 compiler release disk. Must-be-fast X! [X]@ Correlate-Temperature Read-Temperature 2DUP Duff-Value D= 2DROP EXIT THEN Do-Correlation 3.14.1 Controlling ROM Placement By forcing a zero page placement of the most commonly used words, a single byte short call will be used to access the word, hence saving a byte per call. Examples: : Called-a-lot SWAP DUP [ Z ] ; \ Place anywhere in zero page : Once-in-a-blue-moon Init-RAM [ N ] ; \ Don't place in zero Page : Very-Small-Word 3>R DUP 3R@ ; AT 23h \ Place in 5 byte hole between zero page words ; : \ Since this loop \ never terminates, \ then we can save the EXIT Controlling Stack Side Effects The qFORTH compiler attempts to calculate the stack effects of each word. Sometimes, this is not possible, hence the two directives [ E <number> R <number> ] allow the programmer to manually set stack effects of the Expression and the Return Stack. Examples: : I-know-what-I'm-doing : Get_Numbers Flag 3.14.2 ( -- Th Tl ) IF \ Make a quick exit if \ duff data read in \ Note use of EXIT ( Th Tl -- ) HALT BEGIN AGAIN ;; 3.14.3 1+ [X-]! END-CODE @ 5 IF Macro Definitions, EXIT and ;; = BEGIN DUP 1UNTIL [ E 0 ] ; \ Depending on the value of Flag \ the IF .. ELSE .. THEN block will have \ a stack effect of +4 or +3. If fast execution is required, critical words may be invoked as macros and expanded `in-line'. In general, macros are identical in syntax to word definitions, except the colon and semicolon which are replaced by CODE .. END-CODE. 62 1 2 3 4 ELSE 1 2 3 [ E4 ] THEN ; 03.01 MARC4 Programmer's Guide Programming in qFORTH 3.14.4 $INCLUDE Directive It is common programming practice to split a large program into a number of smaller modules, i.e, one file per module. qFORTH allows the programmer to do this with the $INCLUDE <filename[.INC]> directive. This directs the compiler to temporarily take the input source from another file. Include-files may be nested up to a maximum level of four. Example: $INCLUDE Lcd-Words : ; $DEFINE Emulation \ Use EVA prescaler $IFDEF Emulation Eh CONSTANT Prescaler_2 Ch CONSTANT 4_KHz $ELSE Fh CONSTANT Prescaler_2 Dh CONSTANT 4_KHz $ENDIF $IFDEF Emulation : INT4 process ; $ELSE : INT6 process ; $ENDIF \ include the LCD "tool box" Update_LCD Colon-State @ Blink-Colon? 3.14.6 ; 3.14.5 Conditional Compilation Conditional compilation enables the programmer to control which parts of the program are to be compiled. A typical program under development for example has an extra code to aid debugging. This code is removed on the final version. By using a conditional compilation, the programmer can keep all the debugging information in the source, but generate the code only for the application simply by commenting out the $DEFINE DEBUG directive. Examples: $DEFINE Debug \ IF this directive is \ commented out \ THEN no debugging \ code is generated : INT2 $IFDEF Debug CPU-Status Port6 $ENDIF Process-Int2 03.01 Controlling XY Register Optimizations The X/Y optimize qualifiers of the qFORTH compiler help to control the depth of desired optimization steps. D XYLOAD the sequence LIT_p .. LIT_q X! is optimized to: >X $pq D XY@! the sequence >X $pq [X]! is optimized to [>X]! $pq D XYTRACE reloading the x or Y register (i.e., sequences of >X $pq will be replaced by [+X]@ or [Y-]! operations whenever possible. The qFORTH compiler keeps track of which variable is cached in the x and Y registers inside a colon definition. Example: The variables 'On_Time' and 'SwitchNr' are stored in consecutive RAM locations. OUT 63 MARC4 Programmer's Guide Programming in qFORTH qFORTH Source Intermediate Code XYLOAD, XY@! Optimized Final Code after XYTRACE On_Time @ LIT_3 LIT_4 [>X]@ $On_Time [>X]@ $On_Time SwitchNr +! X! [X]@ [>Y]@ $SwitchNr [+X]@ LIT_3 LIT_5 ADD ADD Y! [Y]@ [Y]! [X]! 6 Bytes 5 Bytes ADD [Y]! 10 Bytes 3.15 Recommended Naming Conventions 3.15.1 How to Pronounce the Symbols ! store @ fetch # sharp or "number" $ dollar % percent ^ caret & ampersand * star ( ) left paren and right paren ; paren - dash; not + plus = equals { } faces or "curly brackets" Form [] " ' ~ | \ / < > ? , . square brackets quote as prefix: Tick; as suffix: prime tilde bar backslash slash less-than; left dart greater-than; right dart question or "query" comma dot Example Meaning 1+ 2DUP +DRAW *DRAW integer 1 (4-bit) integer 2 (8-bit) takes relative input parameters takes scaled input parameters EMPLOYEES #EMPLOYEES EMPLOYEE# EMPLOYEE [13] +EMPLOYEE table or array total number of elements current item number (variable) sets current item advance to next element Arithmetic 1name 2name +name *name Data structures names #name name# ( n) name +name 64 03.01 MARC4 Programmer's Guide Programming in qFORTH name+ /name >name DATE+ /SIDE >IN size of offset to item from beginning of structure size of (elements "per") index pointer SLIDE< MOVE> <PORT4 >PORT0 FEET>METERS \LINE /LINE backwards forwards from to convert to downward upward SHORT? -SHORT? ?DUP ( maybe DUP) +CLOCK BLINKING -CLOCK -BLINKING return Boolean value returns reversed Boolean operates conditionally enable or, absence of symbol disable @CURSOR !CURSOR SECONDS! INDEX@ ' INC-MINUTE save value of restore value of store into fetch from address of name Direction, conversion name< name> <name >name name>name \name /name Logic, control name? -name? ?name +name name -name Memory @name !name name! name@ ' name Numeric types Dname D+ 2 cell size, 2's complement integer encoding Mname M* mixed 4 and 8-bit operator Tname T* 3 cell size Qname Q* 4 cell size These naming conventions are based on a proposal given by Leo Brodie in his book 'Thinking FORTH'. 03.01 65 MARC4 Programmer's Guide Programming in qFORTH 3.16 Literature List 3.16.1 Recommended Literature "Starting Forth" is highly recommended as a good general introduction to FORTH, especially chapters 1 to 6. "Starting FORTH" is now also available in German, French, Dutch, Japanese and Chinese. "Thinking FORTH" is the follow-on book to "Starting FORTH" and discusses more advanced topics, such as system-level programming. "Complete FORTH" has been acknowledged as the definitive FORTH text book. Title: "Starting FORTH" (2nd edition) Author: Leo Brodie Publisher: Prentice Hall, 1987 ISBN: 0-13-843079-9 Title: Author: Publisher: ISBN: Title: Author: Publisher: ISBN: Title: Author: Publisher: 3.16.2 "Programmieren in FORTH" (German Version) Leo Brodie Hanser, 1984 3-446-14070-0 "Thinking FORTH" Leo Brodie Prentice Hall, 1984 0-13-917568-7 "Complete FORTH" Winfield Sigma Technical Press, 1983 Literature of General Interest The following list shows the spectrum of FORTH literature. This literature is of background interest ONLY and may contain information which is not completely relevant for programming in qFORTH on the MARC4. Title: Author: Publisher: ISBN: "Mastering FORTH" Leo Brodie Brady Publishing, 1989 0-13-559957-1 Title: "Dr. Dobbs Tool-Box of FORTH Vol. II", Publisher: M&T Books, 1987 ISBN: 0-934375-41-0 Title: "FORTH" (Byte Magazine) Author: L. Topin Publisher: McGraw Hill, 1985 66 03.01 MARC4 Programmer's Guide Programming in qFORTH Title: Authors: "The use of FORTH in process control" Proc. of the International '77 Mini-Micro Computer Conference, Geneva; Moore & Rather, Publisher: I PC and Technology Press, England, 1977 Title: "FORTH: A cost saving approach to Software Development" Author : Hicks Publisher: Wescon/Los Angeles, 1978 Title: "FORTH's Forte is Tighter Programming" Author: Hicks Publisher: Electronics (Magazine), March 1979 Title: Authors: Publisher: ISBN: 03.01 "FORTH a text and reference" Kelly & Spier Prentice Hall, 1986 0-13-326331-2 67 I. Hardware Description II. Instruction Set III. Programming in qFORTH IV. qFORTH Language Dictionary V. Addresses MARC4 Programmer's Guide qFORTH Dictionary 4 4.1 qFORTH Dictionary Preface This dictionary is written as a reference guide for programmers of the MARC4 microcontroller family. The qFORTH DICTIONARY categorizes each qFORTH word and MARC4 assembler instruction according to its function (PURPOSE), category, stack effects and changes to the stack(s) by the instruction. The affected condition code flags, X and Y register changes are also described in detail. The length of each instruction is specified by the number of bytes generated at compile time. A short demonstration program for each instruction is also included. The language qFORTH is described in the section III "Programming in qFORTH" which includes a language tutorial and learner's guide. First-time programmers of qFORTH are urged to read this chapter before consulting this guide. The associated effects and changes of the listed qFORTH word are described in this reference guide. The entries are sorted in alphabetical order. You can find a reference in the index for unused MARC4 assembler mnemonics. 03.01 71 MARC4 Programmer's Guide qFORTH Dictionary 4.2 Introduction Every entry in this dictionary is listed on a separate page. The page structure for every entry contains the following topics: 1. "Purpose:" This section gives a short explanation of each qFORTH vocabulary entry and explains its operational function. 2. "Category:" A classification of the qFORTH vocabulary entries is given. All entries in this dictionary are classified in the following categories (same categories are used in the `MARC4 qFORTH Quick Reference Guide'): A: Usage-specific categories: Arithmetic/logical Arithmetic (`+', `-' ... ), logical operations (`AND',`OR') and bit manipulations ('ROR' ..) on 4-bit or 8-bit values. Comparisons Comparison operations on either single- or double-length values resulting in the Branch condition flag being set to determine the program flow (`>', `>=', ... ). Control structures Control structures are used for conditional branches such as IF ... ELSE ... THEN and loops (DO ... LOOP). Interrupt handling The MARC4 instruction set allows the programmer to handle up to 8 hardware/software interrupts and to enable/disable all interrupts. Other qFORTH words permit the programmer to determine the actually used depth or available free space on the Expression and Return Stack. Memory operations Read, modify and store single-, double- or multiple-length values in memory (RAM). Stack operations The sequence of the items and the number or the value of items held on the stack may be modified by stack operations. Stack operations may be of single-, double- or triple(12-bit)-length (`SWAP', ... ). 72 03.01 MARC4 Programmer's Guide qFORTH Dictionary B: Language-specific categories: Assembler instructions qFORTH programs may contain MARC4 native code instructions; all qFORTH words consist of assembler and/or qFORTH colon definitions and/or qFORTH macros. qFORTH colon definitions All qFORTH colon definitions begin with a `:' and end with a `;'. They are processed like subroutines in other high-level languages; that means, that they are "called" with a short (1) or long CALL (2 bytes) at execution time. The `;' is translated to an EXIT instruction (return from subroutine). At execution time, the program counter is loaded with the calling address from the Return Stack. Colon definitions can be "called" from various program locations as opposed to qFORTH macros which are placed "in-line" by the compiler at each "calling" address. qFORTH macro definitions All qFORTH macros begin with a `CODE' and end with an `END-CODE'. The compiler replaces the macro definition by an in-line code. Predefined data structures Predefined data structures do not use any ROM-bytes (except ROM look-up tables). They are used for defining constants, variables or arrays in the RAM. With `AT', you can force the compiler to place a qFORTH word at a specific address in the ROM or a variable at a specific address in the RAM. Compiler directives Compiler directives are used to include other source files at compile time, to define RAM or ROM sizes for the target device or to control the RAM or ROM placement (p.e. $INCLUDE, $RAMSIZE, $ROMSIZE). Most entries belong to a usage-specific and a language-specific category, i.e. `+' belongs to the category arithmetic/logical and to the category assembler instructions; `VARIABLE' belongs only to the category predefined data structures. 3. "Library implementation" For qFORTH words which are not MARC4 assembler instructions, the assembly level implementation is included in the description. Refer to the library items "CODE" / "END-CODE" and ":" / ";" for improved understanding of this representation. These items will help when simulating/emulating the generated code with the simulator/emulator or when optimizing your program for ROM length. The MARC4 native code is written in the dictionary for MARC4 assembler instructions. The assembler mnemonic `(S)BRA' means that the compiler tries to optimize all BRA mnemonics to SBRA (short branches only one byte) if the option is switched on and optimization is possible (page boundaries can not be crossed by the SBRA, but only by the BRA). 03.01 73 MARC4 Programmer's Guide qFORTH Dictionary 4. "Stack effect" This category describes the effects on the Expression and Return Stack when executing the described instruction. See `stack-related conventions' to better understand the herein used syntax and semantics. 5. "Stack changes" These lines include the number of elements which will be popped from or pushed onto the stacks when executing the instruction. 6. "Flags" The "flags" part of each entry describes the flag effect of the instruction. 7. "X Y registers" In this part, the effect on the X and Y registers is described. This is only important if the X or Y registers are explicitly referenced. Note: The compiler optimizer changes the used code inside of colon definitions through the X/Y-register-tracking technique. Attention: The X register can be replaced in qFORTH macros by the Y register and vice versa (see the explanation of the optimizer in the qFORTH compiler user's guide)! 8. "Bytes used" This part gives the number of bytes used in the MARC4 ROM by the qFORTH colon definition, the qFORTH macro or by the assembler instruction. Note: The optimizer of the compiler may shorten the actual program module. 9. "See also" This section includes similar qFORTH words or words of the same category. The '%'symbol in this field signifies that there are no similar words for this entry. 10. "Example" An example for using the described qFORTH word is given in this section. All examples are tested and may be demonstrated with the MARC4 software development system. 74 03.01 MARC4 Programmer's Guide qFORTH Dictionary 4.3 Stack-Related Conventions Expression Stack The Expression Stack contains the program parameters. This stack is refered to as either the "EXP Stack" or just "EXP", "data stack" or just "stack". 4-, 8- and 12-bit data elements are placed onto the stack with the least significant nibble on top. Return Stack The Return Stack contains the subroutine return addresses as well as the loop indices and is also used to temporarily unload parameters from the Expression Stack. This stack is refered to as either the "RET stack" or just "RET". X/Y-registers The two general-purpose 8-bit registers X and Y permit direct and indirect access ( with additional pre-increment or post-decrement addressing modes) to all RAM cells. Stack notation addr n byte d hml t flags 8-bit memory address 4-bit value (nibble single length) 8-bit value (represented as a double nibble) 8-bit unsigned integer (double length) 'higher middle lower' nibble of a 12-bit value. 12-bit memory/stack operation (triple length) the flags of the Condition Code Register The stack effects shown in the dictionary represent the stack content, separated by two dashes ( -- ), before and after execution of the instruction. The Top Of Stack (TOS) is always shown on the right. As an example, the SWAP and DUP instructions have the following Expression Stack effects: SWAP DUP 03.01 before: after the operation. | | V V EXP : ( n2 n1 -- n1 n2 ) EXP : ( n1 -- n1 n1 ) TOS (top of stack) 75 MARC4 Programmer's Guide qFORTH Dictionary A similar representation specifying the stack effect of an instruction, shows the stack contents after execution. AAAAA AA A AAAA AAAAAA AA AAAA AAAAAA AA AAAA AAAAA AA AAAAA AAAAAA AA AAAA AAAAAA AA AAAA AAAAA AA AAAAA AAAAAA AA AAAA AAAAAA AA AAAA AAAAAAA AAAAA AAAAAA AA AAAA AAAAAA AAAAAA AAAAA AA AAAAA AAAAAA AA AAAA AAAAAA AA AAAA AAAAA AA AAAAA AAAAAA AA AAAA AAAAAA AA AAAA AAAAA AA AAAAA AAAAAA AA AAAA AAAAAA AA AAAA AAAAAAAAAAAA AAAAAA AAAAAAAAAAAA AAAA AA Expression Stack: 1 2 2 TOS SWAP 1 TOS DUP 1 Push two 1 Swap top 2 Duplicate 1 constants ? two elements ? top elements 2 . . . . . . TOS Return Stack notation: A Return Stack entry contains a maximum of 3 nibbles on each level (normally a 12-bit ROM address). If (e.g. in a DO..LOOP) only 2 nibbles of 3 possible nibbles are required there is 'u' for `undefined' or `don't care' used in the notation: 3 1 DO ( RET: -- u|limit|index ) or ( RET: -- u|3|1 ) 4.4 Flags and Condition Code Register There are three flags which interact with qFORTH instructions. Together with a fourth flag, which is reserved for Atmel Wireless & Microcontrollers, they are accessible via the 4-bit Condition Code Register - "CCR". A binary value 1 indicates that the corresponding flag has been set. A binary value 0 indicates a cleared flag. The order of the flags in the CCR is used in text as follows: Carry % Branch Interrupt enable 76 C % B I bit 3 bit 2 bit 1 bit 0 CARRY flag (MSB) (reserved) BRANCH flag I_ENABLE flag (LSB) 03.01 MARC4 Programmer's Guide qFORTH Dictionary 4.5 MARC4 Memory Addressing Model Memory Operations AAAAAAAA A AAAAAA AAAAA A AAAA AAA A AAA AA A AAAAA AAAA A AA A AAAAAAAA AAAAAA AAAA AAA AAAAA AA AAAAAA AAA AAAAA AAAAAAAA AAAA AAA AAA AA AAAAAAAA AAAAAA AAAA AAA AAA AAA AA AAAAAAAA AAAAAA AAAA AAA AAA AAA AA AAAAAAAA AAAAAA AAAA AAA AAA AAA AA AAAAAA AAA AAA AAAAAAAA AAAA AAA AA AAAAAAAA AAAAAA AAAA AAA AAA AAA AA AAAAAAAA AAAAAA AAAA AAA AAA AAA AA 4-bit variable address points to --> n <-- RAM 8-bit variable address points to --> nh nl 12-bit variable address points to --> nh nm nl nh = most significant nibble nl = least significant nibble See the entries 2/VARIABLE, 2/L/ARRAY and 2/3@ for further information. The following example shows, how to handle an 8-bit variable: 1 CONSTANT n_low 2VARIABLE KeyPressTime : Example 0 0 KeyPressTime 2! KeyPressTime 2@ 1 M+ IF DROP 1 THEN KeyPressTime 2! ; 03.01 ( constant and variable declaration ) ( 8-bit variable ) ( initialize this variable ( increment by 1 the 8-bit variable ( the lower nibble is on top of ( reset to 01h on overflow ( store the new 8-bit value back ) ) ) ) ) 77 MARC4 Programmer's Guide qFORTH Dictionary 4.6 4.6.1 The qFORTH Language - Quick Reference Guide Arithmetic/Logical + -C +C 1+ 12* 2/ D+ DD2/ D2* M+ MAND OR ROL ROR SHL SHR NEGATE DNEGATE NOT XOR 4.6.2 > < >= <= <> = 0<> 0= D> D< D>= D<= D= D<> D0<> D0= DMAX DMIN MAX MIN 78 EXP ( n1 n2 -- n1-n2 ) EXP ( n1 n2 -- n1+n2 ) EXP ( n1 n2 -- n1+/n+/C ) EXP ( n1 n2 -- n1+n2+C ) EXP ( n -- n+1 ) EXP ( n -- n-1 ) EXP ( n -- n*2 ) EXP ( n -- n DIV 2 ) EXP ( d1 d2 -- d1+d2 ) EXP ( d1 d2 -- d1-d2 ) EXP ( d -- d/2 ) EXP ( d -- d*2 ) EXP ( d1 n -- d2 ) EXP ( d1 n -- d2 ) EXP ( n1 n2 -- n1^n2 ) EXP ( n1 n2 -- n1 v n2 ) EXP ( -- ) EXP ( -- ) EXP ( n -- n*2 ) EXP ( n -- n/2 ) EXP ( n -- -n ) EXP ( d -- -d ) EXP ( n -- /n ) EXP ( n1 n2 -- n3 ) Subtract the top two nibbles Add up the two top 4-bit values 1's complement subtract with borrow Add with carry top two values Increment the top value by 1 Decrement the top value by 1 Multiply the top value by 2 Divide the 4-bit top value by 2 Add the top two 8-bit values Subtract the top two 8-bit values Divide the top 8-bit value by 2 Multiply the top 8-bit value by 2 Add a 4-bit to an 8-bit value Subtract 4-bit from an 8-bit value Bitwise AND of top two values Bitwise OR the top two values Rotate TOS left through carry Rotate TOS right through carry Shift TOS value left into carry Shift TOS value right into carry 2's complement the TOS value 2's complement top 8-bit value 1's complement of the top value Bitwise Ex-OR the top 2 values Comparisons EXP ( n1 n2 -- ) EXP ( n1 n2 -- ) EXP ( n1 n2 -- ) EXP ( n1 n2 -- ) EXP ( n1 n2 -- ) EXP ( n1 n2 -- ) EXP ( n -- ) EXP ( n -- ) EXP ( d1 d2 -- ) EXP ( d1 d2 -- ) EXP ( d1 d2 -- ) EXP ( d1 d2 -- ) EXP ( d1 d2 -- ) EXP ( d1 d2 -- ) EXP ( d -- ) EXP ( d -- ) EXP ( d1 d2 -- dMax ) EXP ( d1 d2 -- dMin ) EXP ( n1 n2 -- nMax ) EXP ( n1 n2 -- nMin ) If n1>n2, then branch flag set If n1<n2, then branch flag set If n1>=n2, then branch flag set If n1<=n2, then branch flag set If n1<>n2, then branch flag set If n1=n2, then branch flag set If n <>0, then branch flag set If n = 0, then branch flag set If d1>d2, then branch flag set If d1<d2, then branch flag set If d1>=d2, then branch flag set If d1<=d2, then branch flag set If d1=d2, then branch flag set If d1<>d2, then branch flag set If d <>0, then branch flag set If d =0, then branch flag set 8-bit maximum value of d1, d2 8-bit minimum value of d1, d2 4-bit maximum value of n1, n2 4-bit minimum value of n1, n2 03.01 MARC4 Programmer's Guide qFORTH Dictionary 4.6.3 Control Structures AGAIN BEGIN CASE DO ELSE ENDCASE ENDOF EXECUTE EXIT IF LOOP <n> OF REPEAT EXP ( -- ) EXP ( -- ) EXP ( n -- n ) EXP ( limit start -- ) RET ( -- u|limit|start ) EXP ( -- ) EXP ( n -- ) EXP ( n -- n ) EXP ( ROMAddr -- ) RET ( ROMAddr -- ) EXP ( -- ) EXP ( -- ) EXP ( c n -- ) EXP ( -- ) THEN UNTIL WHILE EXP ( -- ) EXP ( -- ) EXP ( -- ) +LOOP ?DO ?LEAVE -?LEAVE EXP ( n -- ) RET ( u|limit|I -- u|limit|I+n ) EXP ( n -- ) RET ( -- u|u|n ) EXP ( -- ) RET ( u|u|I--u|u|I-1 ) EXP ( Limit Start -- ) EXP ( -- ) EXP ( -- ) 4.6.4 Stack Operations 0 .. Fh, 0 .. 15 ' <name> EXP ( -- n ) EXP ( -- n ) EXP ( -- ROMAddr ) <ROT >R ?DUP DEPTH DROP DUP I J EXP ( n1 n2 n -- n n1 n2) EXP ( n -- ) RET ( -- u|u|n ) EXP ( n -- n n ) EXP ( -- n ) EXP ( n -- ) EXP ( n -- n n ) EXP ( -- I ) RET ( u|u|I -- u|u|I ) EXP ( -- J ) NIP OVER PICK RET ( u|u|J u|u|I -- u|u|J u|u|I ) EXP ( n1 n2 -- n2 ) EXP ( n1 n2 -- n1 n2 n1 ) EXP ( x -- n[x] ) #DO #LOOP RFREE R> R@ 03.01 EXP ( -- n ) EXP ( -- n ) RET ( u|u|n -- ) EXP ( -- n ) RET ( u|u|n -- u|u|n ) Ends an infinite loop BEGIN .. AGAIN BEGIN of most control structures Begin of CASE .. ENDCASE block Initializes an iterative DO..LOOP Executed when IF condition is false End of CASE..ENDCASE block End of <n> OF .. ENDOF block Execute word located at ROMAddr Unstructured EXIT from `:'-definition Conditional IF .. ELSE .. THEN block Repeat LOOP, if index+1<limit Execute CASE block, if n =c Unconditional branch to BEGIN of BEGIN .. WHILE REPEAT Closes an IF statement Branch to BEGIN, if condition is false Execute WHILE .. REPEAT block, if condition is true Repeat LOOP, if I+n < limit Execute the #DO .. #LOOP block n-times Decrement loop index by 1 downto zero if start=limit, skip LOOP block Exit any loop, if condition is true Exit any loop, if condition is false Push 4-bit literal on EXP stack Places ROM address of colon-definition <name> on EXP stack Move top value to 3rd stack position Move top value onto the Return Stack Duplicate top value, if n <>0 Get current Expression Stack depth Remove the top 4-bit value Duplicate the top 4-bit value Copy loop index I from Return to Expression Stack Fetch index value of outer loop [2nd Return Stack level entry] Drop second to top 4-bit value Copy 2nd over top 4-bit value Copy the x-th value from the Expression Stack onto TOS Get # of unused RET stack entries Move top 4-bits from return to Expression Stack Copy top 4-bits from return to Expression Stack 79 MARC4 Programmer's Guide qFORTH Dictionary ROLL ROT SWAP TUCK 2>R EXP ( n -- ) EXP ( n1 n2 n -- n2 n n1) EXP ( n1 n2 -- n2 n1 ) EXP ( n1 n2 -- n2 n1 n2 ) EXP ( n1 n2 -- ) RET ( -- u|n2|n1 ) EXP ( n1 n2 -- ) EXP ( d -- d d ) EXP ( d1 d2 -- d2 ) EXP ( d1 d2 -- d1 d2 d1 ) EXP ( d1 d2 d -- d d1 d2) EXP ( -- n1 n2 ) RET ( u|n2|n1 -- ) EXP ( -- n1 n2 ) RET ( u|n2|n1 -- u|n2|n1) EXP ( d1 d2 d -- d2 d d1) EXP ( d1 d2 -- d2 d1 ) EXP ( d1 d2 -- d2 d1 d2 ) EXP ( n1 n2 n3 -- ) RET ( -- n3|n2|n1 ) EXP ( n1 n2 n3 -- ) EXP ( t -- t t ) EXP ( -- n1 n2 n3 ) 2DROP 2DUP 2NIP 2OVER 2<ROT 2R> 2R@ 2ROT 2SWAP 2TUCK 3>R 3DROP 3DUP 3R> RET ( n3|n2|n1 -- ) EXP ( -- n1 n2 n3 ) RET ( n3|n2|n1 -- n3|n2|n1 ) 3R@ 4.6.5 Drop top 2 values from the stack Duplicate top 8-bit value Drop 2nd 8-bit value from stack Copy 2nd 8-bit value over top value Move top 8-bit value to 3rd pos'n Move top 8-bits from Return to Expression Stack Copy top 8-bits from return to Expression Stack Move 3rd 8-bit value to top value Exchange top two 8-bit values Tuck top 8-bits under 2nd byte Move top 3 nibbles from the Expression onto the Return Stack Remove top 3 nibbles from stack Duplicate top 12-bit value Move top 3 nibbles from Return to the Expression Stack Copy 3 nibbles (1 entry) from the Return to the Expression Stack Memory Operations ! @ +! 1+! 1-! 2! 2@ D+! D-! DTABLE@ DTOGGLE ERASE FILL MOVE ROMByte@ TOGGLE 3! 3@ T+! T-! TD+! TD-! 80 Move n-th value within stack to top Move 3rd stack value to top pos. Exchange top two values on stack Duplicate top value, move under second item Move top two values from Expression to Return Stack EXP ( n addr -- ) EXP ( addr -- n ) EXP ( n addr -- ) EXP ( addr -- ) EXP ( addr -- ) EXP ( d addr -- ) EXP ( addr -- d ) EXP ( d addr -- ) EXP ( d addr -- ) EXP ( ROMAddr n -- d ) EXP ( d addr -- ) EXP ( addr n -- ) EXP ( addr n n1 -- ) EXP ( n from to -- ) EXP ( ROMAddr -- d ) EXP ( n addr -- ) EXP ( nh nm nl addr -- ) EXP ( addr -- nh nm nl ) EXP ( nh nm nl addr -- ) EXP ( nh nm nl addr -- ) EXP ( d addr -- ) EXP ( d addr -- ) Store a 4-bit value in RAM Fetch a 4-bit value from RAM Add 4-bit value to RAM contents Increment a 4-bit value in RAM Decrement a 4-bit value in RAM Store an 8-bit value in RAM Fetch an 8-bit value from RAM Add 8-bit value to byte in RAM Subtract 8-bit value from a byte in RAM Indexed fetch of a ROM constant Exclusive-OR 8-bit value with byte in RAM Sets n memory cells to 0 Fill n memory cells with n1 Move an n-digit array in memory Fetch an 8-bit ROM constant Ex-OR value at address with n Store 12-bit value into a RAM array Fetch 12-bit value from RAM Add 12-bits to 3 RAM cells Subtract 12-bits from 3 nibble RAM array Add byte to a 3 nibble RAM array Subtract byte from 3 nibble array 03.01 MARC4 Programmer's Guide qFORTH Dictionary 4.6.6 Predefined Structures ( ccccccc) \ ccccccc : <name> ; [FIRST] [LAST] CODE END-CODE ARRAY 2ARRAY CONSTANT 2CONSTANT LARRAY 2LARRAY Index ROMCONST VARIABLE 2VARIABLE <n> ALLOT AT <address> : INTx : $AutoSleep : $RESET 4.6.7 EXP ( d -- ) EXP (n|d addr--addr') EXP ( -- ) EXP ( -- ) EXP ( -- ) RET ( -- ROMAddr ) EXP ( -- ) Assembler Mnemonics ADD ADDC CCR! CCR@ CMP_EQ CMP_GE CMP_GT CMP_LE CMP_LT CMP_NE CLR_BCF SET_BCF TOG_BF DAA DAS DEC DECR DI DROPR EXIT EI IN INC NOP 03.01 RET ( -- ) RET ( ROMAddr -- ) EXP ( -- 0 ) EXP ( -- n|d ) EXP ( -- ) EXP ( -- ) EXP ( n -- ) EXP ( n -- ) EXP ( n -- ) EXP ( d -- ) EXP ( d -- ) In-line comment definition Comment until end of the line Beginning of a colon definition Exit; ends any colon definition Index (=0) for first array element Index for last array element Begins an in-line macro definition Ends an In-line macro definition Allocates space for a 4-bit array Allocates space for an 8-bit array Defines a 4-bit constant Defines an 8-bit constant Allocates space for a long 4-bit array with up to 255 elements Allocates space for a long byte array Run-time array access using a variable array index Define ROM look-up table with 8-bit values Allocates memory for 4-bit value Creates an 8-bit variable Allocate space for <n+1> nibbles of un-initialized RAM Fixed <address> placement Interrupt service routine entry Entry point address on Return Stack underflow Entry point on power-on reset EXP ( n1 n2 -- n1+n2 ) EXP ( n1 n2 -- n1+n2+C ) EXP ( n -- ) EXP ( -- n ) EXP ( n1 n2 -- n1 ) EXP ( n1 n2 -- n1 ) EXP ( n1 n2 -- n1 ) EXP ( n1 n2 -- n1 ) EXP ( n1 n2 -- n1 ) EXP ( n1 n2 -- n1 ) EXP ( -- ) EXP ( -- ) EXP ( -- ) EXP ( n>9 or C set -- n+6) EXP ( n -- 10+/n+C ) EXP ( n -- n-1 ) RET ( u|u|I -- u|u|I-1 ) EXP ( -- ) RET ( u|u|u -- ) RET ( ROMAddr -- ) EXP ( -- ) EXP ( port -- data ) EXP ( n -- n+1 ) EXP ( -- ) Add the top two 4-bit values Add with carry top two values Write top value into the CCR Fetch the CCR onto top of stack If n1=n2, then Branch flag set If n1>=n2, then Branch flag set If n1>n2, then Branch flag set If n1<=n2, then Branch flag set If n1<n2, then Branch flag set If n1<>n2, then Branch flag set Clear Branch and Carry flag Set Branch and Carry flag Toggle the Branch flag BCD arithmetic adjust [addition] 9's complement for BCD subtract Decrement top value by 1 Decrement value on the Return Stack Disable interrupts Drop element from Return Stack Exit from current `:'-definition Enable interrupts Read data from an I/O port Increment the top value by 1 No operation 81 MARC4 Programmer's Guide qFORTH Dictionary NOT RP! RP@ RTI SLEEP SWI0 SWI7 SP! SP@ SUB SUBB TABLE OUT X@ [X]@ [+X]@ [X-]@ [>X]@ $xx X! [X]! [+X]! [X-]! [>X]! $xx Y@ [Y]@ [+Y]@ [Y-]@ [>Y]@ $xx Y! [Y]! [+Y]! [Y-]! [>Y]! $xx >RP $xx >SP $xx >X $xx >Y $xx 82 EXP ( n -- /n ) EXP ( d -- ) EXP ( -- d ) RET ( RETAddr -- ) EXP ( -- ) EXP ( -- ) EXP ( d -- ) EXP ( -- d ) EXP ( n1 n2 -- n1-n2 ) EXP ( n1 n2 -- n1+/n2+C ) EXP ( -- d ) RET ( RetAddr RomAddr --) EXP ( data port -- ) EXP ( -- d ) EXP ( -- n ) EXP ( -- n ) EXP ( -- n ) EXP ( -- n ) EXP ( d -- ) EXP ( n -- ) EXP ( n -- ) EXP ( n -- ) EXP ( n -- ) EXP ( -- d ) EXP ( -- n ) EXP ( -- n ) EXP ( -- n ) EXP ( -- n ) EXP ( d -- ) EXP ( n -- ) EXP ( n -- ) EXP ( n -- ) EXP ( n -- ) EXP ( -- ) EXP ( -- ) EXP ( -- ) EXP ( -- ) 1's complement of the top value Store as Return Stack Pointer Fetch current Return Stack Pointer Return from interrupt routine Enter 'sleep-mode', enable all interrupts Software triggered interrupt Store as Stack Pointer Fetch current Stack Pointer 2's complement subtraction 1's complement subtract with Borrow Fetches an 8-bit constant from an address in ROM Write data to I/O port Fetch current x register contents Indirect x fetch of RAM contents Preincrement x indirect RAM fetch Postdecrement x indirect RAM fetch Direct RAM fetch, x addressed Move 8-bit address to x register Indirect x store of RAM contents Preincrement x indirect RAM store Postdecrement x indirect RAM store Direct RAM store x addressed Fetch current Y register contents Indirect Y fetch of RAM contents Preincrement Y indirect RAM fetch Postdecrement Y indirect RAM fetch Direct RAM fetch, Y addressed Move address to Y register Indirect Y store of RAM contents Preincrement Y indirect RAM store Postdecrement Y indirect RAM store Direct RAM store, Y addressed Set Return Stack Pointer Set Expression Stack Pointer Set x register immediately Set Y register immediately 03.01 MARC4 Programmer's Guide qFORTH Dictionary 4.7 Short Form Dictionary MARC4 - Control Commands AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AA AAAAA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AAA AAAAAAAAAA AA AA AA AAA AAAAAA AAAAAAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAAAAAAAAAAAAAAA AAAAAAAAA AA AAAAA AA AAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AAA AAAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AAAAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAA AAAAAAAAAA AAAAAAAAA AA AAAAA AA AAA AAAAAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAA AAAAAAAAAA AA AA AA AAA AAAAAA AAAAAAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AAAAA AA AAA Command AGAIN Bytes 3 BEGIN 0 DO 1 #DO 1 ?DO 5 LOOP 9 #LOOP 4 +LOOP 10 ?LEAVE 2 -?LEAVE 3 REPEAT 3 UNTIL 3 WHILE 3 CASE 0 ELSE 3 ENDCASE 1 ENDOF 3 EXECUTE 3 IF 3 OF 4 THEN 0 CCR@ 1 CCR! 1 CLR_BCF 2 EI 2 EXIT 1 DI 1 SET_BCF 1 SWI0..SWI7 4 TOG_BF 1 03.01 Expression Stack Return Stack X Y CY B I CY B limit index-- index-- limit index-- -- (n1 n2 n3) -- n -- -- limit index -- u u index -- u limit index -- (-1 level) -- u u index-- u u index-1 u limit index-- u limit index+n CY B CY B B CY B B CY B B B CY B n -- CY B ROMaddr -- --(2+x level)-- B CY B CY B n1 -- n1n2 --(n1) -- n n -- --(1 level)-- CY B CY B CY B I I oldPC -- I CY B -- (2 level) -- I B 83 MARC4 Programmer's Guide qFORTH Dictionary MARC4 - Mathematic Commands AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AAAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AAAA AAAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AAAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAAAAA AAAAAAAAA AAA AAAAAAAAAA AA AA AA AA A AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA A AA AAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA A AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA A AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA A AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA A AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA A AA A AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AAAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AAAA AAAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AAAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AAAAAA AAA Command ADD + +! INC 1+ 1+! ADDC +C D+ D+! M+ T+! Bytes 1 1 4 1 1 4 1 1 7 8 5 19 TD+! DAA SUB - DEC 1- 1-! SUBB -C D- D-! M- T-! 20 1 1 1 1 1 4 1 1 8 10 5 22 TD- DAS 2* D2* 2/ D2/ CMP_EQ = 0= 22 3 1 4 1 4 1 2 3 84 Expression Stack n1 n2 -- n1+n2 n1 n2 -- n1+n2 n addr -- n -- n+1 n -- n+1 addr -- n1 n2 -- n1+n2+CY n1 n2 -- n1+n2+CY d1 d2 -- d1+d2 d addr -- d n -- d+n nh nm nl addr -- (1 level) -- d addr -- (1 level) -- n -- n+6 n1 n2 -- n1-n2 n1 n2 -- n1-n2 n -- n-1 n -- n-1 addr -- n1 n2 -- n1+/n2+CY n1 n2 -- n1+/n2+CY d1 d2 -- d1-d2 d addr -- d1 n -- d1-n nh nm nl addr -- (1 level) -- d addr -- (1 level) -- n -- 9-n n -- n*2 d -- d*2 n -- n/2 d -- d/2 n1 n2 -- n1 n1 n2 -- n -- Return Stack X Y CY CY CY X Y CY X Y -- (1 level) -- -- (1 level) -- -- (1 level) -- -- (2 level) -- --(2 level)-- CY CY CY X Y CY CY X Y CY X Y CY CY CY CY CY CY CY X Y CY CY X Y CY B B B B B B B B B B B B B X Y CY CY CY CY CY CY CY CY CY B B B B B B B B B X Y -- (1 level) -- -- (1 level) -- -- (1 level) -- -- (2 level) -- -- (2 level) -- B B B B B B B B B B B B B I 03.01 MARC4 Programmer's Guide qFORTH Dictionary AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AAAA AAAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AAAA AAAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA A AA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA A AA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AAAA AAAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA A AA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AAAA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AAAA AAAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AAAA AA AAAA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AAAA AAAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AAAA AAAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AA AA AA AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AAAA AAAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AAA AAAA AAAA Command D= D0= CMP_GE >= D>= CMP_GT > D> CMP_LE <= D<= CMP_LT < D< CMP_NE <> 0<> D0<> D<> MAX DMAX MIN DMIN NEGATE DNEGATE NOT ROL ROR SHL SHR AND OR XOR TOGGLE D>S S>D 03.01 Bytes 13 2 1 2 19 1 2 16 1 2 19 1 2 16 1 2 3 3 10 7 30 7 30 2 8 1 1 1 1 1 1 1 1 4 2 2 Expression Stack d1 d2 -- d -- n1 n2 -- n1 n1 n2 -- d1 d2 -- n1 n2 -- n1 n1 n2 -- d1 d2 -- n1 n2 -- n1 n1 n2 -- d1 d2 -- n1 n2 -- n1 n1 n2 -- d1 d2 -- n1 n2 -- n1 n1 n2 -- n -- d -- d1 d2 -- n1 n2 -- nmax d1 d2 --d1 d1 d2-- dmax n1 n2 -- nmin d1 d2 --d1 d1 d2-- dmin n1 -- -n1 d -- -d n1 -- /n1 n -- n*2 n -- n/2 n1 n2 -- n1 and n2 n1 n2 -- n1 v n2 n1 n2 -- n1 xor n2 n1 addr -- d -- n n -- d Return Stack -- (1 level) -- X Y CY CY CY CY CY CY CY CY CY CY CY CY CY CY CY CY CY -- (1 level u d2h d2l) -- -- (1 level u d2h d2l) -- -- (1 level u d2h d2l) -- -- (1 level u d2h d2l) -- -- (1 level) -- -- (1 level) -- -- (3 level) -- -- (1 level) -- -- (3 level) -- CY CY CY CY CY -- (1 level) -- CY CY CY CY CY X Y B B B B B B B B B B B B B B B B B B B I B B B B B B B B B B B B B B B 85 MARC4 Programmer's Guide qFORTH Dictionary MARC4 - Memory Commands AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AA AA AAA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AAAAAAAA AA AA AAAAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAAAAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AA AA AAA A AA AA AAA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AAAAAAAA AA AA A AA AA AAA A AA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA A AA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAA A AA AA AAA AAAAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA Command Bytes @ 2 2@ 3 3@ 4 X@ 1 [X]@ 1 [+X]@ 1 [X-]@ 1 Y@ 1 [Y]@ 1 [+Y]@ 1 [Y-]@ 1 DTABLE@ 14 TABLE 1 ROMBYTE@ 2 ! 2 2! 4 3! 7 X! 1 [X]! 1 [+X]! 1 [X-]! 1 Y! 1 [Y]! 1 [+Y]! 1 [Y-]! 1 ERASE 14 FILL 24 MOVE 14 MOVE> 10 IN 1 OUT 1 ' 3 86 Expression Stack addr -- n addr -- nh nl addr -- nh nm nl -- Xh Xl -- n -- n -- n -- Yh Yl -- n -- n -- n ROMaddr n -- nh nl -- nh nl ROMaddr -- nh nl n addr-- nh nl addr -- nh nm nl -- Xh Xl -- n -- n -- n -- Yh Yl -- n -- n -- n -- addr n-- addr n1 n2 -- n from to -- n from to -- port -- data data port -- - - ROMaddr Return Stack X X X X Y Y Y Y CY B CY B I X X Y Y -- (2 level) -- (2 level) -- -- (2 level) -- -- (1 level) -- X Y X Y X Y X X X Y -- (2 level) -- -- (3 level) -- -- (2 level) -- -- (2 level) -- X X X X Y Y Y Y Y Y B B B 03.01 MARC4 Programmer's Guide qFORTH Dictionary MARC4 - Commands AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AA AAAAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AA AAAAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA A AAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA Command ! #DO #LOOP Bytes 2 1 4 +LOOP 10 -?LEAVE <ROT >RP xxh >SP xxh ?DO ?DUP ?LEAVE @ [+X]! [+X]@ [+Y]! [+Y]@ [X-]! [X-]@ [X]! [X]@ [Y-]! [Y-]@ [Y]! [Y]@ 2! 2<ROT 2@ 2DROP 2DUP 2NIP 2OVER R@ 3 2 2 2 5 5 2 2 1 1 1 1 1 1 1 1 1 1 1 1 4 14 3 2 2 4 8 1 03.01 Expression Stack n addr-- index-- n -- Return Stack X Y X Y -- u u index u u index-- u u index-1 u limit index-- u limit index+n CY B I B CY B B n1 n2 n3 -- n3 n1 n2 limit index-- n -- n n addr -- n n -- -- n n -- -- n n -- -- n n -- -- n n -- -- n n -- -- n nh nl addr -- d1 d2 d3 -- d3 d1 d2 addr -- nh nl n1 n2 -- d -- d d d1 d2 -- d2 d1 d2 --d1 d2 d1 -- n -- u limit index CY CY B B X Y X X Y Y X X Y Y X Y -- (4 level) -- X Y - -(2 level u n2 n1) -- u u n -- u u n 87 MARC4 Programmer's Guide qFORTH Dictionary AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AA AA AAA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AAAAAAAA AA AA AAAAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA Command 2R@ 2ROT 2SWAP 2TUCK 3! 3@ 3DROP 3DUP 3R@ DAA ADD + +! INC 1+ 1+! ADDC +C D+ D+! DAS SUB - DEC 1- 1-! SUBB -C D- D-! 2* D2* 2/ D2/ AGAIN 88 Bytes 1 8 8 6 7 4 3 4 1 1 1 1 4 1 1 4 1 1 7 8 3 1 1 1 1 4 1 1 8 10 1 4 1 4 3 Expression Stack -- n1 n2 d1 d2 d3 -- d2 d3 d1 d1 d2 -- d2 d1 d1 d2 -- d2 d1 d2 nh nm nl addr-- addr -- nh nm nl n1 n2 n3 -- n1n2n3 -- n1n2n3n1n2n3 -- n1 n2 n3 n -- n+6 n1 n2 -- n1+n2 n1 n2 -- n1+n2 n addr -- n -- n+1 n -- n+1 addr -- n1 n2 -- n1+n2+CY n1 n2 -- n1+n2+CY d1 d2 -- d1+d2 d addr -- n -- 9-n n1 n2 -- n1-n2 n1 n2 -- n1-n2 n -- n-1 n -- n-1 addr -- n1 n2 -- n1+/n2+CY n1 n2 -- n1+/n2+CY d1 d2 -- d1-d2 d addr -- n -- n*2 d -- d*2 n -- n/2 d -- d/2 Return Stack u n1 n2 -- u n1 n2 -- (1 level u d1) -- -- (1 level u u d2l) -- -- (1 level d1l d2) -- -- (1 level) -- X Y CY B CY CY CY CY B B B B B B B B B B B B B B B B B B B B B B B B B B I X Y X Y -- (n1 n2 n3) -- n3 n2 n1 -- n3 n2 n1 X Y X Y -- (1 level) -- -- (1 level) -- X Y CY CY CY CY CY CY CY X Y -- (1 level) -- -- (1 level) -- X Y CY CY CY CY CY CY CY CY CY 03.01 MARC4 Programmer's Guide qFORTH Dictionary AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AA AAAAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA Command AND BEGIN CASE CCR! CCR@ CLR_BCF CMP_EQ = 0= D= D0= CMP_GE >= D>= CMP_GT > D> CMP_LE <= D<= CMP_LT < D< CMP_NE <> 0<> D<> D0<> DECR DEPTH DI DMAX DMIN DNEGATE DO DROP 03.01 Bytes 1 0 0 1 1 2 1 2 3 13 2 1 2 19 1 2 16 1 2 19 1 2 16 1 2 3 10 3 1 9 1 30 30 8 1 1 Expression Stack n1 n2 -- n1 and n2 n -- n n -- -- n - - ( 1 level ) - - n1 n2 -- n1 n1 n2 -- n -- d1 d2 -- d -- n1 n2 -- n1 n1 n2 -- d1 d2 -- n1 n2 -- n1 n1 n2 -- d1 d2 -- n1 n2 -- n1 n1 n2 -- d1 d2 -- n1 n2 -- n1 n1 n2 -- d1 d2 -- n1 n2 -- n1 n1 n2 -- n -- d1 d2 -- d -- -(SPh SPl S0h S0l)-- n Return Stack X Y CY B B I CY B I CY CY CY CY CY -- (1 level) -- CY CY CY CY CY CY CY CY CY CY CY CY CY CY CY CY u u n -- u u n-1 -- (1 level) -- CY B B B B B B B B B B B B B B B B B B B B B B B B B CY CY CY B B B -- (1 level) -- --(1 level u d2h d2l)-- --(1 level u d2h d2l)-- --(1 level u d2h d2l)-- --(1 level u d2h d2l)-- I d1 d2 --d1 d1 d2-- dmax d1 d2 --d1 d1 d2-- dmin d -- -d limit index-- -- (3 level) -- -- (3 level) -- -- (1 level) -- -- limit index n -- 89 MARC4 Programmer's Guide qFORTH Dictionary AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AA AA AAA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AAAAAAAA AA AA AAAAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAAAAAAAAA AA AA AAAAA AAA Command DROPR DTABLE@ DTOGGLE DUP EI ELSE ENDCASE ENDOF ERASE EXIT EXECUTE FILL I IF IN INDEX J LOOP M+ M- MAX MIN MOVE MOVE> NEGATE NIP D>S NOP NOT OF OR OUT OVER PICK >R 2>R 90 Bytes 1 14 8 1 2 3 1 3 14 1 3 24 1 3 1 8 6 9 5 5 7 7 14 10 2 2 2 1 1 4 1 1 1 13 1 1 Expression Stack ROMaddr -- const.h const.l d addr -- n1 -- n1 n1 Return Stack u u u -- -- (2 level) -- -- (1 level) -- X Y CY B CY B B CY CY B B CY X Y B B X Y B X Y I I n -- addr n-- ROMaddr - - addr n1 n2 -- -- index port -- data n addr -- -- J -(n1 n2 n3)- d1 n -- d1+n d1 n -- d1-n n1 n2 -- nmax n1 n2 -- nmin n from to -- n from to -- n1 -- -n1 n1 n2 -- n2 d -- n n1 -- /n1 n1 n2 -- n1 n2 -- n1 v n2 data port -- n2 n1 -- n2 n1 n2 x -(2 level)- n[x] n1 n1 n2 -- -- (2 level) -- oldPC -- -- (2 + x level) -- -- (3 level) -- u u index--u u index -- (1 level) -- -- (-1 level) -- -- (-1 level) -- -- (1 level) -- -- (1 level) -- -- (1 level) -- -- (1 level) -- -- (2 level) -- -- (2 level) -- CY B B B CY CY CY CY CY B B B B B X Y X Y B -- (2 level) -- -- u u n1 --u n2 n1 X Y CY B B B CY B 03.01 MARC4 Programmer's Guide qFORTH Dictionary AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA A AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AA AAAAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAA AA AAA AA AAAAAA AAA AAAAAAAAAAA AAAAAAAA AA AAAAA AAAAA Command Bytes 3>R 1 R> 2 2R> 2 3R> 2 RDEPTH 13 REPEAT 3 RFREE 30 ROL 1 ROLL 57 ROMBYTE@ 2 ROR 1 ROT 1 RP! 1 RP@ 1 S>D 2 SET_BCF 1 SHL 1 SHR 1 SP! 1 SP@ 1 SWAP 1 SWI0..SW17 4 T+! 19 T-! 22 TD+! 20 TD-! 22 THEN 0 TOG_BF 1 TOGGLE 4 TUCK 2 UNTIL 3 WHILE 3 X! 1 X@ 1 XOR 1 Y! 1 Y@ 1 03.01 Expression Stack n1 n2 n3 -- -- n -- n1 n2 -- n1 n2 n3 - (2 level) - n Return Stack -- n3 n2 n1 u u n -- u n2 n1 -- n3 n2 n1 -- -- (1 level) -- - (3 level) - n -- (2 level) -- x -(2 level)- ROMaddr -- conh conl -- (4 level) -- -- (2 level) -- X Y CY B I X Y CY CY CY CY CY B B B B B I CY B CY CY CY B B B CB CY CY CY CY B B B B B B B n1 n2 n3 -- n2 n3 n1 RPh RPl -- -- RPh RPl n -- d n -- n*2 n -- n/2 SPh SPl -- -- SPh SPl+1 n2 n1 -- n1 n2 -- (2 level) -- nh nm nl addr-- (1 level) -- nh nm nl addr -- d addr -- (1 level) -- d addr -- (1 level) -- n1 addr -- n1 n2 -- n2 n1 n2 I -- (2 level) -- -- (2 level) -- -- (2 level) -- -- (2 level) -- X X X X Y Y Y Y X Y B B Xh Xl -- -- Xh Xl n1 n2 -- n1 xor n2 Yh Yl -- -- Yh Yl X Y 91 MARC4 Programmer's Guide qFORTH Dictionary MARC4 - Stack Commands AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAAAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAAAA AA AAA A AA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAAAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAAAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAA AA AAA AAAAAA AAA AAAAAAAAAA AAAAAAAAA AA AA AAAAA AAA DECR DEPTH DROP 2DROP 3DROP DROPR DUP ?DUP 2DUP 3DUP I INDEX J NIP 2NIP OVER 2OVER Command Bytes 1 9 1 2 3 1 1 5 2 4 1 8 6 2 4 1 8 n1 -- n1 n1 n -- n n d -- d d n1n2n3 --n1n2n3n1n2n3 -- index d/n addr -- -- J n1 n2 -- n2 d1 d2 -- d2 n2 n1 -- n2 n1 n2 d1 d2 --d1 d2 d1 PICK R@ 2R@ 3R@ >R 2>R 3>R R> 2R> 3R> RDEPTH RFREE ROT 2ROT <ROT 2<ROT RP@ RP! SP@ SP! SWAP 2SWAP 13 1 1 1 1 1 1 2 2 2 13 30 1 5-7 2 14 1 1 1 1 1 8 x -(2 level)- n[x] -- n2 -- n1 n2 -- n1 n2 n3 n1 n1 n2 -- n1 n2 n3 -- -- n -- n1 n2 -- n1 n2 n3 -(2 level)- n -(3 level)- n n1 n2 n3 -- n2 n3 n1 d1 d2 d3 -- d2 d3 d1 n1 n2 n3 -- n3 n1 n2 d1 d2 d3 -- d3 d1 d2 -- RPh RPl RPh RPl -- -- SPh SPl+1 SPh SPl -- n2 n1 -- n1 n2 d1 d2 -- d2 d1 -- (1 level u u d2l) -- n1 n2 -- n2 n1 n2 d1 d2 -- d2 d1 d2 -- (1 level d1l d2) -- TUCK 2TUCK 92 2 6 Expression Stack -(SPh SPl S0h S0l)--n n1 -- n1 n2 -- n1 n2 n3 -- Return Stack u u n -- u u n-1 -- (1 level) -- X Y CY CY B B B CY B CY B CY B CY CY B B I u u u -- -(n1 n2 n3)- u u index--u u index -- (1 level) -- -- (-1 level) -- -- (2 level u n2 n1) -- -- (2 level) -- u u n1 -- u u n1 u n1 n2 -- u n1 n2 n3 n2 n1-- n3 n2 n1 -- u u n1 -- u n2 n1 -- n3 n2 n1 u u n -- u n2 n1 -- n3 n2 n1 -- -- (1 level) -- -- (2 level) -- X Y -- (1 level u d1) -- -- (4 level) -- 03.01 MARC4 Programmer's Guide qFORTH Dictionary 4.8 03.01 Detailed Description of the qFORTH Language 93 MARC4 Programmer's Guide qFORTH Dictionary ! "Store" Purpose: Stores a 4-bit value at a specified memory location. Category: qFORTH macro Library implementation: CODE ! Y! [Y]! ( n addr -- n (n -- ) ) END-CODE Changes in the actually generated code sequence can result due to the compiler optimizing techniques (register tracking) Stack effect: EXP RET Stack changes: EXP: 3 elements are popped from the stack RET: not affected Flags: not affected X Y registers: The contents of the Y or X register may be changed. Bytes used: 2 See Also: +! 2! 3! @ 94 ( n RAM_addr -- ) ( -- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary ! Example: VARIABLE ControlState VARIABLE Semaphore : InitVariables 0 ControlState ! 2 Semaphore ! ; 03.01 ( initialize VARs ) ( Set up control flag ) ( Set up a preset value ) 95 MARC4 Programmer's Guide qFORTH Dictionary ' "tick" Purpose: Leaves a compiled ROM code address on the EXP stack. Used in the form ' <name>. ' searches for a name in the qFORTH dictionary and returns that name's compilation address (code address). If the name is not found in the dictionary, an error message results. Category: Control structure Stack effect: EXP RET Stack changes: EXP: 3 nibbles are pushed on the stack RET: not affected Flags: not affected Bytes used: 3 See Also: EXECUTE 96 ( - -ROM_addr ) ( -- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary ' Example: ' is typically used to initialize the content of a variable with the code address of qFORTH word for vectored execution. For example, a program might contain a variable named $ERROR which would specify the action to be taken if a certain type of error occured. At compile time, $ERROR is "vectored" with a sequence such as 3 ARRAY $ERROR ' ERROR-ROUTINE $ERROR 3! and the main program, if it detects an error, can execute the sequence $ERROR 3@ EXECUTE to invoke the error handler. This program's error-handling routine can be changed "on the fly" by changing the address stored in $ERROR without modifying the main program in any way. 03.01 97 MARC4 Programmer's Guide qFORTH Dictionary #DO "Hash-DO" Purpose: #DO indicates the start of an iterative 'decrement-if-nonzero' loop structure. It is used only within a macrocolon definition in a pair with #LOOP. The value on top of the stack at the time #DO is executed determines the number of times the loop repeats.The value on top is the initial loop index which will be decremented on each iteration of the loop (see example 2). If the current loop index I is not accessed inside of a loop block, this control structure executes much faster than an equivalent n 0 DO ... LOOP. The standard FORTH-83 loop structure n 0 DO ... -1 +LOOP maps directly to the behavior of the n #DO ... #LOOP structure. Category: Control structure / qFORTH macro Library implementation: CODE Stack effect: EXP ( Index -- ) RET ( -- u|u|Index ) Stack changes: EXP: 1 element is popped from the stack RET: 1 element is pushed onto the stack Flags: #DO : #LOOP : X Y registers: not affected Bytes used: 1 See also: #LOOP ?LEAVE -?LEAVE 98 #DO >R $#DO: END-CODE not affected CARRY flag not affected BRANCH flag = Set, if (Index-1 <> 0) 03.01 MARC4 Programmer's Guide qFORTH Dictionary #DO Example 1: 8 ARRAY result : ERASE <ROT Y! 0 [Y]! 1- #DO 0 [+Y]! #LOOP ; : Clear_Result Result 8 ERASE ; ( 8 digit BCD number ( Fill a block of memory with zero ( addr count -- ( count -- count-1 ) ) ) ) ( Use the MARC4 pre-incremented store ) ( REPEAT until length-1 = 0 ) ( Clear result array ) Example 2: 1 CONSTANT port1 : HASH-DO-LOOP 0 #DO I 1- port1 OUT #LOOP ; 03.01 ( loop 16 times ) ( write data to 'port1': F, E, D, C...1,0. ) ( repeat the loop. ) 99 MARC4 Programmer's Guide qFORTH Dictionary #LOOP "Hash-LOOP" Purpose: #LOOP indicates the end of an iterative 'decrement-if-nonzero' loop structure. #LOOP is used only within a colon definition in a pair with #DO. The value on top of the stack at the time #DO is executed determines the number of times the loop repeats. The loop index is decremented on the Return Stack on each iteration, ie. the execution of the #LOOP word, until the index reaches zero. If the new index is decremented to zero, the loop is terminated and the loop index is discarded from the Return Stack. Otherwise, control branches back to the word just after the corresponding #DO word. If the current loop index I is not used inside a loop block this structure executes much faster than an equivalent DO ...LOOP. The behavior of the standard FORTH loop structure 0 DO ... -1 +LOOP is identical to the #DO ... #LOOP structure. Category: Control structure / qFORTH macro Library implementation: CODE #LOOP DECR ( decrement loop index on RET ) (S)BRA _$#DO _$LOOP: DROPR ( drop loop index from RET ) END-CODE Stack effect: EXP ( -- ) IF Index-1 > 0 THEN RET (u|u|Index --u|u|Index-1) ELSE RET ( u|u|Index -- ) EXP: not affected RET: If #LOOP terminates, top element is popped from the stack Stack changes: Flags: CARRY flag BRANCH flag X Y registers: not affected Bytes used: 3-4 See also: #DO ?LEAVE -?LEAVE 100 not affected set as long as index-1 <> 0 03.01 MARC4 Programmer's Guide qFORTH Dictionary #LOOP Example: 16 ARRAY LCD-buffer : FILL-IT Y! #DO ( n count addr -- n count ) ( end address was on stack ) DUP [Y-]! ( duplicate and store value ) #LOOP ; Setup_Full_House Fh 0 LCD-buffer [15] FILL-IT ; 03.01 101 MARC4 Programmer's Guide qFORTH Dictionary $AUTOSLEEP "Autosleep" Purpose: The $AUTOSLEEP function will automatically be placed at ROM address $000 by the compiler and may be redefined slightly by the user. The Return Stack pointer is initialized in $RESET to FCh. After the last interrupt routine is processed and no other interrupt is pending, the PC is automatically loaded to the address $000 ($AUTOSLEEP). This forces the MARC4 into sleep mode through processing the $AUTOSLEEP routine. This sleep mode is a shutdown condition which is used to reduce the average system power consumption, whereby the CPU is halted. The internal RAM data keeps valid during sleep mode. To wake up the CPU again, an interrupt must be received from a peripheral module (timer/counter or external interrupt pin). The CPU starts running at the ROM address where the interrupt service routine is placed. Attention : It is not recommended to use the SLEEP instruction other than in the $RESET or $AUTOSLEEP because it might result in unwanted side effects within other interrupt routines. If any interrupt is active or pending, the SLEEP instruction will be executed in the same way as an NOP! Category: Library implementation: Interrupt handling / predefined qFORTH colon definition : $AUTOSLEEP $TIRED: NOP SLEEP SET_BCF BRA_$TIRED [E0R0] ;; Stack effect: EXP & RET empty Stack changes: EXP: not affected RET: not affected Flags: SLEEP sets the I_ENABLE flag CARRY and BRANCH flags are set by $AUTOSLEEP X Y registers: not affected Bytes used: 4 See also: $RESET, INT0 ... INT7, DI, EI, RTI, SLEEP 102 03.01 MARC4 Programmer's Guide qFORTH Dictionary $AUTOSLEEP Example: \ Improved $AUTOSLEEP routine for noisy environment : Clr_INT_controller ;; RTI [N] :$AUTOSLEEP $_Tired: NOP SLEEP NOP SET_BCF CPr_INT_controller BRA $_Tired [E0 R0] ;; 03.01 \ Clear unwanted spurious \ INT pending/active bits 103 MARC4 Programmer's Guide qFORTH Dictionary $RESET "Dollar-reset" Purpose: The power-on-reset colon definition $RESET is placed at ROM address $008 automatically and is re-definable by the user. The maximum length of this part in the Zero Page is 56 bytes when INT0 is used also. It is normally used to initialize the two stack pointers as well as the connected I/O devices, like timer/ counter, LCD and A/D-converter. An optional SELFTEST is executable on every power-on-reset if Port 0 is forced to a customer specified input value. Category: Interrupt handling / predefined qFORTH colon definition Stack effect: EXP stack pointer initialized RET stack pointer initialized Stack changes: EXP: empty RET: empty Flags: CARRY flag Undefined after power-on reset BRANCH flag Undefined after power-on reset I_ENABLE flag Reset by hardware during POR- Set by the RTI instruction at the end of $RESET. X Y registers: not affected Bytes used: modified by the customer See also: $AUTOSLEEP 104 03.01 MARC4 Programmer's Guide qFORTH Dictionary $RESET Example: 0 CONSTANT port0 FCh 2CONSTANT NoRAM VARIABLE S0 16 ALLOT ( Define expression stack space. VARIABLE R0 31 ALLOT ( Define RET stack : $RESET >RP NoRAM >SP S0 Port0 IN 0= IF Selftest THEN Init_Peripherals ; 03.01 ( Possible $RESET implement. of a customer ( Init RET stack pointer to non-existent memory ( Init EXP stack pointer; above RET stack ( RTI enable Interrupts, goto $AUTOSLEEP ) ) ) ) ) ) 105 MARC4 Programmer's Guide qFORTH Dictionary ( comment) \ "Paren", "Backslash" Purpose: Begins a comment, used either in the form ( ccccc) or \ comment is rest of line The characters "ccccc" delimited by the closing parenthesis are considered a comment and are ignored by the qFORTH compiler. The characters "comment is rest of line" are delimited by the end of line control character(s). NOTE: The " ( " and " \ " characters must be immediately preceded and followed by a blank. Comments should be used freely for documenting programs. They do not affect the size of the compiled code. Category: predefined data structure Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: % 106 03.01 MARC4 Programmer's Guide qFORTH Dictionary ( comment) \ Example: : ExampleWord 13 DUP ROT SWAP 3DROP ; 03.01 ( -- 1 3 ( ******* This is a qFORTH comment ***** \ This is a comment until the end of line. ( 3 3 1 -- 3 1 3 ( clean table again. ( End of ':'-definition ) ) ) ) ) 107 MARC4 Programmer's Guide qFORTH Dictionary + ADD "Plus" Purpose: Adds the top two 4-bit values and replaces them with the 4-bit result on top of the stack. Category (+) : Arithmetic/logical (single-length) (ADD): MARC4 mnemonic MARC4 opcode: 00 hex Stack effect: EXP ( n1 n2 -- n1+n2 ) RET ( -- ) Stack changes: EXP: stack depth reduced by 1, new top element. RET: not affected Flags: CARRY flag Set on arithmetic overflow ( result > 15 ) BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 1 See also: D+! 1+! 1-! - +! +C -C 108 03.01 MARC4 Programmer's Guide qFORTH Dictionary + ADD Example: VARIABLE Result : Single-addition 5 3 + Result ! 3 Result +! ; 03.01 ( RPN addition: 5 + 3 := 8 ) ( Save result in memory ) ( Add 3 to memory location ) 109 MARC4 Programmer's Guide qFORTH Dictionary +! "Plus-store " Purpose: Adds a 4-bit value to the contents of a 4-bit variable. On entry to the function, the TOS value is the 8-bit RAM address of the variable. Category: Memory operation (single-length) / qFORTH macro Library implementation: CODE +! Y! [Y]@ + [Y]! ( n addr -- n ) ( n -- n @RAM[Y] -- sum ) ( sum -- ) END-CODE The qFORTH compiler optimizes a word sequence such as "5 semaphore +!" into an instruction sequence of the following form : [>Y]@ semaphore ADD [Y]! Stack effect: EXP ( n RAM_addr -- ) RET ( -- ) Stack changes: EXP: 3 elements are popped from the stack RET: not affected Flags: CARRY flag: Set on arithmetic overflow ( result > 15 ) BRANCH flag = CARRY flag X Y registers: The contents of the Y or X register may be changed. Bytes used: 4 See also: + ! 110 03.01 MARC4 Programmer's Guide qFORTH Dictionary +! Example: VARIABLE Ramaddress : PLUS-STORE 15 Ramaddress ! 9 Ramaddress +! ; 03.01 ( 15 is stored in the variable ) ( 9 is added to this variable ) 111 MARC4 Programmer's Guide qFORTH Dictionary +C ADDC "Plus-C" Purpose: ADD with CARRY of the top two 4-bit values and replace them with the 4-bit result [n1 + n2 + CARRY] on top of the stack. Category: (+C) : arithmetic/logical (single-length) (ADDC) : MARC4 mnemonic MARC4 opcode: 01 hex Stack effect: EXP ( n1 n2 -- n1+n2+CARRY ) RET ( -- ) Stack changes: EXP: 1 element is popped from the stack RET: not affected Flags: CARRY flag: Set on arithmetic overflow ( result > 15 ) BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 1 See also: -C + DAA ADD 112 03.01 MARC4 Programmer's Guide qFORTH Dictionary +C ADDC Examples: : Overflow 10 8 +C ; ( -- 2 ; BRANCH, CARRY flag set ) : PLUS-C SET_BCF 4 3 +C ; ( -- 8 ; flags : ---- ) (d1 d2 -- d1+d2 ) : D+ \ 8-bit addition using +C ROT + <ROT +C SWAP ; : ADDC-Example 50 190 D+ PLUS-C Overflow 2DROP 2DROP ; 03.01 ( -- 240 = F0h ; no CARRY or BRANCH) ( the results. ) 113 MARC4 Programmer's Guide qFORTH Dictionary +LOOP "Plus-LOOP" Purpose: +LOOP terminates a DO loop. Used inside a colon definition in the form DO ... n +LOOP. On each iteration of the DO loop, +LOOP increments the loop index by n. If the new index is incremented across the limit (>=), the loop is terminated and the loop control parameters are discarded. Otherwise, execution returns just after the corresponding DO. Category: Control structure / qFORTH macro Library implementation: CODE +LOOP 2R> ROT + OVER CMP_LT 2>R (S)BRA _$DO _$LOOP: DROPR END-CODE ( Move Limit & Index on EXP ) ( Check for Index < Limit ) ( Skip Limit & Index from RET ) Stack effect: EXP ( n -- ) IF Index+n < Limit THEN RET ( u|Limit|Index -- u|Limit|Index+n ) ELSE RET ( u|Limit|Index -- ) Stack changes: EXP: top element is popped from the stack RET: top entry is popped from the stack, if +LOOP is terminated Flags: CARRY and BRANCH flags are affected X Y registers: not affected Bytes used: 10 See also: DO ?DO #DO #LOOP LOOP I J ?LEAVE -?LEAVE 114 03.01 MARC4 Programmer's Guide qFORTH Dictionary +LOOP Example: : INCREMENT-COUNT 10 0 DO I 2 +LOOP ; 03.01 ( NOTE: The BRANCH and CARRY flag are ( altered during execution of +LOOP ( EXP after execution: -- 0 2 4 6 8 ) ) ) 115 MARC4 Programmer's Guide qFORTH Dictionary - SUB "Minus" Purpose: 2's complement subtract the top two 4-bit values and replace them with the result [n1 + /n2 + 1] on top of the stack (/n2 is the 1's complement of n2). Category: (-) : arithmetic/logical (single-length) (SUB) : MARC4 mnemonic MARC4 opcode: 02 hex Stack effect: EXP ( n1 n2 -- n1 + n2 + 1 ) RET ( -- ) Stack changes: EXP: top element is popped from the stack RET: not affected Flags: CARRY flag: Set on arithmetic overflow (n1+/n2+1 > 15) BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 1 See also: -C SUBB 116 03.01 MARC4 Programmer's Guide qFORTH Dictionary - SUB Example: : MINUS 5 3 - ; : Underflow 3 5 - ; 03.01 ( TOS = 2 ; flags : --- ) ( TOS = E; BRANCH, CARRY flag set ) 117 MARC4 Programmer's Guide qFORTH Dictionary -?LEAVE "Not-Query-Leave" Purpose: Conditional exit from within a LOOP structure if the previous tested condition was FALSE ( ie. the BRANCH flag is RESET ). -?LEAVE is the opposite to ?LEAVE (condition TRUE). The standard FORTH word sequence NOT IF LEAVE THEN is equivalent to the qFORTH word -?LEAVE. -?LEAVE transfers control just beyond the next LOOP, +LOOP or #LOOP or any other loop structure like BEGIN ... UNTIL, WHILE Category: Control structure / qFORTH macro Library implementation: CODE -?LEAVE TOG_BF ( Toggle BRANCH flag setting ) (S)BRA _$LOOP ( Exit LOOP if BRANCH flag set) END-CODE Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag: not affected BRANCH flag = NOT BRANCH flag X Y registers: not affected Bytes used: 3 See also: DO LOOP +LOOP #LOOP ?LEAVE 118 03.01 MARC4 Programmer's Guide qFORTH Dictionary -?LEAVE Example: 8 CONSTANT Length 7 CONSTANT LSD Length ARRAY BCD_Number : DIGIT+ Y! CLR_BCF #DO [Y]@ +C DAA [Y-]! 0 -?LEAVE #LOOP DROP ; ( 8 digit BCD value ) \ Add digit to n-digit BCD value ( digit n LSD_Addr -- digit n ) ( Clear BRANCH and CARRY flag ) ( Use length as loop index ) ( n -- m+n [BRANCH set on overflow] ) ( m' -- 0 ) ( Finish loop, if NO overflow ) ( Decrement index & repeat if >0 ) : Add8 BCD_Number Length ERASE ( clear the array ) 8 Length BCD_Number [LSD] Digit+ ; 03.01 119 MARC4 Programmer's Guide qFORTH Dictionary -C SUBB "Minus-C" Purpose: Subtract with BORROW [ = NO CARRY oder /CARRY] 1's complement of the top two 4-bit values and replace them with the 4-bit result [ = n1+/n2+/CARRY ] on top of the stack (/n2 is the inverse bit pattern [1's complement] of n2). Category: (-C) : arithmetic/logical (single-length) (SUBB) : MARC4 mnemonic MARC4 opcode: 03 hex Stack effect: EXP ( n1 n2 -- n1+/n2+/CARRY ) RET ( -- ) Stack changes: EXP: top element is popped from the stack RET: not affect Flags: CARRY flag: Set on arithmetic underflow (n1+/n2+/CARRY > 15) BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 1 See also: SUB TCS DAA - +C 120 03.01 MARC4 Programmer's Guide qFORTH Dictionary -C SUBB Example: : DNEGATE \ Two's complement of top byte 0 - SWAP 0 -C SWAP ; 03.01 ( d1 -- -d1 ) 121 MARC4 Programmer's Guide qFORTH Dictionary 0 ... Fh (15) LIT_0 ... LIT_F "Literal" Purpose : PUSH the LITeral <n> (0...15) onto the Expression Stack. Category: Stack operation / assembler instruction MARC4 opcode: 60 ... 6F hex Stack effect: EXP ( -- n ) RET ( -- ) Stack changes: EXP: one element is pushed onto the stack. RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: CONSTANT 2CONSTANT 122 < n = 0 .. Fh > 03.01 MARC4 Programmer's Guide qFORTH Dictionary 0 ... Fh (15) LIT_0 ... LIT_F Example: : LITERAL-example LIT_A LIT_0 + DROP ( is equivalent to A hex or 10 decimal ( is equivalent to 0 decimal ( results in the LIT_A remaining on the TOS ( drop the result. ) ) ) ) ( better used for above sequence : ) Ah 0 + DROP 21h ABh D+ 2DROP 12 1 + DROP ( -- 2 1 -- 2 1 A B ( 2 1 A B -- C C -- ( C -- C 1 -- D -- ) ) ) ; 03.01 123 MARC4 Programmer's Guide qFORTH Dictionary 0<> "Zero-not-equal" Purpose: Compares the 4-bit value on top of the stack to zero. If the value on the stack is not zero, then the BRANCH flag is set in the condition code register (CCR). This differs from standard FORTH, whereby a BOOLEAN value (0 or 1), depending on the comparison result, is pushed onto the stack. Category: Comparison (single-length) / qFORTH macro Library implementation: CODE 0<> 0 CMP_NE DROP END-CODE Stack effect: EXP ( n -- ) RET ( -- ) Stack changes: EXP: top element is popped from the stack RET: not affected Flags: CARRY flag: affected BRANCH flag: set, if (TOS <> 0) X Y registers: not affected Bytes used: 3 See also: 0= D0= D0<> 124 03.01 MARC4 Programmer's Guide qFORTH Dictionary 0<> Example: : NOT-EQUALS-ZERO 5 6 0<> DROP 0 0= ; 03.01 ( -- 6 5 ( 5 6 -- 5; BRANCH flag SET ( 5 -- 0 ( 0 -- ; BRANCH flag SET ) ) ) ) 125 MARC4 Programmer's Guide qFORTH Dictionary 0= "Zero-equal" Purpose: Compares the 4-bit value on top of the stack with zero. If the value of the stack is equal to zero, then the BRANCH flag is set in the condition code register. This differs from standard FORTH, whereby a BOOLEAN value (0 or 1), depending on the comparison result, is pushed onto the stack. Category: Comparison (single-length) / qFORTH macro Library implementation: CODE 0= 0 CMP_EQ DROP END-CODE Stack effect: EXP ( n -- ) RET ( -- ) Stack changes: EXP: top element is popped from the stack RET: not affected Flags: CARRY flag: affected BRANCH flag: set, if (TOS = 0) X Y registers: not affected Bytes used: 3 See also: D0= D0<> 0<> 126 03.01 MARC4 Programmer's Guide qFORTH Dictionary 0= Example: : ZERO-EQUALS 5 6 0<> DROP 0 0= ; 03.01 ( -- 6 5 ( 5 6 -- 5 ; BRANCH flag SET ( 5 -- 0 ( 0 -- ; BRANCH flag SET ) ) ) ) 127 MARC4 Programmer's Guide qFORTH Dictionary 1+ INC "One-plus" Purpose: Increments the 4-bit value on top of the stack (TOS) by 1. Category (1+): Arithmetic/logical (single-length) (INC): MARC4 mnemonic MARC4 opcode: 14 hex Stack effect: EXP ( n -- n+1 ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag: not affected BRANCH flag: set, if (TOS = 0) X Y registers: not affected Bytes used: 1 See also: 1- 1+! 128 03.01 MARC4 Programmer's Guide qFORTH Dictionary 1+ INC Example: VARIABLE PresetValue VARIABLE Switch : DownCounter BEGIN 1- UNTIL DROP ; ( PresetValue -- ( n -- n-1 ) ) : UpCounter BEGIN 1+ UNTIL DROP ; ( PresetValue -- ( n -- n+1 ) ) ( Toggle between 1 <-> 0 ) : SelectDirection 9 PresetValue ! 0 Switch ! BEGIN PresetValue @ Switch 1 TOGGLE IF DownCounter ELSE UpCounter THEN PresetValue 1-! UNTIL ; 03.01 129 MARC4 Programmer's Guide qFORTH Dictionary 1+! "One-plus-store" Purpose: Increments the 4-bit contents of a specified memory location. 1+! requires the address of the variable on top of the stack. Category: Memory operation (single-length) / qFORTH macro Library implementation: CODE 1+! Y! [Y]@ 1+ [Y]! ( increment variable by 1 ) END-CODE Stack effect: EXP ( addr -- ) RET ( -- ) Stack changes: EXP: 2 elements are popped from the stack RET: not affected Flags: CARRY flag: not affected BRANCH flag: set, if (TOS = 0) X Y registers: The address is stored into the Y or X register, then the value is fetched from RAM, the value is incremented on the stack and restored in the address indicated by the Y (or X) register. Bytes used: 4 See also: +! 1-! 130 03.01 MARC4 Programmer's Guide qFORTH Dictionary 1+! Example: VARIABLE State : StateCounter 5 State ! 6 0 DO State 1+! LOOP ; 03.01 ( store 5 in the memory location ) ( set loop index = 6 ) ( increment contents of variable 'State' ) 131 MARC4 Programmer's Guide qFORTH Dictionary 1- DEC "One-minus" Purpose: Decrements the 4-bit value on top of the stack (TOS) by 1. Category (1-): Arithmetic/logical (single-length) (DEC): MARC4 mnemonic MARC4 opcode: 15 hex Stack effect: EXP ( n -- n-1 ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag not affected BRANCH flag Set, if (TOS = 0) X Y registers: not affected Bytes used: 1 See also: 1+ 1-! 132 03.01 MARC4 Programmer's Guide qFORTH Dictionary 1- DEC Example: VARIABLE PresetValue VARIABLE Switch : DownCounter BEGIN 1- UNTIL DROP ; ( PresetValue -- ( n -- n-1 ) ) : UpCounter BEGIN 1+ UNTIL DROP ; ( PresetValue -- ( n -- n+1 ) ) ( Toggle between 1 <-> 0 ) ( UNTIL PresetValue = 0 ) : SelectDirection 9 PresetValue ! 0 Switch ! BEGIN PresetValue @ Switch 1 TOGGLE IF DownCounter ELSE UpCounter THEN PresetValue 1-! UNTIL ; 03.01 133 MARC4 Programmer's Guide qFORTH Dictionary 1-! "One-minus-store" Purpose: Decrements the 4-bit contents of a specified memory location. 1-! requires the address of the variable on top of the stack. Category: Memory operation (single-length) / qFORTH macro Library implementation: CODE 1-! Y! [Y]@ 1- [Y]! END-CODE ( decrement variable by 1 ) Stack effect: EXP ( addr -- ) RET ( -- ) Stack changes: EXP: 2 elements are popped from the stack RET: not affected Flags: CARRY flag: not affected BRANCH flag: set, if (TOS = 0) X Y registers: The address is stored into the Y (or X) register, then the value is fetched from RAM , the value is decremented on the stack and re-stored in the address indicated by the Y (or X) register. Bytes used: 4 See also: +! 1+! ! 134 03.01 MARC4 Programmer's Guide qFORTH Dictionary 1-! Example: VARIABLE PresetValue VARIABLE Switch : DownCounter BEGIN 1- UNTIL DROP ; ( PresetValue -- ( n -- n-1 ) ) : UpCounter BEGIN 1+ UNTIL DROP ; ( PresetValue -- ( n -- n+1 ) ) : SelectDirection 9 PresetValue ! 0 Switch ! BEGIN PresetValue @ Switch 1 TOGGLE ( Toggle between 1 <-> 0 ) IF DownCounter ELSE UpCounter THEN PresetValue 1-! ( UNTIL PresetValue = 0 ) UNTIL ; 03.01 135 MARC4 Programmer's Guide qFORTH Dictionary 2! "Two-store" Purpose: Stores the 8-bit value on TOS into an 8-bit variable in RAM. The address of the variable is the TOS value. Category: Library implementation: Arithmetic/logical (double-length) / qFORTH macro CODE 2! Y! ( nh nl addr -- nh nl ) SWAP ( nh nl -- nl nh ) [Y]! ( nl nh -- nl ) [+Y]! ( nl -- ) END-CODE Stack effect: EXP ( n_h n_l RAM_addr --- ) RET ( -- ) Stack changes: EXP: 4 elements are popped from the stack RET: not affected Flags: not affected X Y registers: The contents of the Y or X register may be changed. Bytes used: 4 See also: 2@ D+! D-! 136 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2! Example 1: : D-STORE 13h 43h 2! ; ( RAM [43] = 1 ; RAM [44] = 3 ( but normally variable names are used ! ) ) Example 2: 2VARIABLE Counter : DoubleCount 0 0 Counter 2! BEGIN 0 1 Counter D+! Counter 2@ 20h D= UNTIL ; 03.01 ( initialize the 8-bit counter ) ( increment the 8-bit counter ( until 20h is reached ... ) ) 137 MARC4 Programmer's Guide qFORTH Dictionary 2* SHL "Two-multiply" Purpose: Multiplies the 4-bit value on top of the stack by 2. SHL shifts TOS left into CARRY flag. AAA AAA AAAA AAAAAAAA AAAA AA AAA AAA AAA AAAA AA AAA AAA AAA AAAA AAAAA AAAAAAAA AAA AAA AAAA AA AAA AAA AAA AAAA AA AAA AAA AAA AAAA AAAAA AAA AAA AAAA AAAAA TOS C Category: <--- 3 2 1 0 <--- 0 (2*) : Arithmetic/logical (single-length) / qFORTH macro (SHL) : MARC4 mnemonic / assembler instruction MARC4 opcode: 10 hex (SHL) Library implementation: CODE 2* SHL END-CODE Stack effect: EXP ( n -- n*2 ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag: MSB of TOS is shifted into CARRY BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 1 See also: ROL ROR SHR 2/ D2* D2/ 138 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2* SHL Example 1: : MULT-BY-TWO 7 2* ( multiply a 4-bit number: ( 7h -- Eh ( multiply a 8-bit number: 'D2*' Macro : ( 18h -- 0 1h [CARRY flag set] ( 0 1h [CARRY] -- 30h ( 18h * 2 = 30h ! use 'D2*' ! ) ) ) ) ) ) ( 3 = 0011b ( [CARRY] 3 -- [CARRY] 9 = 1001b ) ) CLR_BCF 3 ROR DROP ( 3 = 0011b ( [no CARRY] 3 -- [CARRY] 1 = 0001b ) ) SET_BCF 3 ROL DROP ( 3 = 0011b ( [CARRY] 3 -- [no CARRY] 7 = 0111b ) ) CLR_BCF 3 ROL DROP ( 3 = 0011b ( [no CARRY] 3 -- [no CARRY] 6 = 0110b ) ) CLR_BCF Fh 2/ DROP (-SHR-[no CARRY] F -- [CARRY] 7 = 0111b ) CLR_BCF 6 2* DROP ( 6 = 0110b (- SHL - [no CARRY] 6 -- [no C] C = 1100b ) ) 18h SHL SWAP ROL SWAP ; Example 2: : BitShift SET_BCF 3 ROR DROP ; 03.01 139 MARC4 Programmer's Guide qFORTH Dictionary 2/ SHR "Two-divide" Purpose: Divides the 4-bit value on top of the stack by 2. SHR shifts TOS right into CARRY flag. AAA AAA AAAA AAAAAAAA AAAA AA AAA AAA AAA AAAA AA AAA AAA AAA AAAA AAAAA AAAAAAAA AAA AAA AAAA AA AAA AAA AAA AAAA AA AAA AAA AAA AAAA AAAAA AAA AAA AAAA AAAAA TOS 0 Category: ---> 3 2 1 0 ----> C (2/) : arithmetic/logical (single-length) / qFORTH macro (SHR) : MARC4 mnemonic / assembler instruction MARC4 opcode: 12 hex (SHR) Library implementation: CODE 2/ SHR END-CODE Stack effect: EXP ( n -- n/2 ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag: LSB of TOS is shifted into CARRY BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 1 See also: 2* SHL D2* D2/ ROR ROL 140 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2/ SHR Example: : TWO-DIVIDE 10 2/ 30h SWAP SHR SWAP ROR ; ( 10 -- 5 ( divide an 8-bit number: 'D2/' Macro : ( 30h -- 0 1h [CARRY flag set] ( 0 1 [CARRY] -- 18h ( 30h / 2 = 18h ! use 'D2/' ! ) ) ) ) ) For another example see '2*', 'SHL'. 03.01 141 MARC4 Programmer's Guide qFORTH Dictionary 2<ROT "Two-left-rote" Purpose: Moves the top 8-bit value to the third byte position on the EXP stack, ie. performs an 8-bit left rotate. Category: Stack operation (double-length) / qFORTH colon definition Library implementation: : 2<ROT ROT >R ROT >R ROT >R ROT R> R> R> ; ( d1 d2 d3 --- d1 d2h d3 ( d1 d2h d3 --- d1 d3 ( d1 d3 --- d1h d3 ( d1h d3 --- d3 d1 ( d3 d1 --- d3 d1 d2 Stack effect: EXP ( d1 d2 d3 -- d3 d1 d2 ) RET ( -- ) Stack changes: EXP: affected ( changed order of elements ) RET: use of 3 RET levels in between Flags: not affected X Y registers: not affected Bytes used: 14 See also: ROT <ROT 2ROT 142 ) ) ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2<ROT Example: : TWO-LEFT-ROT 11h 22h 33h 2<ROT ROT ; 03.01 ( -- 11h 22h 33h ( 11h 22h 33h -- 33h 11h 22h ( 33h 11h 22h -- 33h 12h 21h ) ) ) 143 MARC4 Programmer's Guide qFORTH Dictionary 2>R "Two-to-R" Purpose: Moves the top two 4-bit values from the Expression Stack and pushes them onto the top of the return stack. 2>R pops the EXP stack onto the RET stack. To avoid corrupting the RET stack and crashing the system, each use of 2>R MUST be followed by a subsequent 2R> ( or an equivalent 2R@ and DROPR ) within the same colon definition. Category: Stack operation (double-length) / assembler instruction MARC4 opcode: 28 hex Stack effect: EXP ( n1 n2 -- ) RET ( -- u|n2|n1 ) Stack changes: EXP: 2 elements are popped from the stack RET: 1 ( 8-bit ) entry is pushed onto the stack Flags: not affected X Y registers: not affected Bytes used: 1 See also: I >R R> 144 2R@ 2R> 3R@ 3>R 3R> 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2>R Example: : 2SWAP >R <ROT R> <ROT ; ( Swap 2nd byte with top ( d1 d2 -- n2_h d1 ( n2_h d1 -- d2 d1 ) ) ) : 2OVER 2>R 2DUP 2R> 2SWAP ; ( Duplicate 2nd byte onto top ( d1 d2 -- d1 ( d1 -- d1 d1 ( d1 d1 -- d1 d1 d2 ( d1 d1 d2 -- d1 d2 d1 ) ) ) ) ) 03.01 145 MARC4 Programmer's Guide qFORTH Dictionary 2@ "Two-fetch" Purpose: Copies the 8-bit value of a 2VARIABLE or 2ARRAY element to the stack. The MSN address of the selected variable is the TOS value. Category: Arithmetic/logical (double-length) / qFORTH macro Library implementation: CODE 2@ Y! [Y]@ [+Y]@ ( addr -- ( -- nh ( nh -- nh nl ) ) ) END-CODE Stack effect: EXP ( RAM_addr -- n_h n_l ) RET ( -- ) Stack changes: EXP: The top two elements will be changed. RET: not affected Flags: not affected X Y registers: The contents of the Y or X register may be changed. Bytes used: 3 See also: Other byte (double-length) qFORTH dictionary words, like D- D+ 2! D+! D-! D2/ D2* D< D> D<> D= D<= D>= D0= D0<> 146 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2@ Example 1: : StoreFetch 13h 43h 2! 43h 2@ 2DROP ( RAM [43] = 1 ; RAM [44] = 3 ( use var name instead of address ( -- 1 3 ) ) ) ( initialize the 8-bit counter ) ( increment the 8-bit counter ( until 20h is reached ... ) ) ; Example 2: 2VARIABLE Counter : DoubleCount 0 0 Counter 2! BEGIN 0 1 Counter D+! Counter 2@ 20h D= UNTIL ; 03.01 147 MARC4 Programmer's Guide qFORTH Dictionary 2ARRAY "Two-ARRAY" Purpose: Allocates RAM memory for storage of a short double-length ( 8-bit / byte ) array, using a 4-bit array index value. Therefore, the number of 8-bit array elements is limited to 16. The qFORTH syntax is as follows: <number> 2ARRAY <identifier> [ AT <RAM-Addr> ] At compile time, 2ARRAY adds <identifier> to the dictionary and ALLOTs memory for storage of <number> double-length values. At execution time, <identifier> leaves the RAM start address of the parameter field ( <identifier> [0] ) on the Expression Stack. The storage area allocated by 2ARRAY is not initialized. Category: Predefined data structure Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: ARRAY LARRAY 2LARRAY 2VARIABLE VARIABLE 148 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2ARRAY Example: 6 2ARRAY RawData 3 CONSTANT STEP : Init_RawData 15h 6 0 DO 2DUP I RawData INDEX 2! STEP M- LOOP 2DROP ; : Setup_RAM Init_RawData RawData [3] 2@ 50h D+ ; 03.01 ( RawData[0] ... RawData[5] ) ( RawData[0] := 15h ( RawData[1] := 12h ( RawData[2] := 0Fh ( RawData[3] := 0Ch ( RawData[4] := 09h ( RawData[5] := 06h ) ) ) ) ) ) 149 MARC4 Programmer's Guide qFORTH Dictionary 2CONSTANT "Two-CONSTANT" Purpose: Creates a double-length ( 8-bit ) constant definition. The qFORTH syntax is as follows: <byte_constant> 2CONSTANT <identifier> which assigns the 8-bit value <byte_constant> to <identifier>. Category: Predefined data structure Stack effect: EXP ( -- d ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: ARRAY, CONSTANT 150 at execution time 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2CONSTANT Example: 00h 2CONSTANT ZEROb ( define byte constants 01h 2CONSTANT ONEb ) : Emit_HexByte 2DUP 3 OUT SWAP 2 OUT SWAP ; ) ) \ Emit routine EXP: ( n1 n2 -- ( Duplicate & emit lower nibble : FIBONACCI ( Display 12 FIBONACCI nrs. ZEROb ONEb ( Set up for calculations 12 0 DO ( Set up loop -- 12 numbers Emit_HexByte ( Emit top 8-bit number 2SWAP 2OVER ( Switch for addition D+ ( Add top two 8-bit numbers LOOP ( Go back for next number Emit_HexByte ( Emit last number too 2DROP 2DROP ( Clean up the stack ; 03.01 ) ) ) ) ) ) ) ) ) 151 MARC4 Programmer's Guide qFORTH Dictionary 2DROP "Two-DROP" Purpose: Removes one double-length ( 8-bit ) value or two single-length ( 4-bit ) values from the Expression Stack. Category: Stack operation (double-length) / qFORTH macro Library implementation: CODE 2DROP DROP DROP END-CODE Stack effect: EXP ( n1 n2 -- ) RET ( -- ) Stack changes: EXP: 2 elements are popped from the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 2 See also: DROP 3DROP 152 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2DROP Example: : TWO-DROP 19H 11H 2DROP ; 03.01 ( Simple example for 2DROP ( -- 19h 11h ( 19h 11h -- 19h ) ) ) 153 MARC4 Programmer's Guide qFORTH Dictionary 2DUP "Two-doop" Purpose: Duplicates the double-length ( 8-bit ) value on top of the Expression Stack. Category: Stack operation (double-length) / qFORTH macro Library implementation: CODE 2DUP OVER OVER END-CODE Stack effect: EXP ( d -- d d ) RET ( -- ) Stack changes: EXP: top 2 elements are pushed again onto the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 2 See also: DUP 3DUP 154 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2DUP Example: 2VARIABLE CounterValue ( 8-bit counter value ) : Update_Byte 2DUP 2@ 2SWAP 18 2SWAP D+! ; ) ) ) ) ) ( addr -- current value ( addr -- addr addr ( addr addr -- d addr ( d addr -- d 18 addr ( d 18 addr -- d : Task_5 CounterValue Update_Byte 3 OUT 2 OUT ; 03.01 ( -- d ) 155 MARC4 Programmer's Guide qFORTH Dictionary 2LARRAY "Two-long-ARRAY" Purpose: Allocates RAM space for storage of a double-length ( 8-bit ) long array which has an 8-bit index to access the 8-bit array elements (more than 16 elements). The qFORTH syntax is as follows <number> 2LARRAY <identifier> [ AT <RAM address> ] At compile time, 2LARRAY adds <identifier> to the dictionary and ALLOTs memory for storage of <number> double-length values. At execution time, <identifier> leaves the RAM start address of the array ( <identifier> [0] ) on the Expression Stack. The storage area ALLOTed by 2LARRAY is not initialized. Category: Predefined data structure Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: ARRAY 2ARRAY LARRAY 156 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2LARRAY Example: 25 2LARRAY VarText 20 2CONSTANT StrLength ROMCONST FixedText StrLength, " Long string example " , : TD- D- IF ROT 1- <ROT THEN ; : TD+ D+ IF ROT 1+ <ROT THEN ; : ROM_Byte@ 3>R 3R@ TABLE ;; ( subtract 8 from 12-bit. ( add 8-bit to a 12-bit value. ) ) ( keep ROMaddr on EXP; fetch char. ) : CopyString FixedText ROM_Byte@ 2>R 2R@ TD+ BEGIN ROM_Byte@ 2R> 1 M- 2>R 2R@ VarText INDEX 2! 0 1 TD- 2R@ D0= UNTIL DROPR 3DROP ; ( copy string from ROM into RAM array) ( get string length. ) ( move length/index to return stack ) ( length + start addr=ROMaddr [lastchar]) ( ) ( get ASCII char ) ( index := index - 1 ) ( store char in array. ) ( ROMaddr := ROMaddr - 1 ) ( index = 0 ? ) ( ) ( skip count & ROMaddr. ) 03.01 157 MARC4 Programmer's Guide qFORTH Dictionary 2NIP "Two-NIP" Purpose: Removes the second double-length ( 8-bit ) value from the Expression Stack. Category: Stack operation (double-length) / qFORTH macro Library implementation: CODE 2NIP ROT DROP ROT DROP END-CODE Stack effect: EXP ( d1 d2 -- d2 ) RET ( -- ) Stack changes: EXP: 2 elements are popped from the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 4 See also: NIP SWAP DROP 158 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2NIP Example: : Cancel-2nd-Byte 9 25 5Ah 2NIP ; 03.01 ( -- 9 19h 5Ah ( 9 19h 5Ah -- 9 5Ah ) ) 159 MARC4 Programmer's Guide qFORTH Dictionary 2OVER "Two-OVER" Purpose: Copies the second double-length ( 8-bit ) value onto the top of the Expression Stack. Category: Stack operation (double-length) / qFORTH colon definition Library implementation: : 2OVER 2>R 2DUP 2R> 2SWAP ; ( d1 d2 -- d1 ) ( d1 -- d1 d1 ) ( d1 d1 -- d1 d1 d2 ) ( d1 d1 d2 -- d1 d2 d1 ) Stack effect: EXP ( d1 d2 -- d1 d2 d1 ) RET ( -- ) Stack changes: EXP: 2 elements are pushed onto the stack RET: 3 levels are used in between Flags: not affected X Y registers: not affected Bytes used: 8 See also: 2DUP 2SWAP OVER 160 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2OVER Example: : Double-2nd-Byte 12H 19H 2OVER ; 03.01 ( -- 12h 19h ( 12h 19h -- 12h 19h 12h ) ) 161 MARC4 Programmer's Guide qFORTH Dictionary 2R> "Two-R-from" Purpose: Moves the double-length ( 8-bit ) value from the Return Stack onto the Expression Stack. 2R@, 2R> and 2>R allow use of the Return Stack as a temporary storage for 8-bit values. 2R> removes elements from the Return Stack onto the Expression Stack. To avoid corrupting the Return Stack and crashing the program, each use of 2R> MUST be preceded by a 2>R within the same colon definition. Category: Stack operation (double-length) / qFORTH macro Library implementation: CODE 2R> 2R@ DROPR END-CODE Stack effect: EXP ( -- n1 n2 ) RET ( u|n2|n1 -- ) Stack changes: EXP: 2 elements are pushed onto the stack RET: 1 ( 8-bit ) entry is popped from the stack Flags: not affected X Y registers: not affected Bytes used: 2 See also: I >R R> 162 2R@ 2>R 3R@ 3>R 3R> 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2R> Example 1: Library implementation: of +LOOP: CODE +LOOP 2R> ROT + OVER CMP_LT 2>R (S)BRA _$DO _$LOOP: DROPR END-CODE ( Move limit & index on EXP ) ( Check for index < limit ) ( Skip limit & index from RET ) ( Duplicate 2nd byte onto top ( d1 d2 -- d1 ( d1 -- d1 d1 ( d1 d1 -- d1 d1 d2 ( d1 d1 d2 -- d1 d2 d1 ) ) ) ) ) Example 2: : 2OVER 2>R 2DUP 2R> 2SWAP ; 03.01 163 MARC4 Programmer's Guide qFORTH Dictionary 2R@ "Two-R-fetch" Purpose: Takes a copy of the 8-bit value on top of the Return Stack and pushes the double-length ( 8-bit ) value on the Expression Stack. 2R@, 2R> and 2>R allow use of the Return Stack as a temporary storage for 8-bit values. Category: Stack operation (double-length) / assembler instruction MARC4 opcode: 2A hex Stack effect: EXP ( -- n1 n2 ) RET ( u|n1|n2 -- u|n1|n2 ) Stack changes: EXP: 2 elements are pushed onto the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: I 164 >R R> 2>R 2R> 3R@ 3>R 3R> 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2R@ Example: : 2OVER 2>R 2DUP 2R@ DROPR 2SWAP ; 03.01 ( Duplicate 2nd byte onto top ( d1 d2 -- d1 ( d1 -- d1 d1 ( d1 d1 -- d1 d1 d2 ( d1 d1 d2 -- d1 d2 d1 ) ) ) ) ) 165 MARC4 Programmer's Guide qFORTH Dictionary 2ROT "Two-rote" Purpose: Moves the third double-length ( 8-bit ) value onto the top of the Expression Stack. Category: Stack operation (double-length) / qFORTH macro definition Library implementation: CODE 2ROT 2>R 2SWAP 2R> 2SWAP END-CODE ( d1 d2 d3 -- d2 d1 ) ( d2 d1 -- d2 d3 d1 ) Stack effect: EXP RET ( -- ) Stack changes: EXP: affected ( changes order of elements ) RET: affected (3 levels are used in betweeen) Flags: not affected X Y registers: not affected Bytes used: 5-7 See also: 2<ROT <ROT ROT 166 ( d1 d2 d3 --- d2 d3 d1 ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2ROT Example: : Rotate-Byte-to-Top 11h 22h 33h 2ROT ; 03.01 ( -- 11h 22h 33h ( 11h 22h 33h -- 22h 33h 11h ) ) 167 MARC4 Programmer's Guide qFORTH Dictionary 2SWAP "Two-SWAP" Purpose: Exchanges the top two double-length ( 8-bit ) values on the Expression Stack. Category: Stack operation (double-length) / qFORTH colon definition Library implementation: : 2SWAP >R <ROT R> <ROT ( d1 d2 -- d2h d1 ) ( d2h d1 -- d2 d1 ) ; Stack effect: EXP ( d1 d2 -- d2 d1 ) RET ( -- ) Stack changes: EXP: affected ( changes order of elements ) RET: affected (1 level is used intermediately) Flags: not affected X Y registers: not affected Bytes used: 8 See also: SWAP 168 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2SWAP Example: : Swap-Bytes 3 12h 19h 2SWAP ; 03.01 ( -- 3 12h 19h ( 3 12h 19h -- 3 19h 12h ) ) 169 MARC4 Programmer's Guide qFORTH Dictionary 2TUCK "Two-TUCK" Purpose: Tucks the top 8-bit ( double-length ) value under the second byte on the Expression Stack, the counterpart to 2OVER. Category: Stack operation (double-length) / qFORTH colon definition Library implementation: : 2TUCK 3>R 2R@ ROT 3R> ; ( n1 n2 n3 n4 -- n1 ( n1 -- n1 n3 n4 ( n1 n3 n4 -- n3 n4 n1 ) ( n3 n4 n1 -- n3 n4 n1 n2 n3 n4 ( n3 n4 n1 n2 n3 n4 -- d2 d1 d2 ) ) ) ) Stack effect: EXP ( d1 d2 -- d2 d1 d2 ) RET ( -- ) Stack changes: EXP: Two 4-bit elements are pushed under the 2nd byte RET: affected ( 1 level is used intermediately ) Flags: not affected X Y registers: not affected Bytes used: 6 See also: TUCK 2OVER 170 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2TUCK Example: : Tuck-under-2nd-Byte 11H 22H 2TUCK ; 03.01 ( -- 11h 22h ( 11h 22h -- 22h 11h 22h ) ) 171 MARC4 Programmer's Guide qFORTH Dictionary 2VARIABLE "Two-VARIABLE" Purpose: Allocates RAM space for storage of one double-length (8-bit) value. The qFORTH syntax is as follows 2VARIABLE <name> [ AT <address.> ] [ <number> ALLOT ] At compile time, 2VARIABLE adds <name> to the dictionary and ALLOTs memory for storage of one double-length value. If AT <address> is appended, the variable/s will be placed at a specific address ( i.e.: 'AT 40h' ). If <number> ALLOT is appended, a total of 2 * ( <number> + 1 ) 4-bit memory locations will be allocated. At execution time, <name> leaves the start address of the parameter field on the Expression Stack. The storage area allocated by 2VARIABLE is not initialized. Category: Predefined data structure Stack effect: EXP ( -- d ) at execution time RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: ALLOT VARIABLE 2ARRAY ARRAY 172 03.01 MARC4 Programmer's Guide qFORTH Dictionary 2VARIABLE Example: 2VARIABLE NoKeyCounter ( 8-bit variable ) : No_KeyPressed 0 0 NoKeyCounter 2! NoKeyCounter 2@ 1 M+ IF NoKeyOver THEN NoKeyCounter 2! ; ( initialise to $00 ( increment by 1 ( 'call' NoKeyOver on overflow ( store the result back ) ) ) ) 03.01 173 MARC4 Programmer's Guide qFORTH Dictionary 3! "Three-store" Purpose: Store the top 3 nibbles into a 12-bit variable in RAM. The most significant digit address of that array has to be the TOS value. Category: Memory operation (triple-length) / qFORTH colon definition Library implementation: : 3! Y! SWAP ROT [Y]! [+Y]! [+Y]! ( nh nm nl addr -- nh nm nl ( nh nm nl -- nl nm nh ( nl nm nh -- nl ( nl -- ) ) ) ) ; Stack effect: EXP RET Stack changes: EXP: 5 elements are popped from the stack RET: not affected Flags: not affected X Y registers: The contents of the Y register will be changed. Bytes used: 7 See also: 3@ T+! T-! TD+! TD-! 174 ( nh nm nl addr -- ) ( -- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary 3! Example: 3 ARRAY 3Nibbles AT 40h ( 3 nibbles at fixed locations. ) : Triples 123h 3Nibbles 3! 321h 3Nibbles T+! 3Nibbles 3@ 3DROP 123h 3Nibbles T-! ; ) ) ) ) 03.01 ( store 123h in the 3 nibbles array. ( 123h + 321h = 444h ( fetch the result onto expression stack . ( 444h - 123h = 321h 175 MARC4 Programmer's Guide qFORTH Dictionary 3>R "Three-to-R" Purpose: Removes the top 3 values from the Expression Stack and places them onto the Return Stack. 3>R unloads the EXP stack onto the RET stack. To avoid corrupting the RET stack and crashing the system, each use of 3>R MUST be followed by a subsequent 3R> within the same colon definition. Category: Stack operation (triple-length) / assembler instruction MARC4 opcode: 29 hex Stack effect: EXP RET Stack changes: EXP: 3 elements are popped from the top of the stack RET: 1 entry ( 3 elements ) is pushed onto the stack Flags: not affected X Y registers: not affected Bytes used: 1 See also: I 176 >R ( n1 n2 n3 -- ( -- n3|n2|n1 R> 2R@ 2>R 2R> ) ) 3R@ 3R> 03.01 MARC4 Programmer's Guide qFORTH Dictionary 3>R Example: : 2TUCK 3>R 2R@ ROT 3R> ; 03.01 \ TUCK top 8-bit value under the 2nd byte ( n1 n2 n3 n4 -- n1 ) ( n1 -- n1 n3 n4 ) ( n1 n3 n4 -- n3 n4 n1 ) ( n3 n4 n1 -- n3 n4 n1 n2 n3 n4 ) ( d1 d2 -- d2 d1 d2 ) 177 MARC4 Programmer's Guide qFORTH Dictionary 3@ "Three-fetch" Purpose: Fetch a 12-bit variable in RAM and push it on the Expression Stack. The most significant digit address of the variable must be on TOS. Category: Memory operation (triple-length) / qFORTH macro Library implementation: CODE 3@ Y! [Y]@ [+Y]@ [+Y]@ ( addr -- ( -- nh ( nh -- nh nm ( nh nm -- nh nm nl ) ) ) ) END-CODE Stack effect: EXP ( addr -- nh nm nl ) RET ( -- ) Stack changes: EXP: 2 elements are popped from and 3 are pushed onto the expression stack. RET: not affected Flags: not affected X Y registers: The contents of the Y or X register may be changed. Bytes used: 5 See also: 3! T+! T-! 178 03.01 MARC4 Programmer's Guide qFORTH Dictionary 3@ Example: 3 ARRAY 3Nibbles AT 40h ( 3 nibbles at fixed locations in RAM ) : Triples 123h 3Nibbles 3! 321h 3Nibbles T+! 3Nibbles 3@ 3DROP 123h 3Nibbles T-! 3Nibbles 3@ 3DROP ; ) ) ) ) ) 03.01 ( store 123h in the 3 nibbles array. ( 123h + 321h = 444h ( fetch the result onto expression stack. ( 444h - 123h = 321h ( fetch the result onto expression stack. 179 MARC4 Programmer's Guide qFORTH Dictionary 3DROP "Three-DROP" Purpose: Removes one 12-bit or three 4-bit values from the Expression Stack. Category: Stack operation (triple-length) / qFORTH macro Library implementation: CODE 3DROP DROP DROP DROP END-CODE Stack effect: EXP ( n1 n2 n3 -- ) RET ( -- ) Stack changes: EXP: 3 elements are popped from the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 3 See also: DROP 2DROP DROPR 180 03.01 MARC4 Programmer's Guide qFORTH Dictionary 3DROP Example: : Skip-top-3-nibbles 3 4 6 7 3DROP ; 03.01 ( -- 3 4 6 7 ( 3 4 6 7 -- 3 ) ) 181 MARC4 Programmer's Guide qFORTH Dictionary 3DUP "Three-doop" Purpose: Duplicates the 12-bit address value on top of the Expression Stack. Category: Stack operation (triple-length) / qFORTH colon definition Library implementation: CODE 3DUP 3>R 3R@ 3R> ( t -- t t ) END-CODE Stack effect: EXP RET Stack changes: EXP: 3 elements are pushed onto the stack RET: affected ( 1 level is used intermediately ) Flags: not affected X Y registers: not affected Bytes used: 4 See also: DUP 2DUP 182 ( n1 n2 n3 -- n1 n2 n3 n1 n2 n3 ( -- ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary 3DUP Example: ROMCONST Message 5 , " Error " , : Duplicate-ROMaddr Message 3DUP ROMByte@ NIP ; 03.01 ( duplicate ROM address on stack ( fetch string length ( get string length as 4-bit value ) ) ) 183 MARC4 Programmer's Guide qFORTH Dictionary 3R> "Three-R-from" Purpose: Moves the top 3 nibbles from the Return Stack and puts them onto the Expression Stack. 3R> unloads the Return Stack onto the Expression Stack. To avoid corrupting the Return Stack and crashing the system, each use of 3R> MUST be preceded by a 3>R within the same colon definition. Category: Stack operation (triple-length) / qFORTH macro Library implementation: CODE 3R> 3R@ DROPR END-CODE Stack effect: EXP ( -- n1 n2 n3 ) RET ( n3|n2|n1 -- ) Stack changes: EXP: 3 elements are pushed onto the stack RET: 1 element (3 nibbles) is popped from the stack Flags: not affected X Y registers: not affected Bytes used: 2 See also: I 184 >R R> 2R@ 2>R 2R> 3R@ 3>R 03.01 MARC4 Programmer's Guide qFORTH Dictionary 3R> Example: CODE 3DUP 3>R 3R@ 3R> END-CODE ( Library implementation: of 3DUP ( t -- ( -- t ( t -- t t ) ) ) ) ROMCONST StringExample 6 , " String " , : Duplicate-ROMAddr StringExample 3DUP 0 DTABLE@ NIP ; 03.01 ( duplicate ROM address on stack ( fetch 1st value of ROM string ( get string length as 4-bit value ) ) ) 185 MARC4 Programmer's Guide qFORTH Dictionary 3R@ "Three-R-fetch" Purpose: Copies the top 3 values from the Return Stack and leaves the 3 values on the Expression Stack. 3R@ fetches the topmost value on the Return Stack. 3R@, 3R> and 3>R allow use of the Return Stack as a temporary storage for values within a colon definition. Category: Stack operation (triple-length) / assembler instruction MARC4 opcode: 2B hex Stack effect: EXP ( -- n1 n2 n3 ) RET ( n3|n2|n1 -- n3|n2|n1 ) Stack changes: EXP: 3 elements are pushed onto the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: I 186 >R R> 2R@ 2>R 2R> - 3>R 3R> 03.01 MARC4 Programmer's Guide qFORTH Dictionary 3R@ Example 1: CODE 3DUP 3>R 3R@ 3R> END-CODE ( Library implementation: of 3DUP ( t -- ( -- t ( t -- t t ) ) ) ) Example 2: : ROM_Byte@ ( ROM_addr -- ROM_addr ROM_byte ) 3>R 3R@ TABLE ;; ( ROM_addr -- ( -- ROM_addr ( ROM_addr -- ROM_addr ROM_byte ( back to 'CALL', implicite EXIT 03.01 ) ) ) ) 187 MARC4 Programmer's Guide qFORTH Dictionary : "Colon" Purpose: Begins compilation of a new colon definition, i.e. defines the entry point of a new subroutine. Used in the form : <name> ... <words> ... ; ':' creates a new dictionary entry for <name> and compiles the sequence between <name> and ';' into this new definition. If no errors are encountered during compilation, the new colon definition may itself be used in subsequent colon definitions. On execution of a colon definition, the current program counter is pushed onto the Return Stack. Category: Predefined data structure Stack effect: EXP RET ( --) ( -- ReturnAddress Stack changes: EXP: RET: not affected The return address to the word which executes this colon definition is pushed onto the stack. Flags: not affected X Y registers: not affected Bytes used: 0 See also: ; INT0 .. INT7 188 ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary : Example: : COLON-Example 3 BEGIN 1+ DUP 9 = UNTIL ; 03.01 ( BEGIN a colon definition ( 3 = initial start value ( increment count 3 -> 9 ( continue until condition is true ( END of DEFINITION with a SEMICOLON ) ) ) ) ) 189 MARC4 Programmer's Guide qFORTH Dictionary ; EXIT RTI "Semicolon" Purpose: Terminates a qFORTH colon definition, i.e. exits the current colon definition. ';' compiles to EXIT at the end of a normal colon definition. It then marks the new definition as having been successfully compiled so that it can be found in the dictionary. ';' compiles to RTI which automatically sets the I_ENABLE flag at the end of an INT0 .. INT7 or $RESET definition. When EXIT is executed, program control passes out of the current definition. EXIT may NOT be used inside any iterative DO loop structure, but it may be used in control structures, such as: BEGIN ... WHILE, REPEAT, ... UNTIL, ... AGAIN, and IF ... [ ELSE ... ] THEN Category: (;) : Predefined data structure (RTI/EXIT): MARC4 mnemonic MARC4 opcode: EXIT : 25 hex Stack effect: EXP RET ( --) ( Return address --) Stack changes: EXP: RET: not affected The address on top of the stack is moved into the PC Flags: I_ENABLE flag Set after execution of the RTI instruction at the end of an INTx (x=0..7) or $RESET definition. CARRY and BRANCH flags are not affected X Y registers: not affected Bytes used: 1 See also: : ?LEAVE -?LEAVE ;; 190 RTI : 1D hex 03.01 MARC4 Programmer's Guide qFORTH Dictionary ; EXIT RTI Example: : Colon-Def 3 BEGIN 1+ DUP 9 = UNTIL ; ( 3 is the initial start value ( increment count from 3 -> 9 ( Repeat UNTIL condition is TRUE ( EXIT from the colon def. with ';' ) ) ) ) : INT5 DI Colon-Def ; ( Register contents saved automatically. ( disable Interrupts ( execute 'colon def' ( RTI - enables all interrupts ) ) ) ) 03.01 191 MARC4 Programmer's Guide qFORTH Dictionary ;; "Double-Semicolon" Purpose: Suppresses the code generation of an EXIT or RTI at the end of a colon definition. This function is typically used after any TABLE instruction (see ROMByte@, DTABLE@), in C computed goto jump tables (see EXECUTE) or in the $AUTOSLEEP definition. Category: Predefined data structure Stack effect: EXP RET ( -- ) ( -- ) Stack changes: EXP: RET: not affected not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: : ; $AUTOSLEEP, ROMByte@, DTABLE@ 192 03.01 MARC4 Programmer's Guide qFORTH Dictionary ;; Example: : Do_Incr DROPR Time_count 1*! \ Skip Return address [N]; : Do_Decr DROPR Time_count 1-! [N]; : Do_Reset DROPR 0 Time_Count ! [N]; : Jump_Table Do_Nothing Do_Inrc Do_Decr Do_Reset ;; AT FF0h \ Do not generate an EXIT : Exec_Example ( n - - ) >R ' Jump_Table R> 2* M+ \ calculate vector address EXECUTE ; 03.01 193 MARC4 Programmer's Guide qFORTH Dictionary < CMP_LT "Less-than" Purpose: 'Less-than' comparison of the top two 4-bit values on the stack. If the second value on the stack is less than the top of stack value, then the BRANCH flag in the CCR is set. Unlike standard FORTH, whereby a BOOLEAN value (0 or 1), depending on the comparison result, is pushed onto the stack. Category: (<) (CMP_LT) : Comparison (single-length) / qFORTH macro : MARC4 mnemonic Library implementation: CODE < CMP_LT DROP END-CODE ( n1 n2 -- n1 [BRANCH flag] ( n1 -- ) ) MARC4 opcode: 08 hex (CMP_LT) Stack effect: < CMP_LT both EXP EXP RET Stack changes: EXP: < 2 elements are popped from the stack CMP_LT top element is popped from the stack not affected RET: ( n1 n2 -- ( n1 n2 -- n1 ( -- Flags: CARRY flag affected BRANCH flag Set, if (n1 < n2) X Y registers: not affected Bytes used: 1-2 See also: <> = <= >= > <> D<> D>= D<= 194 ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary < CMP_LT Example: : LESS-THAN 5 7 CMP_LT 8 6 < 5 CMP_LT DROP ; 03.01 ( Check 5 < 7 and 8 < 6 and 5<5 ( 5 7 -- 5 [ BRANCH and CARRY set ] ( 5 8 6 -- 5 [ BRANCH is NOT set ] ( 5 5 -- 5 ) ) ) ) 195 MARC4 Programmer's Guide qFORTH Dictionary <= CMP_LE "Less-than-equal" Purpose: 'Less-than-or-equal' comparison of the top two 4-bit values on the stack. If the 2nd value on the stack is less than, or equal to the top of stack value, then the BRANCH flag in the condition code register (CCR) is set. Unlike standard FORTH, whereby a BOOLEAN value (0 or 1), depending on the comparison result, is pushed onto the stack. Category: (<=) (CMP_LE) : Comparison (single-length) / qFORTH macro : MARC4 mnemonic Library implementation: CODE <= CMP_LE ( n1 n2 -- n1 [BRANCH flag]) DROP ( n1 -- ) END-CODE MARC4 opcode: 09 hex (CMP_LE) Stack effect: <= CMP_LE both EXP EXP RET Stack changes: EXP: <= 2 elements are popped from the stack CMP_LE top element is popped from the stack not affected RET: ( n1 n2 -- ( n1 n2 -- n1 ( -- Flags: CARRY flag affected BRANCH flag set, if (n1 <= n2) X Y registers: not affected Bytes used: 1-2 See also: D<= 196 ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary <= CMP_LE Example: : LESS-EQUALS 7 5 CMP_LE 7 <= 8 9 <= ; 03.01 ( show 7 <= 5 and 7 <= 7 and 8 <= 9 ( 7 5 -- 7 [ BRANCH flag NOT set ] ( 7 7 -- [ BRANCH flag set ] ( 8 9 -- [ BRANCH and CARRY flag set ] ) ) ) ) 197 MARC4 Programmer's Guide qFORTH Dictionary <> CMP_NE "Not-equal" Purpose: Inequality test for the top two 4-bit values on the stack. If the 2nd value on the stack is NOT equal to the top of stack value, then the BRANCH flag in the CCR is set. Unlike standard FORTH, whereby a BOOLEAN value (0 or 1), depending on the comparison result, is pushed onto the stack. Category: (<>) : Comparison (single-length) / qFORTH macro (CMP_NE) : MARC4 mnemonic Library implementation: CODE <> CMP_NE ( n1 n2 -- n1 [BRANCH flag]) DROP ( n1 -- ) END-CODE MARC4 opcode: 07 hex (CMP_NE) Stack effect: <> CMP_NE both EXP EXP RET Stack changes: EXP: <> 2 elements are popped from the stack CMP_NE top element is popped from the stack not affected RET: ( n1 n2 -- ( n1 n2 -- n1 ( --) Flags: CARRY flag affected BRANCH flag set, if (n1 <> n2) X Y registers: not affected Bytes used: 1-2 See also: 0<> 0= D<> 198 ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary <> CMP_NE Example: : NOT-EQUALS 7 5 CMP_NE 7 <> 8 9 <> ; 03.01 ( show 7 <> 5 and 7 <> 7 and 8 <> 9 ( 7 5 -- 7 [ BRANCH flag set ] ( 7 7 -- [ BRANCH flag NOT set ] ( 8 9 -- [ BRANCH and CARRY flag set ] ) ) ) ) 199 MARC4 Programmer's Guide qFORTH Dictionary <ROT "Left-rote" Purpose: MOVE the TOS value to the third stack position, i.e. performs a LEFTWARD rotation Category: Stack operation (single-length) / qFORTH macro Library implementation: CODE <ROT ROT ROT END-CODE Stack effect: EXP ( n1 n2 n3 -- n3 n1 n2) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 2 See also: ROT 2<ROT 2ROT 200 03.01 MARC4 Programmer's Guide qFORTH Dictionary <ROT Example: : TD+ D+ IF ROT 1+ <ROT THEN ; 03.01 \ Add an 8-bit offset to a 12-bit value \ Add the lower 8-bits ( t1 d2 -- n1 d3 ) \ IF an overflow to the 9th bit occurs, THEN ( n1 d3 -- d3 n1 ) ( d3 n1 -- d3 n1+1 ) ( d3 n1+1 -- n1+1 d3 ) ( n3 d3 -- t3 ) 201 MARC4 Programmer's Guide qFORTH Dictionary = CMP_EQ "Equal" Purpose: Equality test for the top two 4-bit values on the stack. If the 2nd value on the stack is equal to the top of stack value, then the BRANCH flag in the CCR is set. This is unlike standard FORTH, whereby a BOOLEAN value (0 or 1), depending on the comparison result, is pushed onto the stack. Category: (=) (CMP_EQ) Library implementation: CODE = CMP_EQ ( n1 n2 -- n1 [BRANCH flag] DROP ( n1 -- END-CODE MARC4 opcode: 06 hex Stack effect: Stack changes: : Comparison (single-length) / qFORTH macro : MARC4 mnemonic (CMP_EQ) = EXP ( n1 n2 -- ( n1 n2 -- n1 ( -- ) ) ) CMP_EQ both EXP RET EXP: = 2 elements are popped from the stack CMP_EQ top element is popped from the stack not affected RET: Flags: CARRY flag affected BRANCH flag set, if (n1 = n2) X Y registers: not affected Bytes used: 1-2 See also: 0<> 0= D<> D= 202 ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary = CMP_EQ Example: : EQUAL-TO 7 5 CMP_EQ 7 = 8 9 = ; 03.01 ( show 7 = 5 and 7 = 7 and 8 = 9 ( 7 5 -- 7 [ BRANCH flag NOT set ] ( 7 7 -- [ BRANCH flag set ] ( 8 9 -- [ CARRY flag set ] ) ) ) ) 203 MARC4 Programmer's Guide qFORTH Dictionary > CMP_GT "Greater-than" Purpose: 'Greater-than' comparison of the top two 4-bit values on the stack. If the 2nd value on the stack is greater than the top of stack value, then the BRANCH flag in the CCR is set. This is unlike standard FORTH, whereby a BOOLEAN value (0 or 1), depending on the comparison result, is pushed onto the stack. Category: (>) (CMP_GT) : Comparison (single-length) / qFORTH macro : MARC4 mnemonic Library implementation: CODE > CMP_GT ( n1 n2 -- n1 [BRANCH flag]) DROP ( n1 -- ) END-CODE MARC4 opcode: 0A hex Stack effect: > CMP_GT both EXP EXP RET Stack changes: EXP: > CMP_GT RET: 2 elements are popped from the stack top element is popped from the stack not affected Flags: CARRY flag affected BRANCH flag set, if (n1 > n2) X Y registers: not affected. Bytes used: 1-2 See also: 204 (CMP_GT) ( n1 n2 -- ( n1 n2 -- n1 ( -- ) ) ) < <> = >= <> D> D>= D<> D< 03.01 MARC4 Programmer's Guide qFORTH Dictionary > CMP_GT Example: : GREATER-THAN 5 7 CMP_GT 8 6 > 5 CMP_GT DROP ; 03.01 ( check 5 > 7 and 8 > 6 and 5 > 5 ( 5 7 -- 5 [ CARRY set ] ( 5 6 8 -- 5 [ BRANCH set ] ( 5 5 -- ) ) ) ) 205 MARC4 Programmer's Guide qFORTH Dictionary >= CMP_GE "Greater-or-equal" Purpose: 'Greater-than-or-equal' comparison of the top two 4-bit values on the stack. If the 2nd value on the stack is greater than or equal to the top of stack value, then the BRANCH flag in the condition code register (CCR) is set. Unlike standard FORTH, whereby a BOOLEAN value (0 or 1), depending on the comparison result, is pushed onto the stack. Category: (>=) : Comparison (single-length) / qFORTH macro (CMP_GE) : MARC4 mnemonic Library implementation: CODE >= CMP_GE ( n1 n2 -- n1 [BRANCH flag]) DROP ( n1 -- ) END-CODE MARC4 opcode: 0B hex (CMP_GE) Stack effect: >= CMP_GE both EXP EXP RET Stack changes: EXP: >= 2 elements are popped from the stack CMP_GE top element is popped from the stack not affected RET: ( n1 n2 -- ( n1 n2 -- n1 ( -- Flags: CARRY flag affected BRANCH flag set, if (n1 >= n2) X Y registers: not affected. Bytes used: 1-2 See also: <> = <= < > <> D<> D>= D<= 206 ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary >= CMP_GE Example: : GREATER-THAN-EQUALS 7 5 CMP_GE 7 >= 8 9 >= ; 03.01 ( show 7 >= 5 and 7 >= 7 and 8 >= 9 ( 7 5 -- 7 [ BRANCH flag set ] ( 7 7 -- [ BRANCH flag set ] ( 8 9 -- [ CARRY flag set ] ) ) ) ) 207 MARC4 Programmer's Guide qFORTH Dictionary >R "To-R" Purpose: Moves the top 4-bit value from the Expression Stack and pushes it onto the Return Stack. >R pops the EXP stack onto the RET stack. To avoid corrupting the RET stack and crashing the program, each use of >R must be followed by a subsequent R> within the same colon definition. Category: Stack operation / assembler instruction MARC4 opcode: 22 hex Stack effect: EXP RET Stack changes: EXP: top element is popped from the stack RET: One element is pushed onto the stack Flags: not affected X Y registers: not affected Bytes used: 1 See also: I - R> 2R@ 2>R 2R> 3R@ 3>R 3R> 208 ( n1 -- ) ( -- u|u|n1 ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary >R Example: The sequence 3 1 >R 1- R> ( -- 3 1 ) ( 3 1 -- 2 1) temporarily moves the top value on the stack to the Return Stack so that the second value on the stack can be decremented. : 2<ROT ROT >R ROT >R ROT >R ROT R> R> R> ; : JUGGLE-BYTES 11h 22h 33h 2<ROT 2SWAP 2OVER ; 03.01 \ Move top byte to 3rd position on stack ( d1 d2 d3 -- d1 d2h d3 ) ( d1 d2h d3 -- d1 d3 ) ( d1 d3 -- d1h d3 ) ( d1h d3 -- d3 d1 ) ( d3 d1 -- d3 d1 d2 ) ( -- 11h 22h 33h ( 11h 22h 33h -- 33h 11h 22h ( 33h 11h 22h -- 33h 22h 11h ( 33h 22h 11h -- 33h 22h 11h 22h ) ) ) ) 209 MARC4 Programmer's Guide qFORTH Dictionary ?DO "Query-DO" Purpose: Indicates the start of a ( conditional ) iterative loop. ?DO is used only within a colon definition in a pair with LOOP or +LOOP. The two numbers on top of the stack at the time ?DO is executed determine the number of times the loop repeats. The value on top is the initial loop index and the next value is the loop limit. If the initial loop index is equal to the limit, the loop is not executed ( unlike DO ). The control is transfered to the statement directly following the LOOP or +LOOP statement and the two values are popped from the stack. Category: Control structure / qFORTH macro Library implementation: CODE ?DO OVER CMP_EQ 2>R (S)BRA_$LOOP _$DO: END-CODE Stack effect: EXP RET RET ( limit index -- ( -- u|limit|index ( -- ) ) ) if LOOP is executed if LOOP is not executed Stack changes: EXP: 2 elements are popped from the stack RET: 1 element is pushed onto the stack, if loop is executed and not affected, if loop is not executed Flags: CARRY flag affected BRANCH flag set, if (limit = index) X Y registers: not affected Bytes used: 5 See also: DO LOOP +LOOP 210 03.01 MARC4 Programmer's Guide qFORTH Dictionary ?DO Example: VARIABLE Counter : QUERY-DO 0 Counter ! 6 0 DO I0 ?DO Counter 1+! LOOP Counter @ 10 >= ?LEAVE LOOP ; 03.01 ( Counter := 0 ( repeat 6 times ( copy limit, index start = 0 ( first time not executed ( repeat,til count. >= 10 ) ) ) ) ) 211 MARC4 Programmer's Guide qFORTH Dictionary ?DUP "Query-doop" Purpose: Duplicates the top value on the stack only if it is not zero. ?DUP is equivalent to the standard FORTH sequence DUP IF DUP THEN but executes faster. ?DUP can simplify a control structure when it is used just before a conditional test (IF, WHILE or UNTIL). Category: Stack operation (single-length) / qFORTH macro Library implementation: CODE ?DUP DUP OR (S)BRA_$ZERO DUP _$ZERO: END-CODE Stack effect: IF TOS = 0 THEN EXP ELSE EXP RET ( 0 -- 0 ) ( n -- n n ) ( -- ) Stack changes: EXP: A copy of the non zero top value is pushed onto the stack RET: not affected Flags: CARRY flag affected BRANCH flag set, if (TOS = 0) X Y registers: not affected Bytes used: 4-5 See also: DUP 0= 0<> 212 03.01 MARC4 Programmer's Guide qFORTH Dictionary ?DUP Example: : ShowByte DUP 3 OUT SWAP ?DUP IF 2 OUT THEN SWAP ; 03.01 ( b_high b_low -- b_high b_low ( show a byte value as hexadecimal ( b_high b_low -- b_low b_high ( DUP and write only if non zero ( suppress leading zero display ( restore nibble sequence ) ) ) ) ) ) 213 MARC4 Programmer's Guide qFORTH Dictionary ?LEAVE "Query-leave" Purpose: Conditional exit from within a control structure if the previous tested condition was TRUE (ie. BRANCH flag is SET). ?LEAVE is the opposite to -?LEAVE (condition FALSE). The standard FORTH word sequence IF LEAVE ELSE word .. THEN is equivalent to the qFORTH sequence ?LEAVE word ... ?LEAVE transfers control just beyond the next LOOP, +LOOP or #LOOP or any other loop structure like BEGIN ... UNTIL, WHILE . REPEAT or BEGIN ... AGAIN if the tested condition is TRUE.E Category: Control structure / qFORTH macro Library implementation: CODE ?LEAVE (S)BRA _$LOOP ( Exit LOOP if BRANCH set ) END-CODE Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1-2 See also: -?LEAVE 214 03.01 MARC4 Programmer's Guide qFORTH Dictionary ?LEAVE Example: : QUERY-LEAVE 3 BEGIN 1+ DUP 9 = ?LEAVE AGAIN DROP ; 03.01 ( 3 = initial start value ( increment count 3 -> 9 ( keep current value on the stack ( when stack value = 9 then exit loop ( Indefinite repeat loop ( the index ) ) ) ) ) ) 215 MARC4 Programmer's Guide qFORTH Dictionary @ "Fetch" Purpose: Copies the 4-bit value at a specified memory location to the top of the stack. Category: Memory operation (single-length) / qFORTH macro Library implementation: CODE @ Y! [Y]@ ( addr -- ( -- n ) ) END-CODE Stack effect: EXP ( RAM_addr -- n ) RET ( -- ) Stack changes: EXP: 1 element is popped from the stack RET: not affected Flags: not affected X Y registers: The contents of the Y or X register may be changed. Bytes used: 2 See also: 2@ 3@ ! 216 03.01 MARC4 Programmer's Guide qFORTH Dictionary @ Example: VARIABLE DigitPosition 8 ARRAY Result : DisplayResult 7 DigitPosition ! BEGIN DigitPosition @ Fh <> WHILE DigitPosition @ DUP Result INDEX @ OVER OUT 1- DigitPosition ! REPEAT ; : Display 8 0 DO I DUP Result INDEX ! LOOP DisplayResult ; 03.01 ( write ARRAY 'Result' [7]..[0] to ports 7..0 ( initialize position ( REPEAT, 'til index = Fh ( get digit pos: 7 .. 0 ( get digit [7] .. [0] ( DPos val -- DPos val DPos ( data port -- Display digit ( decrement digit & store ( REPEAT always;stop at WHILE ) ) ) ) ) ) ) ) ) ( write 0 .. 7 to ARRAY 'Result' [0.] .. [7] ( 'call' display routine. ) ) 217 MARC4 Programmer's Guide qFORTH Dictionary AGAIN "AGAIN" Purpose: Part of the (infinite loop) BEGIN ... AGAIN control structure. AGAIN causes an unconditional branch in program control to the word following the corresponding BEGIN statement. Category: Control structure / qFORTH macro Library implementation: CODE AGAIN SET_BCF ( execute an unconditional branch ) (S)BRA _$BEGIN END-CODE Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag set BRANCH flag set X Y registers: not affected Bytes used: 2-3 See also: BEGIN UNTIL WHILE REPEAT 218 03.01 MARC4 Programmer's Guide qFORTH Dictionary AGAIN Example: : INFINITE-LOOP 3 BEGIN 1+ DUP 9 = ?LEAVE AGAIN ; 03.01 ( 3 = initial start value ( increment count 3 -> 9 ( keep current value on the stack ( when stack value = 9 then exit loop ( repeat unconditional ) ) ) ) ) 219 MARC4 Programmer's Guide qFORTH Dictionary ALLOT "ALLOT" Purpose: Allocate ( uninitialized ) RAM space for the two stacks and global data of the type VARIABLE or 2VARIABLE. Category: Predefined data structure Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: VARIABLE 2VARIABLE 220 03.01 MARC4 Programmer's Guide qFORTH Dictionary ALLOT Example: VARIABLE Limits 7 ALLOT ( Allocates 8 nibbles for the ( variable LIMITS ) ) VARIABLE R0 31 ALLOT VARIABLE S0 19 ALLOT ( allocate space for RETURN stack ( allot 20 nibbles for EXP stack ) ) 03.01 221 MARC4 Programmer's Guide qFORTH Dictionary AND "AND" Purpose: Bitwise AND of the top two 4-bit stack elements leaving the 4-bit result on top of the Expression Stack. Category: Arithmetic/logical (single-length) / assembler instruction MARC4 opcode: 05 hex Stack effect: EXP ( n1 n2 -- n1^n2 RET ( -- Stack changes: EXP: top element is popped from the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag set if (TOS = 0) X Y registers: not affected Bytes used: 1 See also: NOT OR XOR 222 ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary AND Example: : ERROR 3R@ 3#DO I OUT [ E 0 ] #LOOP ; : Logical 1001b 1100b AND 1000b <> IF ERROR 1010b 0011b AND 0010b <> IF ERROR 1001b 1100b OR 1101b <> IF ERROR 1010b 0011b OR 1011b <> IF ERROR 1001b 1100b XOR 0101b <> IF ERROR 1010b 0011b XOR 1001b <> IF ERROR ; 03.01 ( what shall happen in error case: ) ( show PC, where CPU fails ( suppress compiler warnings. ) ) THEN THEN THEN THEN THEN THEN 223 MARC4 Programmer's Guide qFORTH Dictionary ARRAY "ARRAY" Purpose: Allocates RAM space for storage of a short single-length ( 4-bit / nibble ) array, using a 4-bit array index value. Therefore the number of 4-bit array elements is limited to 16. The qFORTH syntax is as follows: <number> ARRAY <name> [ AT <RAM-Addr> ] At compile time, ARRAY adds <name> to the dictionary and ALLOTs memory for storage of <number> single-length values. At execution time, <name> leaves the RAM start address of the parameter field (<name> [0]) on the expression stack. The storage ALLOTed by an ARRAY is not initialized. Category: Predefined data structure Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: 2ARRAY LARRAY Index ERASE 224 03.01 MARC4 Programmer's Guide qFORTH Dictionary ARRAY Example: 6 ARRAY RawDATA AT 1Eh : Init_ARRAY 5 6 0 DO DUP I RawDATA INDEX ! 1- LOOP DROP ; ( RawDATA[0]...RawDATA[5] ) ( set initial value := 5 ( array index from 0 ... 5 ( indexed store ( decrement store value ) ) ) ) ( The result is: RawDATA[0] := 5 stored in RAM location 1E ( RawDATA[1] := 4 stored in RAM location 1F ( RawDATA[2] := 3 stored in RAM location 20 ( RawDATA[3] := 2 stored in RAM location 21 ( RawDATA[4] := 1 stored in RAM location 22 ( RawDATA[5] := 0 stored in RAM location 23 03.01 ) ) ) ) ) ) 225 MARC4 Programmer's Guide qFORTH Dictionary AT "AT" Purpose: Specifies the ABSOLUTE memory location AT where either a variable is placed in RAM, a L/U table, string or a qFORTH word ( subroutine / interrupt service routine ) is forced to be placed in the ROM area. Category: Predefined data structure Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: VARIABLE ARRAY ROMCONST 226 03.01 MARC4 Programmer's Guide qFORTH Dictionary AT Example: VARIABLE State AT 3 : CheckState State @ CASE 0 OF State 1+! ENDOF 15 OF State 1-! ENDOF ENDCASE [ Z ] ; Test_Status : INT0_Service Fh State ! BEGIN CheckState State 1-! UNTIL ; AT 400h 03.01 ( fetch current state from RAM loc. 3 ) ( increment contents of variable state ) ( force placement in ZERO page ) ( force placement at ROM address 400h ) 227 MARC4 Programmer's Guide qFORTH Dictionary BEGIN "BEGIN" Purpose: Indicates the start of one of the following control structures: BEGIN ... UNTIL BEGIN ... AGAIN BEGIN ... WHILE .. REPEAT BEGIN marks the start of a sequence that may be repetitively executed. It serves as a branch destination (_$BEGINxx:) for the corresponding UNTIL, AGAIN or REPEAT statement. Category: Control structure Library implementation: CODE BEGIN _$BEGIN: [ E 0 R 0 ] END-CODE Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: UNTIL AGAIN REPEAT WHILE ?LEAVE -?LEAVE 228 03.01 MARC4 Programmer's Guide qFORTH Dictionary BEGIN Example: : BEGIN-UNTIL 3 BEGIN 1+ DUP 9 = UNTIL DROP ; : BEGIN-AGAIN 3 BEGIN 1+ DUP 9 = ?LEAVE AGAIN DROP ; : BEGIN-WHILE-REPEAT 3 BEGIN DUP 9 <> WHILE 1+ REPEAT DROP ; 03.01 ( increment value from 3 til 9 ( DUP the current value because the ( comparison will DROP it ( BRANCH and CARRY flags will be set ) ) ) ) ( do the same with an infinite loop ) ( do the same with a WHILE-REPEAT loop ) ( REPEAT increment while not equal 9 ) 229 MARC4 Programmer's Guide qFORTH Dictionary CASE "CASE" Purpose: Indicates the start of a CASE ... OF ... ENDOF ... ENDCASE control structure. Using a 4-bit index value on TOS, CASE compares it sequentially with each value in front of an OF ... ENDOF pair until a match is found. When the index value equals one of the 4-bit OF values, the sequence between that OF and the corresponding ENDOF is executed. Control then branches to the word following ENDCASE. If no match is found, the ENDCASE will DROP the index value from the EXP stack. The 'otherwise' case may be handled by qFORTH words placed between the last ENDOF and ENDCASE. NOTE: However, the 4-bit index value must be perserved across the `otherwise' sequence so that ENDCASE can drop it ! Category: Control structure Library implementation: CODE CASE _$CASE: END-CODE [E0 R0] Stack effect: EXP ( n -- n ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: OF ENDOF ENDCASE 230 03.01 MARC4 Programmer's Guide qFORTH Dictionary CASE Example: 5h CONSTANT Keyboard 1 CONSTANT TestPort1 : ONE 1 TestPort1 OUT ; : TWO 2 TestPort1 OUT ; : THREE 3 TestPort1 OUT ; : ERROR DUP TestPort1 OUT ; ( write 1 to the `TestPort1' ( write 2 to the `TestPort1' ( write 3 to the `TestPort1' ( dump wrong input to the port ( duplicate value for the following ENDCASE; it drops one : CASE-Example KeyBoard IN CASE 1 OF ONE ENDOF 2 OF TWO ENDOF 3 OF THREE ENDOF ERROR ENDCASE ; 03.01 ) ) ) ) ) ( request 1-digit keyboard input ( depending of the input value, ( one of these words will be acti- ( vated. ) ) ) ) ( otherwise ... ( n -- ) ) 231 MARC4 Programmer's Guide qFORTH Dictionary CCR! "CCR-store" Purpose: Store the 4-bit TOS value in the condition code register (CCR). NOTE: All flags will be altered by this command ! Category: Assembler instruction MARC4 opcode: 0E hex Stack effect: EXP ( n -- ) RET ( -- ) Stack changes: EXP: 1 element is popped from the stack RET: not affected Flags: CARRY flag set, if bit 3 of TOS was set BRANCH flag set, if bit 1 of TOS was set I_ENABLE flag set, if bit 0 of TOS was set X Y registers: not affected Bytes used: 1 See also: EI DI CCR@ SET_BCF CLR_BCF 232 03.01 MARC4 Programmer's Guide qFORTH Dictionary CCR! Example 1: : INT5 CCR@ Inc_Time CCR! ; ( timer interrupt service routine ( save the current condition codes ( call procedure. ( restore CCR status ( RTI & Enable interrupts ) ) ) ) ) NOTE: CCR@/! and X/Y@/! will be inserted in INTx-routines by the compiler automatically. Example 2: CODE EI 0001b CCR! END_CODE 03.01 ( enable all interrupts ) 233 MARC4 Programmer's Guide qFORTH Dictionary CCR@ "CCR-fetch" Purpose: Save the contents of the condition code register on TOS. Category: Assembler instruction MARC4 opcode: 0D hex Stack effect: EXP ( -- n) RET ( -- ) Stack changes: EXP: 1 element is pushed onto the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: CCR! EI DI 234 03.01 MARC4 Programmer's Guide qFORTH Dictionary CCR@ Example: 1 CONSTANT Port1 : ?ERROR <> IF Fh Port1 OUT THEN ; : ADD_ADDC_TEST Ah Ch + CCR@ SWAP 6 ?ERROR CCR! Dh 6h +C 4 ?ERROR ; 03.01 ( error routine: are the numbers equal ? ( if unequal, then write Fh to Port1. ) ) ( two digits are dropped from the stack ) ( add up to 8-bit numbers ( 10 12 -- 6 + CARRY flag set ( 6 -- [C-BI flags] 6 ( check correct result ( 6 6 -- ) ( restore CARRY flag setting ( 13 6 [CARRY] -- 4 + CARRY flag set ( check correct result ( 4 4 -- ) ) ) ) ) ) ) ) 235 MARC4 Programmer's Guide qFORTH Dictionary CLR_BCF "Clear BRANCH- and CARRY-Flag" Purpose: Clear the BRANCH and CARRY flag in the condition code register. Category: qFORTH macro Library implementation: CODE CLR_BCF 0 ADD END-CODE Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag reset BRANCH flag reset X Y registers: not affected Bytes used: 2 See also: SET_BCF TOG_BF 236 ( reset CARRY & BRANCH flag ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary CLR_BCF Example: 8 ARRAY Result ( 8-digit BCD number array definition ) : DIG+ Y! CLR_BCF 8 #DO [Y]@ +C DAA [Y-]! 0 -?LEAVE #LOOP DROP ; ( add 1 digit to an 8-digit BCD number ( digit LSD_addr -- digit ; clear flgs ( loop maximal 8 times. ( add digit & do a decimal adjust. ( store; add 0 to the next digit. ( if no more carry, then leave loop. ) ) ) ) ) ) ( last 0 is not used. ( EXIT - return ) ) : ADD-UP-NUMBERS Result 8 ERASE 15 #DO 9 Result [7] DIG+ #LOOP ; ( clear the array. ( loop 15 times. ( put address of last nibble to TOS,-1 ( add 15 times 9 to RESULT ( BRANCH conditionally to begin of loop ( result: 9 * 15 = 135 ) ) ) ) ) ) 03.01 237 MARC4 Programmer's Guide qFORTH Dictionary CODE "CODE" Purpose: Begins a qFORTH macro definition where both MARC4 assembler instructions and qFORTH words may be included. Macros defined as CODE ... END-CODE are executed identically to words created as colon definitions ( i.e. : ... ; ) - except that no CALL and EXIT is placed in the ROM. The macro bytes are placed from the compiler in the ROM to every program sequence where they should be activated. MACROs are often used to improve run-time optimization, as long as the macro is not used too often by the program. NOTE: qFORTH word definitions that change the Return Stack level (>R, 2>R, ... 3R>, DROPR) require CODE ... END-CODE implementations, because the return address would no longer be available. Category: Predefined structure Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: END-CODE colon definition (:) EXIT (;) 238 03.01 MARC4 Programmer's Guide qFORTH Dictionary CODE Example: 5 CONSTANT Port5 3 ARRAY ReceiveData ( 12-bit data item (--------------------- CODE to shift right a 12-bit data word CODE ShiftRDBits ReceiveData Y! [Y]@ ROR [Y]! [+Y]@ ROR [Y]! ( rotate thru CARRY [+Y]@ ROR [Y]! END-CODE : Receive_Bit ReceiveDate Y! ( write data to the array: 5 [Y]! Ah [+Y]! 1 [+Y]! Port5 IN SHL ( Read input from IP53 ShiftRDBits ( shift `ReceiveData' 1 bit right ; 03.01 ) ) ) ) ) ) 239 MARC4 Programmer's Guide qFORTH Dictionary $ INCLUDE "Dollar-Include" Purpose: Compiles qForth source code from another text file. Used in form $INCLUDE <filename> $INCLUDE loads a qForth program from an ASCII text file. Such a source text file may be created using any standard text editor. $INCLUDE is "state-smart" and may be used (together with a filename) inside of a colon definition. The file name extension 'INC' is default and may be omitted. Category: Compiler Stack changes: EXP ( - - ) RET ( - - ) Flags: not affected 240 03.01 MARC4 Programmer's Guide qFORTH Dictionary $ INCLUDE Example: The sequence $INCLUDE MYPROG.SCR causes the qForth source code in file MYPROG.SCR to be compiled. 03.01 241 MARC4 Programmer's Guide qFORTH Dictionary $RAMSIZE $ROMSIZE "Dollar-RAMSize" " Dollar-ROMSize" Purpose: The MARC4 qFORTH compiler's behavior during compilation may be controlled by including $-Sign directives within the source-code file. These $-sign directives consist of one keyword which may be followed by at least one parameter. For more details refer to the "MARC4 User's Guide" Category: Compiler directives $RAMSIZE: Specifies the RAM size of the target processor. Default size is 255 nibbles ( from $00 .. $FF ). Some processors contain 253 nibbles only, whereby the RAM cells at $FC, $FD and $FE are not available. $ROMSIZE: Specifies the ROM size of the target processor. Default size is 4.0K ( from $000 .. $FFF ) ; The constants are as follows: 1.0K = 3Fh, 2.5K = 9Fh and 4.0K = FFh. With '$ROMSIZE' you can access this 8-bit constant in your source program. 242 03.01 MARC4 Programmer's Guide qFORTH Dictionary $RAMSIZE $ROMSIZE Example: $INCLUDE Timer.INC ( Predefined constants: 255 2CONSTANT $RAMSIZE 1.5k 2CONSTANT $ROMSIZE VARIABLE R0 27 ALLOT VARIABLE S0 19 ALLOT 03.01 ( for 253 RAM nibbles [3 auto sleep] ( 1535 ROM bytes - 2 b. for check sum ( resulting constant [$ROMSIZE] = 5Fh ( return stack: 28 nibbles for 7 level ( data stack: 20 nibbles ) ) ) ) ) ) 243 MARC4 Programmer's Guide qFORTH Dictionary CONSTANT "CONSTANT" Purpose: Creates a 4-bit constant; implemented in a qFORTH program as: n CONSTANT <name> with 0 <= n <= 15 or 0 <= n <= Fh or 0000b <= n <= 1111b Creates a dictionary entry for <name>, so that when <name> is later `executed', the value n is left on the stack.This is similar to an assembler EQUate statement in that it assigns a value to a symbol. Category: Predefined data structure Stack effect: EXP ( -- n ) on runtime. RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: 2CONSTANT VARIABLE 2VARIABLE 244 03.01 MARC4 Programmer's Guide qFORTH Dictionary CONSTANT Example: 4h CONSTANT #Nibbles 20 2CONSTANT Nr_of_Apples 03h 2CONSTANT Nr_of_Bananas 8 CONSTANT NumberOfBits 0011b CONSTANT BitMask ( value of valid bits ( value > 15 [Fh] ) ) ( hexadecimal, decimal or ( binary. ) ) ( calculate nr of fruits ( lower nibble: odd or even ? ) ) ( do it with every bit: ) Example: Nr_of_Apples Nr_of_Bananas D+ DUP BitMask AND DROP IF NumberOfBits #DO ... #LOOP THEN ; 03.01 245 MARC4 Programmer's Guide qFORTH Dictionary D+ "D-plus" Purpose: D+ adds the top two 8-bit values on the stack and leaves the result on the Expression Stack. Category: Arithmetic/logical (double-length) / qFORTH colon definition Library implementation: : D+ ROT ADD <ROT ADDC SWAP ; Stack effect: EXP ( d1 d2 -- d_sum ) RET ( -- ) Stack changes: EXP: 2 elements are popped from the stack RET: not affected Flags: CARRY flag set on overflow on higher nibble BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 7 See also: D- 2! 2@ D+! D-! D2/ D2* 246 ( d1h d1l d2h d2l -- d1h d2h d2l d1l ( d1h d2h d2l d1l -- d1h d2h d3l ( d1h d2h d3l -- d3l d1h d2h ( d3l d1h d2h -- d3l d3h ( d3l d3h -- d3 ) ) ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary D+ Example: : DC Double Add 10h 0 5 D+ 18h D+ 14h D+ C0h D+ 2DROP ; 03.01 ( result: -- 15 ; no flags ( result: -- 2D ; no flags ( result: -- 41 ; no flags ( result: -- 01 ; C & B flag ) ) ) ) 247 MARC4 Programmer's Guide qFORTH Dictionary D+! "D-plus-store" Purpose: ADD the TOS 8-bit value to an 8-bit variable in RAM and store the result in that variable. On function entry, the higher nibble address of the variable is the TOS value. Category: Arithmetic/logical (double-length) / qFORTH colon definition Library implementation: : D+! Y! [+Y]@ + [Y-]! [Y]@ +c [Y]! ( nh nl address -- nh nl ( nh nl -- nh nl' ( nh nl' -- nh ( nh -- nh' ( nh' -- ) ) ) ) ) ; Stack effect: EXP (d RAM_addr -- ) RET ( -- ) Stack changes: EXP: 4 elements are popped from the stack RET: not affected Flags: CARRY flag set on overflow on higher nibble BRANCH flag = CARRY flag X Y registers: The contents of the Y register will be changed. Bytes used: 8 See also: The other double-length qFORTH dictionary words, like D- D+ 2! 2@ D-! D2/ D2* D< D> D<> D= D<= D>= D0= D0<> 248 03.01 MARC4 Programmer's Guide qFORTH Dictionary D+! Example: 2VARIABLE count AT 43h : Double_Arithm 13h count 2! ( RAM [43] = 1 ; RAM [44] = 3 ) count 2@ 2DROP ( -- 1 3 ) 55h count D+! b5h count D+! ( 68 in the RAM ; no flags ( 1D in the RAM ; C & B flag ) ) ; 03.01 249 MARC4 Programmer's Guide qFORTH Dictionary D- "D-minus" Purpose: D- subtracts the top two 8-bit values on the EXP stack and leaves the result on the EXP stack. Category: Arithmetic/logical (double-length) / qFORTH colon definition Library implementation: : D- ROT SWAP SUB <ROT SUBB SWAP ( d1h d1l d2h d2l -- d1h d2h d2l d1l ) ( d1h d2h d2l d1l -- d1h d2h d1l d2l ) ( d1h d2h d1l d2l -- d1h d2h d3l ) ( d1h d2h d3l -- d3l d1h d2h ) ( d3l d1h d2h -- d3l d3h ) ( d3l d3h -- d3 ) ; Stack effect: EXP ( d1 d2 -- d1-d2 RET ( -- Stack changes: EXP: 2 elements are popped from the stack RET: not affected Flags: CARRY flag set on arithmetic underflow BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 8 See also: D+ 2! 2@ D+! D-! D2/ D2* D< D> 250 ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary D- Example: : Double_Minus 15h 13h D- 2DROP 13h 15h D- 2DROP 18h 18h D- D0= ; 03.01 ( result: -- 02 ; no flags ) ( result: -- FE ; C & B flag ) ( result: -- 00 ; no flags ) ( result: -- ; B flag set ) 251 MARC4 Programmer's Guide qFORTH Dictionary D-! "D-minus-store" Purpose: Subtract the top 8-bit value from an 8-bit variable in RAM and store the result in that variable. The address of the variable is the TOS value. Category: Library implementation: Stack effect: Arithmetic/logical (double-length) / qFORTH colon definition : D-! Y! ( nh nl address -- nh nl [+Y]@ ( nh nl -- nh nl @RAM[Y] SWAP - ( nh nl @RAM[Y] -- nh nl [Y-]! ( nh nl' -- nh [Y]@ ( nh -- nh @RAM[Y+1] SWAP -c ( nh @RAM[Y+1] -- nh' [Y]! ( nh' -- ; EXP (d RAM_addr -- ) RET ( -- ) Stack changes: EXP: 4 elements are popped from the stack RET: not affected Flags: CARRY flag set on arithmetic underflow BRANCH flag = CARRY flag X Y registers: The contents of the Y register are changed. Bytes used: 10 See also: D- D+ 2! 2@ D+! 252 ) ) ) ) ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary D-! Example: 2VARIABLE Fred : DCompAri 13h Fred 2! 11h Fred D-! 11h Fred D-! ; 03.01 ( 02 in the RAM ; no flags ( F1 in the RAM ; C & B flag set ) ) 253 MARC4 Programmer's Guide qFORTH Dictionary D0<> "D-zero-not-equal" Purpose: Compares the 8-bit value on top of the stack with zero. Instead of pushing a Boolean TRUE flag on the stack if the byte on top of the stack is non-zero, `D0<>' sets the BRANCH flag in the CCR. Category: Arithmetic/logical (double-length) / qFORTH macro Library implementation: CODE D0<> OR ( n1 n2 -- n3 [if 0 then BRANCH flag]) DROP ( n3 -- ) TOG_BF ( Toggle BRANCH flag ) END-CODE Stack effect: EXP RET Stack changes: EXP: 2 elements will be popped from the stack RET: not affected Flags: CARRY flag not affected BRANCH flag Set, if (d <> 0) X Y registers: not affected Bytes used: 3 See also: D- D+ D< D> D<> D= D<= D>= D0= 254 ( d -- ( -- ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary D0<> Example: 1 CONSTANT true 0 CONSTANT false : DCompare 12h D0<> IF true ELSE false THEN DROP 12h D- D0<> IF true ELSE false THEN DROP ; 03.01 ( result is `true' ) ( result is `false' ) 255 MARC4 Programmer's Guide qFORTH Dictionary D0= "D-zero-equal" Purpose: Compare the 8-bit value on top of the stack to zero. Instead of pushing a Boolean TRUE flag on the stack if the byte on top of the stack is zero, `D0=' sets the BRANCH flag in the CCR. Category: Arithmetic/logical (double-length) / qFORTH macro Library implementation: CODE D0= OR DROP ( n1 n2 -- n3 [BRANCH flag re/set]) ( n3 -- [BRANCH flag] ) END-CODE Stack effect: EXP ( d -- ) RET ( -- ) Stack changes: EXP: 2 elements are popped from the stack RET: not affected Flags: CARRY flag not affected BRANCH flag set, if (d = 0) X Y registers: not affected Bytes used: 2 See also: D- D+ D< D> D<> D= D<= D>= D0<> 256 03.01 MARC4 Programmer's Guide qFORTH Dictionary D0= Example: 1 CONSTANT true 0 CONSTANT false : DCompare 12h D0= IF true ELSE false THEN DROP 12h D0- D0= IF true ELSE false THEN DROP ; 03.01 ( result is `false' ) ( result is `true' ) 257 MARC4 Programmer's Guide qFORTH Dictionary D2* "D-two-multiply" Purpose: Multiplies the 8-bit value on top of the stack by 2. Category: Arithmetic/logical (double-length) / qFORTH macro Library implementation: CODE D2* SHL SWAP ROL SWAP ( dh dl -- dh dl*2 ) ( dh dl*2 -- dl*2 dh ) ( dl*2 dh -- dl*2 dh*2 ) ( dl*2 dh*2 -- d*2 ) END-CODE Stack effect: EXP RET Stack changes: EXP: not affected RET: not affected Flags: CARRY flag set on arithmetic overflow BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 4 See also: D- D+ D2/ D<> D= D<= D>= D0= D0<> 258 ( d -- d*2 ) ( -- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary D2* Example: : DMultiply 03 D2* D2* D2* 2DROP 90h D2* 2DROP ; 03.01 ( 03h -> 06h and no flags ) ( 06h -> 0Ch and no flags ) ( 0Ch -> 18h and no flags ) ( 90h -> 20h and C & B flag) ( [90h *2 = 120h] ) 259 MARC4 Programmer's Guide qFORTH Dictionary D2/ "D-two-divide" Purpose: Divides the 8-bit value on top of the stack by 2. Category: Arithmetic/logical (double-length) / qFORTH macro Library implementation: CODE D2/ SWAP SHR SWAP ROR ( dh dl/2 -- dl dh ( dl dh -- dl dh/2 [CARRY flag] ( dl dh/2 [CARRY flag] -- dh/2 dl ( dh/2 dl [CARRY flag] -- d/2 ) ) ) ) END-CODE Stack effect: EXP RET Stack changes: EXP: not affected RET: not affected Flags: CARRY flag set, if LSB of byte on TOS has been set BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 4 See also: D- D+ D+! D-! D2* D<> D= 260 ( d -- d/2 ) ( -- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary D2/ Example: : D2Divide 13h D2/ D2/ D2/ D2/ D2/ 2DROP ; 03.01 ( 13h -> 09h and C & B flag) ( 09h -> 04h and C & B flag) ( 04h -> 02h and no flags ) ( 02h -> 01h and no flags ) ( 01h -> 00h and C & B flag) 261 MARC4 Programmer's Guide qFORTH Dictionary D< "D-less-than" Purpose: `Less-than' comparison for the top two unsigned 8-bit values. Instead of pushing a boolean TRUE flag onto the stack if the 2nd value on the stack is `less-than' the TOS value, `D<' sets the BRANCH flag. Category: Library implementation: Arithmetic/logical (double-length) / qFORTH colon definition : D< ROT ( d1 d2 -- d1h d2 d1l 2>R ( d1h d2h d2l d1l -- d1h d2h OVER ( d1h d2h -- d1h d2h d1h CMP_LT ( d1h d2h d1h -- d1h d2h [B-flag] BRA _BIGGER ( jump if upper nibble is bigger CMP_LT ( d1h d2h -- d1h [BRANCH flag] BRA _IS_LESS ( jump if upper nibble is smaller 2R@ ( d1h -- d1h d2l d1l CMP_LE ( d1h d2l d1l -- d1h d2l _BIGGER: TOG_BF ( correct the BRANCH flag DROP ( d1h d2l -- d1h _IS_LESS: DROP ( d1h -- DROPR ( skip lower nibbles from RET stack [ E -4 R 0 ] ; Stack effect: EXP RET Stack changes: EXP: 4 elements are popped from the stack RET: not affected Flags: CARRY flag affected BRANCH flag = set, if (d1 < d2) X Y registers: not affected Bytes used: 16 See also: D> D<> D= D<= D>= D0= D0<> 262 ) ) ) ) ) ) ) ) ) ) ) ) ) ( d1 d2 -- ) ( -- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary D< Example: 1 CONSTANT true 0 CONSTANT false : DCompare 12h 15h D< IF true ELSE false THEN DROP 15h 12h D< IF true ELSE false THEN DROP 18h 18h D< IF true ELSE false THEN DROP ; 03.01 ( result is `true' ) ( result is `false' ) ( result is `false' ) 263 MARC4 Programmer's Guide qFORTH Dictionary D<= "D-less-equal" Purpose: `Less-than-or-equal' comparison for the top two unsigned 8-bit values. Instead of pushing a Boolean TRUE flag on the stack if the 2nd number on the stack is `less-or-equal-than' the TOS number, `D<=' sets the BRANCH flag. Category: Arithmetic/logical(double-length) / qFORTH colon definition Library implementation: CODE D<= D> TOG_BF END-CODE Stack effect: EXP RET Stack changes: EXP: 4 elements are popped from the stack RET: not affected Flags: CARRY flag affected BRANCH flag = set, if (d1 <= d2) X Y registers: not affected Bytes used: 'D>' See also: D< D> D<> D= D>= D0= D0<> 264 ( d1 d2 -- ) ( -- ) 1 03.01 MARC4 Programmer's Guide qFORTH Dictionary D<= Example: 1 CONSTANT true 0 CONSTANT false : DCompare 12h 15h D<= IF true ELSE false THEN DROP 15h 12h D<= IF true ELSE false THEN DROP 18h 18h D<= IF true ELSE false THEN DROP ; 03.01 ( result is `true' ) ( result is `false' ) ( result is `true' ) 265 MARC4 Programmer's Guide qFORTH Dictionary D<> "D-not-equal" Purpose: Inequality test for the top two 8-bit values. Instead of pushing a Boolean true flag onto the stack if the 2nd value on the stack is 'not-equal' to the TOS value, 'D<>' sets the BRANCH flag. Category: Arithmetic/logical(double-length) / qFORTH colon definition Library implementation: : D<> ROT CMP_NE DROP BRA _NOT_EQ CMP_NE DUP _NOT_EQ: 2DROP [ E -4 R 0 ] ; ( d1h d1l d2h d2l -- d1h d2h d2l d1l ( d1h d2h d2l d1l -- d1h d2h d2l ( d1h d2h d2l -- d1h d2h ( jump if lower nibbles not equal ( d1h d2h -- d1h [BRANCH flag] ( d1h -- d1h d1h ( d1h d2h -- Stack effect: EXP RET ) ) Stack changes: EXP: 4 elements are popped from the stack RET: not affected Flags: CARRY flag affected BRANCH flag = set, if (d1 <> d2) X Y registers: not affected Bytes used: 10 See also: D< D> D= D<= D>= D0= D0<> 266 ( d1 d2 -- ( -- ) ) ) ) ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary D<> Example: 1 CONSTANT true 0 CONSTANT false : DCompare 12h 15h D<> IF true ELSE false THEN DROP 15h 12h D<> IF true ELSE false THEN DROP 18h 18h D<> IF true ELSE false THEN DROP ; 03.01 ( result is `true' ) ( result is `true' ) ( result is `false' ) 267 MARC4 Programmer's Guide qFORTH Dictionary D= "D-equal" Purpose: Equality test for the top two 8-bit values. Instead of pushing a boolean TRUE flag onto the stack if the 2nd value is `equal' to the TOS value, `D=' sets the BRANCH flag. This macro uses the colon definition `D<>'. Category: Arithmetic/logical(double-length) / qFORTH macro Library implementation: CODE D= D<> TOG_BF END-CODE Stack effect: EXP RET Stack changes: EXP: 4 elements are popped from the stack RET: not affected Flags: CARRY flag affected BRANCH flag = set, if (d1 = d2) X Y register: not affected Bytes used: 'D<>' 1 See also: D< D> D<> D<= D>= D0= D0<> 268 ( d1 d2 -- ) ( -- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary D= Example: 1 CONSTANT true 0 CONSTANT false : DCompare 12h 15h D= IF true ELSE false THEN DROP 15h 12h D= IF true ELSE false THEN DROP 18h 18h D= IF true ELSE false THEN DROP ; 03.01 ( result is `false') ( result is `false') ( result is `true') 269 MARC4 Programmer's Guide qFORTH Dictionary D> "D-greater-than" Purpose: 'Greater-than' comparison for the top two 8-bit values. Instead of pushing a Boolean TRUE flag onto the stack if the 2nd value is 'greater-than' to the TOS value, 'D>' sets the BRANCH flag. Category: Arithmetic/logical(double-length) / qFORTH colon definition Library implementation: : D> ROT ( d1 d2 -- d1h d2 d1l 2>R ( d1h d2h d2l d1l -- d1h d2h OVER ( d1h d2h -- d1h d2h d1h CMP_GT ( d1h d2h d1h -- d1h d2h [B-flag] BRA _SMALLER( jump if upper nibble is smaller CMP_GT ( d1h d2h -- d1h [BRANCH flag] BRA _IS_HUGH ( jump if upper nibble is bigger 2R@ ( d1h -- d1h d2l d1l CMP_GE ( d1h d2l d1l -- d1h d2l _SMALLER: TOG_BF ( correct the BRANCH flag DROP ( d1h d2? -- d1h _IS_HUGH: DROP ( d1h -- DROPR ( skip lower nibbles from RET stack [ E -4 R 0 ] ; Stack effect: EXP RET Stack changes: EXP: 4 elements are popped from the stack RET: not affected Flags: CARRY flag affected BRANCH flag = set, if (d1 > d2) X Y registers: not affected Bytes used: 16 See also: D< D<> D= D<= D>= D0= D0<> 270 ) ) ) ) ) ) ) ) ) ) ) ) ) ( d1 d2 -- ) ( -- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary D> Example: 1 CONSTANT true 0 CONSTANT false : DCompare 12h 15h D> IF true ELSE false THEN DROP 15h 12h D> IF true ELSE false THEN DROP 18h 18h D> IF true ELSE false THEN DROP ; 03.01 ( result is 'false' ) ( result is 'true' ) ( result is 'false' ) 271 MARC4 Programmer's Guide qFORTH Dictionary D>= "D-greater-equal" Purpose: 'Greater-than-or-equal' comparison for the top two 8-bit values. Instead of pushing a Boolean TRUE flag onto the stack if the 2nd value is 'greater-than-or-equal' to the TOS value, 'D>=' sets the BRANCH flag. Category: Arithmetic/logical(double-length) / qFORTH colon definition Library implementation: CODE D>= D< TOG_BF END-CODE Stack effect: EXP RET Stack changes: EXP: 4 elements are popped from the stack RET: not affected Flags: CARRY flag affected BRANCH flag = set, if (d1 >= d2) X Y registers: not affected Bytes used: 'D<' 1 See also: D< D> D<> D= D<= D0= D0<> 272 ( d1 d2 -- ) ( -- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary D>= Example: 1 CONSTANT true 0 CONSTANT false : DCompare 12h 15h D>= IF true ELSE false THEN DROP 15h 12h D>= IF true ELSE false THEN DROP 18h 18h D>= IF true ELSE false THEN DROP ; 03.01 ( result is 'false' ) ( result is 'true' ) ( result is 'true' ) 273 MARC4 Programmer's Guide qFORTH Dictionary D>S NIP "Double-to-single" "NIP" Purpose: Transform an 8-bit value into a 4-bit value. Drops second 4-bit value from the stack. Category: Stack operation (single-length) / qFORTH macro Library implementation: CODE D>S | NIP SWAP ( d -- n 0 ) DROP ( n 0 -- n ) END-CODE or ( n1 n2 -- n2 n1 ) ( n2 n1 -- n2 ) Stack effect: EXP ( d -- n ) or EXP ( n1 n2 -- n2 ) RET ( -- ) Stack changes: EXP: 1 element is popped from the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 2 See also: S>D 2NIP 274 03.01 MARC4 Programmer's Guide qFORTH Dictionary D>S NIP Example 1: : NIP_Example 10H 3 NIP 2DROP ; ( -- 1 0 ( 1 0 -- 1 0 3 ( 1 0 3 -- 1 3 ( 1 3 -- ) ) ) ) ( -- 4 ( 4 -- 0 4 ( 0 4 -- 4 ( 4 -- ) ) ) ) Example 2: : StoD_DtoS 4 S>D D>S DROP ; Example 3: Library implementation: of 'DEPTH' : DEPTH SP@ S0 D- ( -- SPh SPl S0h S0l -- diff NIP 1- ( diff -- n ; 03.01 ) ) 275 MARC4 Programmer's Guide qFORTH Dictionary DAA "Decimal Adjust" Purpose: Decimal-arithmetic-adjustment for BCD arithmetic if the digit on top of stack is greater than 9, or the CARRY flag is set. Category: Assembler instruction MARC4 opcode: 16 hex Stack effect: IF TOS > 9 or CARRY-in = 1 THEN EXP ELSE EXP RET ( n -- n+6 ) ( n -- n ) ( --) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag set, if (TOS > 9) or (CARRY-in = 1) BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 1 See also: +C DAS SET_BCF 276 03.01 MARC4 Programmer's Guide qFORTH Dictionary DAA Example : DAA_Example 2 SET_BCF DAA 2 CLR_BCF DAA 11 DAA Bh SET_BCF DAA 2DROP 2DROP ; ( result is: 2 -- 8 & C flag ( result is: 2 -- 2 no flag ( result is: B -- 1 & C flag [Bh = 11] ( result is: B -- 1 & C flag ) ) ) ) Another example for DAA, see DAS entry (next page). 03.01 277 MARC4 Programmer's Guide qFORTH Dictionary DAS "D-A-S" or "Decimal-Adjust for Subtraction" Purpose: Decimal arithmetic for BCD subtraction, computes a 9's complement. Category: qFORTH macro Library implementation: CODE DAS NOT 10 +c END-CODE ( n -- 9-n ) Stack effect: EXP RET Stack changes: EXP: not affected RET: not affected Flags: CARRY and BRANCH flags are affected X Y registers: not affected Bytes used: 3 See also: NOT +C DAA 278 ( n -- 9-n ) ( -- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary DAS Example: 8 CONSTANT BCD# BCD# ARRAY input2 BCD# ARRAY input1 : DIG- Y! SWAP DAS SWAP #DO [Y]@ + DAA [Y-]! 10 -?LEAVE #LOOP DROP ; ( number of BCD digits ) ( digit count LSD_Addr -- ( generate 9's complement ( digit count -- digit ( transfer CARRY on stack ( exit LOOP if NOT CARRY ( repeat until index = 0 ( skip TOS overflow digit ) ) ) ) ) ) ) : BCD- ( count LSD_Addr1 LSD_Addr2 -- Y! X! SET_BCF ( set CARRY and pointer registers #DO [Y]@ [X-]@ DAS ( 9's complement generation + DAA [Y-]! #LOOP ; : Calculate BCD# Input2 [7] Input1 [7] BCD- ( Inp1:=Inp1-Input2 3 BCD# Input1 [7] DIG- ( Input1 := Input1 - 3 ;a 03.01 ) ) ) ) ) 279 MARC4 Programmer's Guide qFORTH Dictionary DECR "Dec-R" Purpose: Decrements the lowest nibble (i.e. the loop index) on the Return Stack. Category: Assembler instruction MARC4 opcode: 1C hex Stack effect: EXP RET Stack changes: EXP: not affected RET: not affected Flags: CARRY flag not affected BRANCH flag = set, if (n-1 <> 0) X Y registers: not affected Bytes used: 1 See also: #DO .. #LOOP (#LOOP uses DECR) 280 ( -- ( u|u|n -- u|u|n-1 ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary DECR Example 1: : DECR_Example 3 >R DECR I DROP DECR DECR DECR DECR DECR DECR DROPR ; ( RET stack: u|u|3 -- u|u|2 & B flag ( EXP stack: -- 2 -- ( RET stack: u|u|2 -- u|u|1 & B flag ( RET stack: u|u|1 -- u|u|0 no flag ( RET stack: u|u|0 -- u|u|F & B flag ( RET stack: u|u|F -- u|u|E & B flag ( RET stack: u|u|E -- u|u|D & B flag ( RET stack: u|u|D -- u|u|C & B flag ( pop "one element" from return stack ) ) ) ) ) ) ) ) ) Example 2: Library implementation: of #LOOP : ( Purpose: #LOOP - macro is used to terminate a #DO loop. ( On each iteration of a #DO loop, #LOOP decrements the ( loop index on the Return Stack. It then compares the index ( to zero and determines whether the loop should terminate. ( If the new index is decremented to zero the loop is ( terminated and the loop index is discarded from the Return ( Stack. Otherwise, control jumps back to the point just after ( the corresponding start of the #DO macro. \ IF Index-1 > 0 \ THEN RET ( u|u|Index -- u|u|Index-1 \ ELSE RET ( u|u|Index -- CODE #LOOP DECR ( RET: u|u|Index -- u|u|Index BRA _$#DO( IF Index > 0, loop again _$LOOP: DROPR ( forget index on return stack END-CODE 03.01 ) ) ) ) ) ) ) ) ) ) ) ) ) 281 MARC4 Programmer's Guide qFORTH Dictionary DEPTH "DEPTH" Purpose: Leaves the currently used depth of the Expression Stack on top of the stack. Category: Stack operation / interrupt handling / qFORTH colon definition Library implementation: : DEPTH SP@ S0 D- NIP 1- ( -- SPh SPl S0h S0l -- diff) ( diff -- n ) ; Stack effect: EXP ( -- n ) RET ( -- ) Stack changes: EXP: 1 element will be pushed onto the stack RET: not affected Flags: CARRY flag affected BRANCH flag set, if (depth = 0) X Y registers: not affected Bytes used: 9 See also: RFREE RDEPTH 282 ( n <= Fh ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary DEPTH Example: : DEPTH-Ex DEPTH 12 DEPTH 34 DEPTH 2DROP 2DROP 2DROP DROP ; 03.01 ( [*1] -- 5 ( 5 -- 5 1 2 ( 5 1 2 -- 5 1 2 8 ( 5 1 2 8 -- 5 1 2 8 3 4 ( 5 1 2 8 3 4 -- [*1] 5 1 2 8 3 4 b ( drop the 4 nibbles and ( the 3 result values. ) ) ) ) ) ) ) 283 MARC4 Programmer's Guide qFORTH Dictionary DI "Disable-Interrupt" or "D-I" Purpose: Disable execution of higher prioritised interrupts until the next EI or RTI instruction is performed. The access to semaphores, variables or peripheral resources by differently prioritised interrupt routines will require a DI/EI sequence. Note: The generation of interrupts and latching in the interrupt pending register is not disabled. Category: Interrupt handling / assembler instruction MARC4 opcode: 1A hex Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: I_ENABLE flag reset CARRY and BRANCH flags are not affected X Y registers: not affected Bytes used: 1 See also: EI RTI INT0 .. INT7 SWI0 .. SWI7 284 03.01 MARC4 Programmer's Guide qFORTH Dictionary DI Example: Library implementation: of ROLL: : ROLL ?DUP IF CCR@ DI >R 1+ PICK >R Y@ 1 M+ X! #DO [+X]@ [+Y]! #LOOP DROP R> R> CCR! ELSE DROP THEN ; 03.01 ( save current I-flag setting on RET st. ( do a PICK, move PICKed value on RET st. ( move ptr from Y -> X reg. ( adjust X reg. pointer ( shift data values one down ) ) ) ) ) ( restore I-flag setting in CCR ) 285 MARC4 Programmer's Guide qFORTH Dictionary DMAX "D-max" Purpose: Leaves the greater of two 8-bit unsigned values on the stack. Category: Stack operation (double-length) / qFORTH colon definition Library implementation: : DMAX ( will be improved/changed soon; using D<=, D>) 2>R ( d1 d2 -- d1 ) 2DUP ( d1 -- d1 d1 ) 2R@ ( d1 d1 -- d1 d1 d2 ) ROT ( d1 d1h d1l d2h d2l -- d1 d1h d2h d2l d1l ) 2>R ( d1 d1h d2h d2l d1l -- d1 d1h d2h ) OVER ( d1 d1h d2h -- d1 d1h d2h d1h ) CMP_LT ( d1 d1h d2h d1h--d1 d1h d2h[B-flag] ) BRA _DMAX1 ( jump if d2 < d1 in higher nibble ) <> ( d1 d1h d2h -- d1 [BRANCH flag] ) BRA _DMAX3 ( jump if d2 > d1 in higher nibble ) 2R@ ( d1 -- d1 d2l d1l ) < ( d1 d2l d1l -- d1 ) BRA _DMAX2 ( jump, if d2l < d1l ) DROPR ( skip compares values from RET stack ) 2DROP ( d1 -- ) 2R> ( -- d2 ) EXIT 2DROP ( skip compares values from EXP stack ) DROPR ( skip values from RET stack ) DROPR ( -- d1 ) [ E -2 R 0 ] _DMAX3: _DMAX1: _DMAX2: ; Stack effect: IF d1 > d2 THEN EXP ELSE EXP RET ( d1 d2 -- d1 ) ( d1 d2 -- d2 ) ( -- ) Stack changes: EXP: 2 elements will be popped from the stack RET: not affected Flags: CARRY and BRANCH flags are affected X Y register: Bytes used: See also: not affected 30 DMIN MAX MIN 286 03.01 MARC4 Programmer's Guide qFORTH Dictionary DMAX Example: : DMAX-Example ABh 25h DMAX 2DROP ( -- A B 2 5 -- A B -- ABh ABh DMAX 2DROP ( -- A B A B -- A B -- 25h ABh DMAX 2DROP ( -- 2 5 A B -- A B -- ; 03.01 ) ) ) 287 MARC4 Programmer's Guide qFORTH Dictionary DMIN "D-min" Purpose: Category: Library implementation: : DMIN _DMIN3: _DMIN1: _DMIN2: Leaves the smaller of two 8-bit unsigned values on the stack. Stack operation (double-length) / qFORTH colon definition 2>R 2DUP 2R@ ROT 2>R OVER CMP_GT BRA _DMIN1 <> BRA _DMIN3 2R@ > BRA _DMIN2 DROPR 2DROP 2R> EXIT 2DROP DROPR DROPR [ E -2 R 0 ] ( will be improved/changed soon; using D<=, D>) ( d1 d2 -- d1 ) ( d1 -- d1 d1 ) ( d1 d1 -- d1 d1 d2 ) ( d1 d1h d1l d2h d2l -- d1 d1h d2h d2l d1l ) ( d1 d1h d2h d2l d1l -- d1 d1h d2h ) ( d1 d1h d2h -- d1 d1h d2h d1h ) ( d1 d1h d2h d1h -- d1 d1h d2h [BRANCH flag]) ( jump if d2 < d1 in higher nibble ) ( d1 d1h d2h -- d1 [BRANCH flag] ) ( jump if d2 > d1 in higher nibble ) ( d1 -- d1 d2l d1l ) ( d1 d2l d1l -- d1 ) ( jump if d2l < d1l ) ( skip compares values from RET stack ) ( d1 -- ) ( -- d2 ) ( skip compares values from EXP stack ( skip values from RET stack ( -- d1 ) ) ) ; Stack effect: IF d1 < d2 THEN EXP ELSE EXP RET ( d1 d2 -- d1 ) ( d1 d2 -- d2 ) ( -- ) Stack changes: EXP: 2 elements are popped from the stack RET: not affected Flags: X Y registers: Bytes used: See also: CARRY and BRANCH flags are affected not affected 30 DMAX MIN MAX 288 03.01 MARC4 Programmer's Guide qFORTH Dictionary DMIN Example: : DMIN-example ABh 25h DMIN 2DROP 25h 25h DMIN 2DROP 25h ABh DMIN 2DROP ; 03.01 ( -- A B 2 5 -- 2 5 -- ( -- 2 5 2 5 -- 2 5 -- ( -- 2 5 A B -- 2 5 -- ) ) ) 289 MARC4 Programmer's Guide qFORTH Dictionary DNEGATE "D-negate" Purpose: 2's complement of the top 8-bit value. Category: Arithmetic/logical(double-length) / qFORTH colon definition Library implementation: : DNEGATE 0 SWAP - 0 ROT -c SWAP ; Stack effect: EXP RET ( d -- -d ( -- Stack changes: EXP: not affected RET: not affected Flags: CARRY and BRANCH flags are affected X Y registers: not affected Bytes used: 8 See also: NEGATE 290 ( dh dl -- dh -dl ( dh -dl -- -dl -dh ( -dl -dh -- -d ) ) ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary DNEGATE Example: 1 CONSTANT true 0 CONSTANT false : D_Negate 18h 12h D- 12h DNEGATE 18h D+ D= IF true ELSE false THEN ; 03.01 ( 18h - 12h = 06h ( 2's complement of 12h add to 18h ( 18h + [-12h] = 06h ? ( is the result equal ? ( 'true' = 1 = YES ! ( end of test: return. ) ) ) ) ) ) 291 MARC4 Programmer's Guide qFORTH Dictionary DO "DO" Purpose: Indicates the start of an iterative loop. DO is used only within a colon definition and only in a pair with LOOP or +LOOP. The two numbers on top of the stack, at the time DO is executed, determine the number of times the loop repeats. The topmost number on the stack is the initial loop index. The next number on the stack is the loop limit. The loop terminates when the loop index is incremented past the boundary between limit-1 and limit (if limit is reached). A DO loop is always executed at least once, even if the loop index initially exceeds the limit. Category: Control structure / qFORTH macro Library implementation: CODE DO 2>R _$DO: [ E -2 R 1 ] END-CODE Stack effect: EXP RET Stack changes: EXP: 2 elements will be popped from the stack RET: 1 element (2 nibbles) will be pushed onto the stack Flags: not affected X Y registers: not affected Bytes used: 1 See also: LOOP #DO #LOOP ?DO +LOOP ?LEAVE -?LEAVE 292 ( limit index -- ( -- u|limit|index ( EXP: limit index -- ) ( RET: -- u|limit|index ) (DO LOOP backpatch label) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary DO Example: : DoLoop 62 DO I TestPort1 OUT LOOP 92 DO I TestPort1 OUT 2 +LOOP ( limit and start on the stack. ( ( copy the index from the Return Stack. ( write 2, 3, 4, 5 to the 'TestPort1'. ( loop until limit = index. ( ( ( ( ( write 2, 4, 6, 8 to the 'TestPort1'. ( ) ) ) ) ) ) ) ) ) ) ) ; 03.01 293 MARC4 Programmer's Guide qFORTH Dictionary DROP "DROP" Purpose: Removes one 4-bit value from top of the Expression Stack, i.e., decrements the Expression Stack pointer. Category: Stack operation (single-length) / assembler instruction MARC4 opcode: 2E hex Stack effect: EXP RET Stack changes: EXP: 1 element is popped from the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: 2DROP 3DROP 294 ( n1 --- ( -- ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary DROP Example: : DROP_Example 19H 11H DROP 2DROP 19h 3DROP ; 03.01 ( -- 1 9 ( 1 9 -- 1 9 1 1 ( 1 9 1 1 -- 1 9 1 ( 1 9 1 -- 1 ( 1 -- 1 1 9 ( 1 1 9 -- ) ) ) ) ) ) 295 MARC4 Programmer's Guide qFORTH Dictionary DROPR "DROP-R" Purpose: Decrements the Return Stack pointer. Removes one entry ( = 3 nibbles) from the Return Stack. Category: Assembler instruction MARC4 opcode: 2F hex Stack effect: EXP RET Stack changes: EXP: not affected RET: 1 element (12-bits) is popped from the Return Stack Flags: not affected X Y registers: not affected Bytes used: 1 See also: >R I R> 2>R 2R> 3>R 3R> EXIT 296 ( -- ) ( x|x|x --- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary DROPR Example 1: : DROPR_Example 1 2 3 3>R DROPR ; ( RET: -- 1|2|3 ( RET: 1|2|3 -- ) ) Example 2: Library implementation: of #LOOP : ( #LOOP - Macro -----------------------------------------) ( Purpose: #LOOP is used to terminate a #DO loop. ) ( ) ( On each iteration of a #DO loop, #LOOP decrements the ) ( loop index on the return stack. It then compares the index ) ( to zero and determines whether the loop should terminate. ) ( If the new index is decremented to zero, the loop is ) ( terminated and the loop index is discarded from the return ) ( stack. Otherwise, control jumps back to the point just after ) ( the corresponding start of the #DO macro. ) \ \ \ IF Index-1 > 0 THEN RET ELSE RET CODE #LOOP DECR BRA _$#DO _$LOOP: DROPR [ E 0 R -1 ] END-CODE 03.01 ( u|u|Index -- u|u|Index-1 ( u|u|Index -- ) ) ( RET: u|u|Index -- u|u|Index ( IF Index > 0, Loop again ( forget Index on RET stack ) ) ) 297 MARC4 Programmer's Guide qFORTH Dictionary DTABLE@ "D-TABLE-fetch" Purpose: Fetches an 8-bit constant from a ROMCONST array, whereby the 12-bit ROM address and the 4-bit index are on the EXP stack. Category: Memory operation (double-length) / qFORTH colon definition Library implementation: DTABLE@ M+ IF ROT 1+ <ROT THEN 3>R TABLE [ E -2 R 0 ] ( ROMh ROMm ROMl ind -- ROMh ROMm' ROMl' ) ( on overflow propagate CARRY ) ( ROMh ROMm' ROMl' -- ROMh' ROMm' ROMl' ) ( move TABLE address to RET stack ( -- consthigh constlow ( TABLE returns directly to the CALLer during microcode execution. ( therefore 'EXIT' is not necessary ) ) ) ) ;; Stack effect: EXP RET Stack changes: EXP: 2 elements will be popped from the stack RET: not affected Flags: CARRY and BRANCH flags are affected X Y registers: not affected Bytes used: 14 See also: TABLE ROMByte@ ROMCONST 298 (ROMh ROMm ROMl index -- consth constl) ( -- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary DTABLE@ Example: ROMCONST DigitTable : D_Table@ 0 0 1 ROMByte@ 2DROP DigitTable 5 DTABLE@ 2DROP DigitTable 1 DTABLE@ 2DROP DigitTable 0 DTABLE@ 2DROP DigitTable Fh DTABLE@ 2DROP 10h , 1 , 2 , 3 , 4 , 45h , 6 , 7 , 8, 9, Ah , Bh , Ch , Dh , Eh , 0Fh , ( fetch byte at address 001h : 0Fh = SLEEP ) ( and delete it. ) ( sixth byte of the table: ( put address and index on the stack. ( fetch and delete the value : 45h . ( second byte of the table: ( put address and index on the stack. ( fetch and delete the value : 01h . ( first byte of the table and min. index : ( put address and index on the stack. ( fetch and delete the value : 10h . ( last byte of the table and max. index : ( put address and index on the stack. ( fetch and delete the value : 0Fh. ) ) ) ) ) ) ) ) ) ) ) ) ; 03.01 299 MARC4 Programmer's Guide qFORTH Dictionary DTOGGLE "D-TOGGLE" Purpose: TOGGLEs [exclusive ors] a byte at a given address with a specified bit pattern. The address of the 8-bit variable is on top of the Expression Stack. Category: Memory operation (double-length) / qFORTH colon definition Library implementation: : DTOGGLE Y! [+Y]@ XOR [Y-]! [Y]@ XOR [Y]! ( d addr -- nh nl ) ( nh nl -- nr rl' ) ( nh ( rl' -- rl' -- ) ) ; Stack effect: EXP RET Stack changes: EXP: 4 elements are popped from the stack RET: not affected Flags: CARRY flag not affected BRANCH flag set, if higher nibble gets zero X Y registers: The contents of the Y register are changed. Bytes used: 8 See also: TOGGLE XOR 300 ( d addr -- ) (-- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary DTOGGLE Example: 2VARIABLE Supra VARIABLE 1Supra : D_Toggle 0 0 Supra 2! FFh Supra DTOGGLE FFH Supra DTOGGLE AAh Supra 2! 55h Supra DTOGGLE 5 1Supra ! 3 1Supra TOGGLE Fh 1Supra ! Fh 1Supra TOGGLE Fh 1Supra TOGGLE ; 03.01 ( reset in the RAM two nibbles to 00h. ( 00h XOR FFh = FFh ( flags: no BRANCH ( 00h XOR FFh = 00h ( flags: BRANCH ( set the two nibbles to AAh. ( 1010 1010 XOR 0101 0101 = 1111 1111 ( flags: no BRANCH ( set in the RAM one nibble to 0101. ( truth table: 0101 XOR 0011 = 0110 ( flags: no BRANCH ( set in the RAM one nibble to Fh. ( 1111 XOR 1111 = 0000 ( flags: BRANCH ( 0000 XOR 1111 = 1111 ( flags: no BRANCH ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) 301 MARC4 Programmer's Guide qFORTH Dictionary DUP "Doop" Purpose: Duplicate the 4-bit value on top of the stack. Category: Stack operation (single-length) / assembler instruction MARC4 opcode: 2D hex Stack effect: EXP RET Stack changes: EXP: 1 element is pushed onto the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: 2DUP 3DUP DROP 302 ( n1 --- n1 n1 ( -- ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary DUP Example: : ONE-DUP 9 5 DUP 3DROP ; 03.01 ( -- 9 ( 9 -- 9 5 ( 9 5 -- 9 5 5 ( 9 5 5 -- ) ) ) ) 303 MARC4 Programmer's Guide qFORTH Dictionary EI "Enable-Interrupt" or "E-I" Purpose: Sets the INTERRUPT_ENABLE flag in the condition code register. RTI (return-from-interrupt) at end of $RESET or an INTx section will also set the interrupt flag. Use EI/DI only, if different tasks use the same resources; i.e. two tasks both use a peripheral EEPROM or RAM - without semaphore handling. Note: Under normal circumstances, the programer will not need to disable or enable interrupts - every task will have just the right interrupt level. Category: Interrupt handling / qFORTH macro Library implementation: CODE EI LIT_1 CCR! END-CODE ( set I_ENABLE flag ) Stack effect: EXP RET Stack changes: EXP: not affected RET: not affected Flags: CARRY flag reset BRANCH flag reset I_ENABLE flag set X Y registers: not affected Bytes used: 2 See also: DI RTI INT0 .. INT7 SWI0 .. SWI7 304 ( -- ) ( -- ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary EI Example: : InterruptFlagRe_Set DI 5 ROLL EI ; 03.01 ( disable the interrupt flag - CCR: x-x- ) ( re-order EXP stack values. ) ( enable the interrupt flag - CCR: x-xI ) 305 MARC4 Programmer's Guide qFORTH Dictionary ELSE "ELSE" Purpose: Part of the IF ... ELSE ... THEN control structure. ELSE, like IF and THEN may be used only within a colon definition. Its use is optional. ELSE executes after the TRUE part following the IF construct. If the condition is true ELSE forces execution to skip over the following FALSE part and resumes execution following the THEN construct. If the condition is false the FALSE block after the ELSE instruction will be executed. Category: Control structure /qFORTH macro Library implementation: CODE ELSE SET_BCF ( set BRANCH&CARRY flag, FORCE jump (S)BRA _$THEN ( to end of IF statement _$ELSE: [E0 R0] END-CODE Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY and BRANCH flags are affected X Y registers: not affected Bytes used: 2-3 See also: IF THEN 306 ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary ELSE Example: : IfElseThen 1 2 <= IF 1 ELSE 0 THEN 12> IF DROP 0 THEN 12> IF 0 ELSE 1 THEN 2DROP ( is 1 <= 2 ? ( yes, so the If block will be executed. ( a 1 will be pushed onto the stack. ( ( true => no execution of the ELSE block. ( ) ) ) ) ) ) ( is 1 > 2 ? ( ( false: nothing will be executed. ( ( ( is 1 > 2 ? ( ( not true => no execution. ( in this case, the ( ELSE block will be executed ( the results from the Expression Stack. ) ) ) ) ) ) ) ) ) ) ) ; 03.01 307 MARC4 Programmer's Guide qFORTH Dictionary END-CODE "END-CODE" Purpose: Terminates an 'in-line' CODE definition. Category: Predefined data structure Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: CODE <-> ':' and ';' 308 03.01 MARC4 Programmer's Guide qFORTH Dictionary END-CODE Example 1: 3 ARRAY ReceiveData ( 12-bit data item (--------------------- CODE to shift right a 12-bit data word CODE ShiftRDBits ReceiveData Y! CLR_BCF ( clear the CARRY for first shift [Y]@ ROR [Y]! [+Y]@ ROR [Y]! ( rotate thru CARRY [+Y]@ ROR [Y]! END-CODE ) ) ) ) : Example 2: ReceiveData Y! ( start address to Y register. 5 [Y]! Ah [+Y]! 0 [+Y]! ShiftRDBits ( shift 'ReceiveData' 1 bit right ) ) ; 03.01 309 MARC4 Programmer's Guide qFORTH Dictionary ENDCASE "End-CASE" Purpose: Terminates a CASE ... OF ... ENDOF ... ENDCASE structure. When it executes, ENDCASE drops the 4-bit CASE index value if it does not match any of the OF comparison values. The 'OTHERWISE' case may be handled by a sequence placed between the last ENDOF and ENDCASE. Please note, however, that a value must be preserved across this sequence so that ENDCASE can drop it. Category: Control structure /qFORTH macro Library implementation: CODE ENDCASE DROP ( n -- ) _$ENDCASE: [ E -1 R 0 ] END-CODE Stack effect: EXP EXP RET Stack changes: EXP: 1 element will be popped from the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: CASE OF ENDOF 310 ( n -- ) (if no match ( -- ) (if matched, then not executed ( -- ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary ENDCASE Example: 5 CONSTANT Keyboard 1 CONSTANT Port1 : ONE 1 Port1 OUT ; ( write 1 to the 'Port1' : TWO 2 Port1 OUT ; ( write 2 to the 'Port1' : THREE 3 Port1 OUT ; ( write 3 to the 'Port1' : ERROR DUP Port1 OUT ; ( dump wrong input to Port1 ( duplicate value for the following ENDCASE; it drops one n. ) ) ) ) ) : CASE-Example KeyBoard IN CASE 1 OF ONE ENDOF 2 OF TWO ENDOF 3 OF THREE ENDOF ERROR ENDCASE ; ) ) ) ) ) ) ) 03.01 ( request 1-digit keyboard input ( depending of the input value, ( one of these words will be ( activated. ( ( otherwise ... ( n -- 311 MARC4 Programmer's Guide qFORTH Dictionary ENDOF "End-OF" Purpose: Part of the OF ... ENDOF structure used within CASE ... ENDCASE. When an OF comparison value matches the CASE index value, ENDOF transfers control to the word following ENDCASE. If there was no match, control proceeds with the word following ENDOF. Category: Control structure /qFORTH macro Library implementation: CODE ENDOF SET_BCF (S)BRA _$ENDCASE _$ENDOF: [E0 R0] END-CODE Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag Set BRANCH flag Set X Y registers: not affected Bytes used: 2-3 See also: ENDCASE CASE OF 312 03.01 MARC4 Programmer's Guide qFORTH Dictionary ENDOF Example: 5 CONSTANT Keyboard 1 CONSTANT Port1 : ONE 1 Port1 OUT ; ( write 1 to the 'Port1' : TWO 2 Port1 OUT ; ( write 2 to the 'Port1' : THREE 3 Port1 OUT ; ( write 3 to the 'Port1' : ERROR DUP Port1 OUT ; ( dump wrong input to the Port1 ( duplicate value for the following ENDCASE; it drops one n. : CASE-Example KeyBoard IN CASE 1 OF ONE ENDOF 2 OF TWO ENDOF 3 OF THREE ENDOF ERROR ENDCASE ; 03.01 ( request 1-digit keyboard input ( depending of the input value, ( one of these words will be ) ( activated. ( ( otherwise ... ( n -- ) ) ) ) ) ) ) ) ) ) ) 313 MARC4 Programmer's Guide qFORTH Dictionary ERASE "ERASE" Purpose: Resets n digits in a block of memory (RAM) to zero. Whereas n is less than 16; if n is zero, then 16 nibbles of RAM is set to 0. Category: Memory operation (multiple-length) / qFORTH colon definition Library implementation: : ERASE <ROT Y! ( addr count -- count 0 [Y]! 1- ( count -- count-1 ) ) #DO 0 [+Y]! #LOOP ; Stack effect: EXP ( addr n -- ) RET ( -- ) Stack changes: EXP: 3 elements are popped from the stack RET: not affected Flags: CARRY flag not affected BRANCH flag Reset X Y registers: The contents of the Y register will be changed. Bytes used: 14 See also: FILL CONSTANT ARRAY 314 03.01 MARC4 Programmer's Guide qFORTH Dictionary ERASE Example: 6 CONSTANT #Nibbles 0 CONSTANT #16 3 CONSTANT TwoLgth #Nibbles ARRAY RamData 16 ARRAY ShortArray TwoLgth 2ARRAY TwoArray 20 2LARRAY TwoLongArray ( #_of_valid_bits ) ( nibble array with 6 elements and index from [0]..[5] ( index from [0] .. [15] ( this array includes bytes ) ) ) : ClearArrays RamData #Nibbles ERASE ( initialize the data array ShortArray #16 ERASE ( 'delete' 16 nibbles TwoArray TwoLgth*2 ERASE ( set whole array to 0. TwoLongArray [4] 8 ERASE ( set byte [4] to [7] to 0. ( for setting whole arrays with more than 16 nibbles to 0, ( a special routine is required; or activate ERASE twice ! ; 03.01 ) ) ) ) ) ) 315 MARC4 Programmer's Guide qFORTH Dictionary EXIT "EXIT" Purpose: Exits from the current colon definition. EXIT may be used in any of the following control structures: BEGIN ... REPEAT, IF ... THEN, CASE ... ENDCASE Note:EXIT may not be used inside of a DO loop ! For ending a colon definition, ';' is translated by the compiler to the EXIT instruction. Category: Control structure / assembler instruction MARC4 opcode: 25 hex Stack effect: EXP ( -- ) RET ( oldPC -- ) Stack changes: EXP: not affected RET: the return address (3 nibbles) is popped from the return stack into the program counter. Flags: not affected X Y registers: not affected Bytes used: 1 See also: ?LEAVE -?LEAVE ; RTI 316 03.01 MARC4 Programmer's Guide qFORTH Dictionary EXIT Example 1: : EXIT-Example 6 2 3 CMP_NE IF SWAP EXIT ELSE DROP THEN ; ( -- 6 2 3 ( 6 2 3 -- 6 2 ( if <> then EXIT else DROP TOS ( 6 2 -- 6 ) ) ) ) ( exits any DO .. LOOP ) Example 2: CODE Leave DROPR EXIT END-CODE : Horizontal? ( example for leave DO .. LOOP DO ( col row -- DUP I Pos@ = IF DROP 0 Leave [ R 0 ] THEN LOOP ; 03.01 ) ) 317 MARC4 Programmer's Guide qFORTH Dictionary EXECUTE "Execute" Purpose: Transfers control to the colon definition whose ROM code address is on the EXP stack. Category: Control structure Library implementation: : EXECUTE 3>R EXIT ; Stack effect: EXP ( ROM addr - - ) RET ( - - ROM addr - - ) Stack changes: EXP: 3 elements are popped from the stack RET: 1 entry is used intermediatly during execution Flags: CARRY flag not affected BRANCH flag not affected X Y registers: not affected See also: ' 318 ;; 03.01 MARC4 Programmer's Guide qFORTH Dictionary EXECUTE Example: : Do_Incr DROPR Time_count 1*! \ Skip return address [N]; : Do_Decr DROPR Time_count 1-! [N]; : Do_Reset DROPR 0 Time_Count ! [N]; : Jump_Table Do_Nothing Do_Inrc Do_Decr Do_Reset ;; AT FF0h \ Do not generate an EXIT : Exec_Example ( n - - ) >R ' Jump_Table R> 2* M+ \ calculate vector address EXECUTE ; 03.01 319 MARC4 Programmer's Guide qFORTH Dictionary FILL "FILL" Purpose: Fill a block of memory (n1 nibbles; 0 <= n1 <= Fh) with a specified digit (n2). Category: Memory operation (multiple-length) / qFORTH colon definition Library implementation: : FILL 2SWAP Y! DUP [Y]! SWAP 1- ( addr count n -- count n addr ( count n addr -- count n ( count n -- n count-1 ) ) ) #DO DUP [+Y]! #LOOP DROP ; Stack effect:: EXP RET Stack changes: EXP: 4 elements are popped from the stack RET: not affected Flags: CARRY flag not affected BRANCH flag reset X Y registers: The contents of the Y register are changed. Bytes used: 16 + '2SWAP' See also: ERASE 320 ( addr n1 n2 -- ( -- ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary FILL Example: 8 CONSTANT Size Size ARRAY Digits : Fill_Example Digits Size 3 FILL 34h Fh 5 FILL 44h 0 6 FILL ; 03.01 ( -- address count data ( fill array digits with 3 ( RAM: 34h...42h - 15nibbles - will be 5. ( RAM: 44h...53h - 16nibbles - will be 6. ) ) ) ) 321 MARC4 Programmer's Guide qFORTH Dictionary I "I" R@ "R-Fetch" Purpose: Leaves (copies) the current #DO or DO loop index on the stack. If not used within a DO ... [+]LOOP, or #DO ... #LOOP, the value returned by I or R@ is undefined. Category: Stack operation (single-length) / assembler instruction Library implementation: CODE R@ I END-CODE (macro of 'R@') MARC4 opcode: 23 hex Stack effect: EXP ( -- index ) RET ( u|limit/u|index -- u|limit/u|index ) Stack changes: EXP: the current loop index will be pushed onto the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: J DO [+]LOOP 322 #DO ... #LOOP 03.01 MARC4 Programmer's Guide qFORTH Dictionary I R@ Example 1: 1 CONSTANT Port1 : HASH-DO-LOOP 14 #DO I Port1 OUT #LOOP ; ( loop 14 times ( write data to 'Port1': E, D, C, ..., 1. ( repeat the loop. ) ) ) Example 2: : Error 3R@ 3 #DO I OUT [ E 0 ] #LOOP [ E 0 ] ; : RFetch 13335 3 >R R@ < IF Error THEN R@ < IF Error THEN R@ > IF Error THEN R@ <> IF Error THEN R> >= IF Error THEN ; 03.01 ( show program counter, where CPU fails. ) ( write address to Port 1, 2 and 3 ) ( suppress compiler warnings. ) ( compare all these values with 3 ( move 3 to return stack ( copy 3 from RET several times ( 'Error' should never be called. ( ( ( return stack gets original state ) ) ) ) ) ) ) 323 MARC4 Programmer's Guide qFORTH Dictionary IF "IF" Purpose: Begins an IF ... ELSE ... THEN or IF ... THEN control structure. When IF is executed the BRANCH flag in the condition code register (CCR) determines the direction of the conditional branch. If the BRANCH flag is TRUE (set), the words between the IF and ELSE (or IF and THEN if no ELSE was compiled) are executed. If the BRANCH flag is false (= 0), and an ELSE clause exists, then the words between ELSE and THEN are executed. In either case, subsequent execution continues just after THEN. Category: Control structure /qFORTH macro Library implementation: CODE IF TOG_BF (S)BRA _$ELSE END-CODE ( complement B-Flag, FORCE jump if false ) ( to _ELSE / _THEN label ) Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag not affected BRANCH flag = NOT BRANCH flag X Y registers: not affected. Bytes used: 1-3 See also: THEN ELSE 324 03.01 MARC4 Programmer's Guide qFORTH Dictionary IF Example: : IfElseThen 1 2 <= IF 1 ELSE 0 THEN 12> IF DROP 0 THEN 12> IF 0 ELSE 1 THEN 2DROP ( is 1 <= 2 ? ( yes, so the If block is executed. ( a 1 will be pushed onto the stack. ( ( true => no execution of the ELSE block. ( ) ) ) ) ) ) ( is 1 > 2 ? ( ( false: nothing will be executed. ( ( ( is 1 > 2 ? ( ( not true => no execution. ( in this case, the ( ELSE block is executed ( the results from the expression stack. ) ) ) ) ) ) ) ) ) ) ) ; 03.01 325 MARC4 Programmer's Guide qFORTH Dictionary IN "IN" Purpose: Read data from an I/O ports. NOTE: Before changing the direction of a bidirectional (nibblewise I/O) port from output to input, first a value of 'Fh' should be written to that port. After power-on-reset, all bidirectional ports are switched to input. Category: Stack operation / assembler instruction MARC4 opcode: 1B hex Stack effect: EXP ( port -- data RET ( -- Stack changes: EXP: RET: ) ) The port address is pulled from the stack; the 'data' is pushed onto the stack. not affected Flags: CARRY flag not affected BRANCH flag set, if port = 0 ! X Y registers: not affected Bytes used: 1 See also: OUT 326 03.01 MARC4 Programmer's Guide qFORTH Dictionary IN Example 1: 1 CONSTANT Port1 : CountDown 15 #DO I Port1 OUT #LOOP ; ( 15 iterations ( copy index from return stack. ( Index is output to the 'Port1' ) ) ) ( port -- data ( port -- port Fh -- p Fh p -- p ( port -- nibble ) ) ) Example 2: : ReadPort Fh OVER OUT IN ; 03.01 327 MARC4 Programmer's Guide qFORTH Dictionary INDEX "INDEX" Purpose: The qFORTH word INDEX performs RAM address computations during runtime to give the programmer the ability to access any element of an ARRAY, 2ARRAY, etc. ... Category: Predefined data structure /qFORTH macro Library implementation: Different routines are available for ARRAY, 2ARRAY, ... Stack effect: EXP ( n d -- d ) EXP ( d d -- d ) RET ( -- ) Stack changes: EXP: 1/2 element(s) will be popped from the stack RET: not affected Flags: CARRY flag reset BRANCH flag = CARRY flag X Y registers: not affected Bytes used: uses 'D+' or 'M+' See also: @ ! ARRAY 2ARRAY LARRAY 2LARRAY 328 for ARRAY, 2ARRAY for LARRAY, 2LARRAY 03.01 MARC4 Programmer's Guide qFORTH Dictionary INDEX Example: 10 ARRAY 10 Nibbles : IndexExample ( write 1 .. 10 into the array [0] .. [9] 10 #DO I ( copy values for writing: A, 9, 8, ... 1 I 1- 10Nibbles INDEX ! #LOOP ( subtract 1 from index for [9] .. [0] ; 03.01 ) ) ) 329 MARC4 Programmer's Guide qFORTH Dictionary 'INT0 ... INT7' "Int-Zero" ... "Int-Seven" Purpose: The interrupt routines can be activated by external hardware or by internal software interrupts (SWI). These predefined HARDWARE/SOFTWARE interrupt service routines are placed at the following fixed addresses by the compiler: Interrupt Priority ROM Address INT0 INT1 INT2 INT3 INT4 INT5 INT6 INT7 lowest 040h 080h 0C0h 100h 140h 180h 1C0h 1E0h Interrupt Opcode (Acknowledge) Size (Bytes) AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA AAAAAA AAAAA AAAAAAAAA AAAAAAAAAAA AAAAA highest C8h D0h D8h E0h E8h F0h F8h FCh (SCALL 040h) (SCALL 080h) (SCALL 0C0h) (SCALL 100h) (SCALL 140h) (SCALL 180h) (SCALL 1C0h) (SCALL 1E0h) 64 64 64 64 64 64 32 unlimited During runtime the PC is set by the interrupt logic to the adresses determined by the compiler. If an interrupt routine gets too long, then the compiler will not be able to place this routine in the corresponding segment. To avoid this problem, it may be necessary to divide the routine and define parts of it as new colon definitions, which will be placed at other free ROM gaps. For more information about interrupts, please have a look in the other manuals ! Category: Interrupt handling Stack effect: EXP ( -- ) RET ( -- [old PC] ) on runtime Stack changes: EXP: not affected RET: 1 entry (old PC) is pushed onto the stade Flags: Will be saved on entry; the @ (fetch) and ! (store) instructions (X@ Y@ CCR@...) will be inserted in the opcode automatically by the compiler - if necessary. X Y registers: not affected Bytes used: 0 See also: SWI0 .. SWI7 RTI $AUTOSLEEP 330 03.01 MARC4 Programmer's Guide qFORTH Dictionary 'INT0 ... INT7' Example: : INT5 CCR@ Y@ X@ IncTime X! Y! CCR! ; 03.01 ( instructions will be inserted by the compiler automatically ( activate the time-increment module every 125 ms ( store the register data back automatically ( an RTI will occur in the opcode. ) ) ) ) 331 MARC4 Programmer's Guide qFORTH Dictionary J "J" Purpose: Leaves the loop index of the next outer DO or #DO loop on the stack when used within a nested loop. If not used within two DO ... [+]LOOP, or #DO ... #LOOP, the value returned by J is undefined. Category: Stack operation (single-length) /qFORTH macro Library implementation: CODE J 2R> I <ROT 2>R END-CODE ( -- limit I ( limit I -- limit I J ( limit I J -- J limit I ( J limit I -- J Stack effect: EXP RET Stack changes: EXP: 1 element will be pushed onto the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 6 See also: I DO ... [+]LOOP #DO ... #LOOP 332 ( -- J ( u|limit|J u|limit|I -- u|limit|J u|limit|I ) ) ) ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary J Example: 1 CONSTANT Port1 : HASH-DO-LOOP 6 #DO I Port1 OUT 2 #DO J Port1 OUT #LOOP #LOOP ; 03.01 ( loop 6 times ( write to 'Port1': 6, 5, 4, ..., 1. ( loop 2 times in the loop ( get index from outer loop. ( repeat the loop 2 times. ( repeat the loop 6 times. ( Port1 - result: 6, 6, 6, 5, 5, 5, 4, ... 2, 1, 1, 1, ) ) ) ) ) ) ) 333 MARC4 Programmer's Guide qFORTH Dictionary LARRAY "Long-ARRAY" Purpose: Allocates RAM space for storage of a long single-length (4-bit) array, using an 8-bit array index value. Therefore, the number of 4-bit array elements can be greater than 16. The qFORTH syntax is as follows: <number> LARRAY <identifier> [ AT <RAM-Addr> ] At compile time, LARRAY adds <name> to the dictionary and ALLOTs memory for storage of <number> single-length values. At execution time, <name> leaves the RAM address of the parameter field ( <name> [0] ) on the expression stack. The storage ALLOTed by an LARRAY is not initialized; see ERASE. Category: Predefined data structure Stack effect: EXP ( -- n ) RET ( -- Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: 2ARRAY ARRAY 2LARRAY Index ERASE 334 a fetch (@) on runtime ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary LARRAY Example: 12 64 ARRAY ShortArray LARRAY LongArray AT 68h : ArrayExample ShortArray [ShortArray Length] ERASE 7 LongArray [12] ! 8 #DO 0 0 LongArray 0 I 1- 2* M+ 2! #LOOP ; 03.01 ( normal array example. ) ( set all 12 nibbles to 0 ) 335 MARC4 Programmer's Guide qFORTH Dictionary LOOP "LOOP" Purpose: LOOP may be used to terminate either DO or ?DO loops. On each iteration of a DO loop, LOOP increments the loop index. It then compares the index to the loop limit to determine whether the loop should terminate. If the new index is incremented across the boundary between limit-1 and limit, the loop is terminated and the loop control parameters are discarded. Otherwise, control jumps back to the point just after the corresponding DO. Category: Control structure /qFORTH macro Library implementation: CODE Stack effect: EXP ( -- ) IF Index+1 < Limit THEN RET ( u|Limit|Index -- u|Limit|Index+1 ELSE RET ( u|Limit|Index -- LOOP 2R> ( -- limit index INC ( limit index -- limit index' OVER ( limit index' -- limit index' limit CMP_LT ( limit index' limit -- limit index' 2>R ( limit index' -- BRA _$DO( IF Index < limit, loop again _$LOOP: DROPR ( forget limit, index on RET stack [ E 0 R -1 ] END-CODE Stack changes: EXP: RET: Flags: CARRY and BRANCH flags are affected X Y registers: not affected Bytes used: 9 See also: DO #DO #LOOP +LOOP 336 ) ) ) ) ) ) ) ) ) not affected IF Index+1 = Limit THEN 1 element (3 nibbles) will be popped from the stack. 03.01 MARC4 Programmer's Guide qFORTH Dictionary LOOP Example: : DoLoop 62 DO I TestPort1 OUT LOOP 92 DO I TestPort1 OUT 2 +LOOP ; 03.01 ( limit and start on the stack. ( ( copy the index from the Return Stack. ( write 2, 3, 4, 5 to the 'TestPort1'. ( loop until limit = index. ( ) ) ) ) ) ) ( ( write 2, 4, 6, 8 to the 'TestPort1'. ( ) ) ) 337 MARC4 Programmer's Guide qFORTH Dictionary M+ "M-plus" Purpose: M+ adds the digit (4 bit) on top of the data stack to the 8-bit value below that Category: Arithmetic/logical (double-length) / FORTH colon definition Library implementation: : M+ + SWAP 0 +c SWAP ; Stack effect: EXP ( d1 n -- d2 RET ( -- Stack changes: EXP: 1 element is popped from the stack. RET: not affected Flags: CARRY flag set on arithmetic overflow BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 5 See also: D- D+ D2* D2/ 338 ) ) M- 03.01 MARC4 Programmer's Guide qFORTH Dictionary M+ Example: : MPlusMinus 13h 5 M+ 5 M- 2DROP 13h 15 M+ 2DROP FCh 9 M+ 9 M- 2DROP ; 03.01 ( 13h + 5 = 18h CARRY: % BRANCH: % ( 18h - 5 = 13h CARRY: % BRANCH: % ( two nibbles. ( 13h +15 = 22h CARRY: % BRANCH: % ( two nibbles. ( FCh + 9 = [105h]05h CARRY: 1 BRANCH: 1 ( 05h - 9 = FCh CARRY: 1 BRANCH: 1 ( two nibbles. ) ) ) ) ) ) ) ) 339 MARC4 Programmer's Guide qFORTH Dictionary M- "M-minus" Purpose: M- subtracts a nibble on the data stack from the 8-bit value below that. Category: Arithmetic/logical (double-length) / FORTH colon definition Library implementation: : M- - SWAP 0 -c SWAP ; Stack effect: EXP ( d1 n -- d2 RET ( -- Stack changes: EXP: 1 element is popped from the stack. RET: not affected Flags: CARRY flag set on arithmetic underflow BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 5 See also: D- D+ D2* D2/ 340 ) ) M+ 03.01 MARC4 Programmer's Guide qFORTH Dictionary M- Example: : MPlusMinus 13h 5 M+ 5 M- 2DROP 13h 15 M+ 2DROP FCh 9 M+ 9 M- 2DROP ; 03.01 ( 13h + 5 = 18h CARRY: % BRANCH: % ( 18h - 5 = 13h CARRY: % BRANCH: % ( two nibbles. ( 13h +15 = 22h CARRY: % BRANCH: % ( two nibbles. ( FCh + 9 = [105h]05h CARRY: 1 BRANCH: 1 ( 05h - 9 = FCh CARRY: 1 BRANCH: 1 ( two nibbles. ) ) ) ) ) ) ) ) 341 MARC4 Programmer's Guide qFORTH Dictionary MAX "MAX" Purpose: Leaves the greater of two 4-bit values on the stack. Category: Comparison (single-length) / qFORTH colon definition Library implementation: : MAX OVER ( n1 n2 -- n1 n2 n1 ) CMP_LT ( n1 n2 n1 -- n1 n2 [BRANCH flag]) BRA _LESS ( jump if n1 < n2 ) SWAP ( n1 n2 -- n2 n1 ) _LESS: DROP ( leave max number on stack ) [ E -1 R 0 ] ; Stack effect: IF n1 > n2 THEN EXP ELSE EXP RET ( n1 n2 -- n1 ( n1 n2 -- n2 ( -- ) ) ) Stack changes: EXP: 1 element will be popped from the stack RET: not affected Flags: CARRY and BRANCH flags are affected X Y register: not affected Bytes used: 7 See also: MIN DMAX DMIN 342 03.01 MARC4 Programmer's Guide qFORTH Dictionary MAX Example: : Min_Max Ah 2 MIN DROP 2 2 MIN DROP 2 Ah MIN DROP Ah 2 MAX DROP Ah Ah MAX DROP 2 Ah MAX DROP ; 03.01 ( -- A 2 -- 2 -- flags: CARRY - ( -- 2 2 -- 2 -- flags: - - ( -- 2 A -- 2 -- flags: - BRANCH ) ) ) ( -- A 2 -- A -- flags: CARRY BRANCH ( -- A A -- A -- flags: - - ( -- 2 A -- A -- flags: - - ) ) ) 343 MARC4 Programmer's Guide qFORTH Dictionary MIN "MIN" Purpose: Leaves the smaller of two 4-bit values on the stack. Category: Comparison (single-length) / qFORTH colon definition Library implementation: : MIN BRA _GREAT: OVER ( n1 n2 -- n1 n2 n1 ) CMP_GT ( n1 n2 n1 -- n1 n2 [BRANCH flag]) _GREAT ( jump if n1 > n2 ) SWAP ( n1 n2 -- n2 n1 ) DROP ( leave max number on stack ) [ E -1 R 0 ] ; Stack effect: IF n1 < n2 THEN EXP ELSE EXP RET ( n1 n2 -- n1 ( n1 n2 -- n2 ( -- ) ) ) Stack changes: EXP: 1 element will be popped from the stack RET: not affected Flags: CARRY and BRANCH flags are affected X Y registers: not affected Bytes used: 7 See also: MAX DMIN DMAX 344 03.01 MARC4 Programmer's Guide qFORTH Dictionary MIN Example: : Min_Max Ah 2 MIN DROP 2 2 MIN DROP 2 Ah MIN DROP Ah 2 MAX DROP Ah Ah MAX DROP 2 Ah MAX DROP ( -- A 2 -- 2 -- flags: CARRY - ( -- 2 2 -- 2 -- flags: - - ( -- 2 A -- 2 -- flags: - BRANCH ) ) ) ( -- A 2 -- A -- flags: CARRY BRANCH ( -- A A -- A -- flags: - - ( -- 2 A -- A -- flags: - - ) ) ) ; 03.01 345 MARC4 Programmer's Guide qFORTH Dictionary MOVE "MOVE" Purpose: Copies an array of digits from one memory location to another. Number of nibbles n : 2 <= n <= Fh (0 moves 16 nibbles) The digit at the LOWEST memory location is copied first [unlike 'MOVE>']. This allows the transfer of data between overlapping memory arrays from a higher to a lower address. Category: Memory operation (multiple-length) / qFORTH colon definition Library implementation: : MOVE Y! X! ( length SrcAddr DestAddr -- [X]@ [Y]! ( Move 1st element 1- #DO [+X]@ [+Y]! #LOOP ; Stack effect: EXP ( n from to -- RET ( -- Stack changes: EXP: 5 elements are popped from the stack RET: not affected Flags: CARRY flag not affected BRANCH flag reset X Y registers: Both the X and Y index registers will be affected. Bytes used: 14 See also: MOVE> FILL ERASE 346 ) ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary MOVE Example: 16 ARRAY A16 AT 40h : MoveArray A16 [15] Y! 0 ( write 0 ... Fh to RAM; start at 40h #DO I 1- [Y-]! #LOOP ( repeat 16 times: copy index to RAM. 4 A16 A16 [12] ( with start address and pre-increm.:o.k. MOVE ( 4 nibbles are moved 12 nibb's backwards ( same result, as with: '4 A16 [3] A16 [15] MOVE>' ! A16 [15] Y! 0 #DO I 1- [Y-]! #LOOP 4 A16 [7] A16 [5] MOVE A16 [15] Y! 0 #DO I 1- [Y-]! #LOOP 4 A16 [5] A16 [7] MOVE ( write 0 ... Fh to RAM; start at 40h ) ) ) ) ) ) ( repeat 16 times: copy index to RAM. ) ( with start address and pre-increm.: o.k. ) ( 4 nibbles are moved 2 nibbles backwards ) ( write 0 ... Fh to RAM; start at 40h ) ( repeat 16 times: copy index to RAM. ) ( with start address and pre-increm.: ) ( ERROR: overwriting of the source array. ) ; 03.01 347 MARC4 Programmer's Guide qFORTH Dictionary MOVE> "MOVE-greater" Purpose: Copies an array of digits from one memory location to another. Number of nibbles n : 2 <= n <= Fh (0 moves 16 nibbles) The digit at the HIGHEST memory location is copied first [unlike 'MOVE']. This allows the transfer of data between overlapping memory arrays from a LOWER to a HIGHER address. Category: Memory operation (multiple-length) / qFORTH colon definition Library implementation: : MOVE> Y! X! ( length SrcAddr DestAddr -- ) #DO [X-]@ [Y-]! #LOOP ; Stack effect: EXP ( n from to -- RET ( -- Stack changes: EXP: 5 elements are popped from the stack RET: not affected Flags: CARRY flag not affected BRANCH flag reset X Y register: Both the X and Y index registers are affected. Bytes used: 10 See also: MOVE FILL ERASE 348 ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary MOVE> Example: 16 ARRAY A16 AT 40h : MoveArray ( an array is used: start at 40h; end at 4Fh, with 0...Fh. A16 [15] Y! 0 ( write 0 ... Fh to RAM; start at 40h #DO I 1- [Y-]! #LOOP ( repeat 16 times: copy index to RAM. 4 A16 [6] A16 [9] ( with end address / post-decrement: o.k. MOVE> ( 4 nibbles are moved 3 nibbles forward. A16 [15] Y! 0 #DO I 1- [Y-]! #LOOP 4 A16 [9] A16 [6] MOVE> ( write 0 ... Fh to RAM; start at 40h ) ) ) ) ) ) ( repeat 16 times: copy index to RAM. ) ( with end address and post-decrement: ) ( ERROR: overwriting of the source array. ) A16 [15] Y! 0 ( write 0 ... Fh to RAM; start at 40h #DO I 1- [Y-]! #LOOP ( repeat 16 times: copy index to RAM. 4 A16 [3] A16 [15] ( with end address and post-decrement: MOVE> ( 4 nibbles are moved 12 nibbles forward. ( same result, as with: '4 A16 A16 [12] MOVE' ! ) ) ) ) ) ; 03.01 349 MARC4 Programmer's Guide qFORTH Dictionary NEGATE "NEGATE" Purpose: 2's complement of the TOS 4-bit value. Category: Arithmetic/logical(single-length) /qFORTH macro Library implementation: CODE NEGATE NOT 1+ ( n -- -n ) END-CODE Stack effect: EXP ( n1 -- -n1 ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag not affected BRANCH flag set, if (TOS = 0) X Y registers: not affected Bytes used: 2 See also: DNEGATE NOT 350 03.01 MARC4 Programmer's Guide qFORTH Dictionary NEGATE Example: code true 1 end-code code false 0 end-code : Negator 8 2 - 2 NEGATE 8 + = IF true ELSE false THEN DROP ; 03.01 ( this is only a simple example for 'true' ) (8 - 2 = 6 ( 2's complement of 2 add to 8 ( 8 + [- 2 ] = 6 ? ( is the result equal ? ( 'true' = 1 = YES ! ( end of test: drop the result. ) ) ) ) ) ) 351 MARC4 Programmer's Guide qFORTH Dictionary NOP "NOP" Purpose: No operation; one instruction cycle of time is used. This is useful if the processor has to wait a short time for an external device or interrupt. Category: Assembler instruction MARC4 opcode: 7C hex Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: $AUTOSLEEP 352 03.01 MARC4 Programmer's Guide qFORTH Dictionary NOP Example 1: ( Library implementation: of SWI0 ) CODE SWI0 0 1 SWI NOP ( activate the base task END-CODE ( the NOP gives time for task .. ( switching to the interrupt control logic . ) ) ) Example 2: : Delay #DO NOP NOP NOP #LOOP ; 03.01 ( n -- [wait 4+n*7 cycles, ..] ( 1 cycle / ..without S/CALL ] ( wait n * 3 cycles ( wait n * 4 cycles / 1 cycle ( wait 2 cycles ) ) ) ) ) 353 MARC4 Programmer's Guide qFORTH Dictionary NOT "NOT" Purpose: 1's complement of the value on top of the stack. Category: Arithmetic/logical(single-length) / assembler instruction MARC4 opcode: 17 hex Stack effect: EXP ( n1 -- /n1 ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag not affected BRANCH flag set, if (/n1 = 0) X Y registers: not affected Bytes used: 1 See also: XOR NEGATE OR AND 354 03.01 MARC4 Programmer's Guide qFORTH Dictionary NOT Example: : NOT_Example 9 NOT DROP ; 03.01 ( -- 1001b ( 9 -- 0110b ( 6 -- ) ) ) 355 MARC4 Programmer's Guide qFORTH Dictionary OF "OF" Purpose: Part of the OF ... ENDOF block used within a CASE ... ENDCASE control structure. OF compares the CASE index value with another 4-bit comparision value. If they are equal, both of them are dropped from the stack and execution continues with the sequence compiled between OF and the next ENDOF. If there was no match, only the comparision value is dropped, and control proceeds with the word following the next ENDOF. Category: Control structure /qFORTH macro Library implementation: CODE OF CMP_NE (S)BRA _$ENDOF DROP [ E -1 R 0 ] END-CODE ( n1 n2 -- n1 [BRANCH flag] ( if no match then . ( branch to next OF ... ENDOF. ( n1 -- Stack effect: EXP ( n1 n2 -- n1 EXP ( n1 n2 -- RET ( -- Stack changes: EXP: 1 element is popped from the stack, if no match EXP: 2 elements are popped from the stack, on match RET: not affected Flags: CARRY and BRANCH flags are affected X Y registers: not affected Bytes used: 3-4 See also: ENDOF CASE ENDCASE 356 ) ) ) ) ) ) ) ( if no match ) ( if matched ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary OF Example: 5 CONSTANT Keyboard 1 CONSTANT TestPort1 : ONE 1 TestPort1 OUT ; ( write 1 to the 'TestPort1' : TWO 2 TestPort1 OUT ; ( write 2 to the 'TestPort1' : THREE 3 TestPort1 OUT ; ( write 3 to the 'TestPort1' : ERROR DUP TestPort1 OUT ; ( dump wrong input to the port ( duplicate value for the following ENDCASE; it drops one n. : CASE-Example KeyBoard IN CASE 1 OF ONE ENDOF 2 OF TWO ENDOF 3 OF THREE ENDOF ERROR ENDCASE ; 03.01 ) ) ) ) ) ( request 1-digit keyboard input ( depending on the input value, ( one of these words will be ( activated. ) ) ) ) ( otherwise ... ( n -- ) ) 357 MARC4 Programmer's Guide qFORTH Dictionary OR "OR" Purpose: Logical OR of the top two elements on the stack. Category: Arithmetic/logical(single-length) / assembler instruction MARC4 opcode: 0C hex Stack effect: : EXP ( n1 n2 -- [n1 v n2]) RET ( -- ) Stack changes: EXP: the TOP element is popped from the stack RET: not affected Flags: CARRY flag not affected BRANCH flag set, if ([n1 v n2] = 0) X Y registers: not affected Bytes used: 1 See also: XOR AND NOT 358 03.01 MARC4 Programmer's Guide qFORTH Dictionary OR Example: : ERROR 3R@ 3 #DO I OUT [ E 0 ] #LOOP ; : Logical 1001b 1100b AND 1000b <> IF ERROR THEN 1010b 0011b AND 0010b <> IF ERROR 1001b 1100b OR 1101b <> IF ERROR 1010b 0011b OR 1011b <> IF ERROR 1001b 1100b XOR 0101b <> IF ERROR 1010b 0011b XOR 1001b <> IF ERROR ; 03.01 ( what happens in case of errors: ) ( show PC, where CPU fails ( suppress compiler warnings. ) ) ( part of e3400 selftest kernel program ) ( IF 'result wrong' THEN call 'ERROR' ! ) THEN THEN THEN THEN THEN 359 MARC4 Programmer's Guide qFORTH Dictionary OUT "OUT" Purpose: Write data to one of the 4-bit I/O ports. Category: Stack operation / assembler instruction MARC4 opcode: 1F hex Stack effect: EXP ( data port -- RET ( -- Stack changes: EXP: data and address will be popped from the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: IN 360 ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary OUT Example: 1 CONSTANT Port1 5 CONSTANT Keyboard : Counter 15 #DO I Port1 OUT #LOOP ; : INT0 Keyboard IN #DO Counter #LOOP ; 03.01 ( 15 iterations ) ( copy the index from the Return Stack ) ( data is output to the port 1 ) ( input HEX value at keyboard - Port 5 ) ( DO-LOOP for the 'in' value ) ( call and execute the counter routine ) 361 MARC4 Programmer's Guide qFORTH Dictionary OVER "OVER" Purpose: Copies the second element onto the top of stack Category: Stack operation (single-length) / assembler instruction MARC4 opcode: 27 hex Stack effect: EXP ( n2 n1 -- n2 n1 n2 RET ( -- Stack changes: EXP: 1 element is pushed onto the top of stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: 2OVER 362 ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary OVER Example: : OVER-Example 3 7 4 OVER 2DROP 2DROP ; 03.01 ( -- 3 7 4 ) ( 3 7 4 -- 3 7 4 7) ( 3 7 4 7 -- ) 363 MARC4 Programmer's Guide qFORTH Dictionary PICK "PICK" Purpose: Copies a value from anywhere on the EXP stack to the TOS. PICK uses the value on the TOS as an index into the stack, and copies the value from that location in the stack. The value on the TOS [not including the index] is the 0th element. 0 <= x <= 14 NOTE: The actual EXP stack depth is not checked by this function, therefore the user should use the DEPTH instruction to ensure that the defined PICK index value is valid. ( i.e., that the depth of the stack permits the desired index) Category: Stack operation (single-length) / qFORTH colon definition Library implementation: : PICK SP@ ROT 1+ M- Y! [Y-]@ ( x SPh SPl -- SPh' SPl' ) ( SPh' SPl' -- n[x] ) ; Stack effect: EXP ( x -- n[x] ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY and BRANCH flags are affected X Y registers: The contents of the Y register will be changed. Bytes used: 8 + 'M-' See also: ROLL 364 03.01 MARC4 Programmer's Guide qFORTH Dictionary PICK Example: ( 0 PICK is equivalent to DUP ) ( 1 PICK is equivalent to OVER ) : PickRoll 12345678 9 Ah Bh Ch Dh Eh Fh 0 1 2 3 4 0 PICK DROP 1 PICK DROP 2 PICK DROP 9 PICK DROP 14 PICK DROP ( *** ROLL *** 0 ROLL 1 ROLL 13 ROLL 10 #DO DROP #LOOP 10 #DO DROP #LOOP ; 03.01 ( write data onto the stack: ( 20 values. ( ..2 3 4 -- ..2 3 4 4 ( ..2 3 4 -- ..2 3 4 3 ( ..2 3 4 -- ..2 3 4 2 ( ..2 3 4 -- ..2 3 4 B ( ..2 3 4 -- ..2 3 4 6 ( ( ..2 3 4 -- ..2 3 4 ( ..2 3 4 -- ..2 4 3 ( ..2 4 3 -- ..2 4 3 7 ) ) ) ) ) ) ) ) ) ) ) ( clear the stack: 20 DROPs ) 365 MARC4 Programmer's Guide qFORTH Dictionary R> "R-from" Purpose: Removes the top 4-bit value from the Return Stack and puts the value on the Expression Stack. R> pops the RET stack onto the EXP stack. To avoid corrupting the RET stack and crashing the system, each use of R> MUST be preceded by a >R within the same colon definition. Category: Stack operation (single-length) /qFORTH macro Library implementation: CODE R> R@ DROPR END-CODE ( copy the index and drop the RET stack) Stack effect: EXP ( -- n ) RET ( u|u|n -- ) Stack changes: EXP: 1 element is pushed onto the stack RET: 1 element (3 nibbles) is popped from the stack Flags: not affected X Y registers: not affected Bytes used: 2 See also: >R I 2>R 2R@ 2R> 3>R 3R@ 3R> 366 03.01 MARC4 Programmer's Guide qFORTH Dictionary R> Example: : 2SWAP >R <ROT R> <ROT ; ( swap 2nd byte with top ( d1 d2 -- n2_h d1 ( n2_h d1 -- d2 d1 ) ) ) : M/MOD >R Fh <ROT BEGIN ROT 1+ <ROT R@ M- UNTIL D>S R> + ; ( d n -- n_quot n_rem ( save divider on RET ( preset quotient = -1 ( increment quotient ( subtract divider ( until an underflow occurs ( n_quot d_rem-n -- n_quot n_rem ) ) ) ) ) ) ) 03.01 367 MARC4 Programmer's Guide qFORTH Dictionary RDEPTH "R-depth" Purpose: Leaves the depth of the RET stack, the current number of 12-bit entries, on top of the EXP stack. Category: Interrupt handling / qFORTH colon definition Library implementation: : RDEPTH RP@ D2/ D2/ NIP ; Stack effect: EXP ( -- n ) RET ( -- ) Stack changes: EXP: 1 element is pushed onto the stack. RET: not affected Flags: CARRY and BRANCH flags are affected X Y registers: not affected Bytes used: 12 See also: DEPTH RFREE INT0 ... INT7 368 ( -- RPh RPl (compute the modulo 4 number (of entries on the RET stack (forget entry of RDEPTH itself ) ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary RDEPTH Example: : Call_Again2 RDEPTH ; ( result is 2. ) : Call_Again1 RDEPTH Call_Again2 ; ( result is 1. ( next level - new address to RET. ) ) B: RDepth_Example RDEPTH Call_Again1 3DROP ; ( result is 0. ( next level - new address to RET. ( all results into wpb [waste]. ) ) ) : $RESET >RP NoRAM >SP S0 RDepth_Example ; 03.01 369 MARC4 Programmer's Guide qFORTH Dictionary REPEAT "REPEAT" Purpose: Part of the BEGIN ... WHILE ... REPEAT control structure. REPEAT forces an unconditional branch back to just after the corresponding BEGIN statement. Category: Control structure /qFORTH macro Library implementation: CODE REPEAT SET_BCF ( set BRANCH flag, force jump BRA _$BEGIN ( jump back to BEGIN _$LOOP: [E0 R0] END-CODE Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY and BRANCH flags are set X Y registers: not affected Bytes used: 2-3 See also: BEGIN WHILE UNTIL AGAIN 370 ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary REPEAT Example: 1 CONSTANT Port1 VARIABLE Count : COUNTER Count 1+! Count @ Port1 OUT ; : BEGIN-WHILE-REPEAT 10 BEGIN 1- DUP 0<> WHILE COUNTER REPEAT ; 03.01 ( increment Count ( write new Count to Port1 ) ) ( decrement the TOS from 10 to 0 ( save TOS ( REPEAT decrement while TOS not equal 0 ( other instructions in this loop ... ( after each decrement the TOS contains ( the value of the present index. ) ) ) ) ) ) 371 MARC4 Programmer's Guide qFORTH Dictionary RFREE "R-free" Purpose: Leaves the number of currently unused return stack entries on top of the Expression Stack, e.g. the available levels of nesting. Moves the addresses of the return stackpointer and the Expression Stack base address [S0] onto the Expression Stack and subtracts them. Final result = number of free levels for further 'calls'. Category: Interrupt handling /qFORTH macro Library implementation: : RFREE RDEPTH D2/ D2/ NIP SWAP - ; Stack effect: EXP ( -- n ) RET ( -- ) Stack changes: EXP: one nibble is pushed onto the Expression Stack. RET: not affected Flags: CARRY and BRANCH flags are affected X Y registers: not affected Bytes used: 17 + 'RDEPTH' See also: DEPTH RDEPTH 372 S0 ( Rn -- Rn S0h S0l ( Rn S0h S0l -- Rn Sn ( Rn Sn -- Rfree ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary RFREE Example: VARIABLE R0 27 ALLOT ( return stack: 28 nibbles, used 21 for ( 7 levels of task switching - additionally : ( 7 nibbles are free for 1-nibble-variables. VARIABLE S0 19 ALLOT ( data stack: 20 nibbles. ) ) ) ) : RFree3 RFREE : RFree2 RFREE RFree3 ; : RFree1 RFREE RFree2 ; : INT0 RFREE RFree1 ; 03.01 DROP ( result value is: 4 ) DROP ( result value is: 5 ( "call" next level. ) ) DROP ( result value is: 6 ( "call" next level. ) ) DROP ( result value is: 7 ( "call" next level. ) ) 373 MARC4 Programmer's Guide qFORTH Dictionary ROL "Rotate-left" Purpose: Rotate the TOS left through CARRY AAA AA AAAA AAAAAAAA AAAA AAA AAA AAAAA AAAA AAA AAA AAAAA AAAA AAA AAA AAAAAAAA AAA AA AAAA AAA AAA AA AAA AAAA AAA AAA AAAAA AAAA AAAAAA AAAAA AAAA AAA AAA TOS <--- Category: C <--- 3 2 1 0 <--- + Arithmetic/logical(single-length) / assembler instruction MARC4 opcode: 11 hex Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag = Bit3 of TOS - before operation BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 1 See also: ROR SHR SHL D2* 374 03.01 MARC4 Programmer's Guide qFORTH Dictionary ROL Example: : BitShift SET_BCF 3 ( 3 = 0011b ) ROR DROP ( [CARRY] 3 -- [CARRY] 9 = 1001b ) CLR_BCF 3 ( 3 = 0011b ) ROR DROP ( [no CARRY] 3 -- [CARRY] 1 = 0001b ) SET_BCF 3 ( 3 = 0011b ) ROL DROP ( [CARRY] 3 -- [no CARRY] 7 = 0111b ) CLR_BCF 3 ( 3 = 0011b ) ROL DROP ( [no CARRY] 3 -- [no CARRY] 6 = 0110b ) (---------------------------------------------------------------) CLR_BCF Fh ( ) 2/ DROP ( - SHR - [no CARRY] F -- [CARRY] 7 = 0111b ) ( ) CLR_BCF 6 ( 6 = 0110b ) 2* DROP ( - SHL - [no CARRY] 6 -- [no C] C = 1100b ) ; 03.01 375 MARC4 Programmer's Guide qFORTH Dictionary ROLL "Rol-L" Purpose: MOVES a value from anywhere on the EXP stack to the TOS. ROLL uses the value on the TOS as an index into the stack and moves the value at that location onto the TOS. The value on the TOS [not including the index] is the 0th element. 0 <= x <= 13 '0 ROLL', does nothing, '1 ROLL', is the same as SWAP, and '2 ROLL', is equivalent to ROT. '3 ROLL', ie. corresponds to ( n1 n2 n3 n4 -- n2 n3 n4 n1 ) Category: Stack operation (single-length) / qFORTH colon definition Library implementation: : ROLL ?DUP IF CCR@ DI >R ( save current I-flag setting on RET 1+ PICK >R ( move PICKed value on RET Y@ ( move ptr from Y -> X reg. 1 M+ X! ( adjust X reg. pointer #DO [+X]@ [+Y]! #LOOP(shift data values one down DROP R> R> CCR! ( restore I-flag setting in CCR ELSE DROP THEN ; Stack effect: EXP ( x -- ) RET ( -- ) Stack changes: EXP: 1 element is popped from the stack RET: not affected Flags: CARRY and BRANCH flags are affected X Y registers: Both, the X and Y index registers will be affected Bytes used: 39 + 'PICK' + 'M+' See also: PICK 376 ) ) ) ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary ROLL Example: : PickRoll 12345678 9 Ah Bh Ch Dh Eh Fh 0 1 2 3 4 0 PICK DROP 1 PICK DROP 2 PICK DROP 9 PICK DROP 14 PICK DROP 0 ROLL 1 ROLL 13 ROLL 10 #DO DROP DROP #LOOP 03.01 ( write data onto the stack: ( 20 values. ( ..2 3 4 -- ..2 3 4 4 =DUP ( ..2 3 4 -- ..2 3 4 3 =OVER ( ..2 3 4 -- ..2 3 4 2 ( ..2 3 4 -- ..2 3 4 B ( ..2 3 4 -- ..2 3 4 6 ( ..2 3 4 -- ..2 3 4 = NOP ( ..2 3 4 -- ..2 4 3 = SWAP ( ..2 4 3 -- ..2 4 3 7 ( clear the stack with 20*DROP ) ) ) ) ) ) ) ) ) ) ) 377 MARC4 Programmer's Guide qFORTH Dictionary ROMByte@ TABLE "ROM-byte-fetch" Purpose: Fetches an 8-bit constant from ROM onto TOS, whereby the 12-bit ROM address is on the Expression Stack. Category: Memory operation (double-length) / qFORTH colon definition MARC4 opcode: 20 hex (TABLE) Library implementation: : ROMByte@ 3>R TABLE Stack effect: ( ROMh ROMm ROMl -- d ( move TABLE address to RET stack ( -- consthigh constlow (TABLE returns directly to the CALLer during the microcode execution [ E -1 R 0 ] ;; ( therefore 'EXIT' is not required EXP RET ( ROMh ROMm ROMl -- consth constl ) ) ) ( -- ) Stack changes: EXP: 1 element will be popped from the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 2 See also: DTABLE@ ROMCONST 378 ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary ROMByte@ TABLE Example: ROMCONST DigitTable 10h , 1 , 2 , 3 , 4 , 45h , 6 , 7, 8 , 9, Ah , Bh , Ch , Dh , Eh , 0Fh , ( Pay attention to the blanks before and after the ',' and to the last ',' : D_Table@ 0 0 1 ROMByte@ 2DROP DigitTable 3>R 3R@ 5 DTABLE@ 2DROP 3R@ 1 DTABLE@ 2DROP 3R@ ROMByte@ 2DROP DigitTable 15 DTABLE@ 2DROP ( fetch byte at address 001h : 0Fh = SLEEP ( delete it. ( save address of L/U table on RET stack ( sixth byte of the table: ( put address and index on the stack. ( fetch and delete the value : 45h . ( second byte of the table: ( put address and index on the stack. ( fetch and delete the value : 01h . ( first byte of the table and min. index : ( put address on the stack. ( fetch and delete the value : 10h . ( last byte of the table and max. index ( put address and index on the stack. ( fetch and delete the value : 0Fh ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ; 03.01 379 MARC4 Programmer's Guide qFORTH Dictionary ROMCONST "ROM-CONSTANT" Purpose: Defines 8-bit constants in the ROM for look-up tables or as ASCII string constants. Attention to the blanks before and after the ',' and to the last ' , ' ! Category: Predefined data structure Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: Depends on number of defined table items (bytes) See also: DTABLE@ ROMByte@ Please note, that only a macro, colon or VARIABLE definition is allowed following a table definition! I.e. ROMCONST Tab1 10h, 13h, 55, 23h 2CONSTANT #Apples is not allowed since a ',' is exspected after 23h. 380 03.01 MARC4 Programmer's Guide qFORTH Dictionary ROMCONST Example 1: 13 CONSTANT TextLength 03h CONSTANT LCD_Data ROMCONST LCD_Text TextLength , " MARC4 Test " , : ExampleText TextLength #DO LCD_Text I DTABLE@ DecodeAscii 4 #DO LCD_Data OUT [ E 0 ] #LOOP [ E 0 ] #LOOP ; ( loop 'TextLength' times. ( gets: 2Eh '.', 44h 'D',..54h'T' ( convert 8-bit -> 16-bit - segm. ( write 4 * 4-bit to LCD. ( suppress warnings of compiler. ) ) ) ) ) Example 2: 0 CONSTANT Aa 1 CONSTANT Ab 2 CONSTANT Ac 3 CONSTANT Ad ROMCONST Matrix 0 1 2 3 : L/U-Table 2>R Matrix R@ 2* S>D D2* D+ IF ROT 1+ <ROT THEN 2R> DROP DTABLE@ ; : Exam2 ; 03.01 CONSTANT P1 CONSTANT P2 CONSTANT P3 CONSTANT P4 11 , 12 , 13 , 14 , 21 , 22 , 23 , 24 , 31 , 32 , 33 , 34 , 41 , 42 , 43 , 44 , ( Ss Pn -- 8-bit-value ( save indices on Return Stack ( push matrix base address ( compute parameter set offset ( ROMaddr := matrix + Pn * 4 ( handle MSD of matrix address ( load Aa ... Ad from RET stack ( fetch indexed value from ROM ) ) ) ) ) ) ) ) Ab P4 L/U-table 381 MARC4 Programmer's Guide qFORTH Dictionary ROR "Rotate-right" Purpose: Rotate right through CARRY AAA AA AAAA AAAAAAAA AAAA AAA AAA AAAAA AAAA AAA AAA AAAAA AAAA AAA AAA AAAAAAAA AAA AA AAAA AAA AAA AA AAA AAAA AAA AAA AAAAA AAAA AAAAAA AAAAA AAAA AAA AAA TOS ---> Category: C ---> 3 2 1 0 ----> C Arithmetic/logical (single-length) / assembler instruction MARC4 opcode: 13 hex Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag = bit0 of TOS - before operation BRANCH flag = CARRY flag X Y registers: not affected Bytes used: 1 See also: ROL SHR SHL 382 03.01 MARC4 Programmer's Guide qFORTH Dictionary ROR Example: : BitShift SET_BCF 3 ( 3 = 0011b ) ROR DROP ( [CARRY] 3 -- [CARRY] 9 = 1001b ) CLR_BCF 3 ( 3 = 0011b ) ROR DROP ( [no CARRY] 3 -- [CARRY] 1 = 0001b ) SET_BCF 3 ( 3 = 0011b ) ROL DROP ( [CARRY] 3 -- [no CARRY] 7 = 0111b ) CLR_BCF 3 ( 3 = 0011b ) ROL DROP ( [no CARRY] 3 -- [no CARRY] 6 = 0110b ) (----------------------------------------------------------------) CLR_BCF Fh ( ) 2/ DROP ( - SHR - [no CARRY] F -- [CARRY] 7 = 0111b ) ( ) CLR_BCF 6 ( 6 = 0110b ) 2* DROP ( - SHL - [no CARRY] 6 -- [no C] C = 1100b ) ; 03.01 383 MARC4 Programmer's Guide qFORTH Dictionary ROT "Rote" Purpose: Moves the third value on the stack to the top of the stack. Category: Stack operation (single-length) / assembler instruction MARC4 opcode: 2C hex Stack effect: EXP ( n1 n2 n3 -- n2 n3 n1 ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: 2ROT <ROT 2<ROT 384 03.01 MARC4 Programmer's Guide qFORTH Dictionary ROT Example: : ROTATE_Example 4 6 9 ROT 3DROP ; 03.01 ( -- 4 6 9 ) ( 4 6 9 -- 6 9 4 ) ( 6 9 4 -- ) 385 MARC4 Programmer's Guide qFORTH Dictionary RP@ "R-P-fetch" Purpose: Fetch the Return Stack pointer. Category: Assembler instruction MARC4 opcodes: 71 hex Stack effect: EXP ( -- RPh RPl ) RET ( -- ) Stack changes: EXP: 2 elements are pushed onto the stack RET: not affected RET: new base address Flags: not affected X Y registers: not affected Bytes used: 1 See also: SP! SP@ >SP $xx RP! >RP FCh R0 386 03.01 MARC4 Programmer's Guide qFORTH Dictionary RP@ Example: VARIABLE R0 47 ALLOT VARIABLE S0 19 ALLOT ( Return Stack: 48 nibbles 13 entry levels ( Data Stack: 20 nibbles. ( the qFORTH word RDEPTH uses 'RP@' to push the Return Stack ( pointer onto the Expression Stack : RDEPTH ( implementation code RP@ ( EXP stack : -- RPh RPl D2/ D2/ ( compute number of entries on the RET stack NIP ( EXP stack : 0 n -- n 1- ( forget the entry of RDEPTH itself. ; : $RESET > SP S0 > RP FCh RDEPTH DROP ; 03.01 ( initialize the stack pointers. ( set RP to autosleep address. ( result is 0 ) ) ) ) ) ) ) ) ) ) ) ) 387 MARC4 Programmer's Guide qFORTH Dictionary RP! "R-P-store" Purpose: Restore the Return Stack pointer. Category: Assembler instruction MARC4 opcodes: 75 hex Stack effect: RP!: EXP ( RPh RPl -- ) RET ( -- ) Stack changes: RP! EXP: 2 elements are popped from the stack RET: Return Stack pointer modified Flags: not affected X Y registers: not affected Bytes used: 1 See also: SP! SP@ >SP $xx RP@ >RP FCh R0 388 03.01 MARC4 Programmer's Guide qFORTH Dictionary RP! Example: VARIABLE R0 47 ALLOT VARIABLE S0 19 ALLOT ( Return Stack: 48 nibbles 13 entry levels ( Data Stack: 20 nibbles. ( the qFORTH word RDEPTH uses 'RP@' to push the Return Stack ( pointer onto the Expression Stack : RDEPTH ( implementation code RP@ ( EXP stack : -- RPh RPl D2/ D2/ ( compute number of entries on the RET stack NIP ( EXP stack : 0 n -- n 1- ( forget the entry of RDEPTH itself. ; : $RESET > SP S0 > RP FCh RDEPTH DROP ; 03.01 ( initialize the stack pointers. ( set RP to autosleep address. ( result is 0 ) ) ) ) ) ) ) ) ) ) ) ) 389 MARC4 Programmer's Guide qFORTH Dictionary >RP FCh, R0 "To-RP address" Purpose: Initialization of the Return Stack pointer. Category: Assembler instruction MARC4 opcodes: R0: predefined data structure >RP $xx = 79xx hex Stack effect: >RP $xx: EXP ( -- ) RET ( -- ) RP := $xx Stack changes: >RP $xx EXP: not affected RET: new base address Flags: not affected X Y registers: not affected Bytes used: 2 See also: SP! SP@ >SP $xx RP@ RP! 390 03.01 MARC4 Programmer's Guide qFORTH Dictionary >RP FCh, R0 Example: VARIABLE R0 47 ALLOT VARIABLE S0 19 ALLOT ( Return Stack: 48 nibbles 13 entry levels ( Data Stack: 20 nibbles. ( the qFORTH word RDEPTH uses 'RP@' to push the Return Stack ( pointer onto the Expression Stack : RDEPTH ( implementation code RP@ ( EXP stack : -- RPh RPl D2/ D2/ ( compute number of entries on the RET stack NIP ( EXP stack : 0 n -- n 1- ( forget the entry of RDEPTH itself. ; : $RESET > SP S0 > RP FCh RDEPTH DROP ; 03.01 ( initialize the stack pointers. ( set RP to autosleep address. ( result is 0 ) ) ) ) ) ) ) ) ) ) ) ) 391 MARC4 Programmer's Guide qFORTH Dictionary S>D "Single-to-double" Purpose: Transform a 4-bit value to an unsigned 8-bit value. Pushes 0 onto the 2nd stack position. Category: Stack operation / qFORTH macro Library implementation: CODE S>D LIT_0 SWAP ( n -- n 0 ) ( n 0 -- d ) END-CODE Stack effect: EXP ( n -- d ) RET ( -- ) Stack changes: EXP: 1 element (0) is pushed onto the 2nd stack position RET: not affected Flags: not affected X Y registers: not affected Bytes used: 2 See also: D>S 392 03.01 MARC4 Programmer's Guide qFORTH Dictionary S>D Example: : Bytes & Nibbles AAAAAAAAAAAA AA AA AA AA AA AAA AA AA AAA AAAAAAAAAAAA AA AA AA AA AA AAA AA AA AAA AAAAAAAAAAAA AA AAAA AAAA AAA AAAA AAA AAAAAAAAAAAA AA AA AA AA AA AAA AA AA AAA AAAAAAAAAAAA AA AAAA AAAA AAA AAAA AAA AAAAAAAAAAAA AA AAAA AAAA AAA AAAA AAA 4 S>D 25h D+ D>S DROP ; 03.01 ( ( ( ( ( 4 0 4 2 5 2 9 9 -- -- -- -- -- 4 0 2 9 ) 4 ) 9 ) ) ) 393 MARC4 Programmer's Guide qFORTH Dictionary SP@ "S-P-fetch" Purpose: Fetch the Expression Stack pointer onto the TOS Category: Assembler instruction MARC4 opcodes: 70 hex Stack effect: EXP ( -- SPh SPl ) RET ( -- ) Stack changes: EXP: 'stack pointer + 1' is pushed onto the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: RP! RP@ >RP FCh SP! >SP S0 394 03.01 MARC4 Programmer's Guide qFORTH Dictionary SP@ Example 1: VARIABLE S0 34 ALLOT \ Define EXP stack depth VARIABLE R0 80 ALLOT \ Define 21 RET stack entries ( The qFORTH word DEPTH uses 'SP@' to push the EXP stack ( pointer onto the Expression Stack ) ) : DEPTH SP@ S0 D- NIP 1- ; ( -- SPh SPl ( SPh SPl -- SPh SPl S0h S0l ( SPh SPl S0h S0l -- diffh diffl ( 0 n -- n ) ( result only on nibble, max Fh ( the value of SP on stack is incremented. ) ) ) ) ) ( initialize the stack pointers. ( Set RP to autosleep address. ( result is 0 ) ) ) : $RESET > SP S0 > RP NoRAM DEPTH DROP ; Example 2: Purpose: Add the 4-bit number on TOS to a 8-bit byte in RAM : M+ ( n addr - - ) X! [+X]@ + [X-]! [X]@ 0 +C [X]! ; : SRAMINIT ( -- ) >SP F9h SP@ X! 0 begin DROP Fh [X]! [X-]@ NOT 0h [X]! [X-]@ OR TOG_BF ?LEAVE DROP X@ 1- OR ( Test all addresses except 00 & 01 until ( Attention: RETURN address stack! Error_Flag ! ( Save result in Error_Flag at FFh ) ) ) >SP S0 [EON]; ) ) 03.01 ( Reset STACKPOINTER again !! ( Don't place in 'ZERO PAGE' 395 MARC4 Programmer's Guide qFORTH Dictionary SLEEP "Sleep" Purpose: The SLEEP instruction forces the MARC4 CPU into sleep mode, whereby the internal CPU clock is halted. The internal RAM data keeps valid during sleep mode. To wake up the CPU again, an interrupt must be received from a module (timer/counter, external interrupt pin or other modules). The CPU starts running at the ROM address where the interrupt service routine is placed. It is not recommended to use the SLEEP instruction other than in the $RESET level or the $AUTOSLEEP routine because it might result in unwanted side effects within other interrupt routines. If any interrupt is active or pending, the SLEEP instruction will be executed in the same way as an NOP! Category: interrupt handling / assembler instruction MARC4 opcode: 0F hex Stack effect: EXP ( - - ) RET ( - - ) Stack changes: EXP: not affected RET: not affected Flags: I_ENABLE flag: set CARRY and BRANCH flags: not affected X Y registers: not affected Bytes used: 1 See also: DI, EI, RTI, $AUTOSLEEP 396 03.01 MARC4 Programmer's Guide qFORTH Dictionary SLEEP Example: \ After POR, wait in power-down mode until a key is pressed to start the application : System _Init Setup_Peripherals Enable_KeyInt SLEEP NOP NOP BEGIN Port5 IN Port5 IN AND Fh = UNTIL Choose_Display 1_Hz .Set_BaseTimer ; 03.01 \ Enable INT1 for nest key input \ Wait for INT1 to happen here \Allow INT processing \ Wait until no key is pressed \ Show power-up display \ Setup 1 Hz INT5 397 MARC4 Programmer's Guide qFORTH Dictionary SP! "S-P-store" Purpose: Restore the Expression Stack pointer. Category: Assembler instruction MARC4 opcodes: 74 hex Stack effect: EXP ( SPh SPl -- ) RET ( -- ) Stack changes: EXP: 2 elements are popped into the stack pointer RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: RP! RP@ >RP $xx SP@ >SP S0 398 03.01 MARC4 Programmer's Guide qFORTH Dictionary SP! Example: VARIABLE S0 34 ALLOT \ Define EXP stack depth VARIABLE R0 80 ALLOT \ Define 21 RET stack entries : SP_ex DUP 0<> (n - - n) IF 2Ah \ This is a stupid example to re-adjust SP ELSE 2Fh THEN SP! ; 03.01 399 MARC4 Programmer's Guide qFORTH Dictionary >SP SO "To-SP S-zero" Purpose: Initialization of the Expression Stack pointer. Category: Assembler instruction MARC4 opcodes: S0: predefined data structure >SP $xx = 78xx Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: the Expression Stack pointer is initialized RET: not affected Flags: not affected X Y registers: not affected Bytes used: 2 See also: RP! RP@ >RP $xx SP@ SP! 400 03.01 MARC4 Programmer's Guide qFORTH Dictionary >SP SO Example 1: VARIABLE S0 34 ALLOT \ Define EXP stack depth VARIABLE R0 80 ALLOT \ Define 21 RET stack entries ( The qFORTH word DEPTH uses 'SP@' to push the EXP stack ( pointer onto the Expression Stack ) ) : DEPTH SP@ S0 D- NIP 1- ; ( -- SPh SPl ( SPh SPl -- SPh SPl S0h S0l ( SPh SPl S0h S0l -- diffh diffl ( 0 n -- n ) ( result only on nibble, max Fh ( the value of SP on stack is incremented. ) ) ) ) ) ( initialize the stack pointers. ( Set RP to autosleep address. ( result is 0 ) ) ) : $RESET > SP S0 > RP NoRAM DEPTH DROP ; Example 2: Purpose: Add the 4-bit number on TOS to a 8-bit byte in RAM : M+ ( n addr - - ) X! [+X]@ + [X-]! [X]@ 0 +C [X]! ; : SRAMINIT ( -- ) >SP F9h SP@ X! 0 begin DROP Fh [X]! [X-]@ NOT 0h [X]! [X-]@ OR TOG_BF ?LEAVE DROP X@ 1- OR ( Test all addresses except 00 & 01 until ( Attention: RETURN address stack! Error_Flag ! ( Save result in Error_Flag at FFh ) ) ) >SP S0 [EON]; ) ) 03.01 ( Reset STACKPOINTER again !! ( Don't place in 'ZERO PAGE' 401 MARC4 Programmer's Guide qFORTH Dictionary SET_BCF "Set-BRANCH-and-CARRY-flag" Purpose: Set the state of the BRANCH and CARRY flag in the MARC4 condition code register. Category: Assembler instruction MARC4 opcode: 19 hex Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag set BRANCH flag set X Y registers: not affected Bytes used: 1 See also: TOG_BCF CLR_BCF 402 03.01 MARC4 Programmer's Guide qFORTH Dictionary SET_BCF Example: : Error ( what happens in case of error: 3R@ 3 #D ( show PC, where CPU fails I OUT [ E 0 ] ( suppress compiler warnings #LOOP ; : CCRf CCR@ 1010b AND ; ( fetch - mask the used flags out : BC_Flags SET_BCF ( flags: C%BI - CARRY % BRANCH x CCRf 1010b ( BRANCH and CARRY flag is set <> IF Error THEN ( no error occured CLR_BCF ( delete BRANCH and CARRY flag CCRf 0000b ( all flags reset or masked off <> IF Error THEN ( no error occured CLR_BCF ( clear table from the compare before TOG_BF ( 0000 -> 00B0 CCRf 0010b ( BRANCH flag is set <> IF Error THEN ( no error occured SET_BCF ( define new machine state TOG_BF ( C%B% -> C%0% CCRf 1000b ( CARRY flag is still set <> IF Error THEN ( no error occured ; 03.01 ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) 403 MARC4 Programmer's Guide qFORTH Dictionary SWAP "SWAP" Purpose: Exchange the top two elements on the Expression Stack Category: Stack operation (single-length) MARC4 opcode: 26 hex Stack effect: EXP ( n2 n1 -- n1 n2 ) RET ( -- ) Stack changes: EXP: exchanges the top two elements with one another RET: not affected Flags: not affected X Y registers: not affected Bytes used: 1 See also: 2SWAP OVER 404 03.01 MARC4 Programmer's Guide qFORTH Dictionary SWAP Example: AAAAAAAAAAAA AA AA AA AA AA AA AAA AA AAA AAAAAAAAAAAA AA AA AA AA AA AA AAA AA AAA AAAAAAAAAAAA AA AAAAAA AAAA AAAAAAAA AAAAAAAAAAAA AA AA AA AA AA AA AAA AA AAA AAAAAAAAAAAA AA AAAAAA AAAA AAAAAAAA : SWAP-Example 374 SWAP DROP + 0= ; 03.01 ( ( ( ( -- 3 3 3 3 7 4 4 7 4 7 -- 4 -- 3 4 -- 3 4 7 -- 7 ) ) ) ) 405 MARC4 Programmer's Guide qFORTH Dictionary 'SWI0 . . . SWI7' "Software-interrupt-zero" ... "Software-interrupt-seven" Purpose: These qFORTH words generate a software interrupt. They allow the programmer to postpone less important tasks until all the important work is completed. Under special circumstances, it may also be used to spawn higher priority jobs from a lower priority task to make them less interruptable. Category: Interrupt handling Library implementation: CODE SWI3 0 8 SWI NOP (NOP gives time for task switch ) END-CODE Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 4 See also: RTI INT0 ... INT7 406 03.01 MARC4 Programmer's Guide qFORTH Dictionary 'SWI0 . . . SWI7' Example: : INT3 UpdateLCD ; ( software triggered interrupt #3 ( update LCD display ) ) : INT5 ScanKeys SWI3 Count 1+! Count @ 0= IF Overflow THEN ; ( external hardware interrupt - level 5 ( do most important action here and now ( more action later, after this job is ( finished; activated from the inter- ( rupt logic after the higher prioritised ( job is completed. ( compiler translates ';' to 'RTI'. ) ) ) ) ) ) ) 03.01 407 MARC4 Programmer's Guide qFORTH Dictionary T+! "T-plus-store" Purpose: ADD the TOS 12-bit value to a 12-bit variable in RAM and store the result in that variable. On function entry, the start/base address of the array is the TOS value. Category: Memory operation (triple-length) / qFORTH colon definition Library implementation: : T+! 2 M+ Y! [Y]@ + [Y-]! [Y]@ +c ( increment addr ) ( nh nm nl addr -- nh nm nl ) ( nh nm nl -- nh nm nl' ) ( nh nm nl' -- nh nm ) ( nh nm -- nh nm' [Y-]! [Y]@ +c ( nh nm' -- nh ( nh -- nh' ) [Y]! ( nh' -- ) ) ) ; Stack effect: EXP ( nh nm nl addr -- ) RET ( -- ) Stack changes: EXP: 5 elements are pushed from the stack RET: not affected Flags: CARRY flag set if arithmetic overflow BRANCH flag = CARRY flag X Y registers: The contents of the Y register will be changed. Bytes used: 14 + 'M+' See also: 3@ 3! T-! 408 03.01 MARC4 Programmer's Guide qFORTH Dictionary T+! Example: 3 ARRAY 3Nibbles AT 40h : Triples 123h3Nibbles 3! 321 3Nibbles T+! 3Nibbles 3@ 3>R 123h 3Nibbles T-! DROPR ; 03.01 ( store 123 in the 3 nibbles array. ( 123 + 321 = 444 ( save the result onto Return Stack. ( 444 - 123 = 321 ( forget the saved result on Return Stack. ) ) ) ) ) 409 MARC4 Programmer's Guide qFORTH Dictionary T-! "T-minus-store" Purpose: Subtracts the TOS 12-bit value from a 12-bit variable in RAM and stores the result in that variable. On function entry the start/base address of the array is the TOS value. Category: Memory operation (triple-length) / qFORTH colon definition Library implementation: : T-! 2 M+ Y! [Y]@ SWAP - [Y-]! [Y]@ SWAP -c [Y-]! [Y]@ SWAP -c [Y]! ( increment addr ( nh nm nl addr -- nh nm nl ( nh nm nl -- nh nm rl nl ( nh nm rl nl -- nh nm ( nh nm -- nh rm nm ( nh rm nm -- nh ( nh -- rh nh ( rh nh -- ) ) ) ) ) ) ) ) ; Stack effect: EXP ( nh nm nl addr -- ) RET ( -- ) Stack changes: EXP: 5 elements are pushed from the stack RET: not affected Flags: CARRY flag set, if arithmetic underflow BRANCH flag = CARRY flag X Y registers: The contents of the Y register are changed. Bytes used: 17 + 'M+' See also: 3@ 3! T+! 410 03.01 MARC4 Programmer's Guide qFORTH Dictionary T-! Example: 3 ARRAY 3Nibbles AT 40h : Triples 123h 3Nibbles 3! 321 3Nibbles T+! 3Nibbles 3@ 3>R 123h 3Nibbles T-! DROPR ; 03.01 ( store 123 in the 3 nibbles array. ( 123 + 321 = 444 ( save the result onto Return Stack. ( 444 - 123 = 321 ( forget the saved result on Return Stack ) ) ) ) ) 411 MARC4 Programmer's Guide qFORTH Dictionary TD+! "T-D-plus-store" Purpose: ADD the 8-bit number on the stack to an 12-bit element in RAM and store the result in that variable. On function entry, the start base address of the array is the TOS value. Category: Arithmetic/logical (triple-length) / qFORTH colon definition Library implementation: : TD+! 2 M+ Y! [Y]@ + [Y-]! [Y]@ +c [Y-]! 0 [Y]@ +c [Y]! ; ( increment addr ( nh nl addr -- nh nl ( nh nl -- nh rl' ( nh rl' -- nh ( nh -- nh rm' ( nh rm' -- 0 ( 0 -- rh' ( rh' -- Stack effect: EXP ( d addr -- ) RET ( -- ) Stack changes: EXP: 4 elements are popped from the stack. RET: not affected Flags: CARRY flag set if arithmetic overflow BRANCH flag = CARRY flag X Y registers: The contents of the Y register are changed. Bytes used: 15 + 'M+' 412 ) ) ) ) ) ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary TD+! Example: 3 ARRAY 3Nibbles : TripDigi F87h 3Nibbles 3! 44h 3Nibbles TD+! 44h 3Nibbles TD+! 44h 3Nibbles TD-! 44h 3Nibbles TD-! ; 03.01 ( store F87 in the RAM. ( F87 + 44 = FCB CARRY: % BRANCH: % ( FCB + 44 = [1]00F CARRY: 1 BRANCH: 1 ( 00F - 44 = FCB CARRY: 1 BRANCH: 1 ( FCB - 44 = F87 CARRY: % BRANCH: % ) ) ) ) ) 413 MARC4 Programmer's Guide qFORTH Dictionary TD-! "T-D-minus-store" Purpose: SUBTRACT the 8-bit number on the stack from an 12-bit element in RAM and store the result in that variable. On function entry, the start base address of the array is the TOS value. Category: Arithmetic/logical (triple-length) / qFORTH colon definition Library implementation: : TD-! 2 Y! [Y]@ - [Y]@ -c [Y]@ -c ; M+ SWAP [Y-]! SWAP [Y-]! 0 [Y]! ( increment addr ( nh nl addr -- nh nl ( nh nl -- nh rl nl ( nh rl nl -- nh ( nh -- rm nh ( rm nh -- [borrow] ( [borrow] -- rh 0 ( rh 0 -- Stack effect: EXP ( d addr -- ) RET ( -- ) Stack changes: EXP: 4 elements are popped from the stack. RET: not affected Flags: CARRY flag set if arithmetic underflow BRANCH flag = CARRY flag X Y registers: The contents of the Y register are changed. Bytes used: 17 + 'M+' See also: 3@ 3! T-! 414 ) ) ) ) ) ) ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary TD-! Example: 3 ARRAY 3Nibbles : TripDigi F87h 3Nibbles 3! 44h 3Nibbles TD+! 44h 3Nibbles TD+! 44h 3Nibbles TD-! 44h 3Nibbles TD-! ; 03.01 ( store F87 in the RAM. ( F87 + 44 = FCB CARRY: % BRANCH: % ( FCB + 44 = [1]00F CARRY: 1 BRANCH: 1 ( 00F - 44 = FCB CARRY: 1 BRANCH: 1 ( FCB - 44 = F87 CARRY: % BRANCH: % ) ) ) ) ) 415 MARC4 Programmer's Guide qFORTH Dictionary THEN "THEN" Purpose: Part of the IF ... ELSE ... THEN control structure which closes the corresponding IF statement. The IF block will be executed ONLY if the condition is TRUE, otherwise - if available - the ELSE block is executed. If the condition is FALSE, the processing goes on with the ELSE part; if there is no ELSE part, the processing goes on after the THEN label. Category: Control structure Library implementation: CODE THEN _$THEN: END-CODE [E0 R0] Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY and BRANCH flags are affected X Y registers: not affected Bytes used: 0 See also: IF ELSE 416 03.01 MARC4 Programmer's Guide qFORTH Dictionary THEN Example: : IfElseThen 1 2 <= IF 1 ELSE 0 THEN 12> IF DROP 0 THEN 12> IF 0 ELSE 1 THEN 2DROP ( is 1 <= 2 ? ( yes, so the If block is executed. ( a 1 will be pushed onto the stack. ( ( true => no execution of the ELSE block. ( ( is 1 > 2 ? ( ( false: nothing will be executed. ( ( ( is 1 > 2 ? ( ( not true => no execution. ( in this case, the ( ELSE block will be executed ( the results from the expression stack. ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ; 03.01 417 MARC4 Programmer's Guide qFORTH Dictionary TOGGLE "TOGGLE" Purpose: TOGGLEs [exclusive-or] a 4-bit variable at a specified memory location with a given bit pattern. On entry to this function, the 8-bit address of the variable is on the top of stack. Category: Memory operation (single-length) /qFORTH macro Library implementation: CODE TOGGLE Y! ( n1 addr -- n1 [Y]@ ( n1 -- n1 n2 XOR ( n1 n2 -- n3 [Y]! ( n3 -- END-CODE ) ) ) ) Stack effect: EXP ( n1 addr -- ) RET ( -- ) Stack changes: EXP: 3 elements are popped from the stack RET: not affected Flags: CARRY flag not affected BRANCH flag Set, if (TOS = 0) X Y registers: The contents of the Y or X register may be changed. Bytes used: 4 See also: DTOGGLE XOR 418 03.01 MARC4 Programmer's Guide qFORTH Dictionary TOGGLE Example: VARIABLE Hoss : D_Toggle 5 Hoss ! 3 Hoss TOGGLE Fh Hoss ! Fh Hoss TOGGLE Fh Hoss TOGGLE ( set in the RAM one nibble to 0101 ( truth table: 0101 XOR 0011 = 0110 ( flags: no BRANCH ( set in the RAM one nibble to Fh. ( 1111 XOR 1111 = 0000 ( flags: BRANCH ( 0000 XOR 1111 = 1111 ( flags: no BRANCH ) ) ) ) ) ) ) ) ; 03.01 419 MARC4 Programmer's Guide qFORTH Dictionary TOG_BF "Toggle-BRANCH-flag" Purpose: Toggle the state of the BRANCH flag in the MARC4 condition code register. If the BRANCH flag = 1 THEN reset the BRANCH flag to 0 ELSE set the BRANCH flag to 1. Category: Assembler instruction MARC4 opcode: 18 hex Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag not affected BRANCH flag = NOT BRANCH flag X Y registers: not affected Bytes used: 1 See also: SET_BCF CLR_BCF 420 03.01 MARC4 Programmer's Guide qFORTH Dictionary TOG_BF Example: : Error ( what happens in case of error: 3R@ 3 #D ( show PC, where CPU fails I OUT [ E 0 ] ( suppress compiler warnings #LOOP ; : CCRf CCR@ 1010b AND ; ( fetch - mask the used flags out : BC_Flags SET_BCF ( flags: C%BI - CARRY % BRANCH x CCRf 1010b ( BRANCH and CARRY flag is set <> IF Error THEN ( no error occured CLR_BCF ( delete BRANCH and CARRY flag CCRf 0000b ( all flags reset or masked off <> IF Error THEN ( no error occured CLR_BCF ( clear table from the compare before TOG_BF ( 0000 -> 00B0 CCRf 0010b ( BRANCH flag is set <> IF Error THEN ( no error occured SET_BCF ( define new machine state TOG_BF ( C%B% -> C%0% CCRf 1000b ( CARRY flag is still set <> IF Error THEN ( no error occured ; 03.01 ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) 421 MARC4 Programmer's Guide qFORTH Dictionary TUCK "TUCK" Purpose: Duplicates the top of the stack and copies the top of stack under the second 4-bit value. Category: Stack operation (single-length) /qFORTH macro Library implementation: CODE TUCK SWAP OVER END-CODE Stack effect: EXP ( n1 n2 -- n2 n1 n2 ) RET ( -- ) Stack changes: EXP: 1 element is pushed onto the stack RET: not affected Flags: not affected X Y registers: not affected Bytes used: 2 See also: 2TUCK ROT OVER 422 ( n1 n2 -- n2 n1 ( n2 n1 -- n2 n1 n2 ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary TUCK Example: : TUCK-Example 12 TUCK 3DROP ; 03.01 ( -- 1 2 ( 1 2 -- 2 1 2 ( 2 1 2 -- ) ) ) 423 MARC4 Programmer's Guide qFORTH Dictionary UNTIL "UNTIL" Purpose: Part of the BEGIN ... UNTIL control structure. When UNTIL is executed, the BRANCH flag determines the result of a conditional branch. If the BRANCH flag is set (TRUE), execution will continue with the word following the UNTIL statement. If the BRANCH flag is FALSE, control branches back to the word following BEGIN. Category: Control structure Library implementation: CODE UNTIL ( complement BRANCH flag TOG_BF BRA _$BEGIN ( BRANCH to BEGIN, if TRUE _$LOOP: [ E 0 R 0 ] END-CODE Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag not affected BRANCH flag = NOT BRANCH flag X Y registers: not affected Bytes used: 2-3 See also: BEGIN 424 ) ) 03.01 MARC4 Programmer's Guide qFORTH Dictionary UNTIL Example: : Example 3 BEGIN 1+ DUP 7 = UNTIL ; 03.01 ( increment from 3 until 7 ( TOS := TOS + 1 ( DUP current TOS because the compiler will ( DROP the current value ( the BRANCH flag is reset after the loop. ) ) ) ) ) 425 MARC4 Programmer's Guide qFORTH Dictionary VARIABLE "VARIABLE" Purpose: Allocates RAM memory for storage of a 4-bit value. The qFORTH syntax is as follows VARIABLE <name> [ AT <addr.> ] [ <number> ALLOT ] At compile time, VARIABLE adds <name> to the dictionary and ALLOTs memory for storage of one normal-length value. If AT <addr.> is appended, the variable/s will be placed at a specific address (i.e.: 'AT 40h'). If <number> ALLOT is appended, a set of <number+1> 4-bit memory locations is allocated. At execution time, <name> leaves the RAM start address on the expression stack. The storage ALLOTed by VARIABLE is not initialized. Category: Predefined data structure Stack effect: EXP ( -- d ) at execution time. RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: not affected X Y registers: not affected Bytes used: 0 See also: 2VARIABLE ALLOT ARRAY CONSTANT 426 03.01 MARC4 Programmer's Guide qFORTH Dictionary VARIABLE Example: 3 CONSTANT TimeLen VARIABLE R0 27 ALLOT ( return stack: 28 nibbles, used 21 for ( 7 levels of task switching. ( 7 nibbles are free for 1nibble variables. VARIABLE S0 19 ALLOT ( data stack: 20 nibbles. VARIABLE MainMode ( one 4-bit variable 2VARIABLE LargeCounter ( one 8-bit variable VARIABLE Nibble50 AT 50h ( 4-bit at a specific address in RAM VARIABLE MoreNibbles AT 40h 6 ALLOT ( 6 nibbles in the RAM. ) ) ) ) ) ) ) TimeLen ARRAY ActualTime ) 03.01 ( 3 nibble array. ) 427 MARC4 Programmer's Guide qFORTH Dictionary WHILE "WHILE" Purpose: Part of the BEGIN ... WHILE ... REPEAT control structure. When WHILE is executed, the BRANCH flag determines the destination of a conditional branch. If the BRANCH flag is set (TRUE), the instructions between WHILE and REPEAT are executed. If the BRANCH flag is FALSE, control branches to the word just past REPEAT. Category: Control structure Library implementation: CODE WHILE ( complement BRANCH flag TOG_BF BRA _$LOOP ( condjump just behind ) REPEAT loop) [E0 R0] END-CODE Stack effect: EXP ( -- ) RET ( -- ) Stack changes: EXP: not affected RET: not affected Flags: CARRY flag not affected BRANCH flag = NOT BRANCH flag X Y registers: not affected Bytes used: 1-3 See also: BEGIN REPEAT UNTIL 428 03.01 MARC4 Programmer's Guide qFORTH Dictionary WHILE Example: : Example 10 BEGIN 1- DUP 0<> WHILE DUP 1 OUT REPEAT ( decrement the TOS , from 10 to 0. ( save TOS ( REPEAT decrement while TOS not equal 0 ) ) ) ( after each decrement the TOS contains ( the value of the present index ) ) ; 03.01 429 MARC4 Programmer's Guide qFORTH Dictionary X@ "X fetch" Purpose: The X-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZE-XYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 72 hex Stack effect: EXP ( - - x_h x_l ) RET ( -- ) Stack changes: EXP: 2 elements are pushed onto the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: not affected Bytes used: 1 See also: X! 430 03.01 MARC4 Programmer's Guide qFORTH Dictionary X@ Example: : SRAMINIT >SP F9h SP@ X! 0 begin DROP X@ 1- OR until Error_Flag ! >SP S0 [EON]; 03.01 ( -- ) Fh [X]! [X-]@ NOT 0h [X]! [X-]@ OR TOG_BF ?LEAVE DROP ( Test all addresses except 00 & 01 ( Attention: RETURN address stack! ( Save result in Error_Flag at FFh ( Reset STACKPOINTER again !! ( Don't place in 'ZERO PAGE' ) ) ) ) ) 431 MARC4 Programmer's Guide qFORTH Dictionary X! "X store" Purpose: The X-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZEXYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 76 hex Stack effect: EXP ( x_h x_l - - ) RET ( -- ) Stack changes: EXP: 2 elements are popped from the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: not affected Bytes used: 1 See also: X@ Y! Y@ 432 03.01 MARC4 Programmer's Guide qFORTH Dictionary X! Example: Purpose: Add the 4-bit number on TOS to a 8-bit byte in RAM : M+ X! [+X]@ + [X-]! [X]@ 0 +C [X]! ; ( n addr - - ) : SRAMINIT >SP F9h SP@ X! 0 begin DROP ( -- ) X@ 1- OR until Error_Flag ! >SP S0 [EON]; 03.01 Fh [X]! [X-]@ NOT 0h [X]! [X-]@ OR TOG_BF ?LEAVE DROP ( Test all addresses except 00 & 01 ( Attention: RETURN address stack! ( Save result in Error_Flag at FFh ( Reset STACKPOINTER again !! ( Don't place in 'ZERO PAGE' ) ) ) ) ) 433 MARC4 Programmer's Guide qFORTH Dictionary [X]@ "indirect X fetch" Purpose: The X-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which uses these MARC4 instructions directly, the qFORTH compiler switch $OPTIMIZE-XYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 30 hex Stack effect: EXP ( - - n ) RET ( -- ) Stack changes: EXP: 1 element is pushed onto the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: used, but not changed Bytes used: 1 See also: [X]! [Y]! [Y]@ 434 03.01 MARC4 Programmer's Guide qFORTH Dictionary [X]@ Example: Purpose: Add the 4-bit number on TOS to a 8-bit byte in RAM : M+ X! [+X]@ + [X-]! [X]@ 0 +C [X]! ; 03.01 ( n addr - - ) 435 MARC4 Programmer's Guide qFORTH Dictionary [+X]@ "pre increment indirect X fetch" Purpose: The X-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZEXYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 31 hex Stack effect: EXP ( - - n ) RET ( - - ) Stack changes: EXP: 1 element is pushed onto the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: The X register is changed by this instruction. Bytes used: 1 See also: X! X@ [x]! [X]@ [+X]! [+Y]@ 436 03.01 MARC4 Programmer's Guide qFORTH Dictionary [+X]@ Example: Purpose: Add the 4-bit number on TOS to an 8-bit byte in RAM : M+ X! [+X]@ + [X-]! [X]@ 0 +C [X]! ; 03.01 ( n addr - - ) 437 MARC4 Programmer's Guide qFORTH Dictionary [X-]@ "post-decrement indirect X fetch" Purpose: The X-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZEXYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 32 hex Stack effect: EXP ( - - n ) RET ( - - ) Stack changes: EXP: 1 element is pushed onto the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: The X register is changed by this instruction Bytes used: 1 See also: X! X@ [X]@ [+X]@ [Y]@ [+Y]@ [Y-]@ 438 03.01 MARC4 Programmer's Guide qFORTH Dictionary [X-]@ Example: ( >Array= Compares two arrays, starting with the last element ( down to lower addresses. Maximal length: 16 elements ( n Addr1 Addr2 result is in branch flag ) ) ) : >Array= X! Y! 0 SWAP #DO [X-]@ [Y-]@ - OR #LOOP 0= ; 03.01 439 MARC4 Programmer's Guide qFORTH Dictionary [X]! "indirect X store" Purpose: The X-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZEXYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 38 hex Stack effect: EXP ( n - - ) RET ( - - ) Stack changes: EXP: 1 element is popped from the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: The X register is not changed by this instruction Bytes used: 1 See also: X! X@ [+X]! [X-]! [Y]! [+Y]! [Y-]! 440 03.01 MARC4 Programmer's Guide qFORTH Dictionary [X]! Example: Purpose: Add the 4-bit number on TOS to an 8-bit byte in RAM : M+ X! [+X]@ + [X-]! [X]@ 0 +C [X]! ; 03.01 ( n addr - - ) 441 MARC4 Programmer's Guide qFORTH Dictionary [+X]! "pre increment indirect X store" Purpose: The X-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZEXYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 39 hex Stack effect: EXP ( n - - ) RET ( - - ) Stack changes: EXP: 1 element is popped from the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: The X register is changed by this instruction Bytes used: 1 See also: X! X@ [X]! [X-]! [Y]! [+Y]! [Y-]! 442 03.01 MARC4 Programmer's Guide qFORTH Dictionary [+X]! Example: Purpose: Add the 4-bit number on TOS to a 8-bit byte in RAM : M+ X! [+X]@ + [X-]! [X]@ 0 +C [X]! ; 03.01 ( n addr - - ) 443 MARC4 Programmer's Guide qFORTH Dictionary [X-]! "post decrement indirect X store" Purpose: The X-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZEXYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 3A hex Stack effect: EXP ( n - - ) RET ( - - ) Stack changes: EXP: 1 element is popped from the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: The X register is changed by this instruction. Bytes used: 1 See also: X! X@ [X]@ [+X]@ [Y]! [+Y]! [Y-]! 444 03.01 MARC4 Programmer's Guide qFORTH Dictionary [X-]! Example: Purpose: Add the 4-bit number on TOS to a 8-bit byte in RAM : M+ X! [+X]@ + [X-]! [X]@ 0 +C [X]! ; 03.01 ( n addr - - ) 445 MARC4 Programmer's Guide qFORTH Dictionary XOR "XOR" Purpose: XOR leaves the bit-wise logical exclusive-or of the top two values on the Expression stack. Category: Arithmetic/logical (single-length) / assembler instruction MARC4 opcode: 04 hex Stack effect: EXP ( n1 n2 -- [n1 XOR n2] ) RET ( -- ) Stack changes: EXP: 1 element is popped from the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag set, if ([n1 XOR n2] = 0) X Y registers: not affected Bytes used: 1 See also: TOGGLE OR AND 446 03.01 MARC4 Programmer's Guide qFORTH Dictionary XOR Example: : Error 3R@ 3 #DO I OUT [ E 0 ] #LOOP ; ( what should happen in case of error: ) ( show PC, where CPU fails ( suppress compiler warnings. ) ) ) ) ) ) ) 3 5 XOR 6 <> IF Error THEN ( truth table: a b a XOR b ( 0 0 0 ( 0 1 1 ( 1 0 1 ( 1 1 0 (==================== ( = hexadec.: 3 5 6 ( ( BRANCH flag is reset [result <> 0] ( XOR top two values; error is not ( activated ( 1100b 1100b XOR 0000b <> IF Error THEN ( BRANCH flag is set [result = 0] ( XOR top two values; error is not ( activated. ( : XOR_Example ( -- ) ) ) ) ) ) ) ) ) ) ) ) ; 03.01 447 MARC4 Programmer's Guide qFORTH Dictionary Y@ "Y fetch" Purpose: The Y-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZE-XYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 73 hex Stack effect: EXP ( - - x_h x_l ) RET ( -- ) Stack changes: EXP: 2 elements are pushed onto the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: not affected Bytes used: 1 See also: Y! 448 03.01 MARC4 Programmer's Guide qFORTH Dictionary Y@ Example 1: 4 ARRAY Ramaddr AT 30h $OPTIMIZE - XYTRACE, -XY@! : Y-STORE Ramaddr [3] Y! 5 [Y-]! 6 [Y-]! 2 [Y-]! 7 [+Y]! ; $OPTIMIZE +XY@!, +XYTRACE ( assign the variable Ramaddr to the Y register ( store 5 in the RAM location 33 ( store 6 in the RAM location 32 ( store 2 in the RAM location 31 ( store 7 in the RAM location 31 ) ) ) ) ) Example 2: Purpose: Substract a 4-bit number on TOS from 8-bits in RAM : M-! Y! [+Y]@ - [Y-]! [Y]@ 0 -c [Y]! ; 03.01 ( n addr - - ) 449 MARC4 Programmer's Guide qFORTH Dictionary Y! "Y store" Purpose: The Y-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZEXYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 77 hex Stack effect: EXP ( x_h x_l - - ) RET ( -- ) Stack changes: EXP: 2 elements are popped from the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: not affected Bytes used: 1 See also: Y@ Y! X@ 450 03.01 MARC4 Programmer's Guide qFORTH Dictionary Y! Example 1: 4 ARRAY Ramaddr AT 30h $OPTIMIZE - XYTRACE, -XY@! : Y-STORE Ramaddr [3] Y! 5 [Y-]! 6 [Y-]! 2 [Y-]! 7 [+Y]! ; $OPTIMIZE +XY@!, +XYTRACE ( assign the variable Ramaddr to the Y register ( store 5 in the RAM location 33 ( store 6 in the RAM location 32 ( store 2 in the RAM location 31 ( store 7 in the RAM location 31 ) ) ) ) ) Example 2: Purpose: Substract a 4-bit number on TOS from 8-bits in RAM : M-! Y! [+Y]@ - [Y-]! [Y]@ 0 -c [Y]! ; 03.01 ( n addr - - ) 451 MARC4 Programmer's Guide qFORTH Dictionary [Y]@ "indirect Y fetch" Purpose: The Y-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZE-XYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 34 hex Stack effect: EXP ( - - n ) RET ( -- ) Stack changes: EXP: 1 element is pushed onto the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: used, but not changed Bytes used: 1 See also: [Y]! [Y]! [Y]@ 452 03.01 MARC4 Programmer's Guide qFORTH Dictionary [Y]@ Example 1: 4 ARRAY Ramaddr AT 30h $OPTIMIZE - XYTRACE, -XY@! : Y-STORE Ramaddr [3] Y! 5 [Y-]! 6 [Y-]! 2 [Y-]! 7 [+Y]! ; $OPTIMIZE +XY@!, +XYTRACE ( assign the variable Ramaddr to the Y register ( store 5 in the RAM location 33 ( store 6 in the RAM location 32 ( store 2 in the RAM location 31 ( store 7 in the RAM location 31 ) ) ) ) ) Example 2: Purpose: Substract a 4-bit number on TOS from 8 bits in RAM : M-! Y! [+Y]@ - [Y-]! [Y]@ 0 -c [Y]! ; 03.01 ( n addr - - ) 453 MARC4 Programmer's Guide qFORTH Dictionary [+Y]@ "pre increment indirect Y fetch" Purpose: The Y-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZEXYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 35 hex Stack effect: EXP ( - - n ) RET ( - - ) Stack changes: EXP: 1 element is pushed onto the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: The Y register is changed by this instruction. Bytes used: 1 See also: Y! Y@ [Y]! [Y]@ [+Y]! [+Y]@ 454 03.01 MARC4 Programmer's Guide qFORTH Dictionary [+Y]@ Example 1: 4 ARRAY Ramaddr AT 30h $OPTIMIZE - XYTRACE, -XY@! : Y-STORE Ramaddr [3] Y! 5 [Y-]! 6 [Y-]! 2 [Y-]! 7 [+Y]! ; $OPTIMIZE +XY@!, +XYTRACE ( assign the variable Ramaddr to the Y register ( store 5 in the RAM location 33 ( store 6 in the RAM location 32 ( store 2 in the RAM location 31 ( store 7 in the RAM location 31 ) ) ) ) ) Example 2: Purpose: Substract a 4-bit number on TOS from 8-bits in RAM : M-! Y! [+Y]@ - [Y-]! [Y]@ 0 -c [Y]! ; 03.01 ( n addr - - ) 455 MARC4 Programmer's Guide qFORTH Dictionary [Y-]@ "post decrement indirect Y fetch" Purpose: The Y-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZEXYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 36 hex Stack effect: EXP ( - - n ) RET ( - - ) Stack changes: EXP: 1 element is pushed onto the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: The Y register is changed by this instruction Bytes used: 1 See also: Y! Y@ [Y]@ [+Y]@ [X]@ [+X]@ [X-]@ 456 03.01 MARC4 Programmer's Guide qFORTH Dictionary [Y-]@ Example: ( >Array= Compares two arrays, starting with the last element ( down to lower addresses. Maximal length: 16 elements ( n Addr1 Addr2 result is in branch flag ) ) ) : >Array= X! Y! 0 SWAP #DO [X-]@ [Y-]@ - OR #LOOP 0= ; 03.01 457 MARC4 Programmer's Guide qFORTH Dictionary [Y]! "indirect Y store" Purpose: The Y-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZEXYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 3C hex Stack effect: EXP ( n - - ) RET ( - - ) Stack changes: EXP: 1 element is popped from the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: The Y register is not changed by this instruction Bytes used: 1 See also: Y! Y@ [+Y]! [Y-]! [X]! [+X]! [X-]! 458 03.01 MARC4 Programmer's Guide qFORTH Dictionary [Y]! Example 1: 4 ARRAY Ramaddr AT 30h $OPTIMIZE - XYTRACE, -XY@! : Y-STORE Ramaddr [3] Y! 5 [Y-]! 6 [Y-]! 2 [Y-]! 7 [+Y]! ; $OPTIMIZE +XY@!, +XYTRACE ( assign the variable Ramaddr to the Y register ( store 5 in the RAM location 33 ( store 6 in the RAM location 32 ( store 2 in the RAM location 31 ( store 7 in the RAM location 31 ) ) ) ) ) Example 2: Purpose: Substract a 4-bit number on TOS from 8 bits in RAM : M-! Y! [+Y]@ - [Y-]! [Y]@ 0 -c [Y]! ; 03.01 ( n addr - - ) 459 MARC4 Programmer's Guide qFORTH Dictionary [+Y]! "pre increment indirect Y store" Purpose: The Y-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZEXYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 3D hex Stack effect: EXP ( n - - ) RET ( - - ) Stack changes: EXP: 1 element is popped from the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: The Y register is changed by this instruction Bytes used: 1 See also: Y! Y@ [Y]! [Y-]! [X]! [+X]! [X-]! 460 03.01 MARC4 Programmer's Guide qFORTH Dictionary [+Y]! Example 1: 4 ARRAY Ramaddr AT 30h $OPTIMIZE - XYTRACE, -XY@! : Y-STORE Ramaddr [3] Y! 5 [Y-]! 6 [Y-]! 2 [Y-]! 7 [+Y]! ; $OPTIMIZE +XY@!, +XYTRACE ( assign the variable Ramaddr to the Y register ( store 5 in the RAM location 33 ( store 6 in the RAM location 32 ( store 2 in the RAM location 31 ( store 7 in the RAM location 31 ) ) ) ) ) Example 2: Purpose: Substract a 4-bit number on TOS from 8 bits in RAM : M-! Y! [+Y]@ - [Y-]! [Y]@ 0 -c [Y]! ; 03.01 ( n addr - - ) 461 MARC4 Programmer's Guide qFORTH Dictionary [Y-]! "post decrement indirect Y store" Purpose: The Y-register can be used as pointer to access variables or arrays in the RAM. For the compilation of a qFORTH word which directly uses these MARC4 instructions, the qFORTH compiler switch $OPTIMIZEXYTRACE should be turned off (no optimizing). Category: Assembler instruction MARC4 opcode: 3E hex Stack effect: EXP ( n - - ) RET ( - - ) Stack changes: EXP: 1 element is popped from the stack. RET: not affected Flags: CARRY flag not affected BRANCH flag not affected X Y registers: The Y register is changed by this instructions. Bytes used: 1 See also: Y! Y@ [Y]@ [+Y]@ [Y]! [+X]! [X-]! 462 03.01 MARC4 Programmer's Guide qFORTH Dictionary [Y-]! Example 1: 4 ARRAY Ramaddr AT 30h $OPTIMIZE - XYTRACE, -XY@! : Y-STORE Ramaddr [3] Y! 5 [Y-]! 6 [Y-]! 2 [Y-]! 7 [+Y]! ; $OPTIMIZE +XY@!, +XYTRACE ( assign the variable Ramaddr to the Y register ( store 5 in the RAM location 33 ( store 6 in the RAM location 32 ( store 2 in the RAM location 31 ( store 7 in the RAM location 31 ) ) ) ) ) Example 2: Purpose: Substract a 4-bit number on TOS from 8 bits in RAM : M-! Y! [+Y]@ - [Y-]! [Y]@ 0 -c [Y]! ; 03.01 ( n addr - - ) 463 MARC4 Programmer's Guide qFORTH Dictionary 464 03.01 MARC4 Programmer's Guide Index Index of "Detailed Description of the qFORTH Language" Symbols ! 94 ?DO 210 ?DUP 212 ?LEAVE 214 ; 190 ;; 192 : 188 ' 96 ' ( COMMENT)' \ 106 'INT0 ... INT7' 330 'SWI0 . . . SWI7' 406 [+X]! 442 [+X]@ 436 [+Y]! 460 [+Y]@ 454 [X]! 440 [X]@ 434 [X-]! 444 [X-]@ 438 [Y]! 458 [Y]@ 452 [Y-]! 462 [Y-]@ 456 #DO 98 #LOOP 100 $AUTOSLEEP 102 $INCLUDE 240 $RAMSIZE 242 $RESET 104 $ROMSIZE = 202 < 194 <= 196 <> 198 <ROT 200 > 204 >= 206 >R 208 >RP FCh 390 >SP 400 Numbers 0 ... Fh (15) 122 0= 126 0<> 124 1+ 128 1+! 130 1- 132 1-! 134 2! 136 2@ 146 2* 138 2/ 140 2<ROT 142 2>R 144 2ARRAY 148 2CONSTANT 150 2DROP 152 2DUP 154 2LARRAY 156 2NIP 158 242 2OVER 160 @ 216 2R@ 164 + 108 2R> 162 +! 110 2ROT 166 +C 112 2SWAP 168 +LOOP 114 2TUCK 170 - 116 2VARIABLE 172 -?LEAVE 118 3! 174 -C 120 3@ 178 03.01 465 MARC4 Programmer's Guide Index 3>R 176 3DROP 180 3DUP 182 3R@ 186 3R> 184 A ADD 108 ADDC 112 AGAIN 218 ALLOT 220 AND 222 ARRAY 224 AT 226 B BEGIN 228 C CASE 230 CCR! 232 CCR@ 234 CLR_BCF 236 CMP_EQ 202 CMP_GE 206 CMP_GT 204 CMP_LE 196 CMP_LT 194 CMP_NE 198 CODE 238 CONSTANT 244 D>= D>S D0= D0<> D2* D2/ DAA DAS DEC DECR DEPTH DI DMAX DMIN DNEGATE DO DROP DROPR DTABLE@ DTOGGLE DUP E EI ELSE END-CODE ENDCASE ENDOF ERASE EXECUTE EXIT 316 D+ 246 D+! 248 D- 250 D-! 252 D= 268 D< 262 D<= 264 D<> 266 J D> 270 J 466 304 306 308 310 312 314 318 190 F FILL D 272 274 256 254 258 260 276 278 132 280 282 284 286 288 290 292 294 296 298 300 302 320 I I IF IN INC INDEX 322 324 326 128 328 332 03.01 MARC4 Programmer's Guide Index L LARRAY 334 LIT_0 ... LIT_F 122 LOOP 336 M M+ 338 M- 340 MAX 342 MIN 344 MOVE 346 MOVE> 348 N NEGATE 350 NIP 274 NOP 352 NOT 354 O OVER 362 OF 356 OR 358 OUT 360 P PICK 364 R RP@ 386 RTI 190 S S>D 392 S0 400 SET_BCF 402 SHL 138 SHR 140 SLEEP 396 SP! 398 SP@ 394 SUB 116 SUBB 120 SWAP 404 T T+! 408 T-! 410 TD+! 412 TD-! 414 THEN 416 TOG_BF 420 TOGGLE 418 TUCK 422 U UNTIL 424 V R@ 322 R> 366 R0 390 W RDEPTH 368 REPEAT 370 WHILE RFREE 372 X ROL 374 X! 432 ROLL 376 X@ 430 ROMByte@ TABLE 378 XOR 446 ROMCONST 380 ROR 382 Y ROT 384 Y! 450 RP! 388 Y@ 448 03.01 VARIABLE 426 428 467 I. Hardware Description II. Instruction Set III. Programming in qFORTH IV. qFORTH Language Dictionary V. Addresses Sales Offices Addresses Europe France Atmel Versailles S.N.C. Les Quadrants - 3, Avenue du Centre BP 309 78054 St.-Quentin-en-Yvelines Cedex Tel: 33 1 30 60 70 00 Fax: 33 1 30 60 71 11 Germany Atmel Germany GmbH Erfurter Strasse 31 85386 Eching Tel: 49 89 3 19 70 0 Fax: 49 89 3 19 46 21 Spain United Kingdom Atmel Germany GmbH Kruppstrasse 6 45128 Essen Tel: 49 2 01 2 47 30 0 Fax: 49 2 01 2 47 30 47 Atmel Wireless & Microcontrollers Atmel Wireless & Microcontrollers Principe de Vergara, 112 28002 Madrid Tel: 34 91 564 51 81 Fax: 34 91 562 75 14 Easthampstead Road Bracknell, Berkshire RG12 1LX Tel: 44 1344 707 300 Fax: 44 1344 427 371 Atmel Germany GmbH Theresienstrasse 2 74072 Heilbronn Postfach 35 3574025 Heilbronn Tel: 49 71 31 67 36 36 Fax: 49 71 31 67 31 63 Sweden Atmel Wireless & Microcontrollers Italy Atmel Nordic AB Kavallerivaegen 24, Rissne POB 2042 17402 Sundbyberg Tel: 46 8 587 48 800 Fax: 46 8 587 48 850 Catalyst Business Centre Crewe Hall Weston Road Crewe, Cheshire CW1 1ZW Tel: 44 1270 252 209 Fax: 44 1270 250 825 Atmel Italia Srl Via Grosio, 10/8 20151 Milano Tel: 39 02 38037-1 Fax: 39 02 38037-234 North America / USA California New Jersey Atmel Corporation 2325 Orchard Parkway San Jose California 95131 Tel: 1 408 441 0311 Fax: 1 408 436 4200 Atmel-WM N.A., Inc c/o Atmel Corporation 1465 Route 31, 5th Floor Annandale New Jersey 08801 Tel: 1 908 848 5208 Fax: 1 908 848 5232 Asia Pacific / Japan China Japan Rep. of Singapore Atmel Shanghai Office Shanghai Eastern Business Bldg 586 Fanyu Road, 4th Floor, Block A 200052 Shanghai Tel: 86 21 6280 9241 Fax: 86 21 62807592 Atmel Japan K.K. Tonetsushinkawa Bldg. 1-24-8 Shinkawa, Chuo-Ku 104-0033 Tokyo Tel: 81 3 3523 3551 Fax: 81 3 3523 7581 Atmel Wireless & Microcontrollers Korea Taiwan, R.O.C. Atmel-WM Korea Ltd 25-4, Yoido-Dong Ste. 605, Singsong Bldg. Youngdeungpo-ku 150-010 Seoul Tel: 822 785 1136 Fax: 822 785 1137 Atmel Wireless & Microcontrollers Hong Kong Atmel-WM Hong Kong Atmel Asia Ltd Chinachem Golden Plaza 77 Mody Rd., Tsimshatsui East, Rm.1219 East Kowloon Tel: 852 23789 789 Fax: 852 23755 733 03.01 03-00 Keppel Building 25 Tampines Street 92 Singapore 528877 Tel: 65 260 8223 Fax: 65 787 9819 8F-2, 266, Sec. 1 Wen Hwa 2 Road, Lin Kou Hsiang 244 Taipei Hsien 244 Tel: 886 2 2609 5581 Fax: 886 2 2600 2735 471 Remarks 472 Remarks 473 Remarks 474 Remarks 475 Remarks 476 Remarks 477 Remarks 478 Remarks 479 Remarks 480