The machine device driver provides an interface to platform-specific hardware for the system configuration and reliability, availability, and serviceability (RAS) subsystems. The machine device driver supports these special files for accessing this hardware from user mode: /dev/nvram and /dev/bus0 ... /dev/busN where N is the bus number. The /dev/nvram special file provides access to special nonvolatile random access memory (RAM) for the purposes of storing or retrieving error information and system boot information. The /dev/busN special files provide access to the I/O buses for system configuration and diagnostic purposes. The presence and use of this device driver and its associated special files are platform-specific and should not be used by general applications.
A program must have the appropriate privilege to open special files /dev/nvram or /dev/busN. For AIX 4.2.1 and later, it must also have the appropriate privilege to open Common Hardware Reference Platform (CHRP) bus special files /dev/pciN, or /dev/isaN.
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.
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 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 containing the base customize information is freed. Subsequent opens will return an ENOENT error code.
The write subroutine is not supported and will return 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 associated with the specified channel. The transfer starts at the offset (within the channel's data area) specified by the offset field 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.
The following ioctl operations can be issued to the machine device driver after a successful open of the /dev/nvram/ special file:
The following four ioctl operations can be used only with the POWER-based architecture. If used with other systems, or if an illegal offset address, size, or slot number is supplied, these operations return an EINVAL error code.
These ioctls can be called from user space or kernel space (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 will be obtained to serialize access to the bus slot configuration register.
This ioctl allows read access to VPD/ROM address space.
The following structure members must be supplied:
The read begins at base address 0xFFA00000. The offset will be added to the base address to obtain the starting address for reading.
The buc_info structure for the selected bus slot will be used to obtain the word increment value. This value performs correct addressing while reading the data.
This ioctl allows read access to the architected configuration registers.
The following structure members must be supplied:
The base address 0xFF200000 will be added to the offset to obtain the address for the read.
This ioctl allows write access to the architected configuration registers.
The following structure members must be supplied:
The base address 0xFF200000 will be added to the offset to obtain the address for the read.
This ioctl 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.
The following four ioctl operations can be used only with the PowerPC Reference Platform and, in AIX 4.2.1 and later, the Common Hardware Reference Platform.
Scans for the variable name in the Global Environment Area, and, if found, the null terminated string will be 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 will be returned.
The following structure members must be supplied:
The specified global variable will be 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 will replace the old after making adjustments for any size deltas. Further, any information moved toward a lower address will have the original area zeroed. If there is no string following the variable name and equal sign, the specified variable will be deleted. If the variable to be deleted is not found, a successful return will occur. The new information will be written to NVRAM. Further, the header in NVRAM will be updated to include the update time of the Global Environment Area and the Crc1 value will be recomputed.
The following structure members must be supplied:
The specified threshold will be set so that any updates done will not exceed the Global Environment Area size minus the threshold. In place of the the mdio structure an integer value is used to specify the threshold. The threshold does not persist across IPLs.
The attributes of the Global Environment Area will be returned to the data area specified by the caller. The gea_attrib structure has been added to mdio.h. It contains the following information:
The length of the CHRP NVRAM partition will be returned to the data area specified by the caller. The following structure members must be supplied:
| Structure Member | Description |
|---|---|
| ulong md_addr | Specifies the partition signature. |
| ulong *md_length | Specifies a pointer to the name of the partition. |
| int md_incr | Not used. |
| ulong md_size | Specifies the data area for the returned partition length. |
| char *md_data | Not used. |
| int md_sla | Not used. |
MIONVPARTRD performs read actions on CHRP NVRAM partitions. The following structure members must be supplied:
| Structure Member | Description |
|---|---|
| ulong md_addr | Specifies the partition signature. |
| ulong *md_length | Specifies a pointer to the name of the partition. |
| int md_incr | Specifies the start offset into the partition. |
| ulong md_size | Specifies the number of bytes to be read. |
| char *md_data | Specifies a pointer to the user buffer where data will be copied. |
| int md_sla | Not used. |
MIONVPARTUPD performs write actions to CHRP NVRAM partitions. The following structure members must be supplied:
| Structure Member | Description |
|---|---|
| ulong md_addr | Specifies the partition signature. |
| ulong *md_length | Specifies a pointer to the name of the partition. |
| int md_incr | Specifies the start offset into the partition. |
| ulong md_size | Specifies the number of bytes to be read. |
| char *md_data | Specifies a pointer to the user buffer for data to write. |
| int md_sla | Not used. |
The following error conditions may be returned when accessing the machine device driver with the /dev/nvram/n special file:
All models have at least one bus. For non-CHRP systems, the names are of the form /dev/busN. CHRP systems will have the form /dev/pciN and /dev/isaN.
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 diagnostics are unable to access a device through the diagnostic functions provided by the device's own device driver, they may use the machine device driver to attempt further failure isolation.
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.
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 following commands can be issued to the machine device driver after a successful open of the bus special file:
The close subroutine, ioctl subroutine, lseek subroutine, open subroutine, read subroutine, write subroutine.
The savebase device configuration command.
The bus special file, nvram special file.