Writing FCode 2.x Programs 2550 Garcia Avenue Mountain View, CA 94043 U.S.A. Part No.: 802-1941-10 Revision A, November 1995 1993 Sun Microsystems, Inc. 2550 Garcia Avenue, Mountain View, California 94043-1100 U.S.A. All rights reserved. This product and related documentation are protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Portions of this product may be derived from the UNIX® and Berkeley 4.3 BSD systems, licensed from UNIX System Laboratories, Inc. and the University of California, respectively. Third-party font software in this product is protected by copyright and licensed from Sun’s Font Suppliers. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19. The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications. TRADEMARKS Sun, Sun Microsystems, Sun Microsystems Computer Corporation, the Sun logo, the SMCC logo, and OpenBoot are trademarks or registered trademarks of Sun Microsystems, Inc. UNIX and OPEN LOOK are registered trademarks of UNIX System Laboratories, Inc.. All other product names mentioned herein are the trademarks of their respective owners. All SPARC trademarks, including the SCD Compliant Logo, are trademarks or registered trademarks of SPARC International, Inc. SPARCstation, SPARCserver, SPARCengine, SPARCworks, and SPARCompiler are licensed exclusively to Sun Microsystems, Inc. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. The OPEN LOOK® and Sun™ Graphical User Interfaces were developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun’s written license agreements. X Window System is a trademark and product of the Massachusetts Institute of Technology. THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME. Please Recycle Contents Preface. xv Ordering Sun Documents . xviii 1. SBus Cards and FCode. 1 FCode PROM Format . 2 Interpreting FCode. 2 Device Identification . 2 Creating and Executing FCode Definitions . 3 2. Elements of FCode Programming . 5 Colon Definitions . 6 Stack Operations . 7 Additional Information. 8 Programming Style . 8 Commenting Code. 8 Short Definitions . 9 Stack Comments. 9 iii A Minimum FCode Program. 10 FCode Classes . 11 Primitive FCodes . 12 System FCodes . 12 Interface FCodes. 13 Local FCodes . 13 3. Producing FCode. 15 FCode Source . 15 Tokenizing FCode Source . 16 FCode Binary Format . 17 Testing FCode on the Target Machine . 17 Configuring the Target Machine . 18 Setting Appropriate Configuration Parameters. 18 Modifying The Expansion Bus Probe Sequence. 19 Getting to the Forth Monitor . 20 Using the Forth Monitor to Download FCode . 20 Using dload to Load from Ethernet. 21 Using dlbin to Load From Serial Port A. 21 Using boot to Load From Hard Disk, Floppy Disk, or Ethernet 22 Using the Forth Monitor to Interpret an FCode Program. 22 Interpretation Under OpenBoot 2 . 23 Interpretation Under OpenBoot 1 . 25 Using the Forth Monitor to Browse a Device Node. 26 iv Writing FCode 2.x Programs—November 1995 Device Node Browsing Under OpenBoot 2 . 27 Device Node Browsing Under OpenBoot 1 . 28 Using the Forth Monitor to Test a Device Node Driver . 29 Device Node Methods Under OpenBoot 2 . 29 Device Node Methods Under OpenBoot 1 . 32 Testing FCode in Source Form . 32 Producing an FCode PROM . 33 Exercising an Installed FCode PROM . 33 Exercising FCode Under OpenBoot 2 . 34 Exercising FCode Under OpenBoot 1 . 34 4. Packages . 37 Package Definitions, Package Instances, and Device Nodes . 38 Plug-in Device Drivers . 38 Package Methods . 39 Required Methods . 39 Recommended Methods . 40 Package Data Definitions . 41 Accessing Other Packages . 42 Debugging Packages . 49 Package Mappings. 49 nvramrc. 49 Modifying Package Properties . 49 Standard Support Packages . 50 Sun Disk-Label Support Package. 50 Contents v TFTP Booting Support Package . 51 Deblocker Support Package . 52 5. Properties . 55 Standard FCode Properties. 56 Standard FCode Properties For Cards (General) . 57 Device-type Specific Properties For SBus Cards . 57 General Properties For Parent Nodes . 57 Properties For SBus Parent Nodes. 57 Standard Properties . 58 Manipulating Properties . 72 Property Creation and Modification . 72 Property Values . 73 Property Encoding. 73 Property Retrieval . 73 Property Decoding. 74 Property-Specific FCodes . 75 6. Block and Byte Devices . 77 Block Devices . 77 Byte Devices . 78 Required Methods . 78 Required Properties . 80 Device Driver Examples . 81 Simple Block Device Driver . 81 Extended Block Device Driver . 82 vi Writing FCode 2.x Programs—November 1995 Complete Block and Byte Device Driver . 90 7. Display Devices. 101 Required Methods . 101 Required Properties . 102 Device Driver Examples . 102 Simple Display Device Driver . 102 Extended Display Device Driver . 103 Complete Display Device Driver . 108 8. Hierarchical Devices. 115 Required Methods . 115 SBus Addressing . ..