Firth manual

Firth is a minimal (~4K) implementation of Forth for the Z80.

Contents

• Motivation
• Firth
  • License
  • Binaries
  • Building
  • Emulation
  • Hardware requirements
  • File layout
• The Forth architecture
  • Why Forth?
  • Data stack
  • Execution model
  • Defining words
  • Compilation
  • Immediate words
• Control structures
  • Conditional logic
  • Looping structures
• Firth environment
  • Listing words
  • Debugging
• Forth in Z80 Assembly
  • Primitive words
  • Composite words
• The Z80 architecture
  • Registers
  • Stack pointer
  • Index registers
  • Alternative registers
  • Memory addressing
  • Flags
  • I/O ports
• Z80 Assembly language
  • Asm80
  • Directives
  • Variables
  • Macros
  • Structured assembler
• Appendices
  • Firth words
  • The Z80 instruction set
  • Utility functions
  • Further reading
  • Running unit tests

<!-- ## Motivation A long time ago, I designed a computer kit with my friend Ken Stone which we called the TEC-1. It was a single-board computer kit which we published in Talking Electronics, a Melbourne-based electronics hobbyist magazine. The configuration of the TEC-1 was a Z80 CPU with 2K of ROM and 2K of RAM. It also included a hexidecimal keyboard and a 6 digit 7-segment display. The kit was quite successful and was released at a critical time in Australian computer history. A few thousand TEC-1 kits were sold and, as we learned over the years from people who remember the kit, it introduced many people to computing and programming for the very first time. The kit continues on to this day with other people creating TEC-1 boards and new TEC-1s continue to be built by hobbyists. If they install version 1 of the monitor ROM that came with the original kit they're greeted with an old message from teen-age me: `hello there this is the tec-1 ... designed by john hardy for TE!` In its original form, the TEC-1 offered very little to the programmer. All code needs to be hand assembled and hand entered in via the hexadecimal keyboard. I always wanted to provide the TEC-1 one with a proper programming environment. Fast-forward to the modern era, I started to think about augmenting the TEC-1 circuit with a proper serial interface. I then went to consider (before rejecting) adding a BASIC interpreter to the TEC-1. Instead I decided to pursue another longtime interest of mine (which also dates from the early 80s) I decided that what the TEC-1 needed was a self-hosted programming environment based on Charles Moore's [Forth](https://en.wikipedia.org/wiki/Forth) programming language. This is where Firth comes from. "Firth" is named after the [Firth of Forth](https://en.wikipedia.org/wiki/Firth_of_Forth) an estuary on the river Forth in Scotland -- for no other reason than it's a cool-sounding name although it could be because this is also my "first Forth". -->

Firth

License

Firth is released until the GNU General Public License Version 3. See the LICENSE file in the root folder.

Back to contents

Binaries

TODO: Create a folder containing ROM images for various configurations.

Back to contents

Building

Firth can be built using the ASM80 assembler and can be built at the ASM80 site by the following steps:

1. Press the Import repo from GitHub button
2. Paste the following repo name https://github.com/jhlagado/firth and click OK
3. Select the main.z80 file
4. Download a .bin format binary by clicking on the "Download BIN" button. There are also buttons for downloading binaries in the .sna and .tap formats.

Back to contents

Emulation

Firth can be emulated online by the following steps:

1. Press the Import repo from GitHub button
2. Paste the following repo name https://github.com/jhlagado/firth and click OK
3. Select the main.z80 file
4. Press the Emulator [F10] button

This will cause ASM80 to start emulating the computer hardware specified in the mycomputer.emu file which is set up for a Z80 CPU which uses a Motorola 6850 ACIA serial chip mapped to ports $80 and $81.

The emulator will start up a green screen serial terminal emulation and present you with a prompt

Firth Z80

>

You can type Forth commands into it. e.g

> 1 2 3 * + .

7

You can exit the Forth interpreter by pressing the Back to IDE button on the top right corner.

Back to contents

Hardware requirements

Firth is designed to be run in ROM of a Z80 computer board like the TEC-1. It could also be easily adapted to run on similar systems such as Grant Searle's 7-chip Z80 computer and the RC2014 Z80 single-board computer.

To run Firth on a TEC-1 it some requires additional hardware to expand the memory and run the serial interface. TODO: details of this additional hardware. Firth is designed to run using a Motorola 6850 ACIA serial chip mapped to ports $80 and $81 (or 0x80 and 0x81) as per the hardware arrangement designed by Grant Searle. See the circuit diagram below and note how the 6850 ACIA chip is wired up.

Back to contents

File layout

Here is a listing of Firth's source files with a brief description.

compiler-macros.z80     macros used to enable Forth control and loop structures in ROM
constants.z80           most of the constants need by Firth
dloop-macros.z80        macros used to enable Assembly language looping structures
macros.z80              macros used to implement repetitive Assembly language elements
main.z80                the main file of Firth (start here)
mycomputer.emu          engine configuration file for the asm80 online emulator
primitives.z80          Forth words which are written in assembly language
struct-macros.z80       macros used to enable Assembly language control structures
test-macros.z80         macros used to enable unit tests
tests.z80               unit tests to test various aspects of the Forth engine
utilities.z80           Utility subroutines used by
variables.z80           Memory locations defined in RAM
words.z80               Forth words which written in Forth

You can start by examining main.z80 which is the root file which includes all the other files.

Back to contents

The Forth architecture

Why Forth?

Forth as a programming system has many characteristics which set it apart from other programming languages. It would be wrong to simply describe it as a language compiler like C or an interpreter as with traditional BASIC. It sits in the middle between compiler and interpreter and is its own unique thing with its own execution model.

Forth has been described as a "bottom-up" language because it builds up directly from a small number of assembly language primitives without imposing a significant number of abstractions. Forth can be bootstrapped to run from less than 2K of assembly language. Most of the Forth system is written in Forth itself.

Forth is self-hosting which means that it is possible to write and edit code within the Forth system itself as opposed to targeting it from another system. Forth's abstractions are easy to understand and they simplify the process of writing programs for a microprocessor. Unlike conventional compiler languages, Forth imposes very in the way of system overhead.

So why Forth? Because Forth can be written from a low base of assembly language, it becomes a relatively simple task to get Forth running on diverse range of CPUs. Forth is portable. It irons out the quirks and differences between instruction sets and presents the developer with a much smaller programming surface than traditional assembly language does. Forth unifies many low level programming tasks.

Forth is lightweight. Even a language designed for systems programming such as C is much more "high-level" than Forth and adds considerably more overhead in terms of program size, memory size and computational overhead. Forth programs are extremely compact and are often smaller than the same code written in assembly language.

There is a cost to this compactness however. Forth is usually slower than assembly but not greatly so. Forth is generally pretty fast and favourably comparable with compiled high-level languages. On some CPUs, Forth can be as efficient as machine code itself. This is not the case with 8-bit CPUs however but Forth does significantly improve the productivity of programmers who target the Z80.

Forth integrates well with assembly language and offers the developer the ability to drop back down to assembly for performance sensitive sections of code. Forth never takes the developer far "from the metal". It does however offer them structured flow control and a unified approach to parameter passing which are features that are normally associated with high-level languages. Forth brings structured programming to low-level programming.

Data stack

Forth is similar to other languages in that it uses a stack to send parameters to subroutines. Forth is unusual though in that it separates the manipulation of the stack from the subroutine calls themselves. It also uses the stack to return results back to the caller. Unlike C, Forth may return multiple results from a subroutine.

By interleaving stack manipulation with s