]>
Commit | Line | Data |
---|---|---|
1e22c4d9 | 1 | /** @file\r |
9095d37b LG |
2 | Provides services to notify the PCI bus driver that some events have happened\r |
3 | in a hot-plug controller (such as a PC Card socket, or PHPC), and to ask the\r | |
1e22c4d9 | 4 | PCI bus driver to create or destroy handles for PCI-like devices.\r |
5 | \r | |
9095d37b | 6 | A hot-plug capable PCI bus driver should produce the EFI PCI Hot Plug Request\r |
1e22c4d9 | 7 | protocol. When a PCI device or a PCI-like device (for example, 32-bit PC Card)\r |
9095d37b | 8 | is installed after PCI bus does the enumeration, the PCI bus driver can be\r |
1e22c4d9 | 9 | notified through this protocol. For example, when a 32-bit PC Card is inserted\r |
10 | into the PC Card socket, the PC Card bus driver can call interface of this\r | |
11 | protocol to notify PCI bus driver to allocate resource and create handles for\r | |
12 | this PC Card.\r | |
9095d37b LG |
13 | \r |
14 | The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL is installed by the PCI bus driver on a\r | |
15 | separate handle when PCI bus driver starts up. There is only one instance in\r | |
1e22c4d9 | 16 | the system. Any driver that wants to use this protocol must locate it globally.\r |
9095d37b LG |
17 | The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL allows the driver of hot-plug controller,\r |
18 | for example, PC Card Bus driver, to notify PCI bus driver that an event has\r | |
19 | happened in the hot-plug controller, and the PCI bus driver is requested to\r | |
20 | create (add) or destroy (remove) handles for the specified PCI-like devices.\r | |
21 | For example, when a 32-bit PC Card is inserted, this protocol interface will\r | |
22 | be called with an add operation, and the PCI bus driver will enumerate and\r | |
23 | start the devices inserted; when a 32-bit PC Card is removed, this protocol\r | |
24 | interface will be called with a remove operation, and the PCI bus driver will\r | |
25 | stop the devices and destroy their handles. The existence of this protocol\r | |
1e22c4d9 | 26 | represents the capability of the PCI bus driver. If this protocol exists in\r |
9095d37b | 27 | system, it means PCI bus driver is hot-plug capable, thus together with the\r |
1e22c4d9 | 28 | effort of PC Card bus driver, hot-plug of PC Card can be supported. Otherwise,\r |
9095d37b LG |
29 | the hot-plug capability is not provided.\r |
30 | \r | |
31 | Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r | |
9344f092 | 32 | SPDX-License-Identifier: BSD-2-Clause-Patent\r |
1e22c4d9 | 33 | \r |
34 | @par Revision Reference:\r | |
9095d37b | 35 | This Protocol is defined in UEFI Platform Initialization Specification 1.2\r |
1e22c4d9 | 36 | Volume 5: Standards\r |
9095d37b | 37 | \r |
1e22c4d9 | 38 | **/\r |
39 | \r | |
40 | #ifndef __PCI_HOTPLUG_REQUEST_H_\r | |
41 | #define __PCI_HOTPLUG_REQUEST_H_\r | |
42 | \r | |
43 | ///\r | |
44 | /// Global ID for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL\r | |
45 | ///\r | |
46 | #define EFI_PCI_HOTPLUG_REQUEST_PROTOCOL_GUID \\r | |
47 | { \\r | |
48 | 0x19cb87ab, 0x2cb9, 0x4665, {0x83, 0x60, 0xdd, 0xcf, 0x60, 0x54, 0xf7, 0x9d} \\r | |
49 | }\r | |
50 | \r | |
51 | ///\r | |
52 | /// Forward declaration for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL\r | |
53 | ///\r | |
2f88bd3a | 54 | typedef struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL EFI_PCI_HOTPLUG_REQUEST_PROTOCOL;\r |
1e22c4d9 | 55 | \r |
56 | ///\r | |
57 | /// Enumeration of PCI hot plug operations\r | |
9095d37b | 58 | ///\r |
1e22c4d9 | 59 | typedef enum {\r |
60 | ///\r | |
61 | /// The PCI bus driver is requested to create handles for the specified devices.\r | |
62 | /// An array of EFI_HANDLE is returned, with a NULL element marking the end of\r | |
63 | /// the array.\r | |
64 | ///\r | |
65 | EfiPciHotPlugRequestAdd,\r | |
66 | \r | |
67 | ///\r | |
68 | /// The PCI bus driver is requested to destroy handles for the specified devices.\r | |
69 | ///\r | |
70 | EfiPciHotplugRequestRemove\r | |
71 | } EFI_PCI_HOTPLUG_OPERATION;\r | |
72 | \r | |
73 | /**\r | |
74 | This function is used to notify PCI bus driver that some events happened in a\r | |
9095d37b | 75 | hot-plug controller, and the PCI bus driver is requested to start or stop\r |
1e22c4d9 | 76 | specified PCI-like devices.\r |
9095d37b | 77 | \r |
1e22c4d9 | 78 | This function allows the PCI bus driver to be notified to act as requested when\r |
9095d37b | 79 | a hot-plug event has happened on the hot-plug controller. Currently, the\r |
1e22c4d9 | 80 | operations include add operation and remove operation. If it is a add operation,\r |
9095d37b | 81 | the PCI bus driver will enumerate, allocate resources for devices behind the\r |
1e22c4d9 | 82 | hot-plug controller, and create handle for the device specified by RemainingDevicePath.\r |
9095d37b LG |
83 | The RemainingDevicePath is an optional parameter. If it is not NULL, only the\r |
84 | specified device is started; if it is NULL, all devices behind the hot-plug\r | |
85 | controller are started. The newly created handles of PC Card functions are\r | |
1e22c4d9 | 86 | returned in the ChildHandleBuffer, together with the number of child handle in\r |
87 | NumberOfChildren. If it is a remove operation, when NumberOfChildren contains\r | |
88 | a non-zero value, child handles specified in ChildHandleBuffer are stopped and\r | |
89 | destroyed; otherwise, PCI bus driver is notified to stop managing the controller\r | |
9095d37b LG |
90 | handle.\r |
91 | \r | |
92 | @param[in] This A pointer to the EFI_PCI_HOTPLUG_REQUEST_PROTOCOL\r | |
1e22c4d9 | 93 | instance.\r |
9095d37b LG |
94 | @param[in] Operation The operation the PCI bus driver is requested\r |
95 | to make.\r | |
1e22c4d9 | 96 | @param[in] Controller The handle of the hot-plug controller.\r |
97 | @param[in] RemainingDevicePath The remaining device path for the PCI-like\r | |
98 | hot-plug device. It only contains device\r | |
9095d37b | 99 | path nodes behind the hot-plug controller.\r |
1e22c4d9 | 100 | It is an optional parameter and only valid\r |
9095d37b LG |
101 | when the Operation is a add operation. If\r |
102 | it is NULL, all devices behind the PC Card\r | |
1e22c4d9 | 103 | socket are started.\r |
9095d37b | 104 | @param[in,out] NumberOfChildren The number of child handles. For an add\r |
1e22c4d9 | 105 | operation, it is an output parameter. For\r |
106 | a remove operation, it's an input parameter.\r | |
107 | When it contains a non-zero value, children\r | |
108 | handles specified in ChildHandleBuffer are\r | |
9095d37b LG |
109 | destroyed. Otherwise, PCI bus driver is\r |
110 | notified to stop managing the controller\r | |
1e22c4d9 | 111 | handle.\r |
9095d37b LG |
112 | @param[in,out] ChildHandleBuffer The buffer which contains the child handles.\r |
113 | For an add operation, it is an output\r | |
114 | parameter and contains all newly created\r | |
1e22c4d9 | 115 | child handles. For a remove operation, it\r |
116 | contains child handles to be destroyed when\r | |
117 | NumberOfChildren contains a non-zero value.\r | |
118 | It can be NULL when NumberOfChildren is 0.\r | |
119 | It's the caller's responsibility to allocate\r | |
120 | and free memory for this buffer.\r | |
9095d37b LG |
121 | \r |
122 | @retval EFI_SUCCESS The handles for the specified device have been\r | |
123 | created or destroyed as requested, and for an\r | |
124 | add operation, the new handles are returned in\r | |
1e22c4d9 | 125 | ChildHandleBuffer.\r |
126 | @retval EFI_INVALID_PARAMETER Operation is not a legal value.\r | |
127 | @retval EFI_INVALID_PARAMETER Controller is NULL or not a valid handle.\r | |
128 | @retval EFI_INVALID_PARAMETER NumberOfChildren is NULL.\r | |
9095d37b LG |
129 | @retval EFI_INVALID_PARAMETER ChildHandleBuffer is NULL while Operation is\r |
130 | remove and NumberOfChildren contains a non-zero\r | |
1e22c4d9 | 131 | value.\r |
132 | @retval EFI_INVALID_PARAMETER ChildHandleBuffer is NULL while Operation is add.\r | |
9095d37b | 133 | @retval EFI_OUT_OF_RESOURCES There are no enough resources to start the\r |
1e22c4d9 | 134 | devices.\r |
135 | **/\r | |
136 | typedef\r | |
137 | EFI_STATUS\r | |
138 | (EFIAPI *EFI_PCI_HOTPLUG_REQUEST_NOTIFY)(\r | |
139 | IN EFI_PCI_HOTPLUG_REQUEST_PROTOCOL *This,\r | |
140 | IN EFI_PCI_HOTPLUG_OPERATION Operation,\r | |
141 | IN EFI_HANDLE Controller,\r | |
142 | IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL,\r | |
143 | IN OUT UINT8 *NumberOfChildren,\r | |
144 | IN OUT EFI_HANDLE *ChildHandleBuffer\r | |
145 | );\r | |
146 | \r | |
147 | ///\r | |
9095d37b LG |
148 | /// Provides services to notify PCI bus driver that some events have happened in\r |
149 | /// a hot-plug controller (for example, PC Card socket, or PHPC), and ask PCI bus\r | |
1e22c4d9 | 150 | /// driver to create or destroy handles for the PCI-like devices.\r |
151 | ///\r | |
152 | struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL {\r | |
153 | ///\r | |
9095d37b LG |
154 | /// Notify the PCI bus driver that some events have happened in a hot-plug\r |
155 | /// controller (for example, PC Card socket, or PHPC), and ask PCI bus driver\r | |
156 | /// to create or destroy handles for the PCI-like devices. See Section 0 for\r | |
1e22c4d9 | 157 | /// a detailed description.\r |
158 | ///\r | |
2f88bd3a | 159 | EFI_PCI_HOTPLUG_REQUEST_NOTIFY Notify;\r |
1e22c4d9 | 160 | };\r |
161 | \r | |
2f88bd3a | 162 | extern EFI_GUID gEfiPciHotPlugRequestProtocolGuid;\r |
1e22c4d9 | 163 | \r |
164 | #endif\r |