Preface

This manual, Writing FCode 3.x Programs (802-6287), 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^(TM) OpenBoot^(TM) 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, "SBus Cards and FCode", introduces the basic relationships between FCode device drivers and the hardware that they control.
Chapter 2, "PCI FCode Information", basic information for developers writing FCode for use with PCI.
Chapter 3, "Elements of FCode Programming", introduces the basic elements of FCode, stack notation, and programming style.
Chapter 4, "Debugging and Testing FCode Programs", describes the process of producing FCode programs, from source files to testing working programs.
Chapter 5, "Helpful Testing and Debugging Hints", is information to consider when you are designing FCode code for PCI.
Chapter 6, "Packages", describes the basic units of FCode program function.
Chapter 7, "Properties", describes properties, which define how an FCode device driver program recognizes the hardware that it controls.
Chapter 8, "Block and Byte Devices", describes the required methods for nonvolatile and sequential-access mass storage devices.
Chapter 9, "Display Devices", describes writing FCode programs for display devices.
Chapter 10, "Memory-Mapped Buses", describes addressing and required properties for memory-mapped buses.
Chapter 11, "Network Devices", describes how to implement network device drivers.
Chapter 12, "Serial Devices", describes programming requirements for serial devices, and gives examples of serial device drivers.
Chapter 13, "PCI FCode Driver Example", shows a PCI FCode driver which is an example of a way of dealing with PCI-related registers in FCode.
Chapter 14, "FCode Dictionary", describes currently-defined FCode words and their functions and use, with brief programming examples.

Appendix A, "FCode Reference", lists all currently-defined FCode words according to functional group, name, and byte value.
Appendix B, "FCode Memory Allocation", describes guidelines for memory allocation and de-allocation in FCode.
Appendix C, "Coding Style", contains an OpenBoot coding guideline.
Appendix D, "Differences Between FCode 2.x and 3.x", discusses the FCodes and macros that have changed between FCode 2.x and FCode 3.x.

Related Books

This manual does not cover all you need to know in order to write FCode drivers. The following sources are also useful.

For further information:

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

    http://playground.sun.com/1275

The on-line version of this manual and FCode tools are available at

http://www.sun.com/developers/driver

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

What Typographic Changes Mean

Typeface or Symbol	Meaning	Example
`AaBbCc123`	The names of commands, files, and directories; on-screen computer output	Edit your `.login` file. Use `ls -a` to list all files. `system% You have mail.`
`AaBbCc123`	What you type, contrasted with on-screen computer output	`system%` `su` `Password:`
*AaBbCc123*	Variable: replace with a real name or value	To delete a file, type `rm` *filename*`.`
*AaBbCc123*	Book titles, new words or terms, or words to be emphasized	Read Chapter 6 in *User's Guide`.` These are called class* options. You *must* be root to do this.
[optional]	Optional command-line entry	lpr [-Pprinter]
Code samples ar	e included in boxes and may display the following:	lpr [-Pprinter]
`ok`	The OpenBoot Forth Monitor prompt	`ok`
`%`	UNIX C shell prompt	`system%`
`$`	UNIX Bourne and Korn shell prompt	`system$`
`#`	Superuser prompt, all shells	`system#`

Ordering Sun Documents

The SunDocs Order Desk is a distribution center for Sun Microsystems technical documentation. You can use major credit cards and company purchase orders. You can order documentation in the following ways:

In the U.S.A.	Outside the U.S.A.
Call 1-800-247-0250	Call 1-801-342-3450
Fax 1-801-373-6798	Fax 1-801-373-6798
World Wide Web: `http://www.sun.com/sundocs/catalog.html`

Sun Welcomes Your Comments

We are interested in improving our documentation and welcome your comments and suggestions. You can email or fax your comments to us. Please include the part number of your document in the subject line of your email or fax message.

Email: smcc-docs@sun.com
Fax: SMCC Document Feedback 1-415-786-6443