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
for information about entering the user interface.

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

Note - 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 s
et-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.

Setting Security Variables

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).

Command Security

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)

Caution - 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.

Full Security

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.

Here are some examples.

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
)

Caution - 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:

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.

Note - Some systems do not support the oem-logo feature.

Input and Output Control

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.

Selecting Input and Output Device Options

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
)

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

Serial Port Characteristics

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

Note - 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.

Selecting Boot Options

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.

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
)

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

Note - 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.

Note - 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."

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.

Using nvramrc

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

Editing the Contents of the Script

The script editor,
nvedit
, lets you create and modify the script using the commands listed in
.

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
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.)

Activating the Script

Use the following steps to create and activate the script:

At the
ok
prompt, type
nvedit.

Edit the script using editor commands.

Type
Control-C
to get out of the editor and back to the
ok
prompt.

If you have not yet typed
nvstore
to save your changes, you may type
nvrun
to execute the contents of the temporary edit buffer.

1. Type
nvstore
to save your changes.

2. Enable the interpretation of the script by typing:

setenv use-nvramrc? true

3. 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.