This chapter describes how to access and modify non-volatile RAM (NVRAM) configuration variables.
System configuration variables are stored in the system NVRAM. These variables determine the start-up machine configuration and related communication characteristics. You can modify the values of the configuration variables, and any changes you make remain in effect even after a power cycle. Configuration variables should be adjusted cautiously.
The procedures described in this chapter assume that the user interface is active. See Chapter 1, Overview for information about entering the user interface.
Table 3-1 lists a typical set of NVRAM configuration variables defined by IEEE Standard 1275-1994.
Table 3-1 Standard Configuration Variables
Variable |
Typical Default |
Description |
---|---|---|
auto-boot? |
true |
If true, boot automatically after power on or reset. |
boot-command |
boot |
Command that is executed if auto-boot? is true. |
boot-device |
disk net |
Device from which to boot. |
boot-file |
empty string |
Arguments passed to booted program. |
diag-device |
net |
Diagnostic boot source device. |
diag-file |
empty string |
Arguments passed to booted program in diagnostic mode. |
diag-switch? |
false |
If true, run in diagnostic mode. |
fcode-debug? |
false |
If true, include name fields for plug-in device FCodes. |
input-device |
keyboard |
Console input device (usually keyboard, ttya, or ttyb). |
nvramrc |
empty |
Contents of NVRAMRC. |
oem-banner |
empty string |
Custom OEM banner (enabled by oem-banner? true). |
oem-banner? |
false |
If true, use custom OEM banner. |
oem-logo |
no default |
Byte array custom OEM logo (enabled by oem-logo? true). Displayed in hexadecimal. |
oem-logo? |
false |
If true, use custom OEM logo (else, use Sun logo). |
output-device |
screen |
Console output device (usually screen, ttya, or ttyb). |
screen-#columns |
80 |
Number of on-screen columns (characters/line). |
screen-#rows |
34 |
Number of on-screen rows (lines). |
security-#badlogins |
no default |
Number of incorrect security password attempts. |
security-mode |
none |
Firmware security level (options: none, command, or full). |
security-password |
no default |
Firmware security password (never displayed). |
use-nvramrc? |
false |
If true, execute commands in NVRAMRC during system start-up. |
An dditional configuration variable is defined by the SBus binding to IEEE Standard 1275-1994. The variable is shown in Table 3-2.
Table 3-2 SBus Configuration Variable
Variable |
Typical Default |
Description |
---|---|---|
sbus-probe-list |
0123 |
Which SBus slots to probe and in what order. |
Different OpenBoot implementations may use different defaults and/or different configuration variables.
NVRAM configuration variables can be viewed and changed using the commands listed in Table 3-3.
Table 3-3 Viewing or Changing Configuration Variables
Command |
Description |
---|---|
printenv |
Display current variables and current default values. printenv variable shows the current value of the named variable. |
setenv variable value |
Set variable to the given decimal or text value. (Changes are permanent, but often take effect only after a reset.) |
set-default variable |
Reset the value of variable to the factory default. |
set-defaults |
Reset variable values to the factory defaults. |
password |
Set security-password |
The following pages show how these commands can be used.
Solaris provides the eeprom utility for modifying OpenBoot configuration variables.
To display a list of the current variable settings on your system, type:
ok printenv Variable Name Value Default Value oem-logo 2c 31 2c 2d 00 00 00 00 ... oem-logo? false false oem-banner oem-banner? false false output-device ttya screen input-device ttya keyboard sbus-probe-list 03 0123 diag-file diag-device net net boot-file boot-device disk disk net auto-boot? false true fcode-debug? true false use-nvramrc? false false nvramrc screen-#columns 80 80 screen-#rows 34 34 security-mode none none security-password security-#badlogins 0 diag-switch? true false ok
In the displayed, formatted list of the current settings, numeric variables are often shown in decimal.
To change a variable setting, type:
ok setenv variable-name value
variable-name is the name of the variable. value is a numeric value or text string appropriate to the named variable. A numeric value is interpreted as a decimal number, unless preceded by 0x, which is the qualifier for a hexadecimal number.
For example, to set the auto-boot? variable to false, type:
ok setenv auto-boot? false ok
Many variable changes do not affect the operation of the firmware until the next power cycle or system reset at which time the firmware uses the variable's new value.
You can reset one or most of the variables to the original defaults using the set-default variable and set-defaults commands.
For example, to reset the auto-boot? variable to its default setting (true), type:
ok set-default auto-boot? ok
To reset most variables to their default settings, type:
ok set-defaults ok
On SPARC systems, it is possible to reset the NVRAM variables to their default settings by holding down Stop-N while the machine is powering up. When issuing this command, hold down Stop-N immediately after turning on the power to the SPARC system, and keep it pressed for a few seconds or until you see the banner (if the display is available). This is a good technique to force a SPARC compatible machine's NVRAM variables to a known condition.
The NVRAM system security variables are:
security-mode
security-password
security-#badlogins
security-mode can restrict the set of operations that users are allowed to perform from the User Interface. The three security modes, and their available commands, are listed in the following table in the order of most to least secure.
Table 3-4 Commands Available for security-mode Settings
Mode |
Commands |
---|---|
full |
All commands except for go require the password. |
command |
All commands except for boot and go require the password. |
none |
No password required (default). |
With security-mode set to command:
A password is not required if you type the boot command by itself. However, if you use the boot command with an argument, a password is required.
The go command never asks for a password.
A password is required to execute any other command.
Examples are shown in the following screen.
ok boot (no password required) ok go (no password required) ok boot filename (password required) Password: (password is not echoed as it is typed) ok reset-all (password required) Password: (password is not echoed as it is typed)
It is important to remember your security password and to set the security password before setting the security mode. If you forget this password, you cannot use your system; you must call your vendor's customer support service to make your machine bootable again.
To set the security password and command security mode, type the following at the ok prompt:
ok password ok New password (only first 8 chars are used): ok Retype new password: ok setenv security-mode command ok
The security password you assign must be between zero and eight characters. Any characters after the eighth are ignored. You do not have to reset the system; the security feature takes effect as soon as you type the command.
If you enter an incorrect security password, there will be a delay of about 10 seconds before the next boot prompt appears. The number of times that an incorrect security password is typed is stored in the security-#badlogins variable.
The full security mode is the most restrictive. With security-mode set to full:
A password is required any time you execute the boot command.
The go command never asks for a password.
A password is required to execute any other command.
ok go (no password required) ok boot (password required) Password: (password is not echoed as it is typed) ok boot filename (password required) Password: (password is not echoed as it is typed) ok reset-all (password required) Password: (password is not echoed as it is typed)
It is important to remember your security password and to set the security password before setting the security mode.. If you forget this password, you cannot use your system; you must call your vendor's customer support service to make your machine bootable again.
To set the security password and full security, type the following at the ok prompt:
ok password ok New password (only first 8 chars are used): ok Retype new password: ok setenv security-mode full ok
The banner configuration variables are:
oem-banner
oem-banner?
oem-logo
oem-logo?
To view the power-on banner, type:
ok banner Sun Ultra 1 SBus (UltraSPARC 167 MHz),Keyboard Present PROM Rev. 3.0, 64MB memory installed, Serial # 289 Ethernet address 8:0:20:d:e2:7b, Host ID: 80000121 ok
The banner for your system may be different.
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 variables.
To insert a custom text field in the power-on banner, type:
ok setenv oem-banner Hello Mom and Dad ok setenv oem-banner? true ok banner Hello Mom and Dad ok
The system displays the banner with your new message, as shown in the preceding screen.
The graphic logo is handled differently. oem-logo 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 corner pixel. The next bit controls the pixel to the right of it, and so on.
To create a new logo, first create a Forth array containing the correct data; then copy this array into oem-logo. The array is then installed in oem-logo with $setenv. The example below fills the top half of oem-logo with an ascending pattern.
ok create logoarray d# 512 allot ok logoarray d# 256 0 do i over i + c! loop drop ok logoarray d# 256 " oem-logo" $setenv ok setenv oem-logo? true ok banner
To restore the system's original power-on banner, set the oem-logo? and oem-banner? variables to false.
ok setenv oem-logo? false ok setenv oem-banner? false ok
Because the oem-logo array is so large, printenv displays approximately the first 8 bytes (in hexadecimal). To display the entire array, use the phrase oem-logo dump. The oem-logo array is not erased by set-defaults, since it might be difficult to restore the data. However, oem-logo? is set to false when set-defaults executes, so the custom logo is no longer displayed.
Some systems do not support the oem-logo feature.
The console is used as the primary means of communication between OpenBoot and the user. The console consists of an input device, used for receiving information supplied by the user, and an output device, used for sending information to the user. Typically, the console is either the combination of a text/graphics display device and a keyboard or an ASCII terminal connected to a serial port.
The configuration variables related to the control of the console are:
input-device
output-device
screen-#columns
screen-#rows
You can use these variables to assign the power-on defaults for the console. These values do not take effect until after the next power cycle or system reset.
The input-device and output-device variables control the firmware'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. The values of input-device and output-device must be device specifiers. The aliases keyboard and screen are often used as the values of these variables.
When the system is reset, the named device becomes the initial firmware console input or output device. (If you want to temporarily change the input or output device, use the input or output commands described in Chapter 4, Using Forth Tools)
To set ttya as the initial console input device, type:
ok setenv input-device ttya ok
If you select keyboard for input-device, and the device is not plugged in, input is accepted from a fallback device (typically ttya) after the next power cycle or system reset. If you select screen for output-device, but no frame buffer is available, output is sent to the fall-back device after the next power cycle or system reset.
To specify an SBus frame buffer as the default output device (especially if there are multiple frame buffers in the system), type:
ok setenv output-device /sbus/SUNW,leo ok
The following values represent the typical range of communications characteristics for serial ports:
baud = 110, 300, 1200, 2400, 4800, 9600, 19200, or 38400 bits/second
#bits = 5, 6, 7, or 8 (data bits)
parity = n (none), e (even), or o (odd), parity bit
#stop = 1 (1), . (1.5), or 2 (2) stop bits
rts/cts and xon/xoff handshaking are not implemented on some systems. When a selected protocol is not implemented, the handshake variable is accepted but ignored; no messages are displayed.
You can use the following configuration variable to determine whether or not the system will boot automatically after a power cycle or system reset.
auto-boot?
If auto-boot? is true and if OpenBoot is not in diagnostic mode, the system boots automatically after a power-cycle or system reset using the boot-device and boot-file values.
These variables can also be used during manual booting to select the boot device and the program to be booted. For example, to specify default booting from the network server, type:
ok setenv boot-device net ok
Changes to boot-file and boot-device take effect the next time that boot is executed.
The Power-on Testing variables are:
diag-switch?
diag-device
diag-file
diag-level
Setting diag-switch? to true causes the function diagnostic-mode? to return true. When diagnostic-mode? returns true, the system:
Performs more thorough self tests during any subsequent power-on or system reset process.
May display additional status messages (the details are implementation dependent).
Uses different configuration variables for booting. (For more details on the effects on the boot process, see Chapter 2, Booting and Testing Your System)
Most systems have a factory default of false for the diag-switch? variable. To set diag-switch? to true, type:
ok setenv diag-switch? true ok
Some systems have a hardware diagnostic switch that also cause diagnostic-mode? to return true. Such systems run the full tests at power-on and system reset if either the hardware switch is set or diag-switch? is true.
Some implementations enable you to force diag-switch? to true by using an implementation-dependent key sequence during power-on. Check your system's documentation for details, or see Appendix C, Troubleshooting Guide."
To set diag-switch? to false, type:
ok setenv diag-switch? false ok
When not in diagnostic mode, the system does not announce the diagnostic tests as they are performed (unless a test fails) and may perform fewer tests.
The nvramrc configuration variable whose contents are called the script, can be used to store user-defined commands executed during start-up.
Typically, nvramrc is used by a device driver to save start-up configuration variables, to patch device driver code, or to define installation-specific device configuration and device aliases. It can also be used for bug patches or for user-installed extensions. Commands are stored in ASCII, just as the user would type them at the console.
If the use-nvramrc? configuration variable is true, the script is evaluated during the OpenBoot start-up sequence as shown:
Perform power-on self-test (POST)
Perform system initialization
Evaluate the script (if use-nvramrc? is true)
Execute probe-all (evaluate FCode)
Execute install-console
Execute banner
Execute secondary diagnostics
Perform default boot (if auto-boot? is true)
It is sometimes desirable to modify the sequence probe-all install-console banner. For example, commands that modify the characteristics of plug-in display devices may need to be executed after the plug-in devices have been probed, but before the console device has been selected. Such commands would need to be executed between probe-all and install-console. Commands that display output on the console would need to be placed after install-console or banner.
This is accomplished by creating a custom script which contains either banner or suppress-banner since the sequence probe-all install-console banner is not executed if either banner or suppress-banner is executed from the script. This allows the use of probe-all, install-console and banner inside the script, possibly interspersed with other commands, without having those commands re-executed after the script finishes.
Most User Interface commands can be used in the script. The following cannot:
boot
go
nvedit
password
reset-all
setenv security-mode
The script editor, nvedit, lets you create and modify the script using the commands listed in Table 3-5.
Table 3-5 Commands Affecting NVRAMAC
Command |
Description |
---|---|
nvalias alias device-path |
Stores the command "devalias alias device-path" in the script. The alias persists until either nvunalias or set-defaults is executed. |
$nvalias |
Performs the same function as nvalias except that it takes its arguments, name-string and device-string, from the stack. |
nvedit |
Enters the script editor. If data remains in the temporary buffer from a previous nvedit session, resumes editing those previous contents. If not, reads the contents of nvramrc into the temporary buffer and begins editing it. |
nvquit |
Discards the contents of the temporary buffer, without writing it to nvramrc. Prompts for confirmation. |
nvrecover |
Recovers the contents of nvramrc if they have been lost as a result of the execution of set-defaults; then enters the editor as with nvedit. nvrecover fails if nvedit is executed between the time that the nvramrc contents were lost and the time that nvrecover is executed. |
nvrun |
Executes the contents of the temporary buffer. |
nvstore |
Copies the contents of the temporary buffer to nvramrc; discards the contents of the temporary buffer. |
nvunalias alias |
Deletes the specified alias from nvramrc. |
$nvunalias |
Performs the same function as nvunalias except that it takes its argument, name-string, from the stack. |
The editing commands shown in Table 3-6 are used in the script editor.
Table 3-6 Script Editor Keystroke Commands
Keystroke |
Description |
---|---|
Control-B |
Moves backward one character. |
Escape B |
Moves backward one word. |
Control-F |
Moves forward one character. |
Escape F |
Moves forward one word. |
Control-A |
Moves backward to beginning of the line. |
Control-E |
Moves forward to end of the line. |
Control-N |
Moves to the next line of the script editing buffer. |
Control-P |
Moves to the previous line of the script editing buffer. |
Return (Enter) |
Inserts a new line at the cursor position and advances to the next line. |
Control-O |
Inserts a newline at the cursor position and stays on the current line. |
Control-K |
Erases from the cursor position to the end of the line, storing the erased characters in a save buffer. If at the end of a line, joins the next line to the current line (i.e. deletes the newline). |
Delete |
Erases the previous character. |
Backspace |
Erases the previous character. |
Control-H |
Erases the previous character. |
Escape H |
Erases from beginning of word to just before the cursor, storing erased characters in a save buffer. |
Control-W |
Erases from beginning of word to just before the cursor, storing erased characters in a save buffer. |
Control-D |
Erases the next character. |
Escape D |
Erases from the cursor to the end of the word, storing the erased characters in a save buffer. |
Control-U |
Erases the entire line, storing the erased characters in a save buffer. |
Control-Y |
Inserts the contents of the save buffer before the cursor. |
Control-Q |
Quotes the next character (i.e. allows you to insert control characters). |
Control-R |
Retypes the line. |
Control-L |
Displays the entire contents of the editing buffer. |
Control-C |
Exits the script editor, returning to the OpenBoot command interpreter. The temporary buffer is preserved, but is not written back to the script. (Use nvstore afterwards to write it back.) |
Use the following steps to create and activate the script:
Edit the script using editor commands.
If you have not yet typed nvstore to save your changes, you may type nvrun to execute the contents of the temporary edit buffer.
Type nvstore to save your changes.
Enable the interpretation of the script by typing:
setenv use-nvramrc? true
Type reset-all to reset the system and execute the script, or type:
nvramrc evaluate
to execute the contents directly.
The following example shows you how to create a simple colon definition in the script.
ok nvedit 0: : hello ( -- ) 1: ." Hello, world. " cr 2: ; 3: ^C ok nvstore ok setenv use-nvramrc? true ok reset-all ... ok hello Hello, world. ok
Notice the nvedit line number prompts (0:, 1:, 2:, 3:) in the above example. These prompts are system-dependent.