[src/trunk]: src/share/man/man4 Add few paragraphs about the idea behind ECs ...

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/3160ba7c0f45
branches:  trunk
changeset: 752491:3160ba7c0f45
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Sat Feb 27 19:38:39 2010 +0000

description:
Add few paragraphs about the idea behind ECs from a hardware angle. Also add
a CAVEATS section because of the problematic and difficult nature of ECs.
Update copyright, bump date.

diffstat:

 share/man/man4/acpiec.4 |  97 ++++++++++++++++++++++++++++++++++++++----------
 1 files changed, 77 insertions(+), 20 deletions(-)

diffs (124 lines):

diff -r 858e9b97896b -r 3160ba7c0f45 share/man/man4/acpiec.4
--- a/share/man/man4/acpiec.4   Sat Feb 27 19:23:38 2010 +0000
+++ b/share/man/man4/acpiec.4   Sat Feb 27 19:38:39 2010 +0000
@@ -1,6 +1,6 @@
-.\" $NetBSD: acpiec.4,v 1.4 2008/04/30 13:10:53 martin Exp $
+.\" $NetBSD: acpiec.4,v 1.5 2010/02/27 19:38:39 jruoho Exp $
 .\"
-.\" Copyright (c) 2002, 2004 The NetBSD Foundation, Inc.
+.\" Copyright (c) 2002, 2004, 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -24,7 +24,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd December 12, 2007
+.Dd February 27, 2010
 .Dt ACPIEC 4
 .Os
 .Sh NAME
@@ -38,24 +38,67 @@
 .Nm
 driver supports ACPI Embedded Controllers.
 .Pp
-It provides
-embedded controller access for other ACPI devices.
-On many systems which have an
+An ACPI Embedded Controller
+.Pq Tn EC
+is typically a small microprocessor that is responsible for various tasks
+related to
+.Tn ACPI .
+The primary task is to handle
+.Tn ACPI
+specific interrupts, which are mapped to so-called
+.Tn ACPI
+General Purpose Events
+.Pq Tn GPEs .
+Other possible functions include embedded access to other buses such as the
+.Xr iic 4 .
+.Pp
+The
+.Tn ACPI
+specific events range from user initiated events to events triggered by
+the hardware.
+When such an event occurs, typically either a System Management Interrupt
+.Pq Tn SMI
+or a System Control Interrupt
+.Pq Tn SCI
+is raised.
+The latter is an active, visible, shareable, level interrupt.
+On most Intel chipsets
+.Tn SCI
+is hardwired to the interrupt number 9.
+The main task of an
+.Tn EC
+is to raise a system control interrupt.
+.Pp
+All GPEs generate SCIs.
+A typical example of the internal wiring of
+.Tn GPEs
+could involve
+.Xr gpio 4 :
+when say the
+.Tn AC
+adapter is connected, a certain
+.Tn GPIO
+line becomes active, a given
+.Tn GPE
+is flagged, and a
+.Tn SCI
+interrupt is raised by the
+.Tn EC ,
+leading to execution of
+.Tn ACPI
+machine code in order to locate the handler associated with the event.
+A corresponding driver,
+.Xr acpiacad 4
+in this case, will finally finish the processing of the event.
+.Pp
+Due to the reasons described above, majority of
+.Tn ACPI
+specific drivers are dysfunctional without
+.Nm .
+It is therefore recommended that
 .Nm
-device, other ACPI devices such as
-.Xr acpiacad 4 ,
-.Xr acpibat 4 ,
-or
-.Xr acpitz 4
-implicitly depend on the
-.Nm
-device.
-Therefore it is a good idea to enable
-.Nm
-with other ACPI devices unless you are sure
-the system does not have an
-.Nm
-device.
+is always enabled,
+even though it may not be required on some older systems.
 .Sh SEE ALSO
 .Xr acpi 4
 .Sh HISTORY
@@ -64,3 +107,17 @@
 driver
 appeared in
 .Nx 1.6 .
+.Sh CAVEATS
+Many machines depend on early attachment of
+.Nm .
+In such cases the information required by
+.Nm
+should be available as a separate and optional
+Embedded Controller Descriptor Table
+.Pq Tn ECDT .
+If an
+.Tn ECDT
+is not available or early attachment can not be carried out due other reasons,
+the initialization of the whole
+.Xr acpi 4
+subsystem may be problematic.