PDGuide - The Desktop Management Interface (DMI)
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
This chapter provides background about the DMI, information about the relationship between DMI and VPD (vital product data) and coding examples.
DMI Overview
The Desktop Management Interface (DMI) provides the means for software and hardware components to define VPD information. DMI also provides a standard function set that management applications can use to access that information.
The DMI consists of four elements:
- Format for describing information
- Format for data transfer
- Mechanism for data transfer
- Set of services for facilitating communication
You define component descriptions in a language that is called the Management Information Format (MIF). Each component has a MIF file that describes the manageable characteristics of the component.
Component providers use the Component Interface (CI) to describe how to access management information and enable a component to be managed.
Applications use the Management Interface (MI) to manage components.
The CI and MI are data interfaces, as opposed to procedural interfaces.
The Service Layer (SL) is an active, resident code that runs on the system. The SL mediates between the MI and the CI and performs services on behalf of each.
The DMI is a local interface that is used within a single system. DMI does not replace existing network management protocols. DMI provides a consistent method for providing instrumentation to those protocols. The Service Layer is the broker of local instrumentation.
DMI provides the following:
- Independence of a specific computer, operating system, or management protocol
- An easily adopted interface for application developers
- Does not require a network
- Mapping to existing management protocols.
The DMI does not address or specify a protocol for management over a network.
DMI Structure
The DMI is a local interface for single-system use, regardless of being a standalone desktop system or part of a network. The interface consists of the following parts:
- Service Layer (SL): A local program that collects and manages product information in the MIF database. The Service Layer distributes requested information to management applications through the Management Interface (MI) and to manageable products through the Component Interface (CI).
- MIF database: The database containing the installed or attached manageable product information. MIF files contain the information, and the Service Layer manages the information.
- Management applications: Remote or local programs used to interrogate, track, control, and list the elements of a desktop system. A management application can be any of the following:
- a graphical user interface program
- a network management agent
- an installer program
- a diagnostics program
- a remote procedure call.
- Manageable products: Components that are connected to or part of a desktop computer system or network server. Components can be part of the system code, or you can add them later. Each product has a MIF file in the MIF database that contains pertinent product management information.
The following figure shows the DMI structure:
DMIFunctionalDiagram
Enabling Manageable Products for DMI
The product manufacturer needs to decide which attributes of the product are manageable. To enable a product for DMI you write a MIF file that contains descriptions of these manageable attributes. Group the attributes logically so you can write instrumentation code to provide attribute data.
Use the SystemView Agent Programmer's Guide in the Toolkit in the Problem Determination Tools folder as a reference for enabling products. This book defines requirements for products that communicate with the Service Layer. To develop such a product:
- Read the SystemView Agent Programmer's Guide to get an understanding of how components interface with the Service Layer and the supported commands.
- Define manageable attributes and specific features of your product. Look for existing MIF groups that may apply to your product.
- Begin with the ComponentID group and define MIF groups that are based on the features of your product. Use as many of the existing standard groups that apply to your product as is possible. Standard groups are available from the Desktop Management Task Force (DMTF). If needed, add proprietary groups for unique features of the product.
- Decide if the attributes are read-only, read-write, or write-only, and define MIF attributes for each group.
- Use the syntax that is defined in the SystemView Agent Programmer's Guide to create your MIF file.
- Determine whether to use run-time programs or the direct interface to provide component information to the Service Layer. Write your instrumentation code accordingly.
- Change the programs that install or delete MIF database file for your component.
- Decide which errors, exceptions, or problems are to be sent to the Service Layer as indications and the attribute information to include. Real-time, intelligent product management is made possible by using indications because the system immediately notifies management applications when a problem occurs. Add code to your product to send these indications to the Service Layer. The system uses the DmiIndicate command block to pass events to the Service Layer. See the SystemView Agent Programmer's Guide in the Problem Determination Tools folder on the system for information about the DmiIndicate command block.
Designing MIF Files
MIF files are the key to enabling your product to be managed by the desktop system. A well designed MIF file is important.
The DMI requires that the MIF file be an ASCII text file that contains the groups and attributes that you defined for your product. You must provide all meaningful information by using the MIF file. The text in the file must follow the defined syntax and grammar.
After you decide which product attributes are manageable, define the attributes into standard groups as much as possible in the MIF file.
The DMI Specification describes attribute characteristics and options. All attributes must have these four items defined:
- Name
- The name of the attribute
- ID
- The unique, sequential attribute ID within the group containing the attribute
- Type
- The attribute's data type. The type is either a specific data type that DMI supports or an enumerated list that provides flexibility in the attribute definitions
- Value
- The actual value (to be put into the database) or a pointer to the instrumentation that gets the value
In addition, you can optionally define description, access, and storage attributes.
The description can be one or many lines. The description text should be as clear and informative as possible to provide management applications with complete information about the attribute. You need a good description at the component level and group level.
The system uses an access statement to determine whether the attribute's value is read-only, read-write, or write-only.
The storage statement provides a hint to management applications about whether to assist in optimizing storage requirements. Two options are available:
- common - you use this option to signify that the attribute value is typically limited to a small set of possibilities that you can be optimize.
- specific - you use this option to signify that the attribute value is not a good candidate for optimization because of the possibility of a large number of different values.
You can find the MIF file requirements in the SystemView Agent Programmer's Guide in the Toolkit in the Problem Determination Tools folder.
MIF Attribute Storage
The system stores product attribute information in a MIF file. The two ways to store this information are as follows:
- Hard coding the information in the MIF database.
- Keeping the information in your own storage location (for example, a database or in read-only memory (ROM)).
Hard Coding Information into a MIF Database
The simplest way to make product information known through DMI is by hard coding the information into the MIF database. Using this method requires no access code to be written, and DMI retrieves the product information from the DMI database.
Hard-coded information has a major limitation: the system cannot dynamically update the information yet maintain data integrity. If you set an attribute to read/write, anyone can update that value. Another restriction of hard-coded information is that you cannot add or delete rows in tables. The only way to update a read-only attribute is by deleting the old MIF file and installing a new MIF file with the updated values.
Storing Information in Your Own Storage Location
Instrumentation is program code that the Service Layer starts. The code can be a run-time program that requests attribute values. The code could also be a direct interface program. The direct interface program runs on the system and is connected to the Service Layer.
Use run-time programs for products that provide transitory data or that are not associated with a device driver that is loaded in RAM. Use run-time programs for background tasks such as the system BIOS.
Use direct interface programs when the system requires persistent data for products that use device drivers or background programs.
All instrumentation code should include the header file DMIAPI.H.
Instrumentation code that the Service Layer starts must provide one value at a time. The code must be able to handle the following DMI commands that are accessed through the DmiCiInvoke call from the Service Layer:
- DmiGetAttributeCmd
- DmiSetAttributeCmd
- DmiGetRowCmd
- DmiGetFirstRowCmd
- DmiGetNextRowCmd
Every command must call the pConfirmFunc function, including the set commands and the commands that generate errors. When you use the DmiGetRowCmd command, the Service Layer builds the DmiGetRowCnf structure prior to calling DmiCiInvoke. In addition, the GroupKeyData structures are allocated and the oGroupKeyList slot in the DmiGetRowCnf structure is filled in. Any instrumentation code you provide must change only the confirm buffer, not the DmiInvoke command buffer.
The DMI procedure library (DMIAPI) is part of the Toolkit and provides a simple method of handling these constraints. The Component Interface outline makes use of DMIAPI. If you use the outline program as the basis for your instrumentation program, you need only write the five outlined procedures. When you use the outline program, you do not need to consider any of the issues above.
Dynamic Link Libraries (DLL)
The Component Interface outline lists five procedures that define the simplest method for you to write run-time instrumentation. When you complete the outline files, include them in the library and in your program.
To use run-time programs, use an instrument to specify the attribute value of the MIF Path block name. The block name should contain the run-time program file name or path name. (See the SystemView Agent Programmer's Guide on the system for details about using the Path block in the MIF file.) This program runs when the Service Layer needs to access the attribute values.
If the file name in the path block does not have a complete path, the Service Layer uses the library path to find the DLL.
Direct Interface (DI) Programs
Your component must register with the Service Layer before it can use the direct interface. You specify the keyword DIRECT-INTERFACE in the Path block of the MIF file. If the direct interface program is not running, the system returns an error when the Service Layer attempts to access attributes.
Direct interface components register with the Service Layer using the DmiRegisterCiCmd command. When an attribute value needs to be accessed, the Service Layer passes control to the direct interface program. A direct interface program must use the DmiUnregisterCiCmd to unregister with the Service Layer before the system unloads the program.
Indications
Component instrumentation sends unsolicited messages, to the Service Layer to signal some particular situation. The messages are known as events. When the messages reach a management application, they are known as indications. The indication ID identifies indications. The IDs start at the number 1. Events are often a sign of a catastrophic occurrence or other activity that the system should know about immediately. The event identification is specific to a given component and appears as an unsolicited "get." You specify event structures as groups in the component's MIF file.
In DMI, all commands are specified by using data blocks. Component instrumentation uses the function call DmiIndicate() to send the indication block and any following blocks to the Service Layer for processing. The C language prototype call is as follows:
unsigned long DmiIndicate(PTR command)
where command is the complete command block. The system returns a 32-bit status value to indicate success or failure.
The Service Layer immediately returns control to the component instrumentation while it processes the indication. The component instrumentation is free to issue additional indications, but it cannot reuse the original indication block buffer until the Service Layer processing is complete. Simultaneous indications from a component instrumentation must use different indication blocks. When the Service Layer has completed processing the indication, it calls the function pResponseFunc() identified in the original indication block. At that point, the component instrumentation can reuse the block.
Installing MIF Files
When you install your product on a system, the installation process is responsible for putting the component MIF file into the existing MIF database. If the Service Layer is not running, the system stores the component MIF file in the MIF subdirectory.
Install programs use the DmiCiInstallCmd function to install the MIF file in the MIF database.
To accommodate DMI, your installation process must provide an ASCII text MIF file. When you create the MIF file, follow the format that is found in the SystemView Agent Programmer's Guide on the system.
If the Service Layer is not running when you install the MIF, you can copy the MIF file to the <boot-drive>OS2\SYSTEM\RAS\MIFS directory. The next time the system starts the DMI Service Layer, the system installs the MIF file in the MIF database. Then system copies the file to the <boot-drive>OS2\SYSTEM\RAS\BACKUP directory, and deletes the file from the MIFS directory.