Develop Functional Specification

Functional Specification

The development of the Functional Specification is a critical step in the process of developing an SMI implementation. The Functional Specification will document the instrumentation API(s) and values needed to populate each CIM class, CIM property and CIM method defined in the vendor schema. The document also describes any algorithms needed for converting instrumentation data to the CIM. The Functional Specification is used by developers to create the providers. The functional specification, known as a Mapping Specification, maps the instrumentation API to the CIM elements.

A Functional Specification is organized by profile. For each profile, the CIM classes are listed. Then for each CIM class, the properties and methods are listed. For each property, the name, criteria (Mandatory, Conditions(with condition), Optional), data type and possible values and instrumentation information is listed. If the property has a static value, then show the value in the instrumentation information column. For example, some classes have the CreationClassName property, which will always be the vendor class name.

The following is an example of an entry:

ACME_Array (CIM_ComputerSystem) M

Instrumentation API(s) do not usually correspond exactly to the CIM information required by the SMI Specification. For example, the operational status of an array is represented by the CIM_ComputerSystem.OperationalStatus property. Valid property values might be 2 (OK) or 8 (Starting). Rarely will a single instrumentation API exists that will return the value of 2 when the array is behaving normally. Instead, it is more probable that several API(s) must be called, each returning different data which then must be analyzed in combination to determine if the array is behaving normally and that 2 should be returned as the value for OperationalStatus. Thus, for each non-static property, the Functional Specification must show all of the steps required to calculate the CIM value to be returned by the provider. If the property is an array, then multiple values might be returned. Each step should show the API to use, including the values for the API input arguments. In some cases, determining the proper value for the input argument may require calling yet another API, which should be shown as a necessary prior step. Any algorithm that must be applied to the value returned by the instrumentation API should be explained in sufficient detail for a developer to properly implement the provider. Ideally, a developer should be able to create a provider from the Functional Specification without requiring additional information. In other words, if the functional specification is created properly the developer should not have to read the SMI-S or CIM schema.

The Functional Specification information for methods may be complicated. Each profile in the SMI Specification has a "Methods of the Profile" section that explains each method in the profile. For each method, the input arguments, output arguments and return codes are listed. The same level of detail as for non-static properties should be included for each method. In other words, each step should have information about the API to be used and what the input arguments should be. Any algorithm that must be applied during a step should be fully explained. The final step is to calculate the value of the output arguments and the return code based upon the results of previous steps.

Some methods, in the SMI Specification, may take noticeably longer to complete than others. In the case of long running methods, the method returns immediately while the actual operation of the method is performed in the background. Such methods typically have an output argument called Job, which is an instance of CIM_ConcreteJob. While the method runs in the background, the SMI Client uses CIM_ConcreteJob to monitor the progress of method completion. The Functional Specification should contain information about the steps required to start the method running in the background.

For association classes, the required information is different. The properties of an association class are references to other classes. Therefore, the value is the name of the vendor subclass. The Functional Specification must describe the algorithm for finding the other endpoint. For example, in the Disk Drive Lite profile, CIM_Realizes is a mandatory association between CIM_PhysicalPackage and CIM_DiskDrive. Assuming that ACME subclasses are derived for each, the Functional Specification describes how the ACME_Realizes provider finds an instance of ACME_DiskDrive when starting from an instance of ACME_PhysicalPackage, and vice versa.

The Functional Specification should contain information about the cardinality of an association, being as the complexity for implementing an association depends directly upon its cardinality. The simplest association has 1-1 cardinality; i.e., only a single instance of each referenced class can exist. A complicated association has 1-N cardinality; i.e. only a single instance of one referenced class can exist but many instances of the other referenced class might exist. The most complex associations have N-N cardinality; i.e., many instances of each referenced class might exist. In some profiles, a diagram will show the cardinality of the association. For example, in the Masking and Mapping profile, a diagram shows that AuthorizedSubject is a 1-N cardinality association with one CIM_StorageHardwareID instance relating to many (indicated by an asterisk) CIM_AuthorizedPrivilege instances. In contrast, CIM_AssociatiedPrivilege is a 1-1 cardinality association between CIM_StorageHardwareID and CIM_SCSIProtocolController while CIM_ProtocolControllerForUnit is an N-N cardinality association. Not all profiles have diagrams showing association cardinality. For such cases, examine the MOF file for the association class. If the Max(1) qualifier is shown, then the cardinality for that referenced class is one. If no Max qualifier is shown, then the possible cardinality for that referenced class is unlimited or N.

The SMI Specification uses CIM indication classes to provide a mechanism for an SMI Implementation to notify an SMI Listener that a certain event has occurred. In some cases, upon receiving notification, the SMI Listener will alert the user to take some corrective action. In other cases, an SMI Listener might simply use the notification to refresh the status or configuration information displayed. For some profiles, the SMI Specification requires that an SMI Implementation support certain indication filters. These indication filters are shown in the CIM Elements table. The Element Name column lists the indication filters. If the Requirements column in the table shows Mandatory, the indication filter shall also be implemented. If the Requirement column in the table is Conditional, then a condition will also be listed. If the condition is true, then the indication filter shall also be implemented. If the Requirement column in the table is Optional, the indication filter may be implemented. The Functional Specification should include the supported indication filters for each profile. For each filter, the Functional Specification should show the steps for determining if the event occurred. If the step requires calling an API, the API should be shown with all required inputs/outputs.

When developing the Functional Specification, it may be discovered that instrumentation API(s) are missing for some of the information required by the SMI Specification. Even when API(s) do exist, developing the Functional Specification may show some inefficiencies that can be removed by modifying the API or creating new API(s). Thus, the Functional Specification serves to identify deficiencies and/or inefficiencies in the instrumentation API(s) that must be resolved before the SMI Implementations can be completed.