Open Firmware Client Interface Developer's Guide To assist developers in porting programs to the Open Firmware "client interface", FirmWorks has created "Open Firmware Client Interface Developer's Guide". This manual, available exclusively from FirmWorks, clearly explains the theory and practice of writing and producing client interface programs and is filled with program examples to help you get started. If you need to write a client program for an Open Firmware-based system, this book will provide you with the knowledge you need. A complete table of contents for the manual is provided at the end of this file. In it, you will find chapters on the Open Firmware device tree, available client interface services, configuration variables, booting, debugging and more. To order your copy, contact FirmWorks: 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. ________________ The following is the table of contents of the "Open Firmware Client Interface Developer's Guide" ---------------------------------------------------------------------- CONTENTS Preface vii Chapter 1: The Device Tree and Packages 1 Introduction 1 The Device Tree 1 Device Naming 1 Device Aliases 3 Packages 4 Packages and Instances 5 Opening a Package 7 Package Properties 8 Package Handling and Access 16 /packages Device Node 17 Disk Label Package 17 TFTP Booting Package 18 Chapter 2: Client Services 19 Client Interface Handler 19 Warning 20 Client Interface Structure 20 Client Interface Service Definitions 21 Client Interface 21 Device Tree 21 Device I/O 24 Memory 25 Control transfer 26 User interface 27 Time 28 Chapter 3: Configuration Variables 29 User-Created Configuration Variables 29 Using "the Script", nvramrc 30 Adding/Modifying Properties 32 Patching Around Bugs 33 FCode Driver Bugs 33 Saving Code Fragments 34 Adding Missing Open Firmware Features 35 Heavily Customized Banners 35 Unusual Probe Sequences/Probing Non-SBus Devices 35 Device Drivers 35 Chapter 4: Console, Booting, and Other I/O 37 Console 37 Serial Console 38 Booting 39 Overview 41 Boot Protocols 44 Argument Passing 48 load Command 49 Network I/O 49 Chapter 5: Other Arrangements 51 Client Program Environment 51 Data Format 51 Program Loading and Initialization 52 Stack 52 Arguments 52 Memory and MMU 53 Interrupts and Command Interpreter Reentry 54 Sample Client Program Start Sequence 55 Abort and Go 55 Application Callback 55 Chapter 6: Diagnostics and Debugging 57 Package Selftest Routines 57 `Emergency' Keyboard Chords 58 Debugging a Client Program 59 Breakpoints 59 Symbols 59 Using ctrace 60 First-level Debugging of Client Program Problems 60 Expansion of Client Interface Diagnostic Messages 61 Refining verbose-cif Diagnostic Messages 62 Debugging Problems Occurring at Boot 62 Use of Non-existent Client Interface Service 63 Appendix A: 1275_cif.h 65 Appendix B: 1275_cif.c 67 Appendix C: Sample Startup Code 77 PowerPC 77 SPARC 79 Appendix D: prn_tree.c 81 Appendix E: putchar.c 83 Index 87 ---------------------------------------------------------------------- Copyright (c) 1996-1997 FirmWorks. All rights reserved.