Structure

The FanController module provides an interface which users can call to obtain information about the fans attached to the computer system. It does so through registered drivers which can control a single fan. Applications and tools call the FanController to request information about the fans. The FanController dispatches the requests, if necessary, to the drivers which handle the fans.

Fans

Although Fans within the context of the FanController are generally considered to be devices that move air to perform cooling, there are other mechanisms for cooling. These can still be managed through the FanController system, although it is recommended that they express their function in terms of the duty-cycle percentage, rather than RPM speed.

Fans can be operate in one of three modes of control:

• Manual control. In this mode, the fan is given speeds by the user, and it runs at that speed until a new speed is given.
• Automatic control. In this mode, the fan driver is controlling the speed, and attempts by the user to change the fan speed will be ineffective. This mode will be offered by fan drivers which can either control the speed themselves, or which interface with hardware which offers an automatic management mode.
• Managed control. In this mode, the fan driver is being managed by another module within the system. This control mode is informational, as the operations to control the speed will be effective, but the managing module will override the speed controls as it manages the fan. Fan drivers are never informed that they are running in 'managed' mode - to them it appears that they are under manual control. User interface components should not allow manual changes to fans which are under managed control.

They can be controlled to operate at specific speeds, usually reported in RPM. Or they can be controlled as fractions of their full speed, reported as a percentage. The fan may be unable to report a speed if it has no explicit controls - it may only be able to be turned on and off. Some fans may be able to report that they have failed, either because they are detected as broken, or monitoring reports that they are not performing correctly.

Most fans do not have completely variable controls, and do not allow any set of speeds to be selected. The Fan driver may declare the speeds which the fan can achieve or the accuracy at which it select them. For example, a given fan might only be able to run at 2200, 3000, 3400 and 3900 RPM, and so would report those as the only speeds it provides. Or it might only be able to control the percentage at 10% intervals, so would report an accuracy of 10%.

Speed

The following fan speeds values and ranges are used within the FanController interfaces:

Control mode

Fans may be placed into different control modes. Not all fans will support all modes, and this will be indicated by the fan capability flags. The following control modes are used within the FanController interfaces:

Capability flags

Fan drivers may have different capabilities, and may be able to support different modes of operation. These can be declared through the capabilities flags. This is a 32bit value containing bit values which describe what the fan can do.

The FanController module will use these capabilities to restrict the calls that can be made and avoid calls to the FanDriver.

Location identifier

Fans may be located in different positions relative to the system which is reporting their state. Each fan must supply a location identifier which describes where the fan is located. This is an enumerated set which should allow user interfaces give a visual representation, or description, of the fan locations. Fan locations are broken down into three major parts, held in a word:

• Device type - this indicates the area or entity that the fan is associated with. This allows the user to identify what type of device the fan is trying to cool. The following device types are defined:

  Value	Meaning
  0	CPU device
  1	GPU device
  2	Memory device
  3	I/O card
  4-15	Reserved for discrete internal components
  16	PSU fan
  17	Backplane fan
  18	Radiator fan (fans attached to radiators on passive or active cooling)
  19	Chassis fan
  20-31	Reserved for macro internal components
  32	External fan
  33-239	Reserved for other devices
  240-254	Reserved for users
  255	Generic fan, unknown properties

• Sequence number - this gives more information about which device or location is being described. The meaning differs depending on the device type. For internal devices this sequence number describes the instance of the device which is being cooled. For example, where multiple CPUs exist, each fan will be associated with the CPUs by the sequence number.
• Location - The location in relation to the device. The meaning of this field is dependant on the device type.

Each of these device types has an assignment for the location and sequence number within the location identifier. This allows more specific locations to be supplied to the user.

Fan registration

Fans are registered with FanController through SWI FanController_Register when they are detected. If they are removed, or the driver is terminated, the fan is deregistered with SWI FanController_Deregister. On registration the fan will be assigned an identifier which is unique to this execution of the FanController. The fan identifiers will be recycled if the FanController is restarted.

Change notifications

The FanController will issue notifications as its state changes. This allows other modules and applications to recognise and handle these transitions. For modules, service calls are issued for the state transitions. For applications, a pollword may be updated to indicate that the state of the fans has changed. Strictly, modules could also use the pollword system, although it would be less efficient than simply using the pollwords.

The SWI FanController_TaskPollWord interface allows applications to recognise events by one of three bits being set - a bit which indicates that the controller has died, a bit which indicates that the registrations have changed, and a bit which indicates that fan error state has changed. These notifications are coarse (they do not indicate which fan identifier has been changed) because pollwords are limited to only 32bits, and it is therefore not possible to communicate more information. Applications should act appropriately to locate whether the devices they are interested in have changed.

After the FanController module has started, it will issue Service_FanController_Started on a callback. This allows drivers to register themselves with the FanController. Services are delivered to modules in order of the module registration, and the state of the system may change between initialisations, so fan drivers (and other users of FanController) must not rely on being given the same fan identifier between initialisations.

When the FanController module is killed, it will issue Service_FanController_Dying. At that point, all drivers have been automatically deregistered. Fan drivers should take note that they are no longer registered, and users of the fan system should forget all fan identifiers. Application pollwords will be updated to indicate that the module has died, and applications seeing this bit indicated should treat all fan identifiers as invalid and begin any fan identification process as necessary.

When a new fan is registered or an existing fan is deregistered, the FanController will issue Service_FanController_FanChanged. This allows modules to recognise the coming and going of fan drivers and to update their state appropriately. Application pollwords will be updated to indicate that the registrations have changed. Applications should enumerate the fans to identify whether the fan(s) that they are monitoring have been affected. In many cases, this may just be a new fan driver being loaded, or an existing fan driver being re-initialised. In the former case, the enumeration will show up the new fan. In the latter case, fans being monitored may still be present in the enumeration, but will have changed their fan identifier.

When a fan driver identifies an error state (or that an error state has been resolved) it should issue Service_FanController_FanChangedState. This notifies any modules that the fan is (or is no longer) reporting an error. This state change is reported by the fan driver directly, as it will recognise the error state and can report the information to the FanController and other modules through the service. The FanController will record this error state notification, and will update the application pollwords to report the error condition. Applications should note that the error state may have already been resolved by the time they receive the notification through the pollword.

Fan speed changes are not notified through the service calls. Speed changes could happen many times per second, and can affect every single device. As such, notifications would themselves become a significant part of the system's processing. Additionally, the fan speed may be automatically managed by a fan controller, and the speed be only a value that the driver can read. Such cases make it impossible to accurately report that the speed has changed. Applications and modules wishing to track fans should provide a configurable cadence for polling for the fan speed to allow an appropriate trade off between system utilisation and responsiveness. In many cases, a polling period measured in seconds will have a negligable effect on performance, and interface updates at that speed would be acceptable to most users.

List the fans registered with FanContrller

REM List the fans we know about
fan_id% = 0
REPEAT
    SYS "FanController_Enumerate", fan_id%,,,"" TO fan_id%, location_id%, capabilities%, provider$, accuracy%, max%, speeds%
    IF fan_id% <> -1 THEN
        PRINT"FanID:        ";fan_id%
        PRINT"Location:     &";~location_id%
        PRINT"Capabilities: &";~capabilities%
        PRINT"Provider:     ";provider$
        PRINT"Accuracy:     ";accuracy%
        PRINT"Max speed:    ";max%
        IF speeds% THEN
            PRINT"Supported speeds:"
            ofs% = 0
            WHILE speeds%!ofs% <> -1
                PRINT"              ";speeds%!ofs%
                ofs% += 4
            ENDWHILE
        ENDIF
        PRINT
    ENDIF
UNTIL fan_id% = -1