This article describes how a Configure device method works. It also suggests guidelines for programmers writing their own Configure device configuration methods.
The Configure method moves a device from Defined (not available for use in the system) to Available (available for use in the system). If the device has a driver, the Configure method loads the device driver into the kernel and describes the device characteristics to the driver. For an intermediate device (such as a SCSI bus adapter), this method determines which attached child devices are to be configured and writes their logical names to standard output.
The Configure method is invoked by either the mkdev configuration command or by the Configuration Manager. Because the Configuration Manager runs a second time in phase 2 system boot and can also be invoked repeatedly at run time, a device's Configure method can be invoked to configure an Available device. This is not an error condition. In the case of an intermediate device, the Configure method checks for the presence of child devices. If the device is not an intermediate device, the method simply returns.
In general, the Configure method obtains all the information it needs about the device from the Configuration database. The options specifying the phase of system boot are used to limit certain functions to specific phases.
If the device has a parent device, the parent must be configured first. The Configure method for a device fails if the parent is not in the Available state.
By convention, the first three characters of the name of the Configure method are cfg. The remainder of the name (Dev) can be any characters, subject to operating system file-name restrictions, that identify the device or group of devices that use the method.
|-l Name||Identifies the logical name of the device to be configured.|
|-1||Specifies that the device is being configured in phase 1 of the system boot. This option cannot be specified with the -2 flag. If neither the -1 nor the -2 flags are specified, the Configure method is invoked at runtime.|
|-2||Specifies that the device is being configured in phase 2 of the system boot. This option cannot be specified with the -1 flag. If neither the -1 nor the -2 flags are specified, the Configure method is invoked at runtime.|
Devices that provide vital product data (VPD) are identified in the Predefined Device (PdDv) object class by setting the VPD flag descriptor to TRUE in each of the device's PdDv objects. The Configure method must obtain the VPD from the device and store it in the Customized VPD (CuVPD) object class. Consult the appropriate hardware documentation to determine how to retrieve the device's VPD. In many cases, VPD is obtained from the device driver using the sysconfig subroutine.
Once the VPD is obtained from the device, the Configure method queries the CuVPD object class to see if the device has hardware VPD stored there. If so, the method compares the VPD obtained from the device with that from the CuVPD object class. If the VPD is the same in both cases, no further processing is needed. If they are different, update the VPD in the CuVPD object class for the device. If there is no VPD in the CuVPD object class for the device, add the device's VPD.
By first comparing the device's VPD with that in the CuVPD object class, modifications to the CuVPD object class are reduced. This is because the VPD from a device typically does not change. Reducing the number of database writes increases performance and minimizes possible data loss.
For many of the errors detected, the Configure method exits with the appropriate exit code. In other cases, the Configure method may need to undo some of the operations it has performed. For instance, after loading the device driver and defining the device to the driver, the Configure method may encounter an error while downloading microcode. If this happens, the method will terminate the device from the driver using the sysconfig subroutine and unload the driver using the loadext subroutine.
The Configure method does not delete the special files or unassign the major and minor numbers if they were successfully allocated and the special file created before the error was encountered. This is because the operating system's configuration scheme allows both major and minor numbers and special files to be maintained for a device even though the device is unconfigured.
If the device is configured again, the Configure method will recognize that the major and minor numbers are allocated and that the special files exist.
By the time the Configure method checks for child devices, it has successfully configured the device. Errors that occur while checking for child devices are indicated with the E_FINDCHILD exit code. The mkdev command detects whether the Configure method completed successfully. If needed, it will display a message indicating that an error occurred while looking for child devices.
The following tasks are guidelines for writing a Configure method. When writing for a specific device, some tasks may be omitted. For example, if the device is not an intermediate device or does not have a driver, the method is written accordingly. A device may also have special requirements not listed in these tasks.
The Configure method must:
If the device is already configured (that is, the Device State descriptor of the device's CuDv object indicates the Available state) and is an intermediate device, skip to the task of detecting child devices. If the device is configured but is not an intermediate device, the Configure method will exit with no error.
If the device is in the Defined state, the Configure Method must check the parent device, check for the presence of a device, obtain the device VPD, and update the device's CuDv object.
When the device has a parent, the Configure method will obtain the parent device's CuDv object and check the Device State descriptor. If the object does not exist or is not in the Available state, the method exits with an error.
Another check must be made if a parent device exists. The Configure method must verify that no other device connected to the same parent (at the same connection location) has been configured. For example, two printers can be connected to the same port using a switch box. While each printer has the same parent and connection, only one can be configured at a time.
The Configure method performs this check by querying the CuDv object class. It queries for objects whose Device State descriptor is set to the Available state and whose Parent Device Logical Name and Location Where Connected on Parent Device descriptors match those for the device being configured. If a match is found, the method exits with an error.
If the device has a device driver, the Configure method must:
If the device is an intermediate device but cannot detect attached child devices, query the CuDv object class about this information. The value of the Change Status Flag descriptor for these child devices should be DONT_CARE because the parent device cannot detect them. Sometimes a child device has an attribute specifying to the Configure method whether the child device is to be configured. The autoconfig attribute of TTY devices is an example of this type of attribute.
Regardless of whether the child devices are detectable, the Configure method will write the device logical names of the child devices to be configured to standard output, separated by space characters. If the method was invoked by the Configuration Manager, the Manager invokes the Configure method for each of the child device names written to standard output.
|/dev/bus0||Contains POS registers.|
|/dev/bus1||Contains POS registers.|
|/etc/microcode directory||Contains microcode files. A symbolic link to the /usr/lib/microcode directory.|
|/usr/lib/asw directory||Contains downloaded adapter software.|
The mkdev command.
The busresolve subroutine, genmajor subroutine, genminor subroutine, getminor subroutine, loadext subroutine, mknod subroutine, odm_initialize subroutine, odm_lock subroutine, reldevno subroutine, relmajor subroutine, sysconfig subroutine.
Object Data Manager (ODM) Overview for Programmers in AIX General Programming Concepts: Writing and Debugging Programs.
Customized Devices (CuDv) object class, Predefined Devices (PdDv) object class, Customized Attributes (CuAt) object class, Predefined Attribute (PdAt) object class, Customized Vital Product Data (CuVPD) object class.
Understanding Device States, Understanding Device Dependencies and Child Devices, Loading a Device Driver Configuration Manager Overview, Understanding System Boot Processing, Device Dependent Structure (DDS) Overview in AIX Kernel Extensions and Device Support Programming Concepts.
Device Configuration Subsystem Programming Introduction in AIX Kernel Extensions and Device Support Programming Concepts.
Special Files Overview in AIX Version 4.3 Files Reference.
Writing a Device Method in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.
Writing an Unconfigure Method, Writing a Define Method.
ODM Device Configuration Object Classes.