Writing an Unconfigure Method

This article describes how an Unconfigure device method works. It also suggests guidelines for programmers writing their own Unconfigure device configuration method.

Syntax

Description

The Unconfigure method takes an Available device (available for use in the system) to a Defined state (not available for use in the system). All the customized information about the device is retained in the database so that the device can be configured again exactly as it was before.

The actual operations required to make a device defined depend on how the Configure method made the device available in the first place. For example, if the device has a device driver, the Configure method must have loaded a device driver in the kernel and described the device to the driver through a device dependent structure (DDS). Then, the Unconfigure method must tell the driver to delete the device instance and request an unload of the driver.

If the device is an intermediate device, the Unconfigure method must check the states of the child devices. If any child device is in the Available state, the Unconfigure method fails and leaves the device configured. To ensure proper system operation, all child devices must be unconfigured before the parent can be unconfigured.

Although the Unconfigure method checks child devices, it does not check the device dependencies recorded in the Customized Dependency (CuDep) object class. See "Understanding Device Dependencies and Child Devices" in AIX Kernel Extensions and Device Support Programming Concepts.

The Unconfigure method also fails if the device is currently open. In this case, the device driver returns a value for the errno global variable of EBUSY to the Unconfigure method when the method requests the driver to delete the device. The device driver is the only component at that instant that knows the device is open. As in the case of configured child devices, the Unconfigure method fails and leaves the device configured.

When requesting the device driver to terminate the device, the errno global variable values other than EBUSY can be returned. The driver should return ENODEV if it does not know about the device. Under the best circumstances, however, this case should not occur. If ENODEV is returned, the Unconfigure method should unconfigure the device so that the database and device driver are in agreement. If the device driver returns any other errno global value, it deletes any stored characteristics for the specified device instance. The Unconfigure method indicates that the device is unconfigured by setting the state to Defined.

The Unconfigure method does not generally release the major and minor number assignments for a device, or delete the device's special files in the /dev directory.

By convention, the first four characters of the name of the Unconfigure method should be ucfg. 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.

Flags

Guidelines for Writing an Unconfigure Method

This list of tasks is intended as a guideline for writing an Unconfigure method. When you write a method for a specific device, some tasks may be omitted. For example, if a device is not an intermediate device or does not have a driver, the method can be written accordingly. The device may have special needs that are not listed in these tasks.

The Unconfigure method must:

1. Validate the input parameters. The -l flag must be supplied to identify the device that is to be unconfigured.

2. Initialize the Object Data Manager (ODM) using the odm_initialize subroutine and lock the Configuration database using the odm_lock subroutine. See "Writing a Define Method" for an example.

3. Retrieve the customized device (CuDv) object for the device to be unconfigured. Use the CuDv object whose Device Name descriptor matches the name supplied with the -l flag. If no object is found with the specified name, the method exits with an error.

4. Check the state of the device. If the Device Status descriptor indicates that the device is in the Defined state, then it is already unconfigured. In this case, exit.

5. Check for child devices in the available state. This can be done by querying the CuDv object class for objects whose Parent Device Logical Name descriptor matches this device's name and whose Device Status descriptor is not Defined. If a match is found, this method must exit with an error.

6. Retrieve the Predefined Device (PdDv) object for the device to be unconfigured by getting the PdDv object whose Unique Type descriptor matches the Link to Predefined Devices Object Class descriptor of the device's CuDv object. This object will be used to get the device driver name.

7. Delete device instance from driver and unload driver. Determine if the device has a driver. The Unconfigure method obtains the name of the device from the Device Driver Name descriptor of the PdDv object. If this descriptor is a null string, the device does not have a driver. In this situation, skip to the task of updating the device's state.

   If the device has a device driver, the Unconfigure method needs to include the following tasks:

   1. Determine the device's major and minor numbers using the genmajor and getminor subroutines. These are used to compute the device's devno, using the makedev macro defined in the /usr/include/sysmacros.h file, in preparation for the next task.

   2. Use the sysconfig subroutine to tell the device driver to terminate the device. If a value of EBUSY for the errno global variable is returned, this method exits with an error.

   3. Use the loadext routine to unload the device driver from the kernel. The loadext subroutine will not actually unload the driver if there is another device still configured for the driver. See "Loading a Device Driver" for more details.

8. Set defined status. The device is now unconfigured. The Unconfigure method will update the Device Status descriptor of the device's CuDv object to the Defined state.

9. Close all object classes and terminate the ODM. If there are no errors, exit with an exit code of 0 (zero).

Files

Related Information

Writing a Device Method Overview.

ODM Device Configuration Object Classes.

The mkdev command.

The genmajor subroutine, getminor subroutine, loadext subroutine, odm_initialize subroutine, odm_lock subroutine, sysconfig subroutine.

Writing a Configure Method, Loading A Device Driver, Writing a Define Method.

Customized Devices (CuDv) object class, Predefined Devices (PdDv) object class.

Object Data Manager (ODM) Overview for Programmers in AIX General Programming Concepts: Writing and Debugging Programs.

The Device Dependent Structure (DDS) Overview in AIX Kernel Extensions and Device Support Programming Concepts.

Understanding Device States, Understanding Device Dependencies and Child Devices, Loading a Device Driver in AIX Kernel Extensions and Device Support Programming Concepts.