ACPI/Board-EC interaction: Difference between revisions

From coreboot
Jump to navigation Jump to search
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
This page details the required interface and implementation details for connecting embedded controller ASL files to mainboard ASL files. Implementing this specification is mandatory for every new mainboard/EC added to the tree.
This page details the required interface and implementation details for connecting embedded controller ASL files to mainboard ASL files. Implementing this specification is mandatory for every new mainboard/EC added to the tree.
<span style="background:red">WARNING! The rules presented here are still a work-in-progress and should not yet be taken as as mandatory.</span> However, if you are implementing a new EC, mainboard, or are interested in refactoring existing ASL files, you should join in the conversation and get this specification finalized.


EC ASL files should be self-contained, and not depend on the specific chipset or mainboard. As a result all variables and methods which are used must be standardized to foster interoperability and modularity. This specification details how to achieve those points.
EC ASL files should be self-contained, and not depend on the specific chipset or mainboard. As a result all variables and methods which are used must be standardized to foster interoperability and modularity. This specification details how to achieve those points.


== Defined constants ==
== System Resources ==
 
* EC_SMI_GPE
** The general purpose event (GPE) corresponding to the EC SCI line.


== Hotkey event methods ==
All ECs are assumed to use IO ports '''0x62''' and '''0x66''' for data/commands. If the EC also serves as a keyboard controller, it is assumed to use ports '''0x60''' and '''0x64'''. I/O port accesses to these ports must be directed to the bus to which the EC is connected. These need not be individually documented.


Two proposals exist:
If the EC uses different ports, or needs other system resources, those must be documented in '''src/ec/vendor/model/documentation.txt'''


=== The hammer method ===
== Defined constants ==


Define a set of common ACPI method names which the mainboard code should define, and the EC code can always use.
* EC_SCI_GPE
 
** The general purpose event (GPE) corresponding to the EC SCI line.
The mainboard must #define these to an existing method. The actual ASL methods must not use these long names in ASL. The "MB_" prefix indicates that the mainboard  is providing these methods.
 
Notice that these methods are only called on hotkey events. As such, unless the user has really fast fingers, there isn't a huge ACPI overhead as opposed to setting/clearing the needed bits directly in the caller.
 
* MB_TOGGLE_WLAN() or MB_TOGGLE_WIRELESS() (TODO: only one method should be defined!!!)
** Toggle wireless LAN on and off, or wireless LAN and bluetooth (respectively). EC calls this on hotkey events.
 
* MB_INCREASE_BRIGHTNESS() and MB_DECREASE_BRIGHTNESS()
** Increase or decrease screen brightness. EC calls this on hotkey events.
 
* MB_SWITCH_DISPLAY()
** Switch the active display. EC calls this on hotkey events.
 
* MB_NOTIFY_POWER_EVENT()
** Handle power state notifications and notify CPU device objects to re-evaluate their _PPC and _CST tables.
 
For example:
 
/* Brightness up hotkey event */
Method (_Q11) {               
        MB_INCREASE_BRIGHTNESS();
}
/* Brightness down hotkey event */
Method (_Q12) {               
        MB_DECREASE_BRIGHTNESS();
}
/* Wireless on/off hotkey event */
Method (_Q1C) {               
        MB_TOGGLE_WIRELESS();
}
 
=== The mainboard handler method ===
 
Provide a generic mainboard "EC event" method that any EC _Qxx could call and pass the event ID to. The event ID is a standard defined event ID , greater than 255 so as not to conflict with possible Qxx IDs.  This limits the permutations of mainboard EC event handlers and gives the flexibility to pass all the various EC events to the mainboard for handling.


For example:
== Hotkey and event methods ==


#define EC_EVENT_LID_CLOSED 0x100
Provide a generic mainboard device in the '''\_SB''' scope with a set of pre-defined methods. This way, the EC can pass events to the mainboard for handling.


In the EC ASL:
The mainboard is not required to implement all methods, however, it must provide all such methods for the EC. The EC can call any of these methods. If the EC requires a method which is not part of the standard set, the this fact must be documented '''src/ec/vendor/model/documentation.txt'''.


  /* lid closed */
  Device (MB) {
Method (_Q01) {                
/* Lid open */
        \_SB.MBEC (EC_EVENT_LID_CLOSED)
Method (LIDO) { /* Stub */ }
/* Lid closed */
Method (LIDC) { /* Stub */}
/* Increase brightness */
Method (BRTU) { /* Stub */ }
/* Decrease brightness */
Method (BRTD) { /* Stub */ }
  /* Switch display */
Method (DSPS) { /* Stub */ }
/* Toggle wireless */
Method (WLTG) { /* Stub */ }
/* Decrease brightness */
Method (LIDS) { /* Stub */ }
  }
  }


And the mainboard handler could look like:
These methods should be called by the EC using the '''\_SB.MB''' scope:


  Scope (\_SB)
  /* Decrease brightness hotkey */
Method (_Q11, 0, NotSerialized)
  {
  {
        /* mainboard event handler */
\_SB.MB.BRTD()
        Method (MBEC, 1, Serialized) {
        Switch (ToInteger (Arg0)) {
                Case (EC_EVENT_LID_CLOSED) { ... }
                Case (EC_EVENT_...) { ... }
        }
}
 
=== The mainboard namespace method ===
 
Similar to the mainboard handler method, but handlers are placed in a special namespace.
 
Scope (MB) {
        /* Lid open */
        Method (LIDO) { ... }
        /* Lid closed */
        Method (LIDC) { ... }
        /* Increase brightness */
        Method (BRTU) { ... }
  }
  }
But even in this form there needs to be a generic method for all the special cases...


== EC-specific extensions ==
== EC-specific extensions ==


The EC may provide specific extensions to this specifications. However, any such extension must be fully documented in '''src/ec/vendor/model/documentation.txt'''. The EC must be able to function properly even if the mainboard does not define or use such extensions.
The EC may provide specific extensions to this specifications. However, any such extension must be fully documented in '''src/ec/vendor/model/documentation.txt'''. The EC must be able to function properly even if the mainboard does not define or use such extensions.

Latest revision as of 03:37, 19 April 2014

This page details the required interface and implementation details for connecting embedded controller ASL files to mainboard ASL files. Implementing this specification is mandatory for every new mainboard/EC added to the tree.

EC ASL files should be self-contained, and not depend on the specific chipset or mainboard. As a result all variables and methods which are used must be standardized to foster interoperability and modularity. This specification details how to achieve those points.

System Resources

All ECs are assumed to use IO ports 0x62 and 0x66 for data/commands. If the EC also serves as a keyboard controller, it is assumed to use ports 0x60 and 0x64. I/O port accesses to these ports must be directed to the bus to which the EC is connected. These need not be individually documented.

If the EC uses different ports, or needs other system resources, those must be documented in src/ec/vendor/model/documentation.txt

Defined constants

  • EC_SCI_GPE
    • The general purpose event (GPE) corresponding to the EC SCI line.

Hotkey and event methods

Provide a generic mainboard device in the \_SB scope with a set of pre-defined methods. This way, the EC can pass events to the mainboard for handling.

The mainboard is not required to implement all methods, however, it must provide all such methods for the EC. The EC can call any of these methods. If the EC requires a method which is not part of the standard set, the this fact must be documented src/ec/vendor/model/documentation.txt.

Device (MB) {
	/* Lid open */
	Method (LIDO) { /* Stub */ }
	/* Lid closed */
	Method (LIDC) { /* Stub */}
	/* Increase brightness */
	Method (BRTU) { /* Stub */ }
	/* Decrease brightness */
	Method (BRTD) { /* Stub */ }
 	/* Switch display */
	Method (DSPS) { /* Stub */ }
	/* Toggle wireless */
	Method (WLTG) { /* Stub */ }
	/* Decrease brightness */
	Method (LIDS) { /* Stub */ }
}

These methods should be called by the EC using the \_SB.MB scope:

/* Decrease brightness hotkey */
Method (_Q11, 0, NotSerialized)
{
	\_SB.MB.BRTD()
}

EC-specific extensions

The EC may provide specific extensions to this specifications. However, any such extension must be fully documented in src/ec/vendor/model/documentation.txt. The EC must be able to function properly even if the mainboard does not define or use such extensions.