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 versions 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 PowerPC 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.
The following four ioctl operations can be used only with the PowerPC/Micro Channel systems. 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:
| ulong md_addr | Specifies the offset into the feature/VPD address space to begin reading. |
| ulong md_size | Specifies the number of bytes to be transferred. |
| char md_data | Specifies a pointer to user buffer for data. |
| int md_sla | Specifies a slot number (bus slot configuration select). |
| int md_incr | Requires byte access (MV_BYTE). |
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:
| ulong md_addr | Specifies the offset into the configuration register address space. |
| ulong md_size | Specifies a value of 1. |
| char md_data | Specifies a pointer to user buffer for data. |
| int md_sla | Specifies a slot number (bus slot configuration select). |
| int md_incr | Requires byte or word access (MV_BYTE/MV_SHORT/MV_WORD). |
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:
| ulong md_addr | Specifies the offset into the configuration register address space. |
| ulong md_size | Specifies a value of 1. |
| char md_data | Specifies a pointer to user buffer of data to write. |
| int md_sla | Specifies a slot number (bus slot configuration select). |
| int md_incr | Requires byte or word access (MV_BYTE/MV_SHORT/MV_WORD). |
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:
| ulong md_addr | Specifies reset hold time (in nanoseconds). |
| ulong md_size | Not used. |
| char md_data | Not used. |
| int md_sla | Specifies a slot number (bus slot configuration select). |
| int md_incr | Not used. |
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 versions 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:
| ulong md_addr | Pointer to global variable string which is null terminated with an equal sign as the last non-null character. |
| ulong md_size | Number of bytes in data buffer. |
| int md_incr | Not used. |
| char md_data | Pointer to the data buffer. |
| int md_sla | Not used. |
| ulong md_length | This is a pointer to the length of the returned global variable string(s) including the null terminator(s) if md_length is non-zero. |
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:
| ulong md_addr | Pointer to global variable string which is null terminated. |
| ulong md_size | Not used. |
| int md_incr | Not used. |
| char md_data | Not used. |
| int md_sla | Not used. |
| ulong md_length | This is a pointer to the amount of space left in the Global Environment Area after the update. This is computed as the size of the area minus the length of all global variable strings minus the threshold value. |
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:
| long gea_length | number of bytes in the Global Environment Area of NVRAM. |
| long gea_used | number of bytes used in the Global Environment Area. |
| long gea_thresh | Global Environment Area threshold value. |
| ulong md_addr | Not used. |
| ulong md_size | Size of the data buffer. It must be greater than or equal to the size of (gea_attrib). |
| int md_incr | Not used. |
| char md_data | Address of the buffer to copy the gea_attrib structure. |
| int md_sla | Not used. |
| ulong md_length | Not used. |
The following error conditions may be returned when accessing the machine device driver with the /dev/nvram/n special file:
| EACCESS | A write was requested to a file opened for read access only. |
| ENOENT | An open of /dev/nvram/base was attempted after the first close. |
| EFAULT | A buffer specified by the caller was invalid on a read, write, or ioctl subroutine call. |
| EINVAL | An invalid ioctl operation was issued. |
| ENXIO | A read was attempted past the end of the data area specified by the channel. |
| ENODEV | A write was attempted. |
| ENOMEM | A request was made with a user-supplied buffer that is too small for the requested data or not enough memory could be allocated to complete the request. |
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:
| IOCINFO | Returns machine device driver information in the caller's devinfo structure, as specified by the arg parameter. This structure is defined in the /usr/include/sys/devinfo.h file. The device type for this device driver is DD_PSEU. |
| MIOBUSGET | Reads data from the bus I/O space and returns it in a caller-provided buffer. |
| MIOBUSPUT | Writes data supplied in the caller's buffer to the bus I/O space.
Note: On Micro Channel systems, the ioctlx subroutine can be used to access other buses. In this case, the ext parameter specifies the bus identification value used. |
| MIOMEMGET | Reads data from the bus memory space and returns it to the caller-provided buffer. |
| MIOMEMPUT | Writes data supplied in the caller-provided buffer to the bus memory space. |
| MIOCCGET | Reads data from the Micro Channel I/O controller and returns it in a caller-provided buffer. |
| MIOCCPUT | Writes data supplied in the caller's buffer to the Micro Channel I/O controller. |
| MIOPCFGET | Reads data from the PCI bus configuration space and returns it in a caller-provided buffer. The mach_dd_io structure field md_sla must contain the Device Number and Function Number for the device to be accessed. |
| MIOPCFPUT | Writes data supplied in the caller's buffer to the PCI bus configuration space. The mach_dd_io structure field md_sla must contain the Device Number and Function Number for the device to be accessed. |
| EFAULT | A buffer specified by the caller was invalid on an ioctl call. |
| EIO | An unrecoverable I/O error occurred on the requested data transfer. |
| ENOMEM | No memory could be allocated by the machine device driver for use in the data transfer. |
| /dev/busN | Provides access to the I/O bus. |
| /dev/pciN | Provides access to the I/O bus (CHRP only, versions 4.2.1 and later). |
| /dev/isaN | Provides access to the I/O bus (CHRP only, versions 4.2.1 and later). |
| /dev/nvram | Provides access to platform-specific nonvolatile RAM. |
| /dev/nvram/base | Allows read access to the base customize information stored as part of the boot record. |
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.