PlatformPlugin-README   [plain text]



$Log: PlatformPlugin-README,v $
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"						<string>
 * value:	(non-null)
 *
 * parameters:
 *
 * key:		"sensor-id" / "control-id"			<string>
 * value:	id									<number>
 */
#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"					<string>
 * 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"		<string>
 * value:	value								<number>
 *
 * parameters:
 *
 * key:		"sensor-id"							<string>
 * value:	id									<number>
 *
 *							*** 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"				<string>
 * value:	(non-null)
 *
 * parameters:
 *
 * key:		"sensor-id"							<string>
 * value:	id									<number>
 *
 *							*** 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"		<string>
 * value:	value								<number>
 *
 * parameters:
 *
 * key:		"control-id"						<string>
 * value:	id									<number>
 */
#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"			<string>
 * value:	(non-null)
 *
 * parameters:
 *
 * key:		"control-id"						<string>
 * value:	id									<number>
 */
#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"			<string>
 * value:	meta state							<dictionary>
 *
 * parameters:
 *
 * key:		"ctrlloop-id"						<string>
 * value:	id									<number>
 */
#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"			<string>
 * value:	(non-null)
 *
 * parameters:
 *
 * key:		"ctrlloop-id"						<string>
 * value:	id									<number>
 */
#define kIOPPluginReleaseForcedCtrlLoopKey	"release-forced-ctrlloop"


--------------------------------------------------------------------------------
HOWTO: Creating a new Platform Plugin
--------------------------------------------------------------------------------