$Log: PlatformPlugin-README,v $ Revision 1.7 2004/08/13 22:04:41 eem Dummy checkin to test change to commit messages. Revision 1.6 2004/06/07 21:28:48 eem Dummy checkin to test commit email messages. Revision 1.5 2003/10/11 00:18:26 eem Added comments, reorganized code for clarity/readability. Revision 1.4 2003/10/07 20:10:04 eem Updated Platform Plugin name example. Revision 1.3 2003/09/19 23:58:46 eem Added a bit of documentation. Revision 1.2 2003/09/16 22:35:00 eem Added intro, conventions and project layout info, as well as "to-do" section headings. Revision 1.1 2003/09/16 19:00:33 eem Initial checkin of Platform Plugin README file. -------------------------------------------------------------------------------- MacRISC4 Platform Plugin README -------------------------------------------------------------------------------- This document is intended to describe and otherwise provide information useful to programmers who write and maintain Platform Plugins for use in MacRISC4-based platforms. This will be a constantly evolving body of work so if something in this document is incorrect or incomplete, please update it! -------------------------------------------------------------------------------- What is the Platform Plugin? -------------------------------------------------------------------------------- The Platform Plugin was born out of the need for a kernel-resident entity that could perform platform-specific duties. Historically, many platform-specific tasks have been placed in the Platform Expert (PE). However, this made the PE harder to maintain, costed memory (from code size) on every platform even if a change only pertained to one, and put a burden on testing since changes needed to be regressed on all supported platforms. The Platform Plugin architecture solves these problems. In this model, the PE is specific to a particular system architecture (i.e. AppleMacRISC2PE for G3/G4/UniNorth/KeyLargo-based systems, AppleMacRISC4PE for G5/U3/K2-based systems), and the Platform Plugin contains any code that only affects a certain platform (i.e. PowerMac7,2 or PowerBook6,2). The Plugin is often responsible for thermal management (reading data from temperature, voltage, etc. sensors and controlling CPU speed, system fans, etc.). In order to do this the Plugin implements the thermal architecture described in the Thermal SW ERS. You should be familiar with this document in order to understand some of the concepts that are central to the Plugin's operation, such as the sensor and control abstractions and communications between drivers participating in the thermal system. The latest Thermal SW ERS is available at the following location: afp://cpusw.apple.com/Development/Docs/Thermal SW Contact Paul Resch (pmr@apple.com) if you need access to this document. -------------------------------------------------------------------------------- Coding and Naming Conventions -------------------------------------------------------------------------------- Method names beginning with get/set are accessors for INTERNAL instance data. Method names beginning with fetch/send communicate with an EXTERNAL driver, such as IOHWSensor or AppleSlewClock. -------------------------------------------------------------------------------- Project Layout -------------------------------------------------------------------------------- The Platform Plugin's source code is organized as a set of platform-agnostic superclasses, which are intended to be subclassed by each Plugin. The superclasses implement most of the standard communication infrastructure used by the Thermal SW architecture. They also provide most of the code necessary to parse the thermal profile (described a few sections below) and instantiate internal classes and instance data. The superclass code is located in the IOPlatformPlugins/ directory of the AppleMacRISC4PE project. All of the classes defined and implemented in this directory are platform-agnostic -- there should be NO platform-specific code in this directory!! The superclasses are built into a library driver called IOPlatformPluginFamily.kext with the following CFBundleIdentifier: com.apple.driver.IOPlatformPluginFamily The individual Plugins must declare a dependency on this library kext to ensure that all the superclasses are present for linking into the kernel. The platform-specific code for each Plugin is located in its own subdirectory within the IOPlatformPlugins/ directory. Plugins shall be named with their target platform's model property, with the comma replaced by an underbar, and the string "_PlatformPlugin" appended. For example, for the model property PowerMac7,2 the Plugin should be named PowerMac7_2_PlatformPlugin. The code for this Plugin resides in the IOPlatformPlugins/PowerMac7_2_PlatformPlugin directory within the AppleMacRISC4PE project. -------------------------------------------------------------------------------- KEXT Matching/Loading -------------------------------------------------------------------------------- The Platform Plugin matches and loads to a nub created in MacRISC4PE.cpp. If a platform requires a Plugin, MacRISC4PE is responsible for creating a nub with the expected name and matching criteria: IONameMatch: YourMacA_B_PlatformPlugin (i.e. PowerMac7_2_PlatformPlugin) IOProviderClass: IOPlatformDevice -------------------------------------------------------------------------------- Classes Provided by the IOPlatformPluginFamily -------------------------------------------------------------------------------- IOService | +--- IOPlatformPlugin OSObject | +--- IOPlatformSensor | | | +--- IOPlatformStateSensor | +--- IOPlatformControl | | | +--- IOPlatformSlewClockControl | | | +--- IOPlatformPWMFanControl | +--- IOPlatformCtrlLoop | +--- IOPlatformTableCtrlLoop | +--- IOPlatformPIDCtrlLoop -------------------------------------------------------------------------------- The Platform Thermal Profile -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- Platform Plugin Entry Points and Execution Contexts -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- Platform Plugin Debug Interface (used by PlatformConsole.app) -------------------------------------------------------------------------------- /* * Command keys for the PlatformConsole debug interface */ /* * Force Update * * description: * Causes the platform plugin to refresh the current-value of the indicated * sensor or control. The updated value will be reflected in the I/O registry * after the command returns. * * key: "force-update" * value: (non-null) * * parameters: * * key: "sensor-id" / "control-id" * value: id */ #define kIOPPluginForceUpdateKey "force-update" /* * Force Update All * * description: * Causes the platform plugin to refresh the current-value of all registered * sensors and controls. The updated values will be reflected in the I/O registry * after the command returns. * * key: "force-update-all" * value: (non-null) * * parameters: * * (none) */ #define kIOPPluginForceUpdateAllKey "force-update-all" /* * *** UNIMPLEMENTED *** * * Force Sensor Current Value * * description: * Causes the indicated sensor to report the supplied value as its current-value. * * key: "force-sensor-current-value" * value: value * * parameters: * * key: "sensor-id" * value: id * * *** UNIMPLEMENTED *** */ #define kIOPPluginForceSensorCurValKey "force-sensor-current-value" /* * *** UNIMPLEMENTED *** * * Release Forced Sensor * * description: * Causes a previously forced sensor to return to normal operation. If the indicated * sensor was not previously forced, returns an error. * * key: "release-forced-sensor" * value: (non-null) * * parameters: * * key: "sensor-id" * value: id * * *** UNIMPLEMENTED *** */ #define kIOPPluginReleaseForcedSensorKey "release-forced-sensor" /* * Force Control Target Value * * description: * Overrides the indicated control's target-value to the supplied value. * * key: "force-control-target-value" * value: value * * parameters: * * key: "control-id" * value: id */ #define kIOPPluginForceCtrlTargetValKey "force-control-target-value" /* * Release Forced Control * * description: * Causes a previously forced control to discard the forced target-value and * return to normal operation. If the indicated control has not been * previously forced, returns an error. * * key: "release-forced-control" * value: (non-null) * * parameters: * * key: "control-id" * value: id */ #define kIOPPluginReleaseForcedControlKey "release-forced-control" /* * Force Control Loop Meta State * * description: * Attempts to override the indicated control loop's thermal profile-supplied * meta state(s). The supplied meta state must be the proper format for use by * the indicated control loop. * * key: "force-ctrlloop-meta-state" * value: meta state * * parameters: * * key: "ctrlloop-id" * value: id */ #define kIOPPluginForceCtrlLoopMetaStateKey "force-ctrlloop-meta-state" /* * Release Forced Control Loop * * description: * Causes a previously forced control loop to discard its forced meta state and * return to normal operation using its thermal profile-supplied meta state(s). * If the indicated control loop has not been previously forced, returns an error. * * key: "release-forced-ctrlloop" * value: (non-null) * * parameters: * * key: "ctrlloop-id" * value: id */ #define kIOPPluginReleaseForcedCtrlLoopKey "release-forced-ctrlloop" -------------------------------------------------------------------------------- HOWTO: Creating a new Platform Plugin --------------------------------------------------------------------------------