Open Firmware Command Reference To assist users of Open Firmware compliant systems, FirmWorks has created "Open Firmware Command Reference". This manual, available exclusively from FirmWorks, is an adaptation of previously-existing OpenBoot(tm) documentation that has been adapted to Open Firmware and significantly expanded with information on the use of Open Firmware and non-Sun machines, additional debugging tips, and information on the use of the Forth assembler. The book clearly explains the Open Firmware environment and will help you achieve "power user" status quickly. A complete table of contents for the manual is provided at the end of this file. In it, you will find chapters on booting, system configuration, debugging and more. If you are making the move to Open Firmware, this book will help you make a smooth transition. To order your copy, send this order form to: info@firmworks.com Ordering Information -------------------- We accept orders by mail, email, phone or fax. Payment can be made by check or credit card (Visa/MasterCard/Diners Club/Carte Blanche/JCB; we do *not* accept American Express). If paying by credit card, be sure to include the card's expiration date and the billing address of the card if it is different from the shipping address. Please also include your phone number and email address, in case we have a question about your order. Normally, shipment to US addresses is by Priority Mail and to all other destinations is by airmail. On request, we will also ship by overnight carrier for $5 handling plus our cost [specify carrier and rate (e.g. overnight/second day/economy) and include your phone number]. Order Form --------- Name: _______________________________________________________________ Company: _______________________________________________________________ Address 1: _______________________________________________________________ Address 2: _______________________________________________________________ City: _____________________________________ State: ____ Zip: ________ Country: _______________________________________________________________ Phone: __________________ (In case we have questions about your order) Email: _______________________________________________________________ _____ Copies @ $50.00 $ __________ Shipping and handling $ __________ (15% of book total for U.S. and Canada; 45% elsewhere; overnight for $5 plus actual cost) Subtotal $ __________ Sales tax (8.25% for California residents) $ __________ Total (in U.S. dollars) $ __________ Shipping method --------------- __ Standard __ Expedited (Specify carrier/rate __________________________) Payment method -------------- __ Visa __ MasterCard __ Diners Club __ Carte Blanche __ JCB __ Check (Sorry. We do not accept American Express.) Card Number: _________________________________________ Expires: __________ Signature: _______________________________________________________________ Terms ----- 1. Prices, offerings and terms subject to change without notice. 2. Prices F.O.B. FirmWorks office. Risk of loss passes to customer at time of delivery to carrier. ________________ OpenBoot is a trademark of Sun Microsystems. The following are extracts from "Open Firmware Command Reference" ---------------------------------------------------------------------- Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix Chapter 1: Overview . . . . . . . . . . . . . . . . . . . . . . . . 1 Features of Open Firmware . . . . . . . . . . . . . . . 1 The User Interface . . . . . . . . . . . . . . . . . . . 2 Security Modes . . . . . . . . . . . . . . . . . . . 3 The Device Tree . . . . . . . . . . . . . . . . . . . . 3 Device Path Names, Addresses, and Arguments . . . . . 4 Device Aliases . . . . . . . . . . . . . . . . . . . 6 Displaying the Device Tree . . . . . . . . . . . . . 7 FirmWorks Extensions for Displaying Device Information 10 Getting Help . . . . . . . . . . . . . . . . . . . . . . 11 A Caution About Using Some Open Firmware Commands . . . 12 Chapter 2: Booting and Testing Your System . . . . . . . . . . . . 13 Booting Your System . . . . . . . . . . . . . . . . . . 13 Booting for the Casual User . . . . . . . . . . . . . 15 Booting for the Expert User . . . . . . . . . . . . . 15 Using Partition Numbers in File Specifications . . 18 Explicit Booting from a Network Using RARP and BOOTP19 Running Diagnostics . . . . . . . . . . . . . . . . . . 21 Testing the SCSI Bus . . . . . . . . . . . . . . . . 22 Testing Installed Devices . . . . . . . . . . . . . . 22 Testing the Diskette Drive . . . . . . . . . . . . . 23 Testing Memory . . . . . . . . . . . . . . . . . . . 23 Testing the Network Controller . . . . . . . . . . . 24 FirmWorks/Sun Testing Extensions . . . . . . . . . . 24 Monitoring the Network . . . . . . . . . . . . . . 24 Testing the Mouse . . . . . . . . . . . . . . . . 25 Testing the Parallel Port . . . . . . . . . . . . 25 Testing the Clock . . . . . . . . . . . . . . . . 25 Testing the Sound Circuit . . . . . . . . . . . . 25 Testing the Infrared Port. . . . . . . . . . . . . 26 Testing the Game Port . . . . . . . . . . . . . . 27 Testing with watch-all . . . . . . . . . . . . . . 27 Obtaining System Information . . . . . . . . . . . . . . 27 Resetting the System . . . . . . . . . . . . . . . . . . 28 Chapter 3: Working with Configuration Variables . . . . . . . . . . 29 Displaying and Changing Configuration Variable Settings 32 Displaying Configuration Variables . . . . . . . . . 33 Changing Configuration Variables . . . . . . . . . . 33 Creating Configuration Variables . . . . . . . . . . 34 Editing and Creating Configuration Variables with editenv . . . . . . . . . . . . . . . . . . . . . 35 Changes to Many Variables Are Not Immediately Effective35 Setting Configuration Variables to Default Values . . 35 Accessing Configuration Variables in Programs . . . . . 36 Setting Security Variables . . . . . . . . . . . . . . . 36 Command Security . . . . . . . . . . . . . . . . . . 36 Full Security . . . . . . . . . . . . . . . . . . . . 37 Changing the Power-on Banner . . . . . . . . . . . . . . 38 Input and Output Control . . . . . . . . . . . . . . . . 39 Selecting Input and Output Device Options . . . . . . 40 FirmWorks Extensions for Selecting Input and Output Device Options . . . . . . . . . . . . . . . . 40 Setting Serial Port Characteristics . . . . . . . . . 41 Selecting Boot Options . . . . . . . . . . . . . . . . . 41 Controlling Power-on Self-test . . . . . . . . . . . . . 41 Preserving Configuration Variables Across System Resets 42 Using "the Script", nvramrc. . . . . . . . . . . . . . . 43 The Script Editor, nvedit . . . . . . . . . . . . . . 44 Editing and Activating the Script . . . . . . . . . . 45 Automating Script Updating . . . . . . . . . . . . . 47 Chapter 4: Working with File Systems . . . . . . . . . . . . . . . 49 Working with Drives . . . . . . . . . . . . . . . . . . 49 Working with the Macintosh . . . . . . . . . . . . . . . 50 Working with Directories . . . . . . . . . . . . . . . . 50 Changing and Identifying Directories with chdir and pcwd . . . . . . . . . . . . . . . . . . . . . . . 51 Listing Directories with dir . . . . . . . . . . . . 51 Creating and Deleting Directories with mkdir and rmdir . . . . . . . . . . . . . . . . . . . . . . 53 Working with Files . . . . . . . . . . . . . . . . . . . 54 Copying Individual Files . . . . . . . . . . . . . . 54 Copying File(s) to Another Directory. . . . . . . . . 55 Deleting Files . . . . . . . . . . . . . . . . . . . 56 Renaming Files . . . . . . . . . . . . . . . . . . . 56 Deleting Read-only Files . . . . . . . . . . . . . . 56 Chapter 5: Using Forth Tools . . . . . . . . . . . . . . . . . . . 57 Forth Commands . . . . . . . . . . . . . . . . . . . . . 57 Data Types . . . . . . . . . . . . . . . . . . . . . . . 58 Using Numbers . . . . . . . . . . . . . . . . . . . . . 59 The Stack . . . . . . . . . . . . . . . . . . . . . . . 59 Displaying Stack Contents . . . . . . . . . . . . . . 60 The Stack Diagram . . . . . . . . . . . . . . . . . . 61 Manipulating the Stack. . . . . . . . . . . . . . . . 63 Creating Custom Definitions . . . . . . . . . . . . . . 64 Using Arithmetic Functions . . . . . . . . . . . . . . . 65 Single-Precision Integer Arithmetic . . . . . . . . . 65 Bit-wise Logical Operators . . . . . . . . . . . . . 66 Double Number Arithmetic . . . . . . . . . . . . . . 66 Data Type Conversion . . . . . . . . . . . . . . . . 67 Address Arithmetic . . . . . . . . . . . . . . . . . 68 Accessing Memory . . . . . . . . . . . . . . . . . . . . 68 Virtual Memory . . . . . . . . . . . . . . . . . . . 68 Device Registers . . . . . . . . . . . . . . . . . . 72 Using Defining Words . . . . . . . . . . . . . . . . . . 72 Searching the Dictionary . . . . . . . . . . . . . . . . 76 Dictionary Searching Extensions . . . . . . . . . . . 77 FirmWorks/Sun Dictionary Searching Extension . . . . 79 Compiling Data into the Dictionary . . . . . . . . . . . 80 Displaying Numbers . . . . . . . . . . . . . . . . . . . 81 Working with the Number Base . . . . . . . . . . . . . . 82 Controlling Text Input and Output . . . . . . . . . . . 82 Converting Numbers to Text and Text to Numbers . . . . . 87 Redirecting Input and Output . . . . . . . . . . . . . . 89 FirmWorks/Sun I/O Redirection Extensions . . . . . . 91 Command Line Editor. . . . . . . . . . . . . . . . . . . 91 Conditional Flags . . . . . . . . . . . . . . . . . . . 93 Control Commands . . . . . . . . . . . . . . . . . . . . 94 The if...else...then Structure . . . . . . . . . . . 94 The case Statement . . . . . . . . . . . . . . . . . 95 The begin Loop . . . . . . . . . . . . . . . . . . . 96 The do Loop . . . . . . . . . . . . . . . . . . . . . 98 Additional Control Commands . . . . . . . . . . . . . 100 Error Recovery with catch and throw . . . . . . . . . 102 Time Utilities . . . . . . . . . . . . . . . . . . . 104 Miscellaneous Operations . . . . . . . . . . . . . . 105 FirmWorks/Sun Extensions . . . . . . . . . . . . . . . . 105 FirmWorks File System Extensions . . . . . . . . . . . . 105 Chapter 6: Loading and Executing Programs . . . . . . . . . . . . . 107 Using boot . . . . . . . . . . . . . . . . . . . . . . . 108 Using dl to Load Forth Text Files Over a Serial Port . . 109 Using Windows(tm) Terminal . . . . . . . . . . . . . 109 Using PROCOMM PLUS(r) . . . . . . . . . . . . . . . . 109 Using tip . . . . . . . . . . . . . . . . . . . . . . 110 Using a Macintosh Communications Program . . . . . . 111 MacTerminal . . . . . . . . . . . . . . . . . . . 111 Other Macintosh Communications Programs. . . . . . 111 Using load . . . . . . . . . . . . . . . . . . . . . . . 112 FirmWorks/Sun Extensions for Downloading Binary and FCode Files . . . . . . . . . . . . . . . . . . . . . 113 Using dlbin to Load Binary Executables Over a Serial Port . . . . . . . . . . . . . . . . . . . . . . . 113 Using Windows(tm) Terminal . . . . . . . . . . . . 114 Using PROCOMM PLUS(r) . . . . . . . . . . . . . . 114 Using tip . . . . . . . . . . . . . . . . . . . . 115 Using dlfcode to Load FCode Over a Serial Port . . . 116 Using Windows(tm) Terminal . . . . . . . . . . . . 116 Using PROCOMM PLUS(r) . . . . . . . . . . . . . . 117 Using tip . . . . . . . . . . . . . . . . . . . . 117 Using fload to Load Forth Source Text Files . . . . . 118 Chapter 7: Debugging . . . . . . . . . . . . . . . . . . . . . . . 121 Using the Forth Language Decompiler . . . . . . . . . . 121 Using the Disassembler . . . . . . . . . . . . . . . . . 122 Displaying Registers . . . . . . . . . . . . . . . . . . 123 ARM Registers . . . . . . . . . . . . . . . . . . . . 123 PowerPC Registers . . . . . . . . . . . . . . . . . . 124 SPARC Registers . . . . . . . . . . . . . . . . . . . 124 x86 Registers . . . . . . . . . . . . . . . . . . . . 125 The Symbolic Debugger . . . . . . . . . . . . . . . . . 126 Breakpoints. . . . . . . . . . . . . . . . . . . . . . . 127 Modifying Breakpoint Behavior with .breakpoint . . . 128 The Forth Source-level Debugger . . . . . . . . . . . . 128 Debugger Tips . . . . . . . . . . . . . . . . . . . . 133 Using the FirmWorks/Sun Extensions debug( and )debug . . . . . . . . . . . . . . . . . . . . 133 Debugging Words that Read from the Input Stream. . 133 Debugging Words Invoked by $call-method . . . . . 134 FCode Debugging . . . . . . . . . . . . . . . . . 136 Forth Kernel Debugging . . . . . . . . . . . . . . 136 Using patch and (patch) . . . . . . . . . . . . . . . . 136 Using the FirmWorks/Sun Extension ftrace . . . . . . . . 139 Miscellaneous Debugging Tips . . . . . . . . . . . . . . 139 General . . . . . . . . . . . . . . . . . . . . . . . 139 Problems with more and tip . . . . . . . . . . . . 139 FCode Debugging . . . . . . . . . . . . . . . . . . . 140 Using fcode-debug? . . . . . . . . . . . . . . . . 140 Causing the Tokenizer to Display Messages . . . . 140 Problems with map-in . . . . . . . . . . . . . . . 140 FirmWorks/Sun Debugging Extensions . . . . . . . . . . . 140 General . . . . . . . . . . . . . . . . . . . . . . . 140 Disabling the more Feature . . . . . . . . . . . . 140 Debugging Interrupt 15 . . . . . . . . . . . . . . 141 Spawning a Sub-ordinate Forth Interpreter . . . . 141 FCode Debugging . . . . . . . . . . . . . . . . . . . 141 Debugging Words Defined with FCode . . . . . . . . 141 Failure to Find a Method . . . . . . . . . . . . . 142 Error Messages . . . . . . . . . . . . . . . . . . . 143 Unimplemented Package Method . . . . . . . . . . . 143 Not Enough Parameters . . . . . . . . . . . . . . 143 Obtaining More Verbose Error Messages . . . . . . 144 Snooping property Creation . . . . . . . . . . . . 144 Snooping device_type Creation . . . . . . . . . . 144 Client Interface Debugging . . . . . . . . . . . . . 144 First-level Debugging of Client Program Problems: 144 Expansion of Client Interface Diagnostic Messages 145 Refining verbose-cif Diagnostic Messages . . . . . 146 Debugging Problems Occurring at Boot . . . . . . . 147 Use of Non-existant Client Interface Service . . . 148 Appendix A: Testing with a Communications Program. . . . . . . . . . 149 Preparing the Hardware . . . . . . . . . . . . . . . . . 149 MS-DOS(r) , Windows(tm) and Unix Systems . . . . . . 149 Macintosh Systems . . . . . . . . . . . . . . . . . . 150 Using Windows(tm) Terminal . . . . . . . . . . . . . . . 150 Program Configuration . . . . . . . . . . . . . . . . 151 Controlling Your System . . . . . . . . . . . . . . . 151 Using PROCOMM PLUS(r) . . . . . . . . . . . . . . . . . 152 Program Configuration . . . . . . . . . . . . . . . . 152 Controlling Your System . . . . . . . . . . . . . . . 153 Common Problems with PROCOMM . . . . . . . . . . . . 154 Using tip. . . . . . . . . . . . . . . . . . . . . . . . 154 Common Problems with tip . . . . . . . . . . . . . . 155 Using a Macintosh Communications Program . . . . . . . . 156 Program Configuration . . . . . . . . . . . . . . . . 156 MacTerminal . . . . . . . . . . . . . . . . . . . 156 Other Macintosh Communications Programs. . . . . . 157 Controlling Your System . . . . . . . . . . . . . . . 157 Appendix B: Troubleshooting Guide . . . . . . . . . . . . . . . . . 159 Power-on Initialization Sequence . . . . . . . . . . . . 159 Emergency "Keyboard Chords" . . . . . . . . . . . . . . 161 Preserving Data After a System Crash . . . . . . . . . . 162 Common Failures . . . . . . . . . . . . . . . . . . . . 162 Blank Screen - No Output . . . . . . . . . . . . . . 162 System Hangs During Startup Prior to Initiating the Boot Sequence . . . . . . . . . . . . . . . . . . 163 System Boots From the Wrong Device . . . . . . . . . 164 System Will Not Boot From Ethernet . . . . . . . . . 165 System Will Not Boot From Disk . . . . . . . . . . . 165 SCSI Problems . . . . . . . . . . . . . . . . . . . . 166 Setting the Console to a Specific Monitor . . . . . . 166 Appendix C: Forth Word Reference . . . . . . . . . . . . . . . . . . 167 Appendix D: ARM-Specific Reference . . . . . . . . . . . . . . . . . 197 ARM Register Commands . . . . . . . . . . . . . . . . . 197 ARM Assembler . . . . . . . . . . . . . . . . . . . . . 198 Introduction . . . . . . . . . . . . . . . . . . . . 198 Register Names . . . . . . . . . . . . . . . . . . . 199 Register Usage in the Forth Virtual Machine . . . . . 199 Constants . . . . . . . . . . . . . . . . . . . . . . 200 Literal Number Formats . . . . . . . . . . . . . . . 200 Supported Opcodes . . . . . . . . . . . . . . . . . . 200 Field Mask Names . . . . . . . . . . . . . . . . . . 201 Shifting Specifiers . . . . . . . . . . . . . . . . . 201 "Structured Assembler" . . . . . . . . . . . . . . . 201 Disassembler . . . . . . . . . . . . . . . . . . . . 203 Macros . . . . . . . . . . . . . . . . . . . . . . . 203 Starting Assembly . . . . . . . . . . . . . . . . . . 204 Code Examples . . . . . . . . . . . . . . . . . . . . 206 Appendix E: PowerPC-Specific Reference . . . . . . . . . . . . . . . 207 PowerPC-Specific Configuration Variables . . . . . . . . 207 PowerPC Register Commands . . . . . . . . . . . . . . . 208 PowerPC Assembler . . . . . . . . . . . . . . . . . . . 208 Introduction . . . . . . . . . . . . . . . . . . . . 209 Register Names . . . . . . . . . . . . . . . . . . . 209 Register Usage in the Forth Virtual Machine . . . . . 210 Constants . . . . . . . . . . . . . . . . . . . . . . 210 Supported Opcodes: . . . . . . . . . . . . . . . . . 210 Assembler Structured Conditionals . . . . . . . . . . 211 Condition Names . . . . . . . . . . . . . . . . . 211 Conditionals . . . . . . . . . . . . . . . . . . . 212 Disassembler . . . . . . . . . . . . . . . . . . . . 213 Macros . . . . . . . . . . . . . . . . . . . . . . . 213 Starting Assembly . . . . . . . . . . . . . . . . . . 214 Code Examples . . . . . . . . . . . . . . . . . . . . 216 Appendix F: Sun-Specific Reference . . . . . . . . . . . . . . . . . 217 SPARC-Specific Configuration Variables . . . . . . . . . 217 SPARC-Specific Commands . . . . . . . . . . . . . . . . 218 SPARC Register Commands . . . . . . . . . . . . . . . . 222 SPARC Assembler . . . . . . . . . . . . . . . . . . . . 222 Register Names . . . . . . . . . . . . . . . . . . . 223 Register Usage in the Forth Virtual Machine . . . . . 223 Addressing Modes . . . . . . . . . . . . . . . . . . 223 Register Windows . . . . . . . . . . . . . . . . . . 224 Operation Names . . . . . . . . . . . . . . . . . . . 224 Overall Syntax . . . . . . . . . . . . . . . . . . . 224 Delayed Branches . . . . . . . . . . . . . . . . . . 225 Conditionals . . . . . . . . . . . . . . . . . . . . 225 Structured Conditionals . . . . . . . . . . . . . . . 226 Starting Assembly . . . . . . . . . . . . . . . . . . 226 Forth Virtual Machine Considerations . . . . . . . . 227 Macros . . . . . . . . . . . . . . . . . . . . . . . 228 List of Opcodes . . . . . . . . . . . . . . . . . . . 228 Conditional Branches . . . . . . . . . . . . . . . . 230 Condition Names . . . . . . . . . . . . . . . . . . . 230 System Macros . . . . . . . . . . . . . . . . . . . . 230 Example: a Simple code Word . . . . . . . . . . . . . 230 Register Usage in Forth . . . . . . . . . . . . . . . 231 Disassembler . . . . . . . . . . . . . . . . . . . . 232 Setting the Starting Address . . . . . . . . . . . . 233 Conditional Branches . . . . . . . . . . . . . . . . 234 Traditional Assembler . . . . . . . . . . . . . . 234 Forthmacs Assembler with Structured Conditionals 234 Delayed Branches . . . . . . . . . . . . . . . . . . 235 Loops . . . . . . . . . . . . . . . . . . . . . . . . 236 Scope Loops: Assembler versus Forth . . . . . . . . . 237 Stack Usage . . . . . . . . . . . . . . . . . . . . . 238 Appendix G: 80x86-Specific Reference . . . . . . . . . . . . . . . . 241 x86-Specific Configuration Variables . . . . . . . . . . 241 x86 Register Commands . . . . . . . . . . . . . . . . . 242 x86 Assembler . . . . . . . . . . . . . . . . . . . . . 242 Introduction . . . . . . . . . . . . . . . . . . . . 243 Register Names . . . . . . . . . . . . . . . . . . . 243 Register Usage in the Forth Virtual Machine . . . . . 243 Addressing Mode Syntax, by Example . . . . . . . . . 244 Shift Instructions . . . . . . . . . . . . . . . . . 245 Override Prefixes . . . . . . . . . . . . . . . . . . 245 Supported Opcodes . . . . . . . . . . . . . . . . . . 245 Assembler Structured Conditionals . . . . . . . . . . 245 Condition Names . . . . . . . . . . . . . . . . . 245 Conditionals . . . . . . . . . . . . . . . . . . . 245 Disassembler . . . . . . . . . . . . . . . . . . . . 246 Segment Registers . . . . . . . . . . . . . . . . . . 246 NEXT . . . . . . . . . . . . . . . . . . . . . . . . 246 Macros . . . . . . . . . . . . . . . . . . . . . . . 247 Branches . . . . . . . . . . . . . . . . . . . . . . 247 Starting Assembly . . . . . . . . . . . . . . . . . . 247 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 ---------------------------------------------------------------------- PREFACE Open Firmware Command Reference describes how to use systems that implement firmware that behaves as described by IEEE Standard 1275-1994. This manual is derived from the Sun Microsystems manual, OpenBoot(tm) Command Reference. Who Should Use This Book This manual is written for all users, from systems designers to systems administrators to end users, who wish to use Open Firmware to configure and debug their systems. Contents This manual contains information on using Open Firmware to perform tasks such as: * Booting the operating system * Running diagnostics * Modifying system start-up configuration parameters * Loading and executing programs * Troubleshooting If you want to write Forth programs or if you want to use the more advanced features of this firmware (such as its debugging capabilities), this manual also describes the commands of the Open Firmware Forth Interpreter. Assumptions This manual assumes that you are working on a system that uses FirmWorks's Version 3.0 Open Firmware. Other Open Firmware implementations may use different prompts and/or formatting, and may not support all of the tools and capabilities described in this manual. How This Book Is Organized * Chapter 1, "Overview" describes the user interface and other main features of Open Firmware. * Chapter 2, "Booting and Testing Your System" explains the most common tasks for which Open Firmware is used. * Chapter 3, "Working with Configuration Variables" details how to perform system administration tasks with NVRAM variables. * Chapter 4, "Working with File Systems" describes FirmWorks extensions for working with file systems from within Open Firmware. * Chapter 5, "Using Forth Tools" describes both basic and advanced functions of the Open Firmware Forth language. * Chapter 6, "Loading and Executing Programs" describes how to load and execute programs from various sources (such as Ethernet, disk, or a serial port). * Chapter 7, "Debugging" describes Open Firmware's debugging capabilities, including the decompiler, the Forth source-level debugger, and breakpoints. * Appendix A, "Testing with a Communications Program" describes how to connect your system to another system using serial ports. * Appendix B, "Troubleshooting Guide" discusses solutions for typical situations where you cannot boot the operating system. * Appendix C, "Forth Word Reference" contains all currently-supported Open Firmware Forth commands. * Appendix D, "ARM-Specific Reference" contains ARM-specific Open Firmware extensions. * Appendix E, "PowerPC-Specific Reference" contains PowerPC-specific Open Firmware extensions. * Appendix F, "Sun-Specific Reference" contains Sun-specific Open Firmware extensions. * Appendix G, "80x86-Specific Reference" contains 80x86-specific Open Firmware extensions. Related Books For information on Open Firmware FCode, refer to: * Writing FCode Programs for PCI, FirmWorks, part number 000-0000-0000005-01. For information about Open Firmware, see the following manual: * IEEE Standard 1275-1994 Standard for Boot (Initialization, Configuration) Firmware, Core Requirements and Practices (IEEE Order Number SH17327. 1-800-678-4333) * PCI Bus Binding to IEEE Standard 1275-1994 1.6 (or later). Available by anonymous FTP from ftp://playground.sun.com/pub/p1275/bindings. Other Open Firmware bindings and recommended practice documents are also available on the same site. For more information about Forth and Forth programming, see: * Programming Languages - Forth, American National Standards Institute, Inc. * Forth: A Text and Reference, Mahlon G. Kelly and Nicholas Spies. Prentice Hall, 1986. * Starting FORTH, Leo Brody. FORTH, Inc., second edition, 1987. Information about FirmWorks publications can be obtained with an email request to info@firmworks.com or from http://www.firmworks.com. ---------------------------------------------------------------------- Chapter 1 OVERVIEW This chapter introduces Open Firmware as defined by IEEE Standard 1275-1994. Open Firmware is stored in the boot ROM (read-only memory) of a system, and is executed immediately after you turn on your system. The primary tasks of Open Firmware are: * Test and initialize the system hardware. * Determine the hardware configuration. * Boot the operating system from either a mass storage device or from a network. * Provide interactive debugging facilities for testing hardware and software. Historically, firmware designs have been proprietary to individual companies or even individual machines. A primary goal of Open Firmware is to bring standardization to this area of computing while simultaneously providing an extensible framework that can grow and evolve with changes in technology. Features of Open Firmware The Open Firmware architecture provides a significant increase in functionality and portability when compared to proprietary systems of the past. Although this architecture was first implemented by Sun Microsystems as OpenBoot(tm) on SPARC(R) systems, its design is processor-independent. Some notable features of Open Firmware include: * Plug-in device drivers. A plug-in device driver is usually loaded from a plug-in device such as a PCI card. The plug-in device driver can be used to boot the operating system from that device or to display text on the device before the operating system has activated its own drivers. This feature allows the input and output devices supported by a particular system to evolve without changing the system ROM. * FCode interpreter. Plug-in drivers are written in a machine-independent interpreted language called FCode. Each Open Firmware system ROM contains an FCode interpreter. Thus, the same device and driver can be used on machines with different CPU instruction sets. * Device tree. The device tree is an Open Firmware data structure describing the devices (permanently installed and plug-in) attached to a system. Both the user and the operating system can determine the hardware configuration of the system by inspecting the device tree. * Programmable User Interface. The Open Firmware User Interface is based on the interactive programming language Forth. Sequences of user commands can be combined to form complete programs, and this provides a powerful capability for debugging hardware and software. The User Interface You can enter the Open Firmware environment in the following ways: * By halting the operating system. * By entering an implementation-specific "interrupt" key sequence from the keyboard. (On some systems, this abruptly breaks execution of the operating system and should be used with caution.) * On SPARC systems, the "interrupt" key sequence is Stop-A. * On PowerPC systems with PC-style keyboards, the sequence is Control-Break. * On x86 systems, the sequence is Control-Break. Consult your system documentation for the "interrupt" key sequence for your machine. * By power-cycling the system. If your system is not configured to boot automatically, the system will stop at the User Interface. If automatic booting is configured, you can cause the system to stop at the User Interface by entering the "interrupt" key sequence from the keyboard after the display console banner appears but before the system starts booting the operating system. Consult your system documentation for the "interrupt" key sequence for your machine. * When the system hardware detects an error from which it cannot recover. (This is known as a Watchdog Reset.) Open Firmware provides three external interfaces: * The Client Interface which enables operating systems or other stand-alone programs to access Open Firmware services. * The Device Interface which enables Open Firmware to identify expansion bus plug-in boards (for example, PCI boards) and to obtain boot drivers from those expansion boards. * The User Interface which provides users with powerful scripting and debugging facilities from the command line. This manual describes the third of these interfaces: the command line interface or User Interface. The User Interface is an interactive command interpreter that gives you access to an extensive set of functions for hardware and software development, fault isolation, and debugging. A variety of system users, ranging from end-users to system administrators to system developers, can use these functions. The User Interface prompt is implementation dependent. * FirmWorks's implementation uses ok. * Apple's implementation uses n>, where n is the current number of stack arguments. The examples in this book use the ok prompt. When you enter the User Interface, the following screen is displayed: Type help for more information ok ------------------------ Copyright (c) 1995-1998 FirmWorks. All rights reserved.