This chapter describes the requirements relating to Non-Volatile Memory. Non-Volatile Memory is the repository for system information that must be persistent across reboots and power cycles.

R1--1. Platforms must implement at least 8 KB of Non-Volatile Memory. The actual amount is platform dependent and must allow for 4 KB for the OS. Platforms must provide an additional 4 KB for each installed OS beyond the first. R1--2. Non-Volatile Memory must maintain its contents in the absence of system power. R1--3. Firmware must reinitialize NVRAM to a bootable state if NVRAM data corruption is detected. R1--4. OSs must reinitialize their own NVRAM partitions if NVRAM data corruption is detected. OSs may create free space from the first corrupted NVRAM partition header to the end of NVRAM and utilize this area to initialize their NVRAM partitions. Hardware Implementation Note: The NVRAM terminology used in this chapter goes back to historic implementations that have used battery-powered RAM to implement the non-volatile memory. It should be understood that this is not the only possible implementation. Implementers need to understand that there are no limits on the frequency of writing to the non-volatile memory, so certain technologies may not be applicable. Also, it should be noted that the nvram-fetch and nvram-store RTAS calls do not allow a “busy” Status return, and this may further limit the implementation choices. Software Implementation Note: Refer to for information on accessing NVRAM.

NVRAM is formatted as a set of NVRAM partitions that adhere to the structure in . NVRAM partitions are prefixed with a header containing signature, checksum, length, and name fields. The structure of the data field is defined by the NVRAM partition creator/owner (designated by signature and name). R1--1. NVRAM partitions must be structured as shown in . R1--2. All NVRAM space must be accounted for by NVRAM partitions. R1--3. All IBM-defined NVRAM partitions that are intended to be IBM-unique must have names prefixed with the ASCII representation of the four characters: ibm,. Software Implementation Note: Although the data areas of NVRAM partitions are not required to have error checking, it is strongly recommended that the system software implement robust data structures and error checking. Loss of NVRAM structures due to data corruption can be catastrophic, potentially leading to OS reinstallation and/or complete system initialization.

The signature field is used as the first level of NVRAM partition identification. lists all the currently defined signature types and their ownership classes. The ownership class determines the permission of a particular system software component to create and/or modify NVRAM partitions and/or NVRAM partition contents. All NVRAM partitions may be read by any system software component, but the ownership class has exclusive write permission. Global ownership gives read/write permission to all system software components. These restrictions are made to minimize the possibility of corruption of NVRAM during update activities. Hardware and Software Implementation Note: It is recommended that NVRAM partitions be ordered on the signature field with the lowest value signature NVRAM partition at the lowest NVRAM address (with the exception of signature = 0x7F, free space). This will minimize the effect of NVRAM data corruption on system operation. Field Name Size Description signature 1 byte The signature field is used to identify the NVRAM partition type and provide some level of checking for overall NVRAM contamination. Signature assignments are given in . checksum 1 byte The checksum field is included to provide a check on the validity of the header. The checksum covers the signature, length, and name fields and is calculated (on a byte by byte or equivalent basis) by: add, and add 1 back to the sum if a carry resulted as demonstrated with the following program listing. This checksum algorithm guarantees 0 to be an impossible calculated value. A valid header cannot have a checksum of zero. length 2 bytes The length field designates the total length of the NVRAM partition, in 16-byte blocks, beginning with the signature and ending with the last byte of the data area. A length of zero is invalid. Software Implementation Note: The length field must always provide valid offsets to the next header since an invalid length effectively causes the loss of access to every NVRAM partition beyond it. name 12 bytes The name field is a 12 byte string (or a NULL-terminated string of less than 12 bytes) used to identify a particular NVRAM partition within a signature group. In order to reduce the likelihood of a naming conflict, each platform-specific or OS-specific NVRAM partition name should be prefixed with a company name as specified under the description of the “name” string in the , that is, a company name string in one of the three forms described in the reference, followed by a comma (“,”). If the company name string is null, the name will be interpreted as “other”. Before assigning a new name to a NVRAM partition, software should scan the existing NVRAM partitions and ensure that an unwanted name conflict is not created. data length minus 16 bytes The structure of the data area is controlled by the creator/owner of the NVRAM partition. Signature (see note) Signature Type Ownership Class # Required Description 0x70 System Global 1 For configuration variables. 0x7E Vendor-defined Global 0 to n “name” prefix required. 0x7F Free Space Global 0 to n This signature is used to mark free space in the NVRAM array. The name field of all signature 0x7F NVRAM partitions must be set to 0x7...77. 0xA0 OS Any OS 0 to n General OS usage. Note: Any signature not defined above is reserved, and signatures 0x02, 0x50, 0x51, 0x52, 0x71, and 0x72 are reserved for legacy reasons.

System NVRAM partitions are used for storing information (typically, configuration variables) accessible to both OF and the OS. Refer to for the definition of the contents of the System NVRAM partition named common. R1--1. Every system NVRAM must contain a System NVRAM partition with the NVRAM partition name = common. R1--2. Data in the common NVRAM partition must be stored as NULL-terminated strings of the form: <name>=<string> and the data area must be terminated with at least two NULL characters. R1--3. All names used in the common NVRAM partition must be unique. R1--4. Device and file specifications used in the common NVRAM partition must follow IEEE Std 1275 nomenclature conventions.

The System NVRAM partition, with name = common, contains information that is accessible to both OF and OSs. The contents of this NVRAM partition are represented in the OF device tree as properties (i.e., (name, value) pairs) in the /options node. While OF is available, the OS can alter the contents of these properties by using the setprop client interface service. When OF is no longer available, the OS can alter the contents of the System NVRAM partition itself, following the rules below for the formats of the name and value. Information is stored in the System NVRAM partition as a sequence of (name, value) pairs in the following format: name = value where name follows the rules defined in and value follows the rules defined in . The end of the sequence of pairs is denoted by a NULL (0x00) byte.

Since the data in the System NVRAM partition is an external representation of properties of the /option node, the name component must follow the rules for property names as defined by Section 3.2.2.1.1 Property names of ; i.e., a string of 1-31 printable characters containing no uppercase characters or the characters “/”, “\”, “:”, “[“, “]” or “@”. In addition to these rules, a naming convention is required for OS specific names to avoid name conflicts. Each such name must begin with the OS vendor’s OUI followed by a “,”; e.g., aapl,xxx or ibm,xxx. This introduces separate name spaces for each vendor in which it manages its own naming conventions.

The value component of System NVRAM partition data can contain an arbitrary number of bytes in the range 0x01 to 0xFF, terminated by a NULL (0x00) byte. Bytes in the range 0x01 to 0xFE represent themselves. In order to allow arbitrary byte data to be represented, an encoding is used to represent strings of 0x00 or 0xFF bytes. This encoding uses the 0xFF byte as an escape, indicating that the following byte is encoded as: bnnnnnnn where b, the most-significant bit, is 0 to represent a sequence of 0x00 bytes or 1 to represent a sequence of 0xFF bytes. nnnnnnn, the least-significant 7 bits, is a binary number (in the range 0x01 to 0x7F) that represents the number of repetitions of 0x00 or 0xFF.

OF configuration variables control the operation of OF. In addition to the standard configuration variables defined in , other configuration variables are defined in . While such variables are stored in the System NVRAM partition as described above, they have additional rules placed on the format of the value component. Each configuration variable is also represented by a user interface word (of the same name) that returns stack value(s) when that word is evaluated. Each also has a platform defined default value; the absence of a configuration variable in the System NVRAM partition indicates that the value is set to its default value. The format of the external representation of configuration variables, and their stack representation, is defined by Section 7.4.4.1 Configuration Variables of ; the format depends upon the data type of the configuration variable. Whereas the internal storage format is not defined by , this architecture specifies them as described below. The names of configuration variables are defined in , except as noted otherwise.

The value of a boolean configuration variable is represented in the System NVRAM partition as the string “true” or “false”. The following configuration variables are of type boolean: auto-boot? diag-switch? fcode-debug? oem-banner? oem-logo? use-nvramrc? little-endian? real-mode? menu? (see ).

The value of an integer configuration variable is represented in the System NVRAM partition as a decimal number or a hexadecimal number preceded by “0x”. The following configuration variables are of type integer: screen-#columns screen-#rows security-#badlogins security-mode selftest-#megs real-base real-size virt-base virt-size load-base

The value of a string configuration variable is represented in the System NVRAM partition as the characters of the string. Where multiple “lines” of text are represented, each line is terminated by a carriage-return (0x0D), a line-feed (0x0A), or carriage-return, line-feed sequence (0x0D, 0x0A). The following configuration variables are of type string: boot-command [1] boot-device [1] boot-file [1] diag-device [1] diag-file [1] input-device [1] nvramrc [1] oem-banner [1] output-device [1] security-password [1] bootinfo-nnnnn [*] reboot-command [*] ibm,shadow-boot-device [1] ibm,last-booted [1]

The value of a bytes configuration variable is represented by an arbitrary number of bytes, using the encoding escape for values of 0x00 and 0xFF. The following configuration variables are of type bytes: oem-logo [1]

In order to reduce the boot time of platforms, a configuration variable is defined to communicate from the platform to the OS to what extent spin-up of hard disk drives can be overlapped. Disk drives generally draw more current as the motors spin up to operating speed, thus the capacity of the power supply limits the ability to spin up drives simultaneously. The configuration variable ibm,dasd-spin-interval indicates the minimum time, in seconds, that must be allowed between initiating the spin-up of hard disk drives on the platform. Presence of this variable potentially allows starting up a drive prior to receiving completion status from a drive previously started. The absence of this variable implies no platform knowledge regarding the capability to overlap and, hence, the OS should wait for the appropriate device status before proceeding to subsequent drives (no overlap). R1--1. If a platform wants to overlap spinning up it's hard disk drives to improve boot performance, it must create the ibm,dasd-spin-interval OF configuration variable in the NVRAM signature 0x70 NVRAM partition named common and set it equal to an integer that represents the minimum time, in seconds, that must be allowed between initiating the spin-up of drives on the platform. Firmware Implementation Note: The platform should provide a user-friendly interface to this variable to allow for the possibility of a user installing hard disks that do not conform to the original setting of the variable.

R1--1. All unused NVRAM space must be included in a signature = 0x7F Free Space NVRAM partition. R1--2. All Free Space NVRAM partitions must have the name field set to 0x7...77.

The only NVRAM partitions whose size an OS can modify are OS and Free Space signature NVRAM partitions. As NVRAM partitions are created and modified by an OS, it is likely that free space will become fragmented; free space consolidation may become necessary. R1--1. An OS must not move or delete any NVRAM partition, except OS and Free Space signature NVRAM partitions. R1--2. The NVRAM partition header checksum must be calculated as shown in .