Preface

This manual, Writing FCode 3.x Programs (806-1379), describes how to write, debug, and test FCode programs for SPARC-based systems and PCI or SBus interface card devices. It replaces all previous manuals describing how to write FCode programs. IEEE Standard 1275-1994 is based on the Sun trademark OpenBoot 2.x implementation. OpenBoot 3.x from Sun is compliant with IEEE Standard 1275.

Throughout this book, the reference to FCode PROM might refer to any type of ROM device (ROM, PROM, FlashPROM, etc.).

Who Should Use This Book

This manual is written for designers of PCI and SBus interface cards and other devices that use the FCode programming language. It is written for those designers who have some familiarity with PCI or SBus card design requirements and Forth programming. The sample code in this book is provided as is without any warranty.

The material in this manual is for developers of FCode applications for PCI or SBus peripherals on OpenBoot 3.x. With proper programming precautions, these applications should run on OpenBoot 3.x and earlier versions. By following the IEEE 1275 standard, the same FCode application can also run on non-SPARC systems which are IEEE 1275-compliant. The FCode language is defined by IEEE Standard 1275-1994 Standard for Boot Firmware.

This manual is written for designers who have read and understood the corresponding SBus or PCI specifications and SBus or PCI binding to IEEE Standard 1275-1994 1.2.

How This Book Is Organized

Chapter 1 introduces the basic relationships between FCode device drivers and the hardware that they control.

Chapter 2 has basic information for developers writing FCode for use with PCI.

Chapter 3 introduces the basic elements of FCode, stack notation, and programming style.

Chapter 4 describes the process of producing FCode programs, from source files to testing working programs.

Chapter 5 is information to consider when you are designing FCode code for PCI.

Chapter 6 describes the basic units of FCode program function.

Chapter 7 describes properties, which define how an FCode device driver program recognizes the hardware that it controls.

Chapter 8 describes the required methods for nonvolatile and sequential-access mass storage devices.

Chapter 9 describes writing FCode programs for display devices.

Chapter 10 describes addressing and required properties for memory-mapped buses.

Chapter 11 describes how to implement network device drivers.

Chapter 12 describes programming requirements for serial devices, and gives examples of serial device drivers.

Chapter 13 shows a PCI FCode driver which is an example of a way of dealing with PCI-related registers in FCode.

Chapter 14 describes currently-defined FCode words and their functions and use, with brief programming examples.

Appendix A lists all currently-defined FCode words according to functional group, name, and byte value.

Appendix B describes guidelines for memory allocation and de-allocation in FCode.

Appendix C contains an OpenBoot coding guideline.

Appendix D discusses the FCodes and macros that have changed between FCode 2.x and FCode 3.x.

Typographic Conventions

Typeface or Symbol	Meaning	Examples
`AaBbCc123`	The names of commands, files, and directories; on-screen computer output	Edit your `.login` file. Use `ls -a` to list all files. `% You have mail`.
`AaBbCc123`	What you type, when contrasted with on-screen computer output	`%` `su` `Password:`
AaBbCc123	Book titles, new words or terms, words to be emphasized	Read Chapter 6 in the User's Guide. These are called class options. You must be superuser to do this.
	Command-line variable; replace with a real name or value	To delete a file, type `rm` filename.

Shell Prompts

Shell	Prompt
C shell	machine_name`%`
C shell superuser	machine_name`#`
Bourne shell and Korn shell	`$`
Bourne shell and Korn shell superuser	`#`

Application	Title
IEEE Standard	IEEE Standard 1275-1994 Standard for Boot (Initialization Configuration) Firmware, Core Requirements and Practices
IEEE Standard	IEEE Standard 1275.1-1994 Standard for Boot (Initialization Configuration) Firmware: Instruction Set Architecture (ISA) Supplement for IEEE 1754
IEEE Standard	IEEE Standard 1275.2-1994 Standard for Boot (Initialization Configuration) Firmware: Bus Supplement for IEEE 1496 (SBus)
IEEE Standard	IEEE 1496-1993 Standard for Chip and Module Interconnect Bus: SBus 1-55937-353-9
PCI Local Bus Specification	PCI Local Bus Specification, rev. 2.1, available from PCI Special Interest group: 800-433-5177/503-797-4207 and `http://www.pcisig.com`
OpenBoot	OpenBoot 2.x Command Reference (802-3241)
OpenBoot	OpenBoot 3.x Command Reference (802-5837)
IEEE Standard	PCI-Bus Binding to IEEE Standard 1275-1994, available at `http://playground.sun.com/1275`

Forth and Forth Programming

For further information about Forth and Forth programming:

Mastering Forth, Anita Anderson and Martin Tracy, Brady Communications Co., Inc., 1989

ANSI Forth X3J14

Forth: A Text and Reference, Mahlon G. Kelly and Nicholas Spies. Prentice-Hall, 1986

Starting Forth, Leo Brody. Forth, Inc., second edition, 1987

Forth: The New Model, Jack Woehr. M & T Books, 1992

Forth Interest Group http://forth.org/fig.html

Ordering Sun Documentation

Fatbrain.com, an Internet professional bookstore, stocks select product documentation from Sun Microsystems, Inc.

For a list of documents and how to order them, visit the Sun Documentation Center on Fatbrain.com at:

http://www1.fatbrain.com/documentation/sun

Accessing Sun Documentation Online

The docs.sun.com^SM web site enables you to access Sun technical documentation on the Web. You can browse the docs.sun.com archive or search for a specific book title or subject at:

http://docs.sun.com

Sun Welcomes Your Comments

We are interested in improving our documentation and welcome your comments and suggestions. You can email your comments to us at:

docfeedback@sun.com

Please include the part number (806-1379-10) of your document in the subject line of your email.