Machine Device Driver

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.

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

read and write Subroutines

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.

ioctl Operations

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

Operation	Description
IOCINFO	Returns machine device driver information in the caller's devinfo structure (pointed to 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.
MIOGETKEY	Returns the status of the keylock. The arg parameter should point to a mach_dd_io structure. The `md_data` field should point to an integer; this contains the status of the keylock on return. Note: Not all platforms have a physical keylock that software can read. For these platforms, status is established at boot time.
MIOGETPS	Returns the power status. The arg parameter should point to a mach_dd_io structure. The `md_data` field should point to an integer; this contains the power status on return. Note: Not all platforms provide power status.
MIOIPLCB	Returns the contents of the boot control block. The arg parameter is set to point to a mach_dd_io structure, which describes the data area where the boot control block is to be placed. The format of this control block is specified in the /usr/include/sys/iplcb.h file and the mach_dd_io structure is defined in the /usr/include/sys/mdio.h file. This ioctl operation uses the following fields in the mach_dd_io structure: `md_data` Points to a buffer at least the size of the value in the `md_size` field. `md_size` Specifies the size (in bytes) of the buffer pointed to by the `md_data` field and is the number of bytes to be returned from the boot control block. `md_addr` Specifies an offset into the boot control block where data is to be obtained. Note: Regions within this control block are platform dependent.
MIONVGET	Reads data from an NVRAM address and returns data in the buffer provided by the caller. This is useful for reading the ROS area of NVRAM. A structure defining this area is in the /usr/include/sys/mdio.h file. Use of this ioctl operation is not supported for systems that are compliant with the PowerPC Reference Platform or the Common Hardware Reference Platform and, in AIX® 4.2.1 and later, cause the operation to fail with an EINVAL error code.
MIONVLED	Writes the value found in the arg parameter to the system front panel LED display. On this panel, three digits are available and the arg parameter value can range from 0 to hex FFF. An explanation of the LED codes can be found in the /usr/include/sys/mdio.h file. Note: Not all platforms have an LED.
MIONVPUT	Writes data to an NVRAM address from the buffer provided by the caller. This operation is used only to update the ROS area of NVRAM and only by system commands. Use of this operation in other areas of NVRAM can cause unpredictable results to occur. If the NVRAM address provided is within the ROS area, a new cyclic redundancy code (CRC) for the ROS area is generated. Use of this ioctl operation is not supported on systems that are compliant with the PowerPC Reference Platform or the Common Hardware Reference Platform and, in AIX® 4.2.1 and later, cause the operation to fail with an EINVAL error code.

ioctl Operations for POWER® processor-based Systems

The following four ioctl operations can be used only with the POWER® processor-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.

MIOVPDGET

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

The following structure members must be supplied:

Structure Member	Description
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.

MIOCFGGET

This ioctl allows read access to the architected configuration registers.

The following structure members must be supplied:

Structure Member	Description
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.

MIOCFGPUT

This ioctl allows write access to the architected configuration registers.

The following structure members must be supplied:

Structure Member	Description
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.

MIORESET

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

The following structure members must be supplied:

Structure Member	Description
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.

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, in AIX® 4.2.1 and later, the Common Hardware Reference Platform.

MIOGEARD

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:

Structure Member	Description
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.

MIOGEAUPD

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:

Structure Member	Description
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.

MIOGEAST

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.

MIOGEARDA

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:

Structure Member	Description
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.

MIONVPARTLEN

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

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

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.

Error Codes

The following error conditions may be returned when accessing the machine device driver with the /dev/nvram/n special file:

Error Condition	Description
EACCES	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.

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

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:

Command	Description
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.
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.
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.

Error Codes

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.

Files

/dev/pciN	Provides access to the I/O bus (CHRP only, AIX® 4.2.1 and later).
/dev/isaN	Provides access to the I/O bus (CHRP only, AIX® 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.

Related Information

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.

[ Top of Page | Previous Page | Next Page | Index | Feedback ]