Machine Device Driver

Driver Initialization and Termination

Special initialization and termination requirements do not exist for the machine device driver. This driver is statically bound to the operating system kernel and is initialized during kernel initialization. This device driver does not support termination and cannot be unloaded.

/dev/nvram Special File Support

open and close Subroutines

The machine device driver supports the /dev/nvram special file as a multiplexed character special file. This special file and the support for NVRAM is provided exclusively on this hardware platform to support the system configuration and RAS subsystems. These subsystems open the /dev/nvram/n special file with a channel name, n, specifying the data area to be accessed. An exception is the /dev/nvram file with no channel specified, which provides access to general NVRAM control functions and the LED display on the front panel.

A special channel name of base can be used to read the base customize information that is stored as part of the boot record. This information was originally copied to the disk by the savebase command and is only copied by the driver at boot time. The base customize information can be read only once. When the /dev/nvram/base file is closed for the first time, the buffer that contains the base customize information is freed. Subsequent opens return an ENOENT error code.

read and write Subroutines

The write subroutine is not supported and returns an ENODEV error code. The read subroutine is supported after a successful open of the base channel only. The read subroutine transfers data from the data area that is associated with the specified channel. The transfer starts at the offset (within the channel's data area) specified by the offset field that is associated with the file pointer used on the subroutine call.

On a read subroutine, if the end of the data area is reached before the transfer count is reached, the number of bytes read before the end of the data area was reached is returned. If the read subroutine starts at the end of the data area, zero bytes are read. If the read subroutine starts after the end of the data area, an ENXIO error code is returned by the driver.

The lseek subroutine can be used to change the starting data-area offset to be used on a subsequent read call.

ioctl Operations

The following ioctl operations can be issued to the machine device driver after a successful open of the /dev/nvram/ special file:

ioctl Operations for Systems

The following four ioctl operations can be used only with the POWER® processor-based architecture. If used with other systems, or if an invalid offset address, size, or slot number is supplied, these operations return an EINVAL error code.

These ioctl operations can be called from user space or kernel space (by using the fp_ioctl kernel service), but they are available only in the process environment.

The ioctl argument must be a pointer to a mach_dd_io structure.

The lock is obtained to serialize access to the bus slot configuration register.

MIOVPDGET

This ioctl operation allows read access to VPD/ROM address space.

The following structure members must be supplied:

The read begins at base address 0xFFA00000. The offset is added to the base address to obtain the starting address for reading.

The buc_info structure for the selected bus slot is used to obtain the word increment value. This value performs correct addressing when it reads the data.

MIOCFGGET

This ioctl operation allows read access to the architected configuration registers.

The following structure members must be supplied:

The base address 0xFF200000 is added to the offset to obtain the address for the read.

MIOCFGPUT

This ioctl operation allows write access to the architected configuration registers.

The following structure members must be supplied:

The base address 0xFF200000 is added to the offset to obtain the address for the read.

MIORESET

This ioctl operation allows access to the architected bus slot reset register.

The following structure members must be supplied:

The bus slot reset register bit corresponding to the specified bus slot is set to 0. After the specified delay, the bit is set back to 1 and control returns to the calling program.

If a reset hold time of 0 is passed, the bus slot remains reset on return to the calling process.

ioctl Operations for the PowerPC® Reference Platform Specification and the Common Hardware Reference Platform

The following four ioctl operations can be used only with the PowerPC Reference Platform and the Common Hardware Reference Platform.

MIOGEARD

Scans for the variable name in the Global Environment Area, and, if found, the null terminated string is returned to the caller. A global variable is of the form "variablename=". The returned string is of the form "variablename=string". If the supplied global variable is "*=", all of the variable strings in the Global Environment Area is returned.

The following structure members must be supplied:

MIOGEAUPD

The specified global variable is added to the Global Environment Area if it does not exist. If the specified variable does exist in the Global Environment Area, the new contents replace the old after adjusting any size deltas. Further, any information that is moved toward a lower address has the original area zeroed. If there is no string that follows the variable name and equal sign, the specified variable is deleted. If the variable to be deleted is not found, a successful return occurs. The new information is written to NVRAM. Further, the header in the NVRAM operation is updated to include the update time of the Global Environment Area and the CRC value are recomputed.

The following structure members must be supplied:

MIOGEAST

The specified threshold is set so that any updates done do not exceed the Global Environment Area size minus the threshold. In place of the mdio structure an integer value is used to specify the threshold. The threshold does not persist across IPLs.

MIOGEARDA

The attributes of the Global Environment Area are returned to the data area specified by the caller. The gea_attrib structure is added to mdio.h. It contains the following information:

MIONVPARTLEN

The length of the CHRP NVRAM partition is returned to the data area specified by the caller. The following structure members must be supplied:

MIONVPARTRD

MIONVPARTRD performs read actions on CHRP NVRAM partitions. The following structure members must be supplied:

MIONVPARTUPD

MIONVPARTUPD performs write actions to CHRP NVRAM partitions. The following structure members must be supplied:

Error Codes

The following error conditions might be returned when you access the machine device driver with the /dev/nvram/n special file:

Bus Special File Support

All models have at least one bus. For non-CHRP systems, the names are of the form /dev/busN. CHRP systems have the form /dev/pciN and /dev/isaN.

open and close Subroutines

The machine device driver supports the bus special files as character special files. These special files, and support for access to the I/O buses and controllers, are provided on this hardware platform to support the system configuration and diagnostic subsystems, exclusively. The configuration subsystem accesses the I/O buses and controllers through the machine device driver to determine the I/O configuration of the system. This driver can also be used to configure the I/O controllers and devices as required for proper system operation. If the system diagnostic tests are unable to access a device through the diagnostic functions that are provided by the device's own device driver, they might use the machine device driver to attempt further failure isolation.

read and write Subroutines

The read and write subroutines are not supported by the machine device driver through the bus special files and, if called, return an ENOENT return code in the errno global variable.

ioctl Operations

The bus ioctl operations allow transfers of data between the system I/O controller or the system I/O bus and a caller-supplied data area. Because these ioctl operations use the mach_dd_io structure, the arg parameter on the ioctl subroutine must point to such a structure. The bus address, the pointer to the caller's buffer, and the number and length of the transfer are all specified in the mach_dd_io structure. The mach_dd_io structure is defined in the /usr/include/sys/mdio.h file and provides the following information:

• The md_addr field contains an I/O controller or I/O bus address.
• The md_data field points to a buffer at least the size of the value in the md_size field.
• The md_size field contains the number of items to be transferred.
• The md_incr field specifies the length of the transferred item. It must be set to MV_BYTE, MV_SHORT, or MV_WORD.

The following commands can be issued to the machine device driver after a successful open of the bus special file:

Error Codes

Files