Open Boot PROM Toolkit User's Guide Open Boot PROM Toolkit User’s Guide Copyright ©1990 Sun Microsystems, Inc.—Printed in U.S.A. The Sun logo, Sun Microsystems, and Sun Workstation are registered trademarks of Sun Microsystems, Inc. Sun, Sun-2, Sun-3, Sun-4, Sun386/, Sunlnstall, SunOS, SunView, NFS, SunLink, NeWS, SPARC, and SPARCstation 1 are trademarks of Sun Microsystems, Inc. UNIX is a registered trademark of AT&T. The Sun Graphical User Interface was 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 for the Xerox Graphical User Interface, which license also covers Sun’s licensees. All other products or services mentioned in this document are identified by the trademarks or service marks of their respective companies or organizations, and Sun Microsystems, Inc., disclaims any responsibility for specifying which marks are owned by which companies or organizations. All rights reserved. No part of this work covered by copyright hereon may be reproduced in any form or by any means—graphic, electronic, or mechanical—including photocopying, recording, taping, or storage in an information retrieval system, without the prior written permission of the copyright owner. Restricted rights legend: use, duplication, or disclosure by the U.S. government is subject to restrictions set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013 and in similar clauses in the FAR and NASA FAR Supplement. This product is protected by one or more of the following U.S. patents: 4,777,485; 4,688,190; 4,527,232; 4,745,407; 4,679,014; 4,435,792;4,719,569; 4,550,368 in addition to foreign patents and applications pending. Contents About This Book.:.vii Who Should Read This Book.vii Before Reading This Book. viii How to Use This Book.viii Typographic Conventions.ix Related Books.x Chapter 1. Overview.1 Programmable Read Only Memory.1 Non-Volatile Random Access Memory.2 PROM User Interfaces.2 Sun-Compatible Monitor.2 Forth Toolkit.3 Where to Find What You Need.4 Chapter 2. System Start-Up and Auto-Booting. 7 Power-On Self-Test (POST).7 Auto-Boot Procedure.8 Chapter 3. Using the Sun-Compatible Monitor.9 Starting the Monitor.9 Performing a Power Cycle.11 Interrupting Power-Up Sequence.12 Contents Halting the Operating System.13 Aborting a Hung System.14 Compatible Monitor Functions.15 Booting From the > Prompt.16 Boot Command Syntax.16 Continuing a Halted Program.18 Entering The Forth Toolkit.18 Returning to the > Prompt.19 Chapter 4. Forth Toolkit Fundamentals.21 Forth Commands (Words).22 Getting Help.23 Numbers.24 The Stack.25 Showing the Stack With showstack.25 Stack Diagram. 26 Colon Definitions.27 Keyboard Editor.29 Using Control Key Combinations.29 Using Escape Key Combinations.29 For Further Reference.30 Chapter 5. Using Forth Tools.33 Showing the Stack.34 Using 32-Bit Numbers.35 Manipulating the Stack.35 Numeric Input and Output in Different Bases.37 Using Arithmetic.39 Accessing Memory.41 Examples.47 Using Defining Words.49 Searching the Dictionary.52 Compiling into The Dictionary.53 Controlling Text Input and Output.54 Interpreting Source Code.56 Using Conditional Testing.58 » % )r 1 )r * k (r t I l K i I r L £ f D: S3 0 0 t tv Contents Controlling Conditional Execution...60 Using Conditional Loops.61 Using Counted Loops.63 Using Case Statements.65 Additional Control Commands.66 Using the Disassembler.67 Displaying Registers.68 Using Breakpoints.70 Chapter 6. Using Machine Functions.73 Resetting the System.:.74 Diagnostic Routines.75 Testing Control Registers.76 Testing The Ethernet Controller.76 Testing The Diskette Drive.77 Testing Memory.77 Testing Cache.78 Testing The Clock.78 Displaying System information.79 Booting the System From the Toolkit Prompt.79 Input, Output, and Display Modes.80 Redirecting Input and Output.80 Emergency Procedure.82 Setting Up a tip Connection.83 Ending the tip Session.85 Common Problems With tip.86 Downloading Text Files Over a Serial Line.87 Downloading Binary Files Over a Serial Line.89 Downloading Files Over Ethernet.91 Downloading Files From a Hard Disk.92 Downloading Files From a Floppy Disk.93 Ejecting the Floppy Diskette.95 Preserving Data After a System Crash.95 Symbolic Names.96 SunOS Operating System Calls.96 Manipulating the Cache.97 v Contents Reading and Writing Machine Registers.98 Chapter 7. Using Configuration Parameters .101 Displaying Parameters.102 Changing a Parameter's Value.104 Resetting Default Values.105 Security.107 No Security.108 Command Security.109 Full Security.Ill Changing the Power-On Banner.112 Input and Output Control.115 Setting Serial Port Characteristics.116 Selecting Input and Output Device Options.117 Selecting Boot Options.118 Controlling Power-On Self-Test...119 Appendix A. Sun Monitor Command Equivalents.123 Appendix B. Power-On Self-Test.127 Index.129 About This Book Who Should Read This Book This book describes how to use the Open Boot PROM available in many SPARC products. This PROM is significantly different from PROMs in other Sun systems. It can perform many new functions and has a new user interface. This guide is for Sun system administrators and field service technicians who need to use the boot PROM to do the following: □ Boot the operating system □ Run the Sun Diagnostic Executive □ Modify system start-up configuration parameters □ Perform field service troubleshooting. Software and hardware developers may also find the information in this book useful. Before Reading This Book About This Book Before Reading This Book How to Use This Book If you need to set up a system from scratch, you should read your system's installation guide. The boot PROM has a new Forth-based command interpreter. To effectively use this new interface, it is helpful to be familiar with the Forth programming language, except for simple operations such as booting the system. See "For Further Reference " in Chapter 4 for a list of recently published Forth Language reference materials. This book contains seven chapters and two appendixes: O Chapter 1 is an overview of the boot PROM and the user interfaces. □ Chapter 2 describes what happens during the system start-up self-test and auto-booting sequence. O Chapter 3 describes the Sun-Compatible Monitor interface. Refer to this chapter when you need to boot from the > prompt. □ Chapter 4 describes the basics of how the Forth Toolkit interface works. Anyone who intends to use the Forth Toolkit should read this chapter. □ Chapter 5 describes Forth tools. You will use this chapter when you are working with the Forth programming language. □ Chapter 6 describes basic machine functions. You will use this chapter when you are working with machine- specific programming issues. □ Chapter 7 describes working with NVRAM configuration parameters. You will use this chapter when you are performing typical system administration tasks. □ Appendix A compares other Sun System Open Boot PROM commands with commands used with the open boot PROM. i; i * k i* k k k k k k k k k k k k k k k £ k k p About This Book Typographic Conventions □ Appendix B is a list of the Power-On Self-Tests (POST) with brief descriptions. Typographic Conventions This book uses the following typographic conventions: □ This font is used for emphasis, for a command argument, and for the title of a book. For example: You must type the filename argument as described in the SunOS Reference Manual. O This font indicates a program listing, a command name, a program name, or text the machine displays on the screen, as in a tutorial session. For example: You have new mail. □ This font indicates what you type. Pressing the I Return I key after typing the command line is an assumed action. For example: tutorial% date □ A rectangular box around text indicates a key name. For example: Press the I Return 1 key. When you see two key names within one rectangular box, press and hold the first key down and then press the second key. For example: To press icomroi-d l . press and hold 1 Control 1 . then press (TJ. □ 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] Related Books About This Book i □ Toolkit commands may be typed in either upper or lower case characters. Many Toolkit commands are single character symbols. When these occur in text they are set off with quotation marks. For example: The "+" command adds two numbers. Related Books This book is part of the SBus Developer's Kit, a set of publications available from Sun Microsystems, Inc. The kit includes the following books: □ SBus Specification □ SBus Hardware Application Notes □ Writing SBus Device Drivers □ Writing FCode Programs for SBus Cards □ L64853 SBus DMA Controller Technical Manual □ Open Boot PROM Toolkit User's Guide (this manual). In addition, you might find the following books useful: □ Your system's system administration & network guide □ Your system's installation guide. t * * 5 t t I r i § jr * » I I I * I I & X I i \ i I 1 1 1 1 I I i p a a 4 a a a a Overview This chapter provides an overview of: □ Open boot PROM (Programmable Read Only Memory) □ NVRAM (Non-Volatile Random Access Memory) □ PROM user interfaces. The Open Boot PROM is very different from boot PROMs in other Sun systems. One significant change is in the user interface. The user interface and other changes are described later in this chapter. You might also see Appendix A for a list of commands that perform equivalent functions to the Sun Monitor command set provided with other boot PROMs. Programmable Read Only Memory The primary function of any boot PROM is to interact with the system hardware and to provide the software foundation necessary to run programs. The SunOS Operating System, the Sun Diagnostic Executive, and standalone programs all depend on the boot PROM for their initial program loading. Another function of the boot PROM is to provide a versatile set of tools for testing the system hardware. 2 Non-Volatile Random Access Memory Chapter 1: Overview Non-Volatile Random Access Memory PROM User Interfaces Sun-Compatible Monitor The NVRAM contains information that is used during system boot to set up the basic machine configuration. Unlike the information contained in the open boot PROM, you can change NVRAM parameters. These changes remain in effect even when the system is turned off. The boot PROM interface works in two modes: the Sun- Compatible Monitor and the Forth Toolkit (new command mode). The Sun-Compatible Monitor mode is provided to present a compatible interface to the most common PROM use — booting the system. When you start the Sun-Compatible Monitor, the boot prompt > appears on the display screen. From the boot prompt you may execute an abbreviated set of commands. These commands allow you to boot the system, continue the execution of a halted program, or enter the Forth Toolkit. Chapter 1: Overview Forth Toolkit Forth Toolkit The Toolkit is an interactive command interpreter based 1 on the Forth programming language. The ok prompt indicates that you are in the Toolkit. The Toolkit gives 1 you access to an extensive set of functions for performing hardware development, problem determination (fault isolation), software development, I and debugging. All functions available through the Sun- Compatible Monitor mode are also available through the | Forth Toolkit. I Where to Find What You Need Chapter 1: Overview Where to Find What You Need The following shows where you can find the important information in this manual: Where What You Will Find Chapter 2 System Start-Up and Auto-Booting Overview of power-up and auto-booting sequences. For basic booting and using the Monitor, go to Chapter 3. Chapter 3 Using the Sun-Compatible Monitor Procedures for: 1. Starting the Monitor 2. Booting the system 3. Entering and leaving the Toolkit 4. Performing a power cycle. For an introduction to the Forth Toolkit, go to Chapter 4. Chapter 4 is for anyone who wishes to use the Forth Toolkit Interface. Chapter 4 Forth Toolkit Fundamentals Forth Interface basics as they apply to the PROM Toolkit implementation of the Forth programming Language. For Forth tools, go to Chapter 5. For basic machine functions, go to Chapter 6. For NVRAM Configuration Parameters, go to Chapter 7 Chapter 1: Overview Where to Find What You Need Chapter 5 describes Forth programming capabilities. Where What You Will Find Chapter 5 Using Forth Tools 1. Manipulating the stack 2. Using arithmetic 3. Accessing memory 4. Searching the Forth Dictionary 5. Controlling input and output 6. Conditional testing and execution 7. Using case statements 8. Using the disassembler 9. Using loops 10. Displaying registers 11. Using breakpoints. Chapter 6 describes basic machine control functions. Chapter 6 Using Machine Functions Procedures for: 1. Resetting the system 2. Running Diagnostics 3. Displaying system information 4. Booting from the ok prompt 5. Input/output and display modes 6. Setting up a TIP window 7. Downloading files 8. Controlling disk drives. Chapter 7 describes working with NVRAM configuration parameters. Chapter 7 Using Configuration Parameters Procedures for: 1. Displaying and changing parameters 2. Setting security 3. Changing the power-on banner 4. Input/output control 5. Boot options 6. Controlling POST. Where to Find What You Need Chapter 1: Overview k D * % % * * * £ t £ £ fr- £ I r £ I £ £ £ § r i & 6 2 System Start-Up and Auto- Booting This chapter describes the default start-up and auto¬ booting sequence. Power-On Self-Test (POST) The power-up sequence assumes that the system Integer Unit (IU) is functional and able to fetch instructions from the Open Boot PROM. Turning on the power switch to the system unit, powering-up, resets the IU. Execution of the Power-On Self-Test (POST) sequence begins immediately. The Open Boot PROM contains the programs for the power-on self-tests and system initialization sequence. The overall objectives of POST are to quickly verify that the system functions, initialize the system hardware, and boot the SunOS Operating System. The POST and component initialization occur somewhat simultaneously with each component being initialized as testing completes. See Appendix B for a list of POST with brief descriptions. Note: The POST normally performs minimum- confidence tests (not comprehensive hardware examination) prior to attempting to boot the specified software program. 7 Auto-Boot Procedure Chapter 2: System Start-Up and Auto-Booting ij For more comprehensive tests, see "diag-switch?" in Chapter 7, "Using Configuration Parameters." Auto-Boot When the system test and initialization are completed. Procedure the auto-boot procedure begins. Normally, the PROM attempts to auto-boot vmunix from the system's internal hard disk drive. Auto-boot defaults are contained in the NVRAM configuration parameters. These parameters can be modified using the PROM Toolkit. You can change the default parameter settings to specify another program to be booted or another boot-f rom device. See Chapter 7 for procedures for modifying NVRAM configuration parameters. - As the power-up sequence executes, you will see status You can use the tl-l-Al key messages on the display. At the completion of an combination to access the uninterrupted power-up sequence, the system's login Monitor from the login prompt. prompt displayed . login: When the system is unable to successfully complete one or more of the POSTs or auto-boot, the boot PROM outputs an error message or messages to ttya and/or the console display and attempts to start the Sun-Compatible Monitor program. If a fatal error is encountered, the program will attempt to display a message on ttya and/or the console display and will then loop on the error location. If enough of the system is functional so that the Sun-Compatible Monitor can execute, the PROM displays a brief message and the boot prompt. Type b (boot), c (continue), or n (new command mode) > Chapter 3 describes the functions available from the > prompt. Chapter 4 is an introduction to the Forth Toolkit interface. Chapters 5, 6, and 7 describe using the Forth Toolkit. * I ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥. ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ 8 Using the Sun-Compatible Monitor Starting the Monitor This chapter explains how to access the boot PROM interface and use the Sun-Compatible interface — commonly called the Monitor. The Monitor supports three commands that allow you to boot the system, continue a halted program, and enter the Forth Toolkit. The boot PROM interface operates independently from the SunOS Operating System. Figure 3-1 lists the three ways you can start the interface. Because boot PROM commands can modify any location in memory, it is possible to enter commands incorrectly so that the PROM is unable to execute what you've entered and becomes hung. The system stops responding to input from the keyboard. In that case, your only alternative is to perform a power cycle to bring the system back to normal operation. Once you perform the power cycle, you can interrupt the power-up sequence to return to the command interpreter. When performed as described on the following pages, a power cycle will not produce any adverse effects on your system. Starting the Monitor Chapter 3: Using the Sun-Compatible Monitor Figure 3-1. Starting the Boot PROM Interface Method Procedure Performing a Power-Cycle and Interrupting Power-Up Sequence Halting SunOS Operating System (normal method) 1. If necessary, turn the power to the system unit off and wait 10 seconds 2. Turn on the power to the display (if necessary) 3. Turn on the power to the system unit, and wait several seconds 4. When the word Testing appears on the screen, press 1L1-A) . 1. Save and quit all open files 2. Quit all applications 3. In a shell window, become the system superuser and type: /etc/halt Aborting SunOS Operating System (if hung system) 1. Press Ili-a) . 2. At > prompt, type n 3. At ok prompt type sync 4. Press (Li-Al again when you see the word rebooting. 5. At the ok prompt type old-mode to return to the > prompt (if desired) Performing a Power Cycle Chapter 3: Using the Sun-Compatible Monitor performing a Power Cycle When your system necessary to return becomes hung, a power cycle is the system to normal operation. To perform a power cycle: 1 Turn off the power to the system unit (use the main ' power switch on the back of the system unit). The following drawing shows the location of the power switch on the SPARCstation 1. The local,on of the power switch for other systems mig 2. Wait a minimum of 10 seconds. 3. Turn the power back on. aution: Always allow 10 seconds between turning off ie power and turning it back on again. This pause revents possible damage to power supply components m "viir QVQt-pm unit. Interrupting Power-Up Sequence Chapter 3: Using the Sun-Compatible Monitor Interrupting Power-Up Sequence The most common way to start the PROM interface is to interrupt the power-up sequence. You can interrupt the power-up sequence anytime you turn the system unit on, or when you reset the system from the keyboard. To interrupt the power-up sequence (assuming the system is powered off): 1. Turn on the power to the display. 2. Turn on the power to the system unit. Locate the power toggle switch on the back of the system unit. Press the side of the switch labeled 1. 3. After the word "Testing" appears on the display, press the Ili-aI keys simultaneously. The power-up sequence halts and the system displays a brief message and the boot prompt > . Type b (boot), c (continue), or n (new command mode) > Chapter 3: Using the Sun-Compatible Monitor 1 LUiling IUC Vjpc IULl.ii£ Halting the Operating System To start the boot PROM interface when the SunOS Operating System is running, you must first halt the execution of SunOS. Halting SunOS should be done carefully. When you halt the SunOS Operating System, the Monitor program starts automatically. When the system is running the SunOS Operating System, you should see a machine prompt in an open shell window that looks something like this: hostname% To halt the operating system and start the user I interface: 1. Save and quit all open files. See the Sun System User's Guide for information about ending a work session. 2. Quit all open applications. I 3. Become superuser as described in the Sun System Network Manager's Guide, Chapter 2. Type /bin/su and 1 preSS [Return l . 4. Type /etc/halt and press I Return 1 . | The system displays system halt messages followed by the boot prompt, l i I hostname% /bin/su Password: hostname# /etc/halt Syncing file systems . . . done Halted Type b (boot), c (continue), or n (new command mode) > I I 13 Aborting a Hung System Chapter 3: Using the Sun-Compatible Monitor Aborting a Hung System When the operating system appears to be running but the system does not respond to the mouse and/or keyboard, the system is hung. When you abort a hung system, the PROM user interface automatically starts. If the following sequence does not work — that is, if the system does not respond to the abort attempt — perform a power cycle to return the system to normal operation. If a power cycle does not restore normal system function, call your field service representative for further assistance. To abort a hung system and start the PROM user interface: 1. Press ili-ai . 2. Type n and press 1 Return 1 . The system displays a help message and an ok prompt. 3. Type sync and press [Return I . 4. Press In -a! again when you see the word rebooting. 5. Type old-mode and press I Return I . to return to the > prompt (if desired). Press Ili-aI Type b (boot), c (continue) or n (new command mode) > n Type help for more information ok sync When you see the word rebooting, press ILI-AI again ok old-mode Type b (boot), c (continue) or n (new command mode) > On some keyboards, Q3) appears on the front face of the [ Stop l key. Chapter 3: Using the Sun-Compatible Monitor Compatible Monitor Functions The sync command helps prevents the system from losing data that was not preserved when the system hung. Caution: When the operating system or any other standalone program has already booted, it is preferable not to use [i.i-aI to halt the machine. Aborting program execution with HTaI can cause damage to currently open data files. Compatible Monitor Functions You can disable Sun-Compatible Monitor mode using NVRAM parameters. See Chapter 7 for information about modifying NVRAM configuration parameters. Three commands are supported by the Sun-Compatible Monitor mode. These commands are b for booting the system, c for continuing the execution of a halted program, and n for entering the new command mode called the Forth Toolkit. The c and n are single character commands only. However b supports the standard booting command syntax. The boot PROM Sun-Compatible Monitor mode presents a compatible interface to the most common PROM use, booting the system. All functions available through this mode are also available through the Forth Toolkit. 15 Booting From the > Prompt Chapter 3: Using the Sun-Compatible Monitor Booting From the > Prompt The boot command loads the SunOS Operating System or another executable program into memory and executes that program when the program load completes. All booting operations function identically, whether you are in Sun-Compatible Monitor mode or in the Forth Toolkit. The only difference is that you must type out the entire word "boot" (with a following space if options are used) when you are in the Toolkit. To boot your system, enter a boot command. See the next section "Boot Command Syntax" for the boot command format and the options summary in Figure 3-2 for further details. Syntax for both the > prompt and the Toolkit ok prompt is shown in the following examples. Sun Compatible Monitor > PROM Toolkit ok Description b boot Boot system using defaults b -as boot -as Boot sdO with flags -a (interactive flag) and -s (single- user operation) b le() boot le() Boot vmunix from the network b net boot net Boot vmunix from the network b sd(0, 0 , 2)mydiag boot sd(0,0,2)mydiag Boot mydiag from SCSI drive partition 2 Note: Boot defaults can be changed using NVRAM configuration parameters. The NVRAM defaults are only used if the boot command has no arguments. See Chapter 7 for information about changing defaults. Boot Command Syntax The syntax of the boot command follows. Spaces and tabs typed in the command line are ignored. All arguments shown in italics are optional. When using command options, the command word boot must be followed by a space. > b [device (c,u,p) filename options] ok boot [device (c,u,p) filename options] Chapter 3: Using the bun-uompatwie murmur I ! i I II I I I i 1 I J 1 I Figure 3-2 lists the boot commands and their syntax. Figure 3-2. Boot Option Commands Option _ Description _ device is one of: net or le ( c,u,p ) LANCE Ethernet disk or sd (c,u,p) SCSI hard disk tape or st (c,u,p) SCSI tape f d ( c,u,p ) 3-1/2" diskette drive c Controller Number, default value = 0. u Unit Number, default value = 0; when booting from a hard disk the range may be from 0-3. p Partition Number, default value = 0; when booting from a hard disk the range may be from 0-7. When using le, sd and f d as device identifiers, the parentheses are required in the command line. Example: ble () or ble (0,0,0). The contents of the parentheses depends on the specified device. filename Default = vmunix . The name of the program to be booted, such as stand/diag or vmunix. filename is relative to the root of the selected device and partition (if specified), filename never begins with '/'• It filename is not given, the boot program uses the default file name vmunix. options -a Prompts interactively for the device and name of the file to boot. -b Pass the -b flag through the kernel to init (8) to skip execution of the /etc/rc . local script. -h Halt after loading the program. -s Pass the -s flag through the kernel to init (8) for single-user operation. -i initname Pass the -i initname to the kernel to tell it to run initname as the first program rather than the default /single/init. 17 Continuing a Halted Program Chapter 3: Using the Sun-Compatible Monitor Continuing a The c command is useful if you have halted your SunOS Halted Program Operating System or another program by pressing (lpaI . To resume execution of a halted program: Type b (boot), c (continue), or n (new command mode) > c Program execution resumes. Once execution has resumed, you can choose Redisplay All from the SunView menu to refresh the display and remove any screen artifacts. Note: From the ok prompt, the command go performs the same function as typing c at the > prompt. Entering The Forth To enter boot PROM Forth Toolkit mode from the > Toolkit prompt, type: Type b (boot), c (continue), or n (new command mode) > n Type help for more information ok The monitor enters the Forth Toolkit and displays the ok prompt and help message. s ■ r! r : V: Ej L ! C! V. ll t: l: I l £ I k I I I I I. I I I) k I f i l i i f 18 Chapter 3: Using the Sun-Compatible Monitor Returning to the > Rrompt Returning to the > Prompt After entering the Toolkit, all the functions available from the boot prompt are available from the ok prompt. However, should you wish to exit the Toolkit and return to the > prompt, enter: °k ok old-mode Type b (boot), c (continue), or n (new command mode) The Sun-Compatible Monitor supports a very abbreviated set of functions. From the > prompt you can boot the system, enter the Forth Toolkit, or continue the execution of a halted program. After entering the Forth Toolkit, you can work closely with your system's hardware. The remaining chapters describe using the Forth Toolkit. Even if you are familiar with the operation of the Forth programming language, we recommend that you read Chapter 4 which describes how Forth is implemented in the Open Boot PROM. Returning to the > Prompt Chapter 3: Using the Sun-Compatible Monitor ft - ¥ ¥ fr ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ ¥ r ¥ ¥ 20 4 Forth Toolkit Fundamentals This chapter introduces Forth as it is implemented in the Open Boot PROM. Even if you are already familiar with the Forth programming language, we recommend that you read this chapter because it contains useful information that relates specifically to your system. While it is impossible to provide a complete tutorial on the Forth language here, this chapter covers enough of the basics to enable you to use the Toolkit. To use this chapter to its fullest advantage, work through the examples shown in the gray screens. These examples will help you understand how the interface operates. For additional information, see "For Further Reference" at the end of this chapter. In addition. Chapter 5 "Using Forth Tools" describes the Forth programming language capabilities. Note: As mentioned previously, it is possible to enter commands at the ok prompt that cause the system to become hung. If this happens, you might need to perform a power cycle to return the system to normal operation. This chapter assumes that you have read Chapter 3 and are familiar with how to enter and leave the Forth Toolkit from the Sun-Compatible Monitor. 21 Forth Commands (Words) Chapter 4: Forth Toolkit Fundamentals Forth Commands (Words) In this chapter, the terms word and command are used interchangeably. Forth has a very simple command structure. Forth commands, also called Forth words, consist of any combination of printable characters — for example, letters, digits, or punctuation marks. All of the following are examples of legitimate words: @ dump . 0< + test-memory Words must always be separated by one or more spaces (blanks) in order to be recognized. Press I Return I at the end of any command line to execute the typed command(s). In all examples shown, a I Return I at the end of the line is assumed. Multiple words on a line are simply executed one at a time, from left to right, in the order in which they were entered (from left to right). For example: In this implementation of Forth, upper-case and lower¬ case letters are equivalent. Therefore, testa, TESTA, and TesTa all invoke the same command. Commands that may generate large amounts of output, such as dump or words, can be interrupted by pressing any key. At that point, output is suspended and the following message appears: More [,,q] ? Press the space bar to continue, press l Return I to output one more line and pause again, or type q to abort the command. When you are generating more than one page of output, the system will automatically enter this prompt after every page. £ £ £ £ £ £ £ £ £ £- £ f £- £ r l ' i i r L- £ E. l- i i 22 Chapter 4: Forth Toolkit Fundamentals Getting Help I i I Getting Help Whenever you see the ok prompt on the display, you can ask the system for help by typing one of the help commands. For example: ok help dump Category: Memory access dump ( addr length — ) display memory at addr for length bytes ok The help command displays instructions on how to use the help system and lists the available help categories. ok help category This command shows the help messages for all commands available in the selected category, or possibly a list of sub-categories. ok help name This command shows the help for the named command. Note: Because there are a very large number of command words, help is available for the most frequently used commands only. Figure 4-1 lists commands which describe the help and change functions. Figure 4-1. Help and Mode Commands 1 Command Stack Diagram Description * help (-> List main help categories. J help category (--) Show help for all commands in the category. Use only the first word of the category J description. 1 help name (-> Show help for individual command (where available). 1 ! I Numbers Chapter 4: Forth Toolkit Fundamentals Numbers Numbers are entered simply by typing in the value, for example, 55 or -123. Forth accepts only integer (whole) numbers; fractional values such as 2/3 or 5.77 are not allowed. Be sure to use one or more spaces to separate numbers from words or from each other. The Forth toolkit performs 32-bit integer arithmetic, and all numbers are 32-bit values unless otherwise specified. Because hexadecimal (base 16) numbers are so commonly used, the Forth Toolkit automatically interprets all numbers in hexadecimal, not decimal. Therefore, adding 8 and 7 returns the value f, not 15. However, you can change the operating number base. To operate in decimal (base 10), type the following command: ok decimal ok To change back to hexadecimal (base 16) type: ok hex ok To find out what number base is currently active, type: ok 10 .d 16 ok See "Numeric Input and Output in Different Bases" in Chapter 5 for more information and additional commands regarding hexadecimal versus decimal numeric conversion. 24 Chapter 4: Forth Toolkit Fundamentals The Stack The Forth stack is a last-in, first-out buffer used for temporarily holding numeric information. Think of it as a stack of books: the last one you put on the top is the first one you take off. Understanding the stack is essential to using the Forth Toolkit. To place a number on the stack, simply type its value. ok 44 The value 44 is now on top of the stack ok 7 The value 7 is now on top , with 44 just underneath ok Showing the Stack The contents of the stack are normally invisible until With showstack needed. However, properly visualizing the current stack contents is important for achieving the desired result. To show the stack contents with every ok prompt, type: *» I 9 * I I ► I J * I I 1 I J I i Top of the Stack Remember, the topmost stack item is always shown on the right side of the list. Once invoked, showstack will remain in effect until a machine reset takes place. Nearly all words that require numeric parameters will fetch those parameters from the top of the stack. Any values returned are generally left on top of the stack, where they may be viewed or consumed by another command. For example, the Forth word + removes two numbers from the stack, adds them together, and leaves the result on the stack. ’: t. 25 Stack Diagram Chapter 4: Forth Toolkit Fundamentals Stack Diagram To add two numbers from the top of the stack, type the addition operator + like this: 44 7 8 ok + 44 f ok + 53 ok Remember, all arithmetic is in hex Once the two values are added together, the result is put onto the top of the stack. The Forth word . removes the top stack item and displays that value on the screen. For example: 53 ok 12 53 12 ok . 12 53 ok . 53 ok The stack is now empty ok 3 5 + . 8 ok The stack is now empty Because knowing the stack usage is vital to the proper operation of all Forth words, there is an associated stack diagram in the form (--) for every defined word. The stack diagram specifies what happens to the stack with the execution of the command word. For example, the stack effect diagram for the + word is ( nl n2 -- n3 ). The stack effect diagram for . is (n -- ). Any entries before the — show stack items that are consumed, that is removed from the stack and used by the operation of that word. Any entries after the — show stack items that are left on top of the stack after the word is finished executing. Therefore, + removes two numbers and then leaves the sum on the stack. The word . simply removes one number and displays it. Any word that has no effect on the contents of the stack, such as showstack or decimal, will have a (--) stack Chapter 4: Forth Toolkit Fundamentals Colon Definitions Colon Definitions effect diagram. These words may be executed at any time, with no effect on the contents of the stack. Occasionally, a word will require another word or other text immediately following, such as the see word, used in the form see anyword. The word see has no stack effect. The stack diagram would be: see anyword (-- ) Forth provides an easy means to create custom definitions for new command words. These are called colon definitions, named after the : word used to create them. For example, suppose you wish to create a new word add4 that will add any four numbers together and display the result. The definition could be created as follows: ok add.4 + + + . ok The ; (semi-colon) marks the end of the definition that defines add4 to have the behavior (+ + + .). The three pluses reduce the four stack items to a single sum on the stack, and then the . removes and displays that result. ok 1233 + + + . 9 ok 1233 add4 9 ok Definitions are stored in local memory, which means they are forgotten if a machine reset takes place. To keep useful definitions, either jot them down (for short ones), or create a text file (using your favorite text editor under SunOS) containing the definitions. This text file can then be downloaded whenever it is needed. See "Downloading Files" in Chapter 6 for more information. When you type a definition in the Toolkit, the ok prompt becomes a ] (right square bracket) prompt after you type Colon Definitions Chapter 4: Forth Toolkit Fundamentals the : (colon) and before you type the ; (semi-colon). For example, you could type the definition for add4 like this: ok : add4 ] + + + 1 • 1 ; ok Every definition you create (in a text file) should have a stack effect diagram shown with that definition, even if the stack effect is nil (--). This is vital because the stack diagram tells you how that word is properly used. We also recommend that you use generous stack comments, within the middle of complex definitions, to help trace the flow of execution. For example, when creating add4, it might be defined as: : add4 ( nl n2 n3 n4 — ) + + + . / or : add4 ( nl n2 n3 n4 — ) + + + ( sum ) f Note: The ( open parenthesis is a Forth word meaning to ignore the following text, up to the closing parenthesis ). Like any other Forth word, the open parenthesis must have one or more following spaces. K ; F F F F F F F F F F F F F~ F fe fe £ if F- 1 r fi ii oo Chapter 4: Forth Toolkit Fundamentals Keyboard Editor Keyboard Editor Using Control Key Combinations Using Escape Key Combinations An EMACS-style (one of the text editors available on Sun systems) keyboard line editor and history mechanism is also provided with the Forth Toolkit. This powerful tool enables you to re-execute previous commands without retyping them, and allows editing of the current command line to fix typing errors or to edit previous commands. The line editing commands listed in Figure 4-2 are available for your use when you are typing commands to the Forth Toolkit ok prompt. These commands are control and escape key combinations. To execute a control key combination: 1. Press and hold down the I Control 1 key. 2. Type the desired character key. To execute an escape key combination: 1. Press and release the t Esc 1 key. 2. Type the desired character key. As you review the list of commands, notice that there are commands for the following: □ Moving forward and backward on the command line □ Erasing characters, words, all or a portion of the command line □ Recalling the most recently typed command lines; repeatedly pressing I comroi-p l will recall previous commands (at least 8 are remembered). To insert text at the cursor, simply type normally. Pressing t Return I sends the line (as it currently appears) out for execution. 29 For Further Reference Chapter 4: Forth Toolkit Fundamentals While a small effort is required to learn this function, it will save you time and effort every time you use the Forth Toolkit. Figure 4-2. Line Editor Commands Command Description iCaniraL-hJ Backward one character [ Esc ]1 b ) Backward one word ICquiiqLLJ Forward one character I Esc 1 ( f 1 Forward one word iCQDtrol-a J Beginning of line [ Control-e 1 End of line [ Control -h J Erase previous character (also l Del ] or ( Back Space )) IPsfiJCFD Erase previous portion of word (also 1 Control-w 1) (Control-d 1 Erase this character 1 Esc 1 fd~) Erase this portion of word, from here to end of word [ Control-k J Erase forward, from here to end of line [Control-u J Erase entire line l Control-1. J Retype line l.Cgntrol-q ) Quote next character (to type a control-character) l Control-p ) Recall previous command line l Control-n J Recall subsequent command line For Further For further reading, see one or more of the following Reference reference materials: Mastering Forth Anita Anderson and Martin Tracy Brady Communication Company, Inc. 1230 Avenue of the Americas New York, New York Mastering Forth is particularly useful, because the Forth dialect it describes quite closely resembles the implementation of Forth in the boot PROM. Chapter 4: Forth Toolkit Fundamentals For Further Reference Starting Forth Leo Brodie/Forth, Inc. Prentice-Hall Software Series Englewood Cliffs, New Jersey 07632 Starting Forth is a popular and well-written book. The second edition describes the current Forth standard dialect. Forth 83. Note: There are several differences between the versions of Forth as described in the reference materials and the version described in this guide. Specifically, the boot PROM Forth Toolkit uses 32-bit numbers instead of 16-bit numbers. The editors, described in these books, do not apply. This chapter presented a brief overview of how to use the Forth Toolkit interface. The next three chapters describe many useful Forth commands. Chapter 5 provides information about using the Toolkit and the Forth language. Chapter 6 describes machine-specific issues for writing programs that interact with your system's hardware. Chapter 7 describes NVRAM configuration parameters and how to change them. For Further Reference Chapter 4: Forth Toolkit Fundamentals 5 Using Forth Tools This chapter provides an overview of how to use the many functions provided by the Open Boot PROM's Forth Toolkit. These descriptions are intended to help you get started using this Forth implementation to its fullest capacity. However, you may find that you need more specific information concerning the Forth programming language. For further information, consult any Forth tutorial or reference book, or see "For Further Reference" at the end of Chapter 4 for a short list of Forth Language publications. In this chapter you will find information about: □ Manipulating the stack □ Using numeric input and output in different bases □ Using arithmetic □ Accessing memory □ Searching the Forth dictionary □ Controlling text input and output □ Using conditional testing □ Controlling conditional execution 33 Showing the Stack Chapter 5: Using Forth Tools □ Using conditional and counted loops □ Using case statements □ Using defining words □ Compiling the dictionary □ Using the disassembler □ Displaying registers □ Using breakpoints. This chapter assumes that you are familiar with the boot PROM's Forth Toolkit interface. With the exception of the NVRAM parameter commands, which should only be used with caution, all the commands that are described in this guide can be freely executed at any time. Remember, you can either enter commands at the ok prompt or type them into ASCII text files for downloading and execution. The SPARC Open PROM Toolkit Reference Summary, which comes with your SBus Developer's Kit, provides a list of all commands explained in this book. Showing the Stack For all examples shown in this chapter, showstack is enabled. Every ok prompt is immediately preceded by a display of the current contents of the stack. Every example will work just the same if showstack were not enabled, except that the values immediately before each ok will not be shown. See "The Stack" in Chapter 4 for information about the showstack command. Chapter 5: Using Forth Tools Using 32-Bit Numbers Using 32-Bit Numbers Manipulating the Stack The Forth interpreter implemented in the boot PROM adheres closely to the Forth 83-Standard in most respects. One major exception is that the boot PROM Forth implementation uses 32-bit numbers instead of 16-bit numbers. In most cases, this difference will be transparent to the user. For example, @ and ! (described later in this chapter) work with variables as expected. If you explicitly want a 16-bit fetch or a 32-bit fetch, use w@ or L@ instead of @. Other commands also follow this convention. Stack manipulation commands allow you to add, delete and reorder items on the stack. In most cases, the stack effect diagram fully defines the behavior of the word. A typical use of stack manipulation might be to display the top stack item while preserving all stack items as shown in the example below: 5 77 ok dup Duplicates the top item on the stack 5 7 7 77 ok . Removes and displays the top stack item 7 7 5 7 7 ok The stack is now the same as before Figure 5-1 on the next page lists stack manipulation commands. Manipulating the Stack Chapter 5: Using Forth Tools Figure 5-1 . Stack Manipulation Commands Command Stack Diagram Description clear (??? —) Empties the stack depth (— +n ) Returns the number of items on the stack drop (n-) Removes top item from the stack 2drop ( nl n2 — ) Removes 2 items from the stack dup ( n — n n ) Duplicates the top stack item 2dup ( nl n2 — nl n2 nl n2 ) Duplicates 2 stack items 3dup ( nl n2 n3 -- nl n2 n3 nl n2 n3 ) Duplicates 3 stack items ?dup ( n - n n 1 0 ) Duplicates 1 top stack item if it is non¬ zero nip ( nl nl — n2 ) Discards the second stack item over ( nl n2 -- nl n2 nl ) Copies second stack item to top of stack 2over ( nl n2 n3 n4 -- nl n2 n3 n4 nl n2 ) Copies second 2 stack items pick ( +n -- n2 ) Copies +n-th stack item (1 pick = over) >r (n-) Moves a stack item to the return stack (use with caution) r> (— n) Moves an item from the return stack to the stack (use with caution) r@ (~n) Copies the top of the return stack to the stack (use with caution) roll (+n —) Rotates +n stack items (2 roll = rot) rot (nl n2 n3 -- n2 n3 nl ) Rotates 3 stack items -rot ( nl n2 n3 -- n3 nl n2 ) Inversely rotate 3 stack items 2rot ( nl n2 n3 n4 n5 n6 -- n3 n4 n5 n6 nl n2 )Rotates 3 pairs of stack items swap ( nl n2 -- n2 nl ) Exchanges the top 2 stack items 2swap ( nl n2 n3 n4 — n3 n4 nl n2 ) Exchanges 2 pairs of stack items tuck ( nl n2 -- n2 nl n2 ) Copies the top stack item underneath the second item 36 Chapter 5: Using Forth Tools Numeric Input and Output in Different Bases Numeric Input and Output in Different Bases The commands hex and decimal cause all subsequent numeric input and output to be performed in base 16 or base 10, respectively, d# and h# are useful for inputting a number in the other base, without having to explicitly change the base. For example: ok decimal Change base to decimal ok 4 h# ff 17 2 4 255 17 2 ok . d and . h act like . but display the value in decimal or hex, respectively, regardless of the current base setting. For example: ok hex ok ff . ff .d ff 255 ok . s displays the entire stack contents without disturbing them. It can be safely used at any time for debugging purposes. This is the function that showstack performs automatically. Large numbers such asfffffff are sometimes shown with a decimal point — that is, f f f . f f f f. This is done solely for readability. The Toolkit ignores the decimal point. Numeric Input and Output in Different Bases Chapter 5: Using Forth Tools Figures 5-2, 5-3, and 5-4 list commands to control numeric input and output. Figure 5-2. Changing the Numeric Base Command Stack Diagram Description base (-- adr) Variable containing number base d# number (~n) Interpret the next number in decimal; base is unchanged. decimal (-) Set number base to 10 h# number (~n) Interpret the next number in hex; base is unchanged. hex (-) Set the number base to 16 Figure 5-3. Displaying Output Command Stack Diagram Description . (n-) Display a number in the current base .d (n~) Display n in decimal without changing base .h (n~) Display n in hex without changing base . r ( n size -- ) Display a number in a fixed width field . s (-> Display contents of data stack showstack (--) Automatically shows stack items before ok prompt u. (u ) Display an unsigned number u. r ( u size -- ) Display an unsigned number in a fixed width field Chapter 5: Using Forth Tools Using Arithmetic Figure 5-4 lists "primitives" used to create numeric display words, such as . u. or . r. They are not normally needed. Figure 5-4. Output Display Primitives Command Stack Diagram Description <# (-> Initializes pictured numeric output # ( +nl - +n2 ) Converts next digit # s ( +nl — 0 ) Converts remaining digits hold (char —) Inserts character into pictured output sign (n~) Inserts sign into pictured output #> ( n -- adr len ) Ends pictured output, leaving string ready to type. (. ) ( n -- adr len ) Converts a number into a string, ready to type. (u.) ( u -- adr len ) Converts an unsigned number into a string, ready to type. Using Arithmetic Forth provides a variety of basic arithmetic functions. The commands listed in Figure 5-5 on the next page perform basic arithmetic operations on items in the data stack. Using Arithmetic Chapter 5: Using Forth Tools Figure 5-5. Using Arithmetic Command Stack Diagram Description ★ ( nl n2 — n3 ) Multiplies nl * n2 + ( nl n2 -- n3 ) Adds nl + n2 - ( nl n2 - n3 ) Subtracts nl - n2 / ( nl n2 — quot) Divides nl / n2 « ( nl +n - n2 ) Left shift nl by +n places » ( nl +n — n2 ) Right shift nl by +n places »a ( nl +n - n2 ) Arithmetic right shift nl by + n places */ ( nl n2 n3 — n4 ) nl*n2/n3 1 + ( nl - n2 ) Adds 1 1- ( nl - n2 ) Subtracts 1 2* (nl - n2) Multiplies by 2 2 + ( nl - n2 ) Adds 2 2- ( nl — n2 ) Subtracts 2 2/ ( nl - n2 ) Divides by 2 abs ( n -- u ) Absolute value aligned ( nl - n2 ) Round nl up to the next multiple of 4 and ( nl n2 — n3 ) Bitwise logical AND max ( nl n2 - n3 ) n3 is maximum of nl and n2 min ( nl n2 — n3 ) n3 is minimum of nl and n2 mod ( nl n2 — rem ) Remainder of nl /n2 /mod ( nl n2 — rem quot) Remainder, quotient of nl / n2 * /mod ( nl n2 n3 — rem quot ) Remainder, quotient of nl * n2 /n3 negate ( nl - n2 ) Changes the sign of nl not ( nl - n2 ) Bitwise ones complement or ( nl n2 — n3 ) Bitwise logical OR xor ( nl n2 — n3 ) Bitwise exclusive OR Chapter 5: Using Forth Tools Accessing Memory "L " is sometimes printed here in uppercase to avoid confusion with the number one. Accessing Memory The PROM Toolkit provides interactive commands for examining and setting memory. You can use the Toolkit to: □ read and write to any virtual address □ map virtual addresses to physical addresses. Memory operators allow you to read from and write to any desired memory location. All memory addresses shown in the examples that follow are virtual addresses. A variety of 8-bit, 16-bit, and 32-bit operations are provided. In general, a c (character) prefix indicates an 8-bit (one byte) operation; a w (word) prefix indicates a 16-bit (two byte) operation; and an L (longword) prefix indicates a 32-bit (four byte) operation. You can use the commands listed in Figures 5-6,5-7,5-8, and 5-9 on the following pages to access, modify, map, and test memory locations. Except for commands listed in Figure 5-6, most of these are rarely needed. Accessing Memory Chapter 5: Using Forth Tools Figure 5-6. Memory Accessing Commands (continued on next page) Command Stack Diagram Description 0 (adr -- n) Fetches a 32-bit number from adr, must be 16-bit aligned c@ (adr — byte ) Fetches a byte from adr w@ ( adr — word ) Fetches a 16-bit number from adr, must be 16-bit aligned L@ (adr — long ) Fetches a 32-bit number from adr, must be 32-bit aligned i ( n adr — ) Stores a 32-bit number at adr, must be 16-bit aligned c ! ( n adr — ) Stores low byte of n at adr w ! ( n adr — ) Stores a 16-bit number at adr, must be 16-bit aligned L! (n adr --) Stores a 32-bit number at adr, must be 32-bit aligned blank ( adr u - ) Sets u bytes of memory to space (decimal 32) cmove ( adrl adr2 u - ) Copies u bytes from adrl to adr2, starting at lo byte cmove> ( adrl adr2 u --) Copies u bytes from adrl to adr2, starting at high byte comp ( adrl adr2 len - n ) Compare two byte arrays, n = 0 if arrays are identical, n = 1 if first byte that is different is greater in array#l, n = -1 otherwise dump (adrlen --) Displays len bytes of memory starting at adr erase ( adr u — ) Sets u bytes of memory to 0 fill (adr size byte — ) Sets size bytes of memory to byte cf ill ( adr size byte — ) Sets size bytes of memory to byte ( same as fill) wf ill ( adr size word - -) Sets size bytes of memory to 16-bit word, addr 16-bit aligned Lf ill ( adr size long -- ) Sets size bytes of memory to 32-bit long, addr 32-bit aligned move (adrl adr2 u — ) Copies u bytes from adrl to adr2, handles overlap properly ? (adr -) Displays the 32-bit number at adr, must be 16-bit aligned c? (adr —) Displays the byte at adr w? (adr ~ ) Displays the 16-bit number at adr, must be 16-bit aligned L? (adr —) Displays the 32-bit number at adr, must be 32-bit aligned + ! ( n adr --) Adds n to the 32-bit number stored at adr, must be 16-bit aligned 2! ( nl n2 adr--) Stores 2 numbers at adr; n2 at lower address, must be 32-bit aligned Chapter 5: Using Forth Tools Accessing Memory Figure 5-6. Memory Accessing Commands (continued) Command Stack Diagram Description 2@ unaligned-w@ unaligned-L@ unaligned-W ! unaligned-L! ( adr ~ nl n2 ) Fetches 2 numbers from adr; n2 from lower address, must be 32-bit aligned (adr — word ) Fetches a 16-bit number, any alignment (adr — long) Fetches a 32-bit number, any alignment ( word adr — ) Stores a 16-bit number, any alignment (long adr -- ) Stores a 32-bit number, any alignment Figure 5-7. Memory Mapping Commands (continued on next page) Command Stack Diagram Description allocate-dma ( size -- virt) Present in boot PROM versions 1.0 and 1.1. Only supports a single allocation at a time, and should no longer be used. This function is replaced in boot PROM version 1.2 and later with dma-alloc. dma-alloc ( size -- virt) Allocate and map size bytes of available memory in DMA space. Release allocated memory with free-virtual. This word is only available in boot PROM version 1.2 and later. ( phys size -- virt) Assign a virtual address to be used for later mapping ( size — virt) Allocate and map size bytes of available memory, return the virtual address map-sbus ( physoffset size - virt) Map a region of SBus space. Physoffset is the offset for the desired SBus slot - that is, slot#1=200.0000, slot#2=400.0000, slot#3=600.0000. allocate-virtual alloc-mem Accessing Memory Chapter 5: Using Forth Tools Figure 5-7. Memory Mapping Commands (continued) Command Stack Diagram Description memmap ( phys space size -- virt) Map a region of physical addresses, return the allocated virtual address. The region is unmapped with free-virtual. This word is only available for boot PROM version 1.2 and later. free-dma ( virt size -- ) Free memory allocated by allocate-dma. Present in boot PROM versions 1.0 and 1.1. Only supports a single allocation at a time. These two words are obsolete for boot PROM version 1.2 and later. free-virtual ( virt size --) Undo mappings created with map-sbus, allocate- virtual, memmap, or dma-alloc free-mem ( virt size — ) Free memory allocated by alloc-mem map? ( virt - ) Display memory map information for the virtual address cprobe ( adr -- flag ) Test for data exception using c@ wprobe (adr-- flag ) Test for data exception using w@ Lprobe ( adr -- flag ) Test for data exception using L@ The SBus slot offsets for SPARCstations 1 and 1+ are: □ SBus slot #0-0 (internal slot) □ SBus slot #1 - 200.0000 □ SBus slot #2 - 400.0000 □ SBus slot #3 - 600.0000 Figure 5-8 lists memory mapping primitives to control page and segment maps. These commands are rarely needed. Chapter 5: Using Forth Tools Accessing Memory Figure 5-8. Memory Mapping Primitives Command Stack Diagram Description obio (— space) Specify the device address space for mapping obmem (— space) Specify the onboard memory address space for mapping sbus (— space) Specify the sbus address space for mapping allocate-physical ( size — phys ) Return physical address of some available memory free-physical ( phys size -- ) Free memory allocated by allocate- physical map-page ( phys space virt — ) Map one page (4K) of memory starting at address phys onto virtual address virt in the given address space space. All addresses are truncated to lie on a page boundary map-pages ( phys space virt size — ) Perform consecutive map-pages to map a region of memory to the given size pgmap! ( pmentry virt --) Store a new page map entry for the virtual address pgmap@ ( virt - pmentry ) Return the page map entry for the virtual address pagesize (— size) Return the size of a page, 4K ( hex 1000) segmentsize (— size) Return the size of a segment, 256K (hex 40000) smap! ( smentry virt — ) Store a new segment map entry for the virtual address smap@ ( virt — smentry ) Return the segment map entry for the virtual address smap? ( virt - ) Formatted display of the segment map entry for the virtual address map-segments ( smentry virt len - ) Consecutive smap! s to map a region of memory Accessing Memory Chapter 5: Using Forth Tools Figure 5-9 lists commands to access alternate address space. Figure 5-9. Alternate Address Space Accessing Commands Command Stack Diagram Description spacec ! (byte adr asi —) Store the byte into the given asi and address spacew! (byte adr asi — ) Store the 16-bit word into the given asi and address spaceL! (byte adr asi --) Store the 32-bit word into the given asi and address spacecG ( adr asi — byte ) Fetch the byte from the given asi and address spacew@ (adr asi - word ) Fetch the 16-bit word from the given asi and address spaceL@ ( adr asi — longword ) Fetch the 32-bit word from the given asi and address spacec? ( adr asi -- ) Display the byte at the given asi and address spacew? ( adr asi — ) Display the 16-bit word at the given asi and address spaceL? (adr asi --) Display the 32-bit word at the given asi and address Some useful values for asi are: 2 System space (onboard devices) 8 User instruction space 9 Supervisor instruction space 10 User data space 11 Supervisor data space. Chapter 5: Using Forth Tools Examples Examples ok 10000 20 dump lllltll^ 12 3 10000 05 75 6e 74 10010 ce da 00 00 ok 22 10004 c! ok 123 10006 w! ok 10004 L@ . 226c0123 ok The following examples show how you might use the Toolkit for memory mapping and testing operations. The dump command is particularly useful. It displays a region of memory as both bytes and ASCII values. The following example displays the contents of 20 bytes of memory starting at virtual address 10000. This example also demonstrates reading from and writing to a memory location. Display 20 bytes of memory starting at virtual address 10000 4 5 6 7 8 9 a b c d e f vl23456789abcdef 69 6c 00 40 4e d4 00 00 da 18 00 00 . until. @NT. . Z .... f4 f4 00 00 fe dc 00 00 d3 0c 00 00 NZ..tt..~\..S. . . Change 8-bit byte at location 10004 to 22 Change 16-bit word at location 10006 to 0123 Retrieve and display 32-bit longword at location 10004 If you try to access (with @ for example) an invalid memory location, the operation will immediately abort and the PROM will display an error message, such as Data Access Exception or Bus Error. To test if a location is valid or to write a loop to repeatedly access a location known to generate an exception, you will need the cprobe command. ok fOOOOOOO c@ Data Access Exception ok fOOOOOOO cprobe 0 False (0) indicates error ok : Examples Chapter 5: Using Forth Tools The Toolkit ignores decimal points in numbers. In the following example, decimal points are inserted in numbers to help count zeros. ok ok ok ok ok ok ok ok ok ok ok 4000 alloc-mem . ffec21e0 ffec2leO 4000 free-mem 200.0000 4000 map-sbus constant slotl slotl 100 dump (memory dump of FCode 5000 1000 55 fill Allocate 4000 bytes of memory and display the starting address of the area reserved Return the 4000 bytes of memory at ffec21e0 Map in addresses on an SBus device in slot #1* and create a name for the virtual address that is generated PROM - not shown) Fill in a region of memory 5000-6000 with a fixed pattern The SBus slot offsets for SPARCstations 1 and 1+ are: □ SBus slot #0-0 (internal slot) □ SBus slot #1 - 200.0000 □ SBus slot #2 - 400.0000 □ SBus slot #3 - 600.0000 $ % F F I F r I t r * f F F r !l F I t I I I % t 48 Chapter 5: Using Forth Tools Using Defining Words ) I i The following examples describe how to use the map-page and map-pages commands. Map one page of on-board memory starting at physical address 80.0000 to virtual address 700.0000 ok 80.0000 obmem 700.0000 map-page Map one page of on-board I/O space at address 80.0000 to virtual address 700.0000 ok 80.0000 obio 700.0000 map-page Map multiple pages of on-board memory starting at physical address 80.0000 to virtual address 700.0000 until 4.0000 bytes of memory are mapped ok 80.0000 obmem 700.0000 4.0000 Using Defining The defining word variable assigns a name to a 32-bit Words region of memory which you can use to hold values as needed. Later execution of that name leaves the address of the memory on the stack. Typically, @ and ! are used to read or write at that address. For example: Although variables are fully supported, we encourage you to use values (described next). 49 Chapter 5: Using Forth Tools The defining word value allows you to assign a name to any number. Later execution of that name leaves the assigned value on the stack. The following example assigns a value of 22 to a word named f oo, and then calls f oo to use its assigned value in an arithmetic operation. ok 22 value foo ok foo 3 + . 25 ok The value can be changed with the dictionary compiling word is. For example: Commands created with value are convenient, since you do not have to use the @ every time you want the number. This is more consistent with most other commands, whose execution leaves the desired result directly on the stack. You can use the defining word constant like value, but only to create a name whose value will not change. A simple colon definition : foo 22 ; accomplishes a similar result. Chapter 5: Using Forth Tools Using Defining Words The defining word defer allows you to change the execution of previously defined commands, by creating a slot which can be loaded with different behaviors at different times. For example: Figure 5-10 lists the defining words that you can use for creating dictionary entries. Figure 5-10. Defining Words Command Stack Diagram Description : name (-> Start the creation of a new colon definition r (-> Finish the creation of a new colon definition alias new-name old-name (-> Create a new name with the same behavior as old-name buffer: name (size --) Create a named array in temporary storage constant name (n~) Define a constant (example: 3 constant bar) 2constant name ( nl n2 - ) Define a 2-number constant create name (-) Generic defining word defer name (-) Defining word for forward references or execution vectors using code field address does> (-- adr) Start the run-time clause for defining words variable name (-) Define a variable value name (n~) Create a changeable named constant 51 Searching the Dictionary Chapter 5: Using Forth Tools Searching the Dictionary The dictionary lists all available Forth commands. This section describes some useful tools you can use to search the dictionary. The command words displays all word (command) names in the dictionary, starting with the most recent definitions. The command see, used in the form see thisxvord, will decompile the specified command ( thisword ). This means that it shows the definition used to create that command word. Figure 5-11 lists the commands you can use to search the contents of the dictionary. Figure 5-11. Dictionary Searching Commands Command Stack Diagram Description ' name ( - acf) Finds a word in the dictionary. Returns the code field address. Use outside of definitions ['] name (~ acf) Acts similar to ' but is used inside of definitions find ( pstr — acf n ) Searches for a word in the dictionary. The word to be found is indicated by pstr. n is 0 if not found, 1 if immediate, -1 otherwise words (-) Displays all visible words in the dictionary see name (-) Decompiles the named word* (see) (acf-) Decompiles the word indicated by the code field address* ’'The decompiled definition may sometimes be confusing, because some internal names may have been omitted from the PROM's symbol table to save space. 52 Chapter 5: Using Forth Tools Compiling into The Dictionary Compiling into The Dictionary These commands compile data into the dictionary. Most of these are not normally needed. Figure 5-12 lists these commands. Figure 5-12. Dictionary Compiling Commands Command Stack Diagram Description r (n-) Place a number in the dictionary c. (n~) Place a byte in the dictionary w. ( w — ) Place a 16-bit word in the dictionary L, (n~) Place a 32-bit number in the dictionary t (-) Begin interpreting i (-) Begin compilation allot (n~) Allocate n bytes in the dictionary compile (--) Compile next word at run time [compile] name (-) Compile the next (immediate) word forget name (-) Remove word from dictionary and all subsequent words here (- adr) Address of top of dictionary immediate (-) Mark the last definition as immediate is name (acf —) Install a new action in a defer word or value literal (n~) Compile a number state (- adr) Variable that is nonzero in compile state npatch word-to-patch ( new-n old-n --) Replace first old-n with new-n in the word word-to-patch . Note that the values 0,1, 2, and 3 are actually defined as words, not numbers. Use patch. patch new-word old-word word-to-patch (-) Replace first old-word with new-word in word-to-patch. (patch ( new-n old-n acf — ) Replace first old-n with new-n in word indicated by acf. 53 controlling t ext Input and Output Chapter 5: Using Forth Tools Controlling Text Input and Output This section describes text input and output commands, which are listed in Figures 5-13,5-14, and 5-15. These commands control strings or character arrays, and allow you to enter comments and control keyboard scanning. Comments are used with Forth source code (generally in a text file) to describe the function of the code. The ( (open parenthesis) is a command that begins a comment. Any character up until the closing parenthesis ) is ignored by the Forth interpreter. Remember to follow the ( with a space, so it will be recognized. Stack effect diagrams are one example of comments using (. The \ (backslash) also indicates a comment, terminated by the end of the line of text. The key? command looks at the keyboard to see whether the user has recently typed any key. It returns a flag on the stack: true if a key has been pressed and false otherwise. See the next section, "Using Conditional Testing" for a discussion of the use of flags. The command key waits for a key to be pressed, then returns the ASCII value of that key on the stack. The command ascii, used in the form ascii x, returns on the stack the numerical ASCII code of the letter following. The emit command displays the letter whose ASCII value is on the stack. For example: ok ascii a 61 ok 42 61 42 ok emit emit Ba ' ok Chapter 5: Using Forth Tools Controlling Text Input and Output The cr command sends a carriage-return to the output. For example: ok 3 . 44 . cr 5 . 3 44 5 ok The . " command used in the form . " string " outputs text when needed. This command only works inside of a definition. A " (double quotation mark) is used to mark the end of the text string. For example: ok : testing 34 . ." This is a test" 55 . ; ok.. ok testing 34 This is a test55 ok Finally, some string commands specify an address (the location in memory where the characters reside) and a length (how many characters). Other commands use a packed string or pstr, which is a location in memory containing a byte for the length, immediately followed by the characters. The stack effect comment for the command will indicate which form is used. The count command converts a packed string to an address-length string. 55 Interpreting Source Code Chapter 5: Using Forth Tools Interpreting The command eval takes a string off of the stack Source Code (specified as an address and a length). That string is then interpreted, just as if those characters were entered from the keyboard. If a Forth text file has been loaded into memory (for example, with dload. See "Downloading Files" in Chapter 6), then eval can be used to compile whatever definitions were contained in the file. Figures 5-13, 5-14, and 5-15 list commands to control text input and keyboard scanning, text output display, and strings or character arrays. Figure 5-13. Inputting Text Command Stack Diagram Description ( ccc ) (--) Begin a comment \ rest-of-line (--) Skip the rest of the line key (— char ) Read a character from the keyboard key? (- flag) True if a key has been typed on the keyboard ascii ccc (— char) Numerical value of first ascii character of next word bl (- n) The ASCII code for the space character; decimal 32 1 ft fc fc t l! fc fc fc fc fc fc fc fc fc" fc fc fc fc fc fc fc” fc fc 56 £9 Chapter 5: Using Forth Tools Interpreting Source Code Figure 5-14. Displaying Text Output Command Stack Diagram Description cr (-) Terminates a line on the display and go to the next line emit (char —) Displays the character exit? (-flag) True if the user wants the output to be terminated. This command enables the scrolling control prompt: More [ / / q] ? space (-) Displays a space character spaces (+n -) Displays +n spaces Figure 5-15. Manipulating Text Strings Command Stack Diagram Description 11 CCC” ( — adr len ) Collect an input stream string, either interpreted or compiled . " CCC” (-) Compile a string for later display . ( CCC) (-) Display a string immediately eval ( adr len --) Interpret Forth source from an array p" CCC” (- pstr) Collect a string from the input stream, store as a packed string type ( adr +n - ) Displays characters count ( pstr - adr +n ) Unpack a packed string -trailing ( adr +nl — adr +n2 ) Remove trailing spaces 57 Using Conditional Testing Chapter 5: Using Forth Tools Using Conditional Testing Forth conditionals use flags to indicate true/false values. A flag can be generated in any number of ways based on some criteria for testing. The flag can then simply be displayed off of the stack with the word . or can be used as an input to a conditional control command. Control commands can cause one behavior if a flag is true, and another behavior if the flag is false. Thus, execution can be altered based on the result of a test. A 0 value indicates the flag value is false. A -1 (or any other nonzero number) indicates the flag value is true. In hexadecimal, the value -1 is displayed as f f f f f f f f. For example, the > command takes two numbers off of the stack, and returns true (-1) on the stack if the first number was greater than the second number, or returns false (0) otherwise. For example: ok 3 6 > . 0 3 is not greater than 6 ok The 0= command takes one number off of the stack, and returns true if that number was 0, or returns false otherwise. This word inverts any flag to its opposite value. i; r i i i I i» B fa fa t? fe fc fL £ P K 58 %# Chapter 5: Using Forth Tools Using Conditional Testing Figure 5-16 lists commands that perform relational tests, and leave a true or false flag result on the stack. Figure 5-16. Comparison Commands Command Stack Diagram Description 0< (n - flag ) True if n < 0 0<= ( n -- flag ) True if n < = 0 0<> ( n -- flag ) True if n <> 0 0= ( n -- flag ) True if n = 0 (also inverts any flag) 0> ( n - flag ) True if n > 0 0>= ( n - flag ) True if n > = 0 < ( nl n2 — flag ) True if nl < n2 <= ( nl n2 — flag ) True if nl <= n2 <> ( nl n2 — flag ) True if nl <> n2 = ( nl n2 — flag ) True if nl = n2 > ( nl n2 -- flag ) True if nl > n2 >= ( nl n2 — flag ) True if nl >= n2 between ( n min max — flag ) True if min <= n <= max false (--0) The value FALSE, which is 0 true (- -1 ) The value TRUE, which is -1 u< (ill u2 -- flag ) True if ul < u2 , unsigned u<= ( ul u2 -- flag ) True if ul <= u2, unsigned u> ( ul u2 -- flag ) True if ul > u2, unsigned u>= ( ul u2 — flag ) True if ul > = u2, unsigned within ( n min max — flag ) True if min < = n < max % f ft 59 Controlling Conditional Execution Chapter 5: Using Forth Tools * Controlling Conditional Execution The commands if, else, and then provide a simple if- then-else control structure. The format for using these commands is: M if do this if true else do this if false or then continue normally M if do this if true then continue normally The if consumes a flag off of the stack. If the flag is true (non-zero), the commands just after the if are performed. Otherwise, the commands (if any) just after the else are performed. ok : testit ( n — ) ] 5 > if ." good enough " ] else ." too small " ] then ] . " Done. " ok ok 8 testit good enough Done, ok 2 testit too small Done, ok Note: The ] prompt reminds you that you are part way through creating a new colon definition. It reverts back to ok after you finish the definition with a semicolon. I J i t U- • 6 fc. fe: fe fe fe fe fe fe fe fe fe fe fe fe- 60 u The commands listed in Figure 5-17 control the flow of conditional execution. Figure 5-17. Conditional Program Execution Commands Command Stack Diagram Description else (-) Execute the following code if if failed if (flag -) Execute following code if flag is true then (--) Terminate if. . .else. . .then Using Conditional Loops Conditional loops execute the same commands repeatedly until a certain condition is satisfied. There are two general forms: begin and any commands... flag until begin any commands... flag while more commands repeat In both cases, the commands within the loop will be executed repeatedly until the proper flag value causes the loop to be terminated. Once terminated, execution continues normally with the next command after the closing command word (until or repeat). In the begin. . . until case, the until command removes a flag from the top of the stack and inspects it. If the flag is false, execution continues just after the begin and the loop repeats. If the flag is true, the loop is exited. In the begin . . . while . . . repeat case, the while command removes a flag from the top of the stack and inspects it. If the flag is true, the loop continues by executing the commands just after the while. The repeat command automatically sends control back to the begin to continue the loop. If the flag is false when while is encountered, then the loop is exited immediately. Control goes to the first command after the closing repeat. 61 Using Conditional Loops Chapter 5: Using Forth Tools The following is a simple example: ok begin 4000 c@ . key? until repeat until any key is pressed 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 ok The loop starts by fetching a byte from location 4000 and displaying the value. Then, the key? command is called, which leaves a true on the stack if the user has pressed any key, false otherwise. This flag is consumed by the until and, if the value is false, then the loop continues. Once a key is pressed, the next call to key? returns true and the loop terminates. Unlike many versions of Forth, the Toolkit allows interactive use of loops and conditionals — that is, without first creating a definition. Figure 5-18 lists commands to control the execution of conditional loops. Figure 5-18. Conditional Loop Commands Command Stack Diagram Description again (-> Ends a begin. . . again infinite loop begin (-) Begin a begin. . . while . . . repeat loop or begin...until loop repeat (-> Ends a begin. . . while . . . repeat loop until (flag -) Continues executing a begin. . . until loop until flag is true while (flag --) Continues executing a begin. . . while. . . repeat loop while flag Chapter 5: Using Forth Tools Using Counted Loops Counted loops, called do loops, are used when the number of iterations of the loop can be calculated in advance. Figure 5-19 lists commands to control the execution of counted loops. Note: A do loop normally exits just before the specified ending value is reached. Figure 5-19. Counted Loop Commands Command Stack Diagram Description do (end start --) Begin a do. . . loop. Index goes from start to end-1 inclusive. Example: 10 0 do i . loop ?do (end start -- ) Begin ?do. . . loop to be executed 0 or more times. Index goes from start to end-1 inclusive. i (~n) Loop index j (~n) Loop index for next enclosing loop leave (-) Exit from do. . . loop ?leave (nag -) Exit from a do. . . loop if flag is non-zero loop (-) End of do...loop Hoop (n~) End a do. . . Hoop construct; adds n to loop index and returns to do (if n < 0, index goes from start to end inclusive). Using Counted Loops Using Counted Loops Chapter 5: Using Forth Tools Several loop examples follow: +loop ok 10 5 do i . loop 567 89abcd e f ok ok 2000 1000 do i . i c@ . cr i c@ ff = if leave then 4 +loop 1000 23 10 04 0 1008 fe 100c 0 1010 78 1014 ff ok : scan ( byte — ) ] 6000 5000 Scan memory (5000-6000 )/< ] do dup i c@ <> ( byte error? ) bytes not equal to the patten ] if i . then ( byte ) ] loop ] drop ( the original byte was still on the stack, discard it ) ( byte error? ) ( byte ) Scan memory (5000-6000) for bytes not equal to the pattern (55) ok 55 scan ok 5005 5224 5f99 ok 6000 5000 do i i c! loop ok 500 value testloc ok : testl6 ( --- ) 1.0000 0 ( do 0-ffff ) ] do i testloc w! testloc w@ i <> ( error? ] if ."Error - wrote " i . ." read " tea ] leave ( exit after first error found ) ] then ] loop Fill a region of memory with a stepped pattern (0-1-2-3-...) Write different 16-bit values to r? ) a location and check. testloc w@ . cr d ) This line is optional ok test!6 ok 6000 is testloc ok test16 ok 64 Chapter 5: Using Forth Tools Using Case Statements A high-level case command is provided for selecting alternatives with multiple possibilities. It is easier to read than deeply nested if-then commands. A simple example follows: ok : testit ( testvalue — ) ] case 0 of ." It was zero " endof ] 1 of ." It was one " endof ] ff of Correct " endof ] -2 of " It was minus-two " endof ] (default ) .” It was this value: " dup ♦ ] endcase ." All done." ; ok ok 1 testit It was one All done, ok ff testit Correct All done, ok' 4 testit It was this value: 4 All done. ok Note: The (optional) default clause can use the test value which is still on the stack, but should not remove it (use the dup . phrase instead of .). A successful of clause automatically removes the test value from the stack. Figure 5-20 on the next page lists the conditional case statement commands you can use. Figure 5-20. Case Statement Commands Command Stack Diagram Description case ( selector -- selector ) Begins a case. . . endcase conditional endcase (selector --) Terminates a case. . . endcase conditional endof (-) Terminates an of. . . endof clause withing a case...endcase of (selector test-value - selector 1 {empty} Begins an of. . . endof clause within a case conditional Using Case Statements 65 Additional Control Commands Chapter 5: Using Forth Tools Additional Control The abort command causes immediate termination and Commands returns control to the keyboard, abort" is similar to abort but is different in two respects, abort" removes a flag from the stack and only aborts if the flag is true. Also, abort" prints any desired message when the abort takes place. Figure 5-21 contains descriptions of the various program execution control commands. Figure 5-21. Program Execution Control Commands Command Stack Diagram Description abort (-> Abort current execution and interpret keyboard commands abort” ccc" (flag -) If flag is true, abort and display message execute (acf --) Execute the word whose code field address is on the stack exit (--) Return from the current word quit (-) Abort, but leave stack intact Chapter 5: Using Forth Tools Using the Disassembler The PROM's built-in disassembler translates the contents of memory into equivalent SPARC assembly language. The di s command will begin to disassemble the data content of any desired location. A pause occurs if any key is pressed while disassembly is taking place or after every page of output. At that point, disassembly might be continued or stopped. Disassembly stops automatically when a call or jmp opcode is encountered. You can use the +dis command to continue disassembling at the location where the last disassembly stopped. Memory addresses are normally shown in hex. However, if a symbol table is present, memory addresses will be displayed symbolically whenever possible. Figure 5-22 lists commands that disassemble memory into equivalent opcodes. Figure 5-22. Disassembler Commands Command Stack Diagram Description dis (addr —) Begin disassembling at the given address +dis ( -) Continue disassembling where the last disassembly left off Using the Disassembler i I 67 Displaying Registers Chapter 5: Using Forth Tools Displaying Registers You can enter the Toolkit from the middle of an executing program as a result of a program crash, a user abort with Ili-aI . or an encountered breakpoint (breakpoints are discussed in the next section). In all these cases, the Toolkit automatically saves all of the CPU data register values into a buffer area. These values can then be inspected for debugging purposes. After inspection, program execution can be continued by entering the go command. The saved register values are copied back into the CPU, and then execution resumes (at the location specified by the saved %pc). These saved register values can be changed, if desired, by using the to command. When execution is resumed, the changed values will be copied back into the CPU and used. If you change %pc with the to command, you should also change %npc. It is easier to use set-pc, which changes both registers automatically. For the w and . window commands, a window value of 0 usually specifies the current window — that is, the active window for the subroutine where the program was interrupted. A value of 1 specifies the window for the caller of this subroutine, and 2 specifies the caller's caller, and so on, up to the number of active stack frames. The default starting value is 0. Note: In some earlier versions of the Open Boot PROM, floating-point registers can only be read, but not written. In these versions, the command save-f regs must be executed before you can read floating-point registers. Floating-point registers are not supported in some boot PROMs. Chapter 5: Using Forth Tools Displaying Registers Figure 5-23 lists the SPARC register reading and writing commands. Figure 5-23. SPARC Register Commands Command Stack Diagram Description %g0 through %g7 (— value) %o0 through %o7 (— value) %L0 through %L7 (— value) %i0 through %i7 (— value) %pc %npc %psr (-- value) %y %wim %tbr (— value) % f 0 through %f 31 (— value) %f sr (— value) to regname (value --) set-pc (value —) w (window# ctrace (--) .locals (-) .psr (-) .registers (--) Return the value in the given register Return the value in the given register Return the value in the given register Return the value in the given register Return the value in the given register Return the value in the given register Return the value in the given floating point register Return the value in the given floating point register Change the value stored in any of the above registers Use in the form: value to regname Set %pc to the given value, and set %npc to (value+4) Set the current window, for displaying %ix %lx or %ox Display the return stack showing C subroutines Display the values in the i, L and o registers Formatted display of the %psr data Display values in %g0 through %g7, plus %pc, %npc, %psr, %y, %wim, %tbr Using Breakpoints Chapter 5: Using Forth Tools Using Breakpoints Standalone programs do not run under the SunOS Operating System. Typical programs running under the SunOS Operating System do not normally use this feature, but use other debuggers designed to run under theSunOS Operating System. The Toolkit provides a robust breakpoint capability to assist in the development and debugging of standalone programs. The breakpoint feature lets you pause execution of the test program at any desired point(s). After execution has stopped, registers or memory can be inspected and/or changed, and new breakpoints can be set or cleared. Then, execution can be resumed with the go command. To debug a program using breakpoints: 1. Load the test program into memory at location 4000 (hex). See "Downloading Files" in Chapter 6 for more information. Using dload is generally best, since the symbol table for the program is preserved, boot -h also works if the program is not available over Ethernet. The values for %pc and all other registers will be initialized automatically. 2. Disassemble the downloaded program, if desired, to verify a properly downloaded file. 3. At this point you can begin single-stepping the test program using the step command. Or you can set a breakpoint(s) and then execute (for example, using the commands 4 020 +bp and go), or perform other variations. Chapter 5: Using Forth Tools Using Breakpoints Figure 5-24 lists the breakpoint commands that control and monitor program execution. Figure 5-24. Breakpoint Commands Command Stack Diagram Description go (-) Continue the execution of a halted program .bp (-> Display all curently set breakpoints +bp (addr —) Add a breakpoint at the given address -bp (addr —) Remove the breakpoint at the given address —bp (-> Remove the most recently set breakpoint bpof f (-> Remove all breakpoints step (-> Single-step one instruction steps (n~) Execute n steps hop (-) Like the step command, but treats a subroutine call as a single instruction hops (n~) Execute n hops skip (-) Skip (do not execute) the current instruction till (addr -) Executes until the given address is encountered; equivalent to +bp go return (--) Execute until the end of this subroutine return!. (-) Execute until the end of this leaf subroutine finish-loop (--) Execute until the end of this loop .instruction (-) Display the address, opcode for the last encountered breakpoint .breakpoint (-) Defer word, for display behavior after every breakpoint. Default is .instruction. Change with: ' .registers is .breakpoint ( I I 71 Using Breakpoints Chapter 5: Using Forth Tools The examples shown in this chapter illustrate some of the tools available to you through the boot PROM's Toolkit interface. If you require more information about Forth, consult some of the previously cited reference books. 6 Using Machine Functions This chapter provides machine-specific information about how to control your system using the Open Boot PROM's Forth Toolkit. The machine functions described in this chapter allow you to perform the following tasks: □ Resetting the system □ Running the diagnostics □ Displaying system information □ Booting from the ok prompt □ Redirecting input and output □ Setting up a tip window □ Downloading files □ Ejecting a floppy diskette □ Preserving data after a system crash. The procedures in this chapter assume that you have started the Sun-Compatible Monitor, and have entered the Forth Toolkit. This chapter also assumes that you have read Chapter 4 and are familiar with the Forth Toolkit interface. 73 Resetting the System Chapter 6: Using Machine Functions Resetting the System Occasionally you will find it necessary to reset the system. The reset command, listed in Figure 6-1, resets the system without actually having to turn the power off and on. To reset the system, type: ok reset The power-on self-test and initialization procedure begin immediately. This system reset is very similar to a power cycle. All Forth definitions you entered are forgotten. Figure 6-1. System Resetting Commands Command Stack Diagram Description reset (--) Resets the entire system (very similar to power-cycle) Chapter 6: Using Machine Functions Diagnostic Routines Diagnostic Several diagnostic routines are available through the Routines Toolkit. These on-board tests allow you to test the control registers, the network controller, the floppy disk system, memory, the cache, and the system clock. Figure 6-2 lists commands to perform diagnostic tests. Figure 6-2. Diagnostic Test Commands Command Stack Diagram Description probe-scsi (-) Determine the attached SCSI devices test-control-regs (-> Test registers (context, sync, sync virt, async, async virt, enable) test-net (--) Test Lance Ethernet controller with internal & external loopback test-cache (-) Test cache data and tag fields test-memory (-) Test main memory (number of megabytes indicated in NVRAM configuration parameter self test-#megs). If the diag-switch? NVRAM configuration parameter is set to true, all of memory is tested. test-floppy (-) Test the floppy drive watch-clock (--> Test the clock function \ I I 75 Testing Control Registers Chapter 6: Using Machine Functions Testing Control Registers Control registers reside in hardware on the main-logic board on the SPARCstation 1. The registers that are tested include the context register, the synchronous error register, the synchronous error virtual address register, the asynchronous error register, the asynchronous error virtual address register and the enable register. Other machines might have a different set of control registers. To test control registers, type: ok test-control-regs ok If the system fails this test, a message appears on the screen. If the system passes this test, the system displays the ok prompt. Testing The Ethernet Controller To test the on-board Ethernet controller, type: ok test-net Internal Loopback test - (result) External Loopback test - (result) ok The system responds with a testing message that indicates the result of the test. Chapter 6: Using Machine Functions Testing the Diskette Drive Testing The Diskette Drive The diskette drive test determines whether the diskette drive is functioning properly. A formatted (HD) disk must be inserted into the diskette drive for this test to complete successfully. To test the diskette drive system, type: ok test-floppy Testing the floppy disk system. A formatted disk should be in the drive. It appears to be okay, ok If the test fails, you will see an error message. Eject the diskette by typing eject-floppy at the ok prompt. Testing Memory When you use the memory testing routine, the system will test the number of megabytes specified in NVRAM parameter self test-#megs. One megabyte of memory is tested as the default. When the diagnostic switch NVRAM parameter diag-switch? is enabled, all memory is tested. To test memory, type: ok test-memory There will be a delay while the PROM tests the system before the prompt returns to the display ok If the system fails this test, you will see an error message. Otherwise, the ok prompt returns to the display. ( i i I I 77 i esnng (^acne Chapter 6: Using Machine Functions Testing Cache Testing The Clock The cache test routine exercises the cache buffers. To test the cache, type: ok test-cache There mil be a delay while the PROM tests the system before the prompt returns to the display ok If the system fails this test you will see an error message. Otherwise, the ok prompt returns to the display. To test the clock function, type: ok watch-clock Watching the 'seconds' register of the real time clock chip. - It should be ticking once a second. Type any key to stop. 1 Press any key to stop test ok The system responds by incrementing a number once a second. Press any key to return to the ok prompt. Chapter 6: Using Machine Functions Displaying System Information Displaying System Information The Toolkit provides several commands you can use to display pertinent system information. These commands, listed in Figure 6-3, allow you to display the system banner, the Ethernet address for the Ethernet controller, the contents of the IDPROM, and the version number of the PROM. The IDPROM contains information specific to each individual machine, including the serial number, date, and Ethernet address assigned to the machine. Figure 6-3. System Information Display Commands Command Stack Diagram Description banner (-> Displays power-on banner .enet-addr (-) Displays the current Ethernet address .idprom (-> Displays IDPROM contents, formatted .version (-) Display the version and date of boot PROM .traps (~) Display a list of SPARC trap types Booting the System From the Toolkit Prompt The boot command loads the SunOS Operating System kernel or another executable program into memory, and executes that program when the program load completes. All booting operations function the same, whether you are in the Sun-Compatible Monitor or in the Forth Toolkit. The only difference is that you must type out the entire word boot (followed by a space when using any command options) when you are in the Toolkit. To boot your system from the ok prompt, type the boot command using the standard boot syntax. See Chapter 3 for information about booting. 79 ^uuyia v. using iviucmne tunctions rr Input, Output, and Display Modes Redirecting Input and Output Normally, your system uses a standard Sun keyboard for all user input, and a frame buffer with a connected display screen for most display output. It is possible to redirect the input or output, or both, to either one of the system's serial ports. This might be useful, for example, when debugging a frame buffer. See your system's Installation Guide for information about connecting a terminal to the system unit. The commands input and output change the current sources of input and output. The change takes place immediately without a system reset. The input command must be preceded by one of the following: keyboard, ttya, or ttyb. For example, if input is currently accepted from the keyboard, and you wish to make a change so that input is accepted from a terminal connected to the serial port ttya, type: ok ttya input ok At this point, the Sun keyboard will be non-functional (except for [li-a] ). but any text entered from the terminal connected to ttya will be processed as input. All commands will be executed as usual. To resume using the keyboard as the input device, type from the terminal keyboard: ok keyboard input ok r F- F L L L i t l: fc: fc; fe, fc: fc: fe: E '! * 80 •inrinif Chapter 6: Using Machine Functions Redirecting Input and Output Note that either screen io or keyboard io is equivalent to keyboard input plus screen output. Similarly, the output command must be preceded by one of the following: screen, ttya, or ttyb. If you wish to send output to ttya instead of the normal display screen, type: ok ttya output The screen will not show the answering ok prompt, but the terminal connected to ttya will show the ok prompt, and all further output as well. The command io is used in the same way, except that it changes both the input and output to the specified place. The commands input, output, and io have a temporary effect only. A system reset or power cycle causes the input and output sources to revert back to the default settings specified in the configuration parameters. The NVRAM parameters input-device and output-device control the default input and output sources, and can be changed if desired. See "Changing a Parameter's Value" in Chapter 7 for information about changing defaults. The standard baud rate and digital signal transmission settings for both ttya and ttyb are: 9600 baud, 8 data bits, 1 stop bit, no parity, and no handshaking. These settings can be changed if desired, using the ttya-mode and ttyb- mode NVRAM parameters. Emergency Procedure Chapter 6: Using Machine Functions M Emergency Procedure There is also an emergency procedure, in case a specified input source is unavailable. For example, suppose you typed ttya io and then discovered that your terminal connected to ttya has the wrong baud rate and cannot be easily changed. Or worse, suppose you set the NVRAM parameters incorrectly, so that even a power cycle leaves you without a usable source of input. Even when the Sun keyboard is inactive (because the serial port is being used for input), the Ili-aI key combination from the Sun keyboard will still be detected. When Ili-aI is pressed, the system resets the input source back from the current setting and accepts input to the keyboard. Note: Ili-aI does not change the output source. If output is incorrect, then you might also need to restore the output to the screen connection by typing screen output and pressing [Return l . Characters are not echoed as you type. If you make a mistake, error messages are not displayed. If this procedure does not work correctly, you might need to type n and press I Return I to enter the Toolkit, and then type screen output and press I Return 1 . Figure 6-4 lists commands you can use to redirect input and output. Figure 6-4. Input, Output, and Display Commands Command Stack Diagram Description input (source —) Select source for subsequent input (ttya, ttyb, or keyboard) output (source —) Select source for subsequent output (ttya, ttyb, or screen) io (source —) Select source for subsequent input and output [Li-Al (from keyboard) (-) Redirect input to come from keyboard I! r v i l r l t E t fc t fc fc fc' fe h fc £ t! Chapter 6: Using Machine Functions Setting Up a tip Connection Setting Up a tip Connection You can use the ttya or ttyb ports on your SPARC system to connect to another Sun Workstation (either the same type of SPARC system or a different type of Sun Workstation or server system). This connection allows you to use a shell window on the Sun Workstation as a terminal to your SPARC system being tested. See the on¬ line tip man-page documentation for detailed information about terminal connection to a remote host. We highly recommend the tip method, since it allows you to use the SunOS Operating System windowing and operating system features to assist you in your interactions with the boot PROM. The SunOS Operating System must first be loaded. A communications program or another non-Sun computer can be used in the same way, if the program can keep up with the output baud rate used by the PROM tty port. A simple setup procedure follows. To set up a tip connection: 1. Connect the Sun Workstation (ttyb serial port) to your SPARC system ttya serial port using a serial connection cable. This connection is made with a 3-wire Null Modem Cable. Connect wires 3-2, 2-3, and 7-7. Refer to your Installation Guide for specifications on null modem cables. 2. At the Sun Workstation, add the following lines to the file / etc/remote: hardwire:\ :dv=/dev/ttyb:br#9600:el= A C A S A Q A U A D:ie=%$:oe= A D: 83 Ljisil M. Ll-fS V^l//KU,CUU/i. U. i VJ.C4.Cst CJICCs J CClCCs d i-JUtcO 3. In a shell window on the Sun Workstation, type tip hardwire and press I Return ) . The system will reply, connected. hostname% tip hardwire connected The shell window is now a tip window directed to the Sun Workstation ttyb. 4. At your SPARC system, start the Sun-Compatible Monitor and enter the Toolkit. You see the ok prompt. Note: When you do not have a video monitor attached to your SPARC system unit, connect the SPARC system unit to the Sun Workstation and turn the power on to your SPARC system. Wait 10 or 15 seconds and press Ili-aI to interrupt the power-up sequence and start the Monitor. Type n and press l Return l . Unless the system is totally inoperable, the Toolkit is open and you can continue with the next step in this procedure. 5. To redirect the standard input and output to ttya, if needed, type ttya io and press [Return ) . ok ttya io No echoed response £ £ £ £ £ £ £ £ £ £ £ £ £ £ £ £ £ £ £ £ £ £ fc 4 84 Chapter b: Using Machine functions Ending the tip Session Ending the tip Session 6. Press 1 Return I on the Sun workstation keyboard. The ok prompt appears in the tip window. Caution: Do not type an Ili-a] from a Sun Workstation being used as a tip window to your SPARC system. Doing so will abort the SunOS Operating System on the Sun Workstation. If you forget and accidentally do so, you can recover by immediately typing the letter c then pressing 1 Return 1 . When you are finished using the tip window, you need to end your tip session and exit the tip window. To end the tip session: 1. Redirect the input and output to the screen and keyboard, if needed. 2. In the tip window, type the ~. command. 3. The tip window session is closed, and you see the host prompt. ok hostname% Note: When entering ~ commands in the tip window, the ~ (tilde character) must be the first character entered on the line. When in doubt, press I Return l first. 85 Common Problems With tip Lhapter b: Using Machine functions Common Problems With tip Common problems with tip might occur if: 1. The lock directory is missing or incorrect. There must be a directory /usr/spool/uucp. The owner must be uucp and the group must be staff. The mode is drwxr-sr-x. 2. ttyb is not enabled for logins. The status field for ttyb (or the serial port you are using) must be set to of f in /etc/ttytab. Be sure to execute kill -HUP 1 (see init(8)) as root if you have to change this entry. 3. /dev/ttyb is inaccessible. Sometimes, a program will have changed the protection of /dev/ttyb (or the serial port you are using) so that it is no longer accessible. Make sure that /dev/ttyb has the mode set to crw-rw-rw-. 4. The serial line is in tandem mode. If the tip connection is in tandem mode, the operating system will sometimes send XON (aS) characters, particularly when programs in other windows are generating lots of output. The XON characters will be detected by the Forth key? word, and can cause confusion. The solution is to turn off tandem mode with the t ip command ~s ! tandem. Chapter 6: Using Machine Functions Downloading Text Files Over a Serial Line Downloading Text Files Over a Serial Line File downloading commands allow you to download and interpret a Forth text file over a serial connection made between your SPARC system and a Sun Workstation (or another SPARC system the same type as your SPARC system). You can also download Forth or binary files over an Ethernet connection, or from a locally-attached diskette or the SCSI disk drive. To download a Forth text file over a serial connection, you must have a Sun Workstation connected to a serial port on your SPARC system. The Sun Workstation must have a tip window connection set up. The following procedure assumes that you have made the serial connection described in "Setting up a tip Connection" earlier in this chapter and that you have a t ip window open on the Sun Workstation. Input and output must be directed to that connection. To download a Forth file from a Sun Workstation to your SPARC system: 1. In the Sun Workstation tip window, type dl and press 1 Return - ) . 2. Type ~C and cat myfile.fth Note: The C must be capitalized. The file will be searched for relative to the current working directory when the tip window was activated. 3. Wait several seconds for download to complete. 87 Downloading Text Files Over a Serial Line Chapter 6: Using Machine Functions 1 i 5. If the requested file is not found, the following message is displayed. •- a n_ n v 6. Type IComroi-d I to return to the ok prompt. ! After the downloading is complete, the contents of the * Forth text file are automatically interpreted. You can download files up to 32K using this method. If you need L to interpret a larger file, break it into pieces and download each piece with a separate dl command. !_ • L L L- L h ok dl ~CLocal command?cat myfile.fth myfile.fth: No such file or directory away for 2 seconds I ok 4. Type 1 Control -d 1 . ok dl -CLocal command? cat myfile.fth away for 2 seconds t A D ok 88 Chapter 6: Using Machine Functions Downloading Binary Files Over a Serial Line Downloading Binary Files Over a Serial Line To download a binary file over a serial connection, you must have a Sun Workstation connected to a serial port on your SPARC system. The Sun Workstation must have a tip window set up. The following procedure assumes that you have made the serial connection explained in "Setting up a tip Connection" earlier in this chapter, and that you have a tip window open on the Sun Workstation. Input and output must be directed to that connection. Note: Before beginning this procedure, you must have the shell script sendbin defined in your directory on the Sun Workstation. If your SunOS version is 3.9 or earlier, create a sendbin script file with these statements: # !/bin/sh sleep 5 >/dev/tty & stty -even -odd litout pass8 cat $1 If your SunOS version is 4.0 or later, create a sendbin script file with these statements: # !/bin/sh sleep 5 >/dev/tty & stty -parenb cs8 raw -echo cat $1 After creating a sendbin script file for your SunOS version, you can download your binary file. Note: You must make your sendbin script executable by typing chmod 111 sendbin at the % prompt. 89 Downloading Binary Files Over a Serial Line Chapter 6: Using Machine Functions To download a binary file from a Sun Workstation to your SPARC system: 1. In the Sun Workstation tip window, type dlbin and press (Return 1 . 2. Type ~C and sendbin myfile.ext and press l Return I . The file will be searched for relative to the current working directory when the tip window was activated. 3. Wait several seconds for download to complete. ok dlbin -CLocal command? sendbin myfile.ext away for 2 seconds t ok 4. If the requested file is not found, the following message is displayed. ok dlbin -CLocal command? sendbin myfile.ext myfile.ext: No such file or directory away for 2 seconds t 5. Type ~# to return to the ok prompt. Your file will be placed in a memory location determined by the a.out header of the downloaded file (usually hex 4000). Type init-program go to execute the downloaded binary file, if desired. If the downloaded file is an FCode binary file, interpret it by typing 4000 1 byte-load at the ok prompt. 90 Chapter 6: Using Machine Functions Downloading Files Over Ethernet Downloading Files Over Ethernet For binary files, dload is superior to other downloading methods, because the symbol table (useful in debugging) is also downloaded automatically. dload uses the tf tp protocol to transfer a file over the network. You must have permission for tf tp to access files on your server. Ask your system administrator to remove the # (pound sign) at the beginning of the line "tf tp..." in the server's file /etc/inetd. conf, and to put in a pound sign before the -s flag (if present). This allows tf tp access to any file. You can download any file over Ethernet with the dload command, dload requires that you specify the address at which you wish to download the file. In general, we recommend storing the file at location 4000, which is a known and well behaved address. The address 4000 is used in the following example. To download and execute a file at address 4000: 1. At the ok prompt type 4 000 dload /path/filename.ext and press l Return I . Specify the full pathname relative to the server's root. 2. If your downloaded file: □ is a binary file, type init-program go to execute that program. □ contains Forth text, type 4 000 file-size @ eval to interpret the file. □ contains FCode binary, type 4000 1 byte-load to interpret the file. You can also download files over Ethernet using boot -h (see next section for information). In this case, specify the filename relative to the client's partition on the server, not relative to the server's root. For example, typing boot net myfile .ext -h at the ok prompt specifies the following pathname: /export/root//myfile.ext 91 Downloading Files from a Hard Disk Chapter 6: Using Machine Functions download and execute a file from your local hard disk: If you are downloading a Forth or FCode file, you must convert the file into an a.out format of the required length. You can use f akeboot, available from the SBus Support Group, to perform the conversion. 2. At the ok prompt type boot disk filename.ext -h and press LBaum .)• This command downloads the file from the root directory /filename . ext of your hard disk. 3. If your downloaded file: □ is a binary file, type init-program go to execute that program. □ contains Forth text and was converted using fakeboot, type 4010 4004 @ eval to interpret the file. □ contains FCode binary and was converted using fakeboot, type 4 030 1 byte-load to interpret the file. Downloading Files To From a Flard Disk l. 92 Chapter 6: Using Machine Functions Downloading Files from a Floppy Disk Downloading Files From a Floppy Disk To download and execute a file from your floppy disk: 1. Build a bootable floppy: □ Use a 1.4MB High-Density (HD) floppy, not a Double-Density (DD) floppy. □ Format floppy. Type /bin/fdformat and press 1 Return I. □ Create a file system on your floppy. Type /usr/etc/newf s /dev/rfdOa and press I Return I . □ Mount your floppy. Type mount /dev/fdOa /mnt and preSS [Return l . □ Copy the /boot program from your local disk or server to the /mnt directory on your system. □ Install a boot block. Type cd /usr/mdec and press l Return I . Then type installboot /mnt/boot bootfd /dev/rfdOa and press [Return 1 . 2. If you are downloading a Forth or FCode file, you must convert the file into an a.out format of the required length. You can use f akeboot, available from the SBus Support Group, to perform the conversion. 3. After converting a Forth or FCode file using the f akeboot program, copy the file to your floppy. Type cp filename.ext /mnt and press I Return I . A file copied into /mnt/f ilename. ext will appear in the root directory / filename . ext on your floppy. 4. At the ok prompt type boot fd() filename.ext -h and press I Return I . This command downloads the file from the root directory / filename .ext of your floppy. 93 Downloading Files from a Floppy Disk Chapter 6: Using Machine Functions 5. If your downloaded file: □ is a binary file, type init-program go to execute that program. □ contains Forth text and was converted using fakeboot, type 4 010 4004 @ eval to interpret the file. □ contains FCode binary and was converted using fakeboot, type 4 030 1 byte-load to interpret the file. Figure 6-5 lists the file downloading commands. Figure 6-5. File Downloading Commands Command Stack Diagram Description boot [specifiers] -h (-> Download file from specified source dl (--) Download a Forth file over a serial line with tip and interpret with: ~C cat filename.fth dlbin (--) Download a binary file over a serial line with tip. Type ~C sendbin filename.fth dload filename (addr -) Load the specified file over Ethernet at the given address go (-) Begin execution of previously loaded program or continue execution of an interrupted program init-program (-) Initialize to execute binary file byte-load (addr1 — ) Interpret downloaded FCode binary. Addr is 4030 for a file converted with fakeboot, but usually 4000 otherwise eval (addr len --) Interpret downloaded Forth text file. Type 4010 4004 @ eval for a file converted with fakeboot, otherwise type 4000 file-size @ eval 94 Chapter 6: Using Machine Functions Ejecting the Floppy Diskette I » I I Ej ecting the Your SPARC system might have two types of locally- FIoddv Diskette attached disk drives: a diskette drive and one or more hard disks. Two basic commands provide disk drive control. The eject-floppy command causes the floppy diskette to be ejected from the diskette drive. If this command fails, you can insert a paper clip into the little hole on the drive and physically eject the diskette. i i i \ \ i Preserving Data After a System Crash The sync command forces any information on its way to the hard disk to be written out immediately. This is useful if the SunOS Operating System has crashed, or has been interrupted without preserving all data first. The sync command actually returns control to the SunOS Operating System, which then performs the data saving operations. After the disk data has been synced, the SunOS Operating System begins to save a core image of the operating system. This core dumping procedure is preceeded by the following message: dumping to vp xxxxxxxx offset xxxxxx If you do not need this core dump, you can interrupt the operation with Ili-aI . Figure 6-6 lists commands to control your disk. Figure 6-6. Disk Control Commands Command Stack Diagram Description eject-floppy (-) Ejects the diskette from the floppy drive sync (-> Call SunOS Operating System to write any pending information to the hard disk. Also boots after syncing file systems. I ) 1 i I 95 Symbolic Names Chapter 6: Using Machine Functions Symbolic Names You can use the commands listed in Figure 6-7 for symbolic debugging. For correct execution, the symbol table needs to be loaded before these commands are invoked. See dload in "Downloading Files Over Ethernet" earlier in this chapter. Figure 6-7. Symbolic Name Commands Command Stack Diagram Description . adr (adr -) Display the symbolic name (plus offset) for the given address symname (- adr) Type any valid symbolic name to get the equivalent address SunOS Operating System Calls You can use the command listed in Figure 6-8 to call SunOS Operating System functions. Figure 6-8. SunOS Operating System Call Commands Command Stack Diagram Description wector string (value —) Call SunOS with the given value and string Chapter 6: Using Machine Functions Manipulating the Cache Manipulating the You can use the commands listed in Figure 6-9 to Cache manipulate the cache. Note: Use commands ending with ! with caution. Otherwise your system might become hung. Figure 6-9. Cache Manipulation Commands Command Stack Diagram Description flush-cache (-> Invalidate all cache entries. Present in boot PROM versions 1.0 and 1.1. clear-cache (--> Invalidate all cache entries. Present in boot PROM version 1.2 and later. cache-off (--) Disable the cache cache-on (-) Enable the cache cdata! ( data offset - ) Store the 32-bit data at the cache offset cdata@ ( offset - data ) Fetch (return) data from the cache offset ctag! ( value offset -- ) Store the tag value at the cache offset ctag@ ( offset -- value ) Return the tag value at the cache offset 97 r 6 IVIUUUUC l\Cglblt.I b Chapter 6: Using Machine Functions Reading and You can use the commands listed in Figure 6-10 to read Writing Machine from and write to machine registers. Registers Note: Use commands ending with ! with caution. Otherwise your system might become hung. Figure 6-10. Machine Register Reading and Writing Commands Command Stack Diagram Description aerr ! (data -) Write asynchronous error register aerr@ (-- data) Read asynchronous error register averr ! (data —) Write asynchronous virtual address register averr@ (— data ) Read asynchronous error virtual address register aux! (data - ) Write auxiliary register aux@ (-- data ) Read auxiliary register context! (data —) Write context register contexts (-- data ) Read context register (MMU context) dcontextG (-- data ) Read context register (cache context) dmaaddr! (data —) Write DMA address register dmaaddrQ (-- data ) Read DMA address register enable ! (data -) Write system enable register enableQ (-- data ) Read system enable register interrupt-enable ! (data -) Write interrupt enable register interrupt-enableS (-- data ) Read interrupt enable register serr ! (data -) Write synchronous error register serr@ (-- data ) Read synchronous error register sverr ! (data -) Write synchronous error virtual address register sverr@ (-- data ) Read synchronous error virtual address register r fc,. L £ l l £ £ £ £ £ £ £ £ £ £ £ £ £ £ £r |C 95 Chapter 6: Using Machine Functions Reading and Writing Machine Registers This chapter described ways to control your machine using the boot PROM Toolkit. Chapter 7 describes the special commands you can use to view and change system configuration parameters. If you wish to use the Forth Toolkit to its fullest capacity, please read Chapter 5 for a detailed explanation of the PROM's Forth capabilities, if you have not already done so. 99 Reading and Writing Machine Registers Chapter 6: Using Machine Functions 7 Using Configuration Parameters The system configuration parameters are stored in the system NVRAM. These parameters determine the basic start-up machine configuration and related communication characteristics. This chapter describes how to access and change these parameters. The procedures described in this chapter assume that you have started the Monitor, entered the Forth Toolkit mode, and the ok prompt is displayed on your screen. See Chapter 3 for information about entering the Forth Toolkit. NVRAM configuration parameters can be viewed and changed using the Toolkit commands listed in Figure 7-1. Figure 7-1. Configuration Parameter Commands Command printenv setenv parameter value set-default parameter set-defaults Description Displays all current parameters and current default values (numbers are shown as decimal values) Sets the parameter to the given decimal or text value (Changes are permanent, but usually only take effect after a reset) Resets the value of the named parameter to the factory default Resets most parameter values to the factory defaults 101 Displaying Parameters Chapter 7: Using Configuration Parameters Displaying Parameters To display a list of the current parameter settings, type: ok printenv The system responds by displaying a formatted list of the current parameter settings, similar to the partial list shown in Figure 7-2. Note: Numeric parameters are displayed in decimal. Figure 7-2. Partial Configuration Display Parameter Name Value Default Value sunmon-eompat? true true pern-logo oem-logo? false false oem-banner oem-banner? false false ttyb-mode 9600,8, n, 1, - 9600,8,n,l,- ttya-mode 9600,8,n,l,- 9600,8, n,1, - Figure 7-3 on the next page lists all NVRAM configuration parameters in current SPARCstation 1 and SPARCstation 1+s. This might change with future systems. I r % i i 102 Chapter 7: Using Configuration parameters * **■ Figure 7-3. NVRAM Configuration Parameters Parameter Description Default auto-boot? If true, boot automatically after power up True diag-switch? If true, run in diagnostic mode True* fcode-debug? If true, include name fields for plug-in device Fcodes False keyboard-click? If true, enable keyboard click False mfg-switch? If true, perform repeated system self-tests False oem-banner? If true, use custom OEM banner False oem-logo? If true, use custom OEM logo (else use SUN Logo) False sunmon-compat? If true, come up with old-style monitor prompt '>' True ttya-ignore-cd If true, SunOS ignores carrier-detect on ttya True ttyb-ignore-cd If true, SunOS ignores carrier-detect on ttyb True ttya-rts-dtr-off If true, SunOS does not assert DTR and RTS on ttya False ttyb-rts-dtr-off If true, SunOS does not assert DTR and RTS on ttyb False watchdog-reboot? If true, reboot after watchdog reset False screen-#columns Number of on-screen columns (characters/line) 80+ screen-#rows Number of on-screen rows (lines) used 34+ scsi-initiator-id SCSI bus address of host adapter, range 0-7 7+ security-#badloginsNumber of incorrect security password attempts 0+ selftest-#megs Megabytes of RAM to test on power-up or on test-memorylt input-device Power-on input device (keyboard, ttya or ttyb) keyboard output-device Power-on output device (screen, ttya or ttyb) screen boot-from Boot source (default device is sd) vmunix boot-from-diag Diagnostic boot source leOvmunix hardware-revision System version information no default last-hardware- update System update information no default oem-banner Custom OEM banner (enabled by oem-banner? true) empty sbus-probe-list Which SBus slots are probed and in what order 0123 ttya-mode ttya (baud rate, #bits, parity, #stop, handshake) 9600,8, n, 1, -+ ttyb-mode ttyb (baud rate, #bits, parity, #stop, handshake) 9600,8, n, 1, -+ oem-logo Byte array custom OEM logo (enabled by oem-logo? true) empty sd-targets Map SCSI disk units, e.g. unit #0 = target #3, etc. 31204567 st-targets Map SCSI tape units, e.g. unit #0 = target #4, etc. 45670123 testarea One-byte scratch field, available for read/write test 0+ security-mode System security level (none, command, full) none security-passwd System security password (never displayed) empty *The default is true for boot PROM version 1.1 and later, but false for boot PROM version 1.0. tValues shown in decimal. ( I *' 103 Changing a Parameter's Value Chapter 7: Using Configuration Parameters Changing a Parameter's Value Use the setenv command to change a parameter setting. The setenv command has the following format: setenv parametername value where parametername is one of the listed parameters. value is a numeric value or text string appropriate to the named parameter. Numeric values are entered in decimal. To change the setting of the auto-boot? parameter from true to false, enter: ok setenv auto-boot? false ok This command sets the auto-boot? parameter flag to false. This means that the next time the system is powered on or reset the auto-boot feature is turned off. The system will not attempt to boot the SunOS Operating System after self-tests and initialization have completed. Chapter 7: Using Configuration Parameters Resetting Default Values Resetting Default Values You can reset one or most of the parameters back to the original defaults using the set-default and set-defaults commands. These commands have the following format: set-default parametername set-defaults where parametername is one of the listed parameters. To reset the auto-boot? parameter to its original default setting (true), type: ok set-default auto-boot? ok To reset most parameters to their default settings, type: ok set-defaults ok 105 Resetting Default Values Chapter 7: Using Configuration Parameters Once the default for a parameter is changed or reset, a system reset is usually required for the parameter setting to actually take effect. A system reset (which is very similar to a power cycle) does not necessarily include booting, depending on how the configuration parameters are specified. The parameters that relate to system booting require a system boot for the parameter to take effect. You can use the reset command to reset the system when you have changed a parameter. Figure 7-4 lists additional NVRAM configuration commands, which are used only rarely. r ft fe t t Figure 7-4. Configuration Parameter Command Primitives Command Stack Diagram Description EL parameter (-- value) Return the (current) field value fc show parameter (-) Display the (current) field value (numbers shown in decimal) fe to parameter (value --) Change a (current) field value Examples: false to auto-boot? Text string" to oem-banner fe & fe & & t L L L £ 106 Chapter 7: Using Configuration Parameters Security The security feature of the boot PROM is available on version 1.1 and later boot PROM versions. Setting the security-mode parameter to full or command security restricts the set of actions others are allowed to perform, thus making it more difficult for them to break into your computer network. Figure 7-5 lists the security parameters. Figure 7-5. Security Parameters Parameter Default Description security-mode None System security level (none, command, full) security-passwd Empty System security password security-#badlogins 0* Number of incorrect security password attempts *Value shown in decimal Security There are three security modes: 1. No security 2. Command security 3. Full security. With no security, any command can be executed at the boot prompt > with no password required. Command security is the next level of security and full security is the most secure. With both command and full security, passwords are required to execute certain commands at the boot prompt >. A password is never required from the ok prompt, regardless of security mode. However, a password is required to get to the ok prompt in either command or full security mode. 107 No Security Chapter 7: Using Configuration Parameters No Security With no security (default), no password is required for any command at the boot prompt >. Anyone can execute the three commands at the boot prompt > without a password: □ b (boot) □ n (new) □ c (continue). If you previously set the security to command or full security and wish to set the system with no security, enter the following: ok setenv security-mode none The next time the system checks the boot PROM's security, it will determine that no security (security¬ mode none) has been set for the user. It is also possible to change the PROM security mode using the /etc/eeprom SunOS Operating System command. Chapter 7: Using Configuration Parameters Command. Security Command Security With the security set to command mode, a password is not required if you type the b command at the boot prompt >. However, if you follow the b command with a parameter, a password is required. To execute the n command from the boot prompt >, a password is required. The c command never asks for a password. Examples follow: > b (no password required) > c (no password required) > b filename (password required) PROM Password: (password is not echoed as it is typed) > nil (password required) PROM Password: (password is not echoed as it is typed) To set the security password and command security, enter the following at the ok prompt: ok setenv security—password passwd ok setenv security-mode command ok old-mode The security password you assign follows the same rules as the root password, a combination of six to eight letters and numbers. The security password can be the same as the root password, or you can assign a security password different from the root password. 109 Command Security Chapter 7: Using Configuration Parameters Caution: The security password is important to remember. If you forget your security password, your system will be unbootable and you must call Sun's customer support service to make your machine bootable again. It is not necessary to reset the system. The security feature takes effect as soon as the Sun-Compatible mode (> prompt) is entered. Note: After setting your security password, it is a good idea to remove the password from the screen to prevent someone from seeing it. Press the t Return I key several times to remove the password from the screen. If you enter an incorrect security password, there will be approximately a 10 second delay before the next boot prompt > appears. The number of times that an incorrect security password is typed is stored in the security- #badlogins parameter. This parameter is a 32-bit signed number (680 years worth of attempts at 10 seconds per attempt). This parameter can be set to 0 with the setenv command. Its value can be displayed with the printenv command. An example of setting the number of badlogins to 0 follows: ok setenv security-#badlogins 0 Note: If you enter the boot command in command or full security mode, the PROM will revert to the > prompt the next time that the PROM command interpreter is entered. 110 Chapter 7: Using Configuration Parameters Full Security Full Security The full security mode is the most restrictive. With the security set to full mode, a password is required any time you type the b command at the boot prompt > (either b alone or b followed by a parameter). A password is required to execute the n command from the boot prompt >. The c command never asks for a password. Examples follow: > c (no password required) > b (password required) PROM Password: (password is not echoed as it is typed) > b filename (password required) PROM Password: (password is not echoed as it is typed) > n (password required) PROM Password: (password is not echoed as it is typed) To set the security password and full security, enter the following at the ok prompt: ok setenv security-password passwd ok setenv security-mode full ok old-mode me i ucucf -cj/l uunntr Chapter 7: Using Configuration Parameters Changing the You can use the banner command to view the power-on Power-On Banner banner. Figure 7-6 lists the configuration parameters that control the power-on system banner. Figure 7-6. Banner Configuration Parameters Parameter Default Description oem-banner? False When true, the default Sun banner message displayed during system power up is replaced with whatever text string is present in the oem-banner parameter text field oem-logo? False When true, the data array specified in the oem-logo field is substituted for the Sun logo in the power-on banner oem-banner Empty Custom banner (enabled by oem-banner? true) oem-logo Empty Byte array custom logo (enabled by oem-logo? true) To display the system power-on banner, enter: ok banner The PROM displays the system banner. The following banner is the SPARCstation 1 banner. The banner for your SPARC system might be different. SPARCstation 1: Type 4 Keyboard ROM Rev. 1.0, 8MB memory installed. Serial # 312 Ethernet Address 8 : 0 : 20:6:5:16 , Host ID:51000174 Chapter 7; Using Configuration Parameters Changing the Power-On Banner The banner consists of two parts: the text field and the logo (over serial ports, only the text field is displayed). You can replace the existing text field with a custom text message using the oem-banner and oem-banner? configuration parameters. To insert a custom text field in the power-on banner, enter: ok setenv oem-banner Hello Mom and Dad ok setenv oem-banner? true ok banner ok The system displays the banner with your new message. However, the graphic logo must be handled somewhat differently. The oem-logo field is a 512-byte array, containing a total of 4096 bits arranged in a 64 x 64 array. Each bit controls one pixel. The most significant bit (MSB) of the first byte controls the upper-left comer pixel. The next bit controls the next pixel to the right and so on. 113 xnc x uuuci ~cjh uunnct uiapter /: Using Configuration Parameters To create a new logo, you must first create a Forth array containing the correct data and then copy this array into the oem-logo field. For the following example, the array is created using Forth Toolkit commands. This command could also be done under SunOS Operating System using the /etc/eeprom command. This array is then copied using the to command, which is an NVRAM primitive. The following example fills the top half of the oem-logo field with an ascending pattern, and leaves the bottom half unchanged. ok create logoarray d# 512 allot ok logoarray d# 256 0 do i over i + c! loop drop ok logoarray d# 256 to oem-logo ok setenv oem-logo? true ok banner The system displays the power-on banner with the new logo array. New Logo Array Hello Mom and Dad display Chapter 7: Using Configuration Parameters "•r — • To restore the original Sun power-on banner, set the oem-logo? and oem-banner? parameters to false. ok setenv oem-logo? false ok setenv oem-banner? false ok Because the oem-logo array is so large, printenv only displays the first 8 bytes or so (in hex). To display the entire array, use the oem-logo dump command. The oem-logo array is not erased by set-defaults, since it might be difficult to restore the data. However, oem-logo? will be set to false by execution of set-defaults, so the custom logo will no longer be displayed. Figure 7-7 lists the configuration parameters related to the control of system input and output. You can use these parameters to assign the power-on defaults for input and output, and to adjust the communication characteristics of the ttya and ttyb serial ports. These values do not take effect until the next system reset. Figure 7-7. Input and Output Control Parameters Parameter Default Description input-device keyboard Power-on input device (keyboard, ttya, or ttyb) output-device screen Power-on output device (screen, ttya, or ttyb) ttya-mode 9600, 8, n, 1, -* ttya (baud, #bits, parity, #stop, handshake) ttyb-mode 9600,8, n, 1, -* ttyb (baud, #bits, parity, #stop, handshake) screen-#columns 00 o * Number of on-screen columns (characters/line) screen-#rows 34* Number of on-screen rows (lines) ^Values in decimal Input and Output Control ociung oeriui rurt c naracteristics Chapter 7: Using Configuration Parameters Setting Serial Port Characteristics The default settings for both ttya and ttyb are: 9600 baud 8 data bits no parity 1 stop bit no handshake The communications characteristics for the two serial ports, ttya and ttyb, are set using the following values for the parameters ttya-mode and ttyb-mode. baud, #bits, parity, #stop, handshake where: baud 110,300,1200,2400,4800, 9600,19200, 38400 (bits/second) #bits 5,6,7, 8 (data bits) parity n=none, e=even, o=odd, m=mark, s=space (parity bit) #stop 1=1,. =1.5, 2=2 (stop bits) handshake -=none, h=hardware (rts/cts), s=software (xon/xoff) To set ttya to 1200 baud, seven data bits, one stop bit, even parity, and no handshake, type: ok setenv ttya-mode 1200,7,e,l,- ok Note: rts/cts and xon/xoff handshaking are not implemented on all systems. In this case, the handshake parameter is silently ignored. II It jH- fe fc_ fc & fe gr & fc fef fe- fe £ 116 Chapter 7: Using Configuration Parameters Selecting Input and Output Device Options Selecting Input and Output Device Options The input-device and output-device parameters control the system's selection of input and output devices after a power-on reset. The default input-device value is keyboard and the default output-device value is screen. Input and output can be set to the following values: input-device output-device keyboard* screen** ttya ttya ttyb ttyb * keyboard implies standard Sun keyboard **screen implies frame buffer video display When the system is reset, the named device becomes the default input or output device. If you wish to temporarily change the input or output device, use the input or output commands described in Chapter 6. To set tty a as the power-on default input device, type this command: ok setenv input-device ttya ok Note: If keyboard is selected for input-device but is not plugged in, or if screen is selected for output-device but no on-board frame buffer is available, then both input and output will be sent via ttya after the next power cycle or system reset. Selecting Boot Options Chapter 7: Using Configuration Parameters You can use the configuration parameters to determine whether the system will automatically boot after the system start-up tests and initialization. In addition, the parameters can be used to select the boot device and the program to be booted. Figure 7-8 lists the parameters that control boot options. Figure 7-8. Boot Options Parameters Parameter Default Description auto-boot? True Determines whether the system will automatically boot after the power-on self¬ test and system initialization. If true and diag-switch? is set to false, the Open PROM attempts to boot whatever file is specified by the boot-f rom parameter. boot-from vmunix Boot source filename (default device is sd) Selecting Boot Options The boot-f rom parameter defaults to the filename vmunix. The boot-f rom parameter is used during auto¬ boot or when you boot the system manually without specifying a filename. If no device is specified, the default device is assumed to be the system's internal hard disk. However, you can use the boot-f rom parameter to specify a different device and file. For example, to specify the file myunix to be auto-booted single-user from the Ethernet server, type: ok setenv boot-from le()myunix -s ok boot Specified booting begins immediately Chapter 7: Using Configuration Parameters Controlling Power-On Self Test Controlling Power- Enabling the diagnostic switch parameter diag-switch? On Self-Test causes the system to perform a more thorough self-test during power-on. After diag-switch? is enabled, additional status messages are sent out (some to ttya and some to the specified output device) and all of memory is tested. Figure 7-9 lists the power-on testing parameters. The default value of diag-switch? is true, but the actual value is set to false at the factory. If the default values are restored with set-defaults, the diag-switch? value becomes true. Figure 7-9. Power-On Testing Parameters (continued on next page) Parameter Default Description diag-switch? True When diag-switch? is true, the system calls out diagnostic tests as they are executed (at power-on time) and performs complete memory tests (all of memory is tested). Each Power-On Self-Test prints its name (either to ttya or to the default output device) as it begins to execute, and the boot PROM attempts to boot the program specified by the boot-f rom-diag parameter. When diag-switch? is false, the system will not call out the diagnostic tests as they are run, unless a test fails, and will not run any additional tests. Note: The default value is true for boot PROM version 1.1 and later, but false for boot PROM version 1.0. Regardless of the default value, all systems are shipped from the factory with a current value of false for diag-switch? 119 Controlling Power-On Self Test Chapter 7: Using Configuration Parameters Figure 7-9. Power-On Testing Parameters (continued) Parameter Default Description mfg-switch? False When true, the system repeats the power-on self-test and initialization sequence until interrupted with the Ili-aI key sequence. selftest-#megs 1* Number of megabytes of RAM to test on power-up or on test-memory. This value is ignored if diag-switch? is true. boot-from-diag leOvmunix Diagnostic boot source filename *Value shown in decimal. The self test-#megs parameter determines how much of the RAM will be tested during the power-on self tests. The default for this parameter is one megabyte. When the mf g-switch? parameter is set to true, the system repeats power-on self-test and initialization until interrupted with an fTTAl key sequence. For example: To power-up in diagnostic mode if diag-switch? is set to false: 1. Set the diag-switch? parameter to true. 2. Reset the system. ok setenv diag-switch? true ok reset See your system's Field Service Manual for more information about using diagnostics. 220 Chapter 7: Using Configuration Parameters Controlling Power-On Self Test This chapter described the configuration parameters contained in NVRAM. Changes made to these parameters are permanent. The configuration parameter commands listed in Figure 7-1 have been created to simplify using these parameters. However, configuration parameters should always be adjusted cautiously. When correctly used, these configuration parameters allow you flexibility in working with your system's hardware. 121 Controlling Power-On Self Test Chapter 7: Using Configuration Parameters 722 A Sun Monitor Command Equivalents Figure A-l lists the most commonly used Sun Monitor commands, with the Forth Toolkit commands that perform equivalent functions. Figure A-l. Command Equivalents (continued on next page) Sun Monitor Command Forth Toolkit Command A C source-addr dest-addr len source-addr dest-addr len move a i .version A T address address map? b [boot spec] boot [boot spec] addr dload pathname c address go or address set-pc go d window # .registers . locals windowU .window e address action address w? value address w! 123 Appendix A: Sun Monitor Command Equivalents Figure A-l. Command Equivalents (continued on next page) Sun Monitor Command Forth Toolkit Command f addr 1 addr 2 pattern size g vector argument h i cache-data-offset action j cache-tag-offset action kl or k2 kb 1 address action m address action o address action addr kbytes byte cf ill addr #bytes shortiuord wf ill addr kbytes longword If ill go sync value wector argument help help name help category address cdataG . value address eclat a ! address ctag@ . value address ctag! reset banner address L? value address L! address smap? value address smap! address c? value address c! I » s r t r &- * t. p address action q offset action address pgmap@ address map? pte address pgmap! physical space # virtual map-page physical space # virtual size map-pages space#: obmem, obio, sbus printenv setenv parametername value set-default parametername set-defaults E t E. t E ii £ * 124 Appendix A: Sun Monitor Command Equivalents Figure A-l. Command Equivalents (continued) Sun Monitor Command Forth Toolkit Command s step-count step step-count steps r register-number action register name . value to register-name s space# address space# spacec? address space# spacew? address space# spaceL? value address space# spacec! value address space# spacew! value address space# spaceL! t program n steps u various options device input device output device io devices: ttya, ttyb, screen, keyboard v addrl addr2 address size dump w address argument value wector argument X test-control-regs test-net test-cache test-memory test-floppy watch-clock z number address type ten address +bp address -bp return returnL .bp till finish-loop Appendix A: Sun Monitor Command Equivalents k fei £ £ £- fe r fe_ * t- £ £ £ £ £ £ £ £ £ % ■— t T1 B Power-On Self-Test Figure B-l lists the Power-on Self-Test (POST) for the SPARCstation 1, with brief descriptions. Figure B-l. POST Descriptions (continued on next page) Test Name Description PROM Checksum Calculates the checksum of the PROMs and compares the calculated value with the expected value. Segment Map Address Writes the number of each segment map location to that location, then reads back the value and compares it with the expected value. The entire range of segment map addresses is written prior to the read and compare operation. When an error is detected, the test loops on the error location. j- Page Map Address Writes the number of each page map location to that location, then reads back the value and compares the observed value with the expected value. The entire range of Page Map addresses is written prior to the read and compare operations. When an error is detected, the test loops on the error location. ^ Context Register \ Performs write-read-compare cycles on the context register using patterns 0x08,0x07, through 0x00. \ 127 Appendix B: Power-On Self-Test Figure B-l. POST Descriptions (continued) Test Name Description Synchronous Error Register Performs write-read-compare cycles on the synchronous error register, using patterns Oxff, Oxfe, through 0x00, and also patterns 0x80ff, 0x80fe, through 0x800. Synchronous Error Virtual Address Register Performs write-read-compare cycles on the synchronous error virtual address register using patterns Oxffffffff, 0x0, 0x00000001,0x00000002,0x00000004,0x00000008, through 0x80000000. Asynchronous Error Register Performs write-read-compare cycles on the asynchronous error register, using patterns 0xb0,0xa0,0x90,0x80,0x30, 0x20, 0x10, and 0x00. Asynchronous Error Virtual Address Register Performs write-read-compare cycles on the asynchronous error virtual address register using patterns Oxffffffff, 0x0, 0x00000001, 0x00000002,0x00000004, 0x00000008, through 0x20000000. System Enable Register Examines the system enable register for correct bits set. System Memory Tests main memory. The number of megabytes tested is indicated by the NVRAM parameter self test-#megs. Index Note: Page references for commands appear in bold. Symbols ! 42,49 # 39 #> 39 #s 39 %f0 through %f31 69 %fsr 69 %g0 through %g7 69 %i0 through %i7 69 %L0 through %L7 69 %npc 68, 69 %o0 through %o7 69 %pc 68,69,70 %psr 69 %tbr 69 %y 69 %yim 69 ( 28,54,56 (ccc) 56 (u.) 39 (.) 39 (patch 53 (see) 52 ) 28,54,56 * 40 V 40 V mod 40 + 25,26,27,28,40,49,50 +! 42 +bp 70,71,125 +dis 67 +loop 63, 64 , 53 - 40 - 26 -bp 71 -bp 71,125 -rot 36 -trailing 57 . 26, 27, 28, 38, 47, 48, 49, 50, 58, 62, 64, 65, 125 .( 57 51,57,60,65 .adr 96 .bp 71,125 .breakpoint 71 .d 24,37,38,51 .enet-addr 79 .h 37,38,51 .idprom 79 .instruction 71 .locals 69,123 .psr 69 .r 38 .registers 69,123 .s 37,38 .traps 79 .version 79,104,123 .window 68,123 / 40 / etc/eeprom 114 /etc/halt 10,13 /etc/remote 83 /mod 40 < 59 <# 39 « 40 <= 59 <> 59,64 = 59,64 > 58,59,60 >=59 > prompt viii, 8,12,14,16,18,19 booting from 16 returning to 19 » 40 »a 40 >r 36 ? 42 ?do 63 ?dup 36 ?leave 63 @ 35,42,49,50 \ 54,56 ] 53,60 ] prompt 60 ~. 85 ~C 87 ' 51,52 " ccc" 57 Numerics 0< 59 0<= 59 0<> 59 0= 58,59 0> 59 0>= 59 1+ 40 1- 40 2! 42 2 * 40 2+ 40 2- 40 2/ 40 2@ 43 2constant 51 2drop 36 2dup 36 2over 36 2rot 36 2swap 36 32-bit integer 24 32-bit numbers 31,35 3dup 36 A abort 66 abort" 66 aborting a hung system 10,14 abs 40 absolute value 40 acf 52,53,66 addition 40 address code field 52, 66 adds 1 40 adds 2 40 aerr! 98 aerr@ 98 again 62 alias 51 aligned 40 alloc-mem 43,48 allocate-dma 43 allocate-physical 45 allocate-virtual 43 allot 53 and 40 130 Index arithmetic right shift nl by +n places 40 using 39 ascii 54, 56 asi 46 asynchronous error register 128 asynchronous error virtual address register 128 auto-boot 8 auto-boot? 103 aux! 98 aux@ 98 averr! 98 averr@ 98 B b, boot 12,15,109, 111 b, command security 109 back space, editor command 30 backward one character, editor command 30 backward one word, editor command 30 banner 79,112,113,124 displaying 79,113 base 24, 37, 38 displaying the number in the current base 38 setting the number base to 10 38 variable containing number base 38 base 10 24, 38 base 16 38 base 16 numbers 24 baud rate 81,82,103,115,116 begin 61, 62 begin compilation 53 beginning of line, editor command 30 between 59 bitwise ones complement 40 bl 56 blank 42 boot 17,79,110 prom displaying the version and date 79 version 104 boot-h 17,70,94 boot prompt 2 boot-from 103 boot-fro m-diag 103,120 booting 79 after start-up tests and initalization 118 from the > prompt 16 from the ok prompt 16 bpoff 71 breakpoint commands 70 buffer 51 byte copying u bytes from adr 1 to adr 2 42 copying u bytes from adr 1 to adr 2 starting at high byte 42 copying u bytes from adr 1 to adr 2 starting at lo byte 42 displaying len bytes of memory starting at adr 42 displaying the byte at adr 42 fetching a byte from adr 42 storing low byte of n at adr 42 byte-load 94 c c! 42,47,64, 124 c, continue 12,15,18,109 c? 42,124 c@ 42,62,64 cable null modem 83 cache 78, 97 data and tag fields testing 75 testing 78 cache-off 97 cache-on 97 call 67 carriage-return 55 case 65 cat 87 cdata! 97,124 cdata@ 97,124 cfill 42 changes sign of nl 40 J31 Index clear 36 clear-cache 97 clock function testing 75, 78 system 78 cmove 42 cmove> 42 code field address 51, 52, 66 colon definition 50, 51 colon definitions 27 command line erasing characters or words 29 command line, moving forward and backwards 29 command security 109 command syntax 22 comments in Forth code 54 comp 42 53 compile 53 compile next (immediate) word 53 configuration parameters 101 constant 48, 50, 51 context register 127 context! 98 context® 98 control key 29 Control-D 88 contstants defining word 50 count 55, 57 cprobe 44,47 CPU data register 68 cr 55,57,64 create 51 ctag! 97,124 ctag® 97,124 ctrace 69 CTRL A, beginning of line 30 CTRL B, backward one character 30 CTRL D, erase this character 30 CTRL E, end of line 30 CTRL F, forward one character 30 CTRL H, erase previous character 30 CTRL K, erase forward 30 CTRL L, retype line 30 CTRL N, recall subsequent command line 30 CTRL P, recall previous command line 30 CTRL Q, quote next character 30 CTRL U, erase entire line 30 CTRL W, erase previous portion of word 30 D d# 37,38 data stack displaying the 38 dcontext® 98 decimal 24, 37, 38 decimal number 37 decimal NVRAM parameters 101,103,104, 107,115,120 decimal point 24 decimal points 48 default values 101 defer 51 defining command words 27 defining word 49, 50, 51 defining word constants 50 Del, erase previous character 30 depth 36 diag-s witch? 103,118,119,120 diagnostic boot from source filename 103,120 routines 75 switch setting 119,120 diagnostic, switch setting 103 dictionary displaying all the visible words in the dictionary 52 finding a word 52 placing a number in the dictionary 53 dis 67 disassembler 67 132 Index diskette drive system 77 test 75 ejecting 95 displaying a num 38 displaying an unsigned num 38 dividing by 2 40 division 40 dl 87,94 dlbin 94 dload 56,70,91,94,123 DMA allocate and map size of memory in DMA space 43 dma allocate and map 44 dma-alloc 43 dmaaddr! 98 dmaaddr® 98 do 63,64 do loops 63 does> 51 downloading files 27, 56, 70, 87, 94 downloading files over a seial connection 94 downloading files over a serial connection 89 downloading files over ethernet 91,94 drop 36 dump 22, 42,47, 48,125 dup 35,36 duplicate the top item on the stack 35 duplicating n 36 duplicating the top stack item 36 E editor 29 editor commands 30 eject-floppy 95 else 60,61 EMACS 29 emit 54, 57 enable! 98 enable® 98 end of line, editor command 30 endcase 65 endof 65 entering the Forth Toolkit 18 erase 42 erase entire line, editor command 30 erase forward, editor command 30 erase previous character, editor command 30 erase this character, editor command 30 erase this portion of word, editor command 30 ESC B, backward one word 30 ESC D, erase this portion of word 30 ESC F, forward one word 30 ESC H, erase previous portion of word 30 escape key 29 ethernet 17 address displaying 79 controller testing 75, 76 downloading files 70, 91 loading the specified file over 94 ethernet, downloading files 94 eval 56, 57, 94 examples 47 exchanging the top 2 stack items 36 exclusive or 40 execute 66 exit 66 exit? 57 F false 58, 59 fcode-debug? 103 files downloading 27, 56, 87 files, downloading 70 fill 42 find 52 finish 125 finish-loop 71 flag 58 floppy ejecting 95 133 Index floppy disk drive system 77 test 75 flush-cache 97 forget 53 Forth file 94 reference materials 30,31 source 57 text 87,88,91,92,94 Toolkit entering 18 mode 2 Forth 83-Standard 35 Forth text 87 Forth Toolkit 3 forward one character, editor command 30 forward one word, editor command 30 frame buffer 80 free-dma 44 free-mem 44,48 free-physical 45 free-virtual 44 full security 111 G go 68,70,71,94,124 H h# 37,38 halting the SunOS Operating System 10,13 halting the SunOS operating system 10,13 hardware-revision 103 help 23,124 here 53 hex 24,37,38 displaying a number in hex without changing the base 38 setting the number ba 38 setting the number base to base 16 38 hex number 24,37,38 interpreting the next number in hex 38 history mechanism 29 hold 39 hop 71 hops 71 hung system 9,11,14, 21 aborting 10,14 I i 63,64 ID PROM displaying contents 79 if 60,61,64 immediate 53 init-program 94 input 80,82,115,117,125 input device keyboard 115,117 ttya 115,117 ttyb 115,117 input-device 81,103,115,117,118 input-device, keyboard 117 inpu t-device, ttya 117 input/output 81, 82 inserting text 29 integer 24 32-bit 24 integer unit 7 interpreting begin interpreting 53 interrupt-enable! 98 interrupt-enable@ 98 interrupting the power-up sequence 10,12 io 81,82,125 is 53, 64 IU 7 J j 63 jmp 67 K key 56 key? 54,56,62,86 234 Index keyboard 80,125 input device 117 keyboard-click? 103 L L! 42,124 L, 53 L? 42,124 L@ 35,42,47 LI-A 8,10,12,14, 68, 80, 82,84, 95,120 last-hardware-update 103 leave 63, 64 left shift nl by +n places 40 Lfill 42 line editor 29, 30 line editor commands backward one character 30 backward one word 30 end of line 30 erase entire line 30 erase forward 30 erase previous character 30 erase previous portion of word 30 erase this character 30 erase this portion of word 30 forward one character 30 forward one word 30 quote next character 30 recall previous command line 30 recall subsequent command line 30 retype line 30 literal 53 loading the file over Ethernet 94 logical and 40 logical or 40 loop 63,64 loops 61, 63 loops, conditional 61 loops, counted 63 Lprobe 44 M main memory testing 120 manufacturing switch setting 120 manufacturing, switch setting 103 map, displaying memory 44 map-page 45, 49, 124 map-pages 45,49, 124 map-sbus 43, 48 map-segments 45 map? 44, 123 max 40 maximum 40 memmap 44 memory 67, 70 accessing 41 allocate and map size bytes of available memory 43 displaying len bytes of memory starting at adr 42 displaying memory map information 44 main testing 75 mapping 47 setting cnt bytes of memory to byte 42 setting size bytes of memory to 16-bit word 42 setting size bytes of memory to 32-bit long 42 setting size bytes of memory to byte 42 setting u bytes of memory to 0 42 setting up u bytes of memory to space 42 testing 77,120 memory, accessing 42,43 memory, mapping 45 mfg-switch? 103,120 min 40 minimum 40 mod 40 monitor 3, 8,15, 21, 73, 79 mode 2 starting 9 monitor mode 2 v 135 Index monitor, sun-compatible 2 move 42,123 multiplication 40 multiplies by 2 40 N n 14 n, new command mode 12,15,84,109 negate 40 nip 36 no security 108 Non-Volatile Random Access Memory 2,8,15, 16,31,81,82,101 Non-Volatile Read Only Memory 1 not 40 npatch 53 null modem cable 83 number 16-bit displaying the 16-bit number at adr 42 fetching a 16-bit number 43 fetching a 16-bit number from adr 42 storing a 16-bit number 43 storing a 16-bit number at adr 42 32-bit 24,31,35 adding n to the 32-bit number stored at adr 42 displaying the 32-bit number at adr 42 fetching a 32-bit number 43 fetching a 32-bit number from adr 42 storing a 32-bit number 43 storing a 32-bit number at address 42 storing a 32-bit number at adr 42 decimal 37 interpreting the next number in decimal 38 displaying a number in a fixed width field 38 an unsigned number 38 displaying a number in hex without changing the base 38 displaying a number in the current base 38 displaying an unsigned number 38 displaying n in decimal without changing the base 38 fetching two numbers from adr 43 hex 37 hexidecimal displaying n in hex without changing the base 38 interpreting the next number in hex 38 setting the number base to 16 38 storing two numbers at adr 42 unsigned displaying an unsigned number 38 numbers 24 NVRAM 1,2,8,15,16,31,81,82,101 o obio 45,49, 124 obmem 45,49,124 oem-banner 102,103,112,113 oem-banner? 102,103,112,113,115 oem-logo 102,103,112,113,114 oem-logo? 102,103,112,115 of 65 ok prompt 3,16,18, 21,29, 81 booting from 16 old-mode 10,14,19 operating system 1, 7, 9,10, 79, 95 halting 10 or 40 output 80, 81,82,115,117, 125 output device screen 115 ttya 115 ttyb 115 output-device 81,103, 115, 117,118 screen 117 output-device, screen 117 output-device, ttya 117 over 36 P p" 57 packed string 55,57 i i i i i i 3 i H U 1 I i 136 E £ m ftri Index page map 127 | page, ma P one P a g e memor y 45 page, perform consecutive map-pages 45 | pagesize 45 parameter 106 | displaying 101,102 power-on testing 119 J resetting all parameters to the default 101,105 j resetting the named parameter to the defau 101,105 j setting 101,104 system configuration 101 I parentheses 54,56 left 54 | right 54 password \ security 109 patch 53 | pgmap! 45,124 pgmap? 124 j pgmap® 45,124 physical address 41 I pick 36 ports 80 < POST 7,127 power cycle 9,11,21,81,82 } Power-On Self-Test 7,127 power-on testing parameters 119 j power-up sequence, interrupting 10,12 printenv 101,102,124 j probe-scsi 75 * PROM * Programmable Read Only Memory 1 prompt j > 8,14,16,18,19 boot 2 j ok 3,16,18, 21, 81 prompt, ok 29 j pstr 52, 55,57 * Q ^ quit 66 quote next character, editor command 30 R r> 36 r@ 36 RAM testing 120 recall previous command line, editor command 30 recall subsequent command line, editor command 30 registers 68, 69, 70 test control 75 remainder ofnl/n2 40 quotient of nl*n2/n3 40 quotient of nl /n2 40 repeat 61, 62 reset 74,106,120,124 resetting parameter defaults 105 the system 74 return 71,125 returning to the > prompt 19 returnL 71,125 retype line, editor command 30 right shift nl by +n places 40 roll 36 rot 36 round nl up to next multiple of 4 40 s save-fregs 68 sbus 45,124 SBus map a region of SBus space 43 slot offsets 44 sbus-probe-list 103 screen 81,82,125 output device 117 screen-#columns 103,115 screen-#rows 103,115 SCSI 17 SCSI devices determining 75 137 Index scsi-initia tor-id 103 sd-targets 103 security 103,107 command 109 full 111 none 108 password 109 security password 103 security-#badlogins 103,107 security-mode 103,107,108 security-passwd 103,107,109 see 27, 52 segment map 127 segmentsize 45 selftest-#megs 103,120 serial 80 cable 83 porta 8,80,81,83 portb 80,81,83 ports 115,116 serial connection downloading files 89, 94 serr! 98 serr@ 98 set-default 101,105,124 set-defaults 101,105,124 set-pc 68, 69 setenv 101,104,108,124 ttya-mode 116 show 106 showing the stack 34 showstack 25,34,38 sign 39 skip 71 slot 48 slot offsets 44 smap! 45,124 smap? 45,124 smap@ 45 soft-reset 124 space 57 spaced 46,125 spacec? 46,125 spacec@ 46 spaceL! 46,125 spaceL? 46,125 spaceL@ 46 spaces 57 spacew! 46,125 spacew? 46,125 spacew@ 46 st-targets 103 stack 25 copying +nth stack items 36 copying item from top of return stack to data stack 36 copying the second 2 stack items 36 copying the second item to the top of the stack 36 copying the top stack item underneath the second item 36 data displaying the contents 38 diagram 26 discarding the second stack item 36 duplicating 2 stack items 36 duplicating 3 stack items 36 duplicating n if it is non-zero 36 duplicating the top item on the stack 35 duplicating the top stack 36 exchanging the top 2 stack items 36 inversely rotating 3 stack items 36 moving a stack item to the return stack 36 moving an item from the return stack to the data stack 36 removing 2 items from the stack 36 removing n from the stack 36 removing the top stack item 36 returning the number of items on the stack 36 rotating +n stack items 36 rotating 3 pairs of stack items 36 rotating 3 stack items 36 showing 34 showing stack items before the ok prompt 38 standalone programs 70 starting the monitor 9 state 53 step 70,71,125 138 Index steps 71,125 stop, key 14 string 55, 57 packed 55 string, packed 57 subtraction 40 subtracts 2 40 Sun-Compatible Monitor 3, 8,15, 21, 73, 79 sun-compatible monitor 2 Sun-Compatible Monitor mode 2 Sun-Compatible Monitor mode 2 sunmon-compat? 102,103 SunOS Operating System 1, 7, 9,10,13, 70 SunOS operating system 79, 95, 96 SunOS Operating System halting 10 sverr! 98 sverr® 98 swap 36 switch setting 103 symbol table 67, 91, 96 symbolic debugging 96 symname 96 sync 10,14,15,95,124 synchronous error register 128 synchronous error virtual address register 128 system clock 78 system configuration parameters 101 system enable register 128 T terminal 80 test control registers 75 test-cache 75, 78, 125 test-control-regs 75, 76,125 test-floppy 75,77, 125 test-memory 75, 77, 125 test-net 75,76, 125 testarea 103 text inserting 29 text input 54 text output 54 tftp protocol 91 then 60, 61, 64 till 71,125 tip 83,86 tip window 83, 84,85, 86, 87 to 68,69,106,114, 125 traps displaying a list of SPARC trap types 79 true 58, 59 ttya 8,80,81,83,125 input device 117 ttya-ignore-cd 103 ttya-mode 81, 102,103,115,116 ttya-rts-dtr-off 103 ttyb 80,81,83,125 input device 117 ttyb-ignore-cd 103 ttyb-mode 81,102,103,115,116 ttyb-rts-dtr-off 103 tuck 36 type 57 u u. 38 u.r 38 u< 59 u<= 59 u> 59 u>= 59 unaligned-L! 43 unaligned-L@ 43 unaligned-W! 43 unaligned-w@ 43 until 61, 62 v value 50, 51, 64 variable 49, 51 version boot PROM 104 version, boot prom 79 139 Index virtual address 41 w w 68,69 w! 42,47,64,123 w, 53 w. 53 w? 42,123 w@ 35,42,64 watch-clock 75, 78,125 watchdog-reboot? 103 weetor 96,124,125 wfill 42,124 while 61, 62 within 59 words 22, 52 wprobe 44 140 sun microsystems Sun Microsystems, Inc. 2550 Garcia Avenue Mountain View, CA 94043 415 960-1300 FAX 415 969-9131 Part Number: 800-5279-10 Revision B of January 1991