Forth 7 Cross Compiler with VFX code generation Microprocessor Engineering Limited Copyright c 1998-2010, 2011, 2012, 2013, 2015, 2016 Microprocessor Engineering Limited Published by Microprocessor Engineering MPE VFX Forth Cross Compiler User manual Manual revision 7.5 1 October 2016 Software Software version 7.5 For technical support Please contact your supplier For further information MicroProcessor Engineering Limited 133 Hill Lane Southampton SO15 5AF UK Tel: +44 (0)23 8063 1441 Fax: +44 (0)23 8033 9691 e-mail: [email protected] [email protected] web: www.mpeforth.com i Table of Contents 1 Licence terms :::::::::::::::::::::::::::::::::::::::::::::::::: 1 1.1 Distribution of application programs ::::::::::::::::::::::::::::::::::::::::::::::: 1 1.2 Evaluation and Lite compilers ::::::::::::::::::::::::::::::::::::::::::::::::::::: 1 1.3 Warranties and support:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 1 2 Installing the system :::::::::::::::::::::::::::::::::::::::::: 3 2.1 System requirements :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 3 2.2 Installation and configuration :::::::::::::::::::::::::::::::::::::::::::::::::::::: 3 2.2.1 Windows ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 3 2.2.2 Linux and Mac OS X ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 4 2.3 Release notes :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 8 3 System components ::::::::::::::::::::::::::::::::::::::::::: 9 3.1 MPE Forth cross-compiler :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 10 3.2 Standalone target Forth :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 10 3.3 Umbilical Forth :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 11 3.4 Documentation directory ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 11 3.5 Control files :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 11 3.6 Compiler versions :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 11 3.7 Learning Forth ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 12 4 How Forth is documented ::::::::::::::::::::::::::::::::::: 13 4.1 Forth words :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 13 4.2 Stack notation ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 14 4.3 Input text :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 15 4.4 Other markers:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 16 5 Configuring with macros::::::::::::::::::::::::::::::::::::: 17 5.1 Text macros:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 17 5.2 Directory structures :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 18 6 Generating a target Forth kernel ::::::::::::::::::::::::::: 19 6.1 Is your target already supported? ::::::::::::::::::::::::::::::::::::::::::::::::: 19 6.2 The control file ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 19 6.3 Memory map::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 19 6.3.1 Setting the memory map :::::::::::::::::::::::::::::::::::::::::::::::::::: 19 6.3.2 Start and end of Flash::::::::::::::::::::::::::::::::::::::::::::::::::::::: 20 6.3.3 Start and end of initialised RAM :::::::::::::::::::::::::::::::::::::::::::: 20 6.3.4 Start and end of uninitialised RAM :::::::::::::::::::::::::::::::::::::::::: 20 6.3.5 Setting the compilation areas :::::::::::::::::::::::::::::::::::::::::::::::: 21 6.4 Modifying the serial line drivers :::::::::::::::::::::::::::::::::::::::::::::::::: 21 6.4.1 Interrupt driven ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 21 6.4.2 Polled ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 22 6.4.3 Initialising the serial line::::::::::::::::::::::::::::::::::::::::::::::::::::: 22 6.4.4 Sending a character to the host :::::::::::::::::::::::::::::::::::::::::::::: 22 6.4.5 Receiving a character from the host :::::::::::::::::::::::::::::::::::::::::: 22 ii Forth 7 Cross Compiler 6.4.6 Generic I/O device table::::::::::::::::::::::::::::::::::::::::::::::::::::: 23 6.5 Setting up the system :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 23 6.5.1 Setting up the hardware ::::::::::::::::::::::::::::::::::::::::::::::::::::: 23 6.5.2 Setting up the software :::::::::::::::::::::::::::::::::::::::::::::::::::::: 24 6.6 Cross-compiling :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 24 6.6.1 Creating an image ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 24 6.6.2 Log display :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 24 6.6.3 Turning the log on and off ::::::::::::::::::::::::::::::::::::::::::::::::::: 25 6.6.4 Log to file or printer ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 25 6.6.5 Compilation summary ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 25 6.6.6 The created image ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 25 6.6.7 Problems, problems ... ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 26 6.7 Downloading the compiled image ::::::::::::::::::::::::::::::::::::::::::::::::: 26 6.7.1 Downloading to Flash ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 27 6.7.2 Downloading to an emulator or programmer ::::::::::::::::::::::::::::::::: 27 6.8 Running the target Forth ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 27 6.8.1 Switching to target mode :::::::::::::::::::::::::::::::::::::::::::::::::::: 27 6.8.2 Resetting the target board ::::::::::::::::::::::::::::::::::::::::::::::::::: 27 6.8.3 The sign-on ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 27 6.9 Cross-compiling an application ::::::::::::::::::::::::::::::::::::::::::::::::::: 29 6.9.1 Modifying the control file :::::::::::::::::::::::::::::::::::::::::::::::::::: 29 6.9.2 Running your application :::::::::::::::::::::::::::::::::::::::::::::::::::: 29 6.10 Generating a turnkey application :::::::::::::::::::::::::::::::::::::::::::::::: 29 6.10.1 Using MAKE-TURNKEY :::::::::::::::::::::::::::::::::::::::::::::::::: 30 6.10.2 Using ATCOLD :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 31 6.11 Umbilical Forth ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 32 6.11.1 Comms links ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 32 6.11.2 Serial line configuration :::::::::::::::::::::::::::::::::::::::::::::::::::: 34 6.11.3 Memory drivers :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 35 6.11.4 Downloading to Flash :::::::::::::::::::::::::::::::::::::::::::::::::::::: 36 6.11.5 Using In-Application-Programming (IAP)::::::::::::::::::::::::::::::::::: 36 6.11.6 Interactive debugging::::::::::::::::::::::::::::::::::::::::::::::::::::::: 37 6.11.7 Problems, problems :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 37 6.12 Serial port problems::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 38 6.12.1 Windows USB serial devices :::::::::::::::::::::::::::::::::::::::::::::::: 39 6.12.2 Windows terminal emulators:::::::::::::::::::::::::::::::::::::::::::::::: 39 6.12.3 Mac OS X USB serial devices::::::::::::::::::::::::::::::::::::::::::::::: 39 6.12.4 Linux USB serial devices ::::::::::::::::::::::::::::::::::::::::::::::::::: 40 7 Optimising the target Forth ::::::::::::::::::::::::::::::::: 41 7.1 Reducing the image size :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 41 7.2 Removing headers :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 41 7.2.1 Removing all headers :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 41 7.2.2 Selectively removing headers ::::::::::::::::::::::::::::::::::::::::::::::::: 41 7.3 Factoring your code :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 41 7.4 Removing excess code :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 42 7.5 Using equates instead of constants :::::::::::::::::::::::::::::::::::::::::::::::: 42 7.6 Removing forward references ::::::::::::::::::::::::::::::::::::::::::::::::::::: 43 7.7 Using Umbilical Forth :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 43 7.8 Speeding up your code ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 43 iii 8 Generic I/O::::::::::::::::::::::::::::::::::::::::::::::::::: 45 8.1 About Generic I/O ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 45 8.2 Creating a new device :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 45 8.3 Selecting a device :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 46 9 Multitasker ::::::::::::::::::::::::::::::::::::::::::::::::::: 47 9.1 Initialising the multitasker:::::::::::::::::::::::::::::::::::::::::::::::::::::::: 47 9.1.1 Selecting the multi-tasker :::::::::::::::::::::::::::::::::::::::::::::::::::: 47 9.1.2 Starting the multitasker ::::::::::::::::::::::::::::::::::::::::::::::::::::: 47 9.1.3 Stopping the multitasker::::::::::::::::::::::::::::::::::::::::::::::::::::: 47 9.2 Writing a task:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 48 9.2.1 Using the scheduler :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 48 9.2.2 An example task :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 48 9.2.3 Task dependent variables :::::::::::::::::::::::::::::::::::::::::::::::::::: 48 9.2.4 Controlling tasks ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::