Preface

This manual, Writing FCode Programs, replaces both Writing FCode Programs for SBus Cards and Writing FCode 2.0 Programs.

Who Should Use This Book

This manual is written for designers of SBus interface cards and other devices that use the FCode interface language. It assumes that you have some familiarity with SBus card design requirements and Forth programming.

The material covered in this manual is specifically for those developing FCode applications on OpenBoot 2.0 or later SPARCsystems, and those developing SBus cards for either OpenBoot 2.0 only or both OpenBoot 1.0 and OpenBoot 2.0 and later systems.

This manual also assumes that you have read and understood SBus Specification B.0 (or later) and OpenBoot Command Reference.

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, "Elements of FCode Programming", introduces the basic elements of FCode, stack notation, and programming style.
• Chapter 3, "Producing FCode", describes the process of producing FCode programs, from source file to testing working programs.
• Chapter 4, "Packages", describes the basic units of FCode program function.

• Chapter 5, "Properties", describes properties, which define how an FCode device driver program "sees" the hardware that it controls.
• Chapter 6, "Block and Byte Devices" through Chapter 10, "Serial Devices" describe currently-defined device types, programming requirements, and give some examples of device drivers for the various device types.
• Chapter 11, "FCode Dictionary", describes currently-defined FCode words, their functions and use, with brief programming examples.
• Appendix A, "FCode Reference", lists all currently-defined Fcode words according to functional grouping, name, and byte value.
• Appendix B, "OpenBoot Interrupt Testing", describes how to go about dealing with interrupts when testing SBus devices, including programming examples.
• Appendix C, "FCode Memory Allocation", describes guidelines for memory allocation and deallocation in FCode.
• Appendix D, "Changes in OpenBoot 1 FCode Usage", describes differences in programming style between OpenBoot 1 and OpenBoot 2 practice, and changes in usage of FCode words that have changed between OpenBoot 1 and OpenBoot 2.

Related Books

This manual does not pretend to cover everything you need to know to write FCode drivers for SBus cards. You'll have to read some other books, too.

For information about SBus, OpenBoot 2.0, SBus device drivers, and writing device drivers for Sun workstations, see the following Sun manuals:

• OpenBoot Command Reference, 801-7042-10
• OpenBoot Quick Reference, 800-5675-11
• Writing SBus Device Drivers, 800-4455-10

For more information about Forth and Forth programming and SBus, see:

• Mastering Forth, Anita Anderson and Martin Tracy. Brady Communication Company, Inc., 1989.
• Forth: A Text and Reference, Mahlon G. Kelly and Nicholas Spies. Prentice Hall.
• Starting FORTH, Leo Brody. FORTH, Inc., second edition, 1987.
• Forth: a New Model, Jack Woehr. M & T Books, 1992.
• OpenBoot Command Reference, 801-7042-10
• IEEE Standard for a Chip and Module Interconnect Bus: Sbus, IEEE Std 1496- 1993

Software Tools

Some programs specifically mentioned in this manual for use in developing FCode programs are included on a diskette in the SBus Developer's Kit. Instructions for using these programs are included on the diskette.

If you don't have access to a complete SBus Developer's Kit, or if your SPARCstation doesn't have a diskette drive, contact the Sun SBus Technical Support Group (sbustech@Sun.com) for the software.

What Typographic Changes and Symbols Mean

The following table describes the typeface changes and symbols used in this book.

Table P-1

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	Command-line placeholder: 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.
Code samples are included in boxes and may display the following:
%	UNIX C shell prompt	system%
ok	OpenBoot command prompt	ok
$	UNIX Bourne and Korn shell prompt	system$
#	Superuser prompt, all UNIX shells	system#

This manual follows a number of typographic conventions:

• Text beginning with a capitalized letter indicates a key name or a panel button on a window-based program. For example:

  Press the Control-C key.

  When you see two key names separated by a dash, press and hold the first key down, then press the second key. For example:

  To press Control-C, press and hold Control, then press C.

• In a command line, square brackets indicate an optional entry and italics indicate an argument that you must replace with the appropriate text. For example:

  cd [directory]