1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
ACPI Driver Interface
---------------------
Overview:
1) Register each instance of a device with "acpi_register"
2) Call "acpi_access" before accessing the hardware.
(this will ensure that the hardware is awake and ready)
3) "acpi_transition" callback is called before entering D1-D3
or after entering D0
4) Call "acpi_dev_idle" when the device is not being used
(not required by will improve idle detection)
5) When unloaded, unregister the device with "acpi_unregister"
/*
* Description: Register a device with the ACPI subsystem
*
* Parameters:
* info - static device information
* type - device type
* hid - PnP identifier (or 0 if unknown)
* trans - device state transition callback
* adr - bus number and address or unique id
*
* Returns: Registered ACPI device or NULL on error
*
* Details: The device type, bus number, and bus address should be
* enough information to reconstruct the device tree and
* identify device dependencies
*
* Examples:
* struct acpi_dev_info info = {ACPI_SYS_DEV, ACPI_VGA_HID, vga_trans};
* dev = acpi_register(&info, 0);
*
* struct pci_dev *pci_dev = pci_find_dev(...);
* struct acpi_dev_info info = {ACPI_PCI_DEV, 0, trans};
* dev = acpi_register(&info, ACPI_PCI_ADR(pci_dev));
*/
struct acpi_dev *acpi_register(struct acpi_dev_info *info, unsigned long adr);
/*
* Description: Unregister a device with ACPI
*
* Parameters:
* dev - ACPI device previously returned from acpi_register
*/
void acpi_unregister(struct acpi_dev *dev);
/*
* Device idle/use detection
*
* In general, drivers for all devices should call "acpi_access"
* before accessing the hardware (ie. before reading or modifying
* a hardware register). Request or packet-driven drivers should
* additionally call "acpi_idle" when a device is not being used.
*
* Examples:
* 1) A keyboard driver would call acpi_access whenever a key is pressed
* 2) A network driver would call acpi_access before submitting
* a packet for transmit or receive and acpi_idle when its
* transfer and receive queues are empty.
* 3) A VGA driver would call acpi_access before it accesses any
* of the video controller registers
*
* Ultimately, the ACPI policy manager uses the access and idle
* information to decide when to transition devices between
* device states.
*/
/*
* Description: Update device access time and wake up device, if necessary
*
* Parameters:
* dev - ACPI device previously returned from acpi_register
*
* Details: If called from an interrupt handler acpi_access updates
* access time but should never need to wake up the device
* (if device is generating interrupts, it should be awake
* already) This is important as we can not wake up
* devices (run AML, etc.) from an interrupt handler.
*/
void acpi_access(struct acpi_dev *dev);
/*
* Description: Identify device as currently being idle
*
* Parameters:
* dev - ACPI device previously returned from acpi_register
*
* Details: A call to acpi_idle might signal to the policy manager
* to put a device to sleep. If a new device request arrives
* between the call to acpi_idle and the acpi_transition
* callback, the driver should fail the acpi_transition request.
*/
void acpi_dev_idle(struct acpi_dev *dev);
/*
* Transition function
*
* Parameters:
* dev - ACPI device previously returned from acpi_register
* state - the device state being entered
*
* Returns: 0 if the state transition is possible and context saved
* EINVAL if the requested device state is not supported
* EBUSY if the device is now busy and can not transition
* ENOMEM if the device was unable to save context (out of memory)
*
* Details: The device state transition function will be called
* before the device is transitioned into the D1-D3 states
* or after the device is transitioned into the D0 state.
* The device driver should save (D1-D3) or restore (D0)
* device context when the transition function is called.
*
* For system devices, the ACPI subsystem will perform
* the actual hardware state transition itself. For bus
* devices, after the driver's acpi_transition function
* is called, the bus driver's acpi_transition function
* is called to perform the actual hardware state transition.
*
* Once a driver returns 0 (success) from a transition
* to D1-3 request, it should not process any further
* requests or access the device hardware until a
* call to "acpi_access" is made.
*/
typedef int (*acpi_transition)(struct acpi_dev *dev, acpi_dstate_t state);
|
