2 The SioBusDxe driver is used to create child devices on the ISA bus and
3 installs the Super I/O protocols on them.
5 Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
7 SPDX-License-Identifier: BSD-2-Clause-Patent
11 #ifndef __SIO_BUS_DXE_H__
12 #define __SIO_BUS_DXE_H__
16 #include <IndustryStandard/Pci.h>
18 #include <Protocol/PciIo.h>
19 #include <Protocol/SuperIo.h>
21 #include <Library/UefiDriverEntryPoint.h>
22 #include <Library/UefiLib.h>
23 #include <Library/UefiBootServicesTableLib.h>
24 #include <Library/DebugLib.h>
25 #include <Library/ReportStatusCodeLib.h>
26 #include <Library/MemoryAllocationLib.h>
27 #include <Library/BaseMemoryLib.h>
28 #include <Library/DevicePathLib.h>
30 #include "SioService.h"
33 // SIO Bus driver private data structure
36 EFI_PCI_IO_PROTOCOL
*PciIo
;
37 UINT64 OriginalAttributes
;
38 } SIO_BUS_DRIVER_PRIVATE_DATA
;
44 extern EFI_COMPONENT_NAME_PROTOCOL gSioBusComponentName
;
45 extern EFI_COMPONENT_NAME2_PROTOCOL gSioBusComponentName2
;
49 // EFI Component Name Functions
53 Retrieves a Unicode string that is the user readable name of the driver.
55 This function retrieves the user readable name of a driver in the form of a
56 Unicode string. If the driver specified by This has a user readable name in
57 the language specified by Language, then a pointer to the driver name is
58 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
59 by This does not support the language specified by Language, then
60 EFI_UNSUPPORTED is returned.
62 @param[in] This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL
63 or EFI_COMPONENT_NAME_PROTOCOL instance.
64 @param[in] Language A pointer to a Null-terminated ASCII string
65 array indicating the language. This is the
66 language of the driver name that the caller is
67 requesting, and it must match one of the
68 languages specified in SupportedLanguages. The
69 number of languages supported by a driver is up
70 to the driver writer. Language is specified
71 in RFC 4646 or ISO 639-2 language code format.
72 @param[out] DriverName A pointer to the Unicode string to return. This
73 Unicode string is the name of the driver
74 specified by This in the language specified by
77 @retval EFI_SUCCESS The Unicode string for the Driver specified by
78 This and the language specified by Language was
79 returned in DriverName.
80 @retval EFI_INVALID_PARAMETER Language is NULL.
81 @retval EFI_INVALID_PARAMETER DriverName is NULL.
82 @retval EFI_UNSUPPORTED The driver specified by This does not support
83 the language specified by Language.
88 SioBusComponentNameGetDriverName (
89 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
91 OUT CHAR16
**DriverName
95 Retrieves a Unicode string that is the user readable name of the controller
96 that is being managed by a driver.
98 This function retrieves the user readable name of the controller specified by
99 ControllerHandle and ChildHandle in the form of a Unicode string. If the
100 driver specified by This has a user readable name in the language specified
101 by Language, then a pointer to the controller name is returned in
102 ControllerName, and EFI_SUCCESS is returned. If the driver specified by This
103 is not currently managing the controller specified by ControllerHandle and
104 ChildHandle, then EFI_UNSUPPORTED is returned. If the driver specified by
105 This does not support the language specified by Language, then
106 EFI_UNSUPPORTED is returned.
108 @param[in] This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL
109 or EFI_COMPONENT_NAME_PROTOCOL instance.
110 @param[in] ControllerHandle The handle of a controller that the driver
111 specified by This is managing. This handle
112 specifies the controller whose name is to be
114 @param[in] ChildHandle The handle of the child controller to retrieve
115 the name of. This is an optional parameter
116 that may be NULL. It will be NULL for device
117 drivers. It will also be NULL for a bus
118 drivers that wish to retrieve the name of the
119 bus controller. It will not be NULL for a bus
120 driver that wishes to retrieve the name of a
122 @param[in] Language A pointer to a Null-terminated ASCII string
123 array indicating the language. This is the
124 language of the driver name that the caller is
125 requesting, and it must match one of the
126 languages specified in SupportedLanguages. The
127 number of languages supported by a driver is up
128 to the driver writer. Language is specified in
129 RFC 4646 or ISO 639-2 language code format.
130 @param[out] ControllerName A pointer to the Unicode string to return.
131 This Unicode string is the name of the
132 controller specified by ControllerHandle and
133 ChildHandle in the language specified by
134 Language from the point of view of the driver
137 @retval EFI_SUCCESS The Unicode string for the user readable name
138 in the language specified by Language for the
139 driver specified by This was returned in
141 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
142 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
144 @retval EFI_INVALID_PARAMETER Language is NULL.
145 @retval EFI_INVALID_PARAMETER ControllerName is NULL.
146 @retval EFI_UNSUPPORTED The driver specified by This is not currently
147 managing the controller specified by
148 ControllerHandle and ChildHandle.
149 @retval EFI_UNSUPPORTED The driver specified by This does not support
150 the language specified by Language.
155 SioBusComponentNameGetControllerName (
156 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
157 IN EFI_HANDLE ControllerHandle
,
158 IN EFI_HANDLE ChildHandle OPTIONAL
,
160 OUT CHAR16
**ControllerName
165 // Driver Binding Protocol interfaces
169 Tests to see if this driver supports a given controller. If a child device is
170 provided, it further tests to see if this driver supports creating a handle
171 for the specified child device.
173 This function checks to see if the driver specified by This supports the
174 device specified by ControllerHandle. Drivers will typically use the device
175 path attached to ControllerHandle and/or the services from the bus I/O
176 abstraction attached to ControllerHandle to determine if the driver supports
177 ControllerHandle. This function may be called many times during platform
178 initialization. In order to reduce boot times, the tests performed by this
179 function must be very small, and take as little time as possible to execute.
180 This function must not change the state of any hardware devices, and this
181 function must be aware that the device specified by ControllerHandle may
182 already be managed by the same driver or a different driver. This function
183 must match its calls to AllocatePages() with FreePages(), AllocatePool() with
184 FreePool(), and OpenProtocol() with CloseProtocol(). Since ControllerHandle
185 may have been previously started by the same driver, if a protocol is already
186 in the opened state, then it must not be closed with CloseProtocol(). This is
187 required to guarantee the state of ControllerHandle is not modified by this
190 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL
192 @param[in] ControllerHandle The handle of the controller to test. This
193 handle must support a protocol interface
194 that supplies an I/O abstraction to the
196 @param[in] RemainingDevicePath A pointer to the remaining portion of a
197 device path. This parameter is ignored by
198 device drivers, and is optional for bus
199 drivers. For bus drivers, if this parameter
200 is not NULL, then the bus driver must
201 determine if the bus controller specified by
202 ControllerHandle and the child controller
203 specified by RemainingDevicePath are both
204 supported by this bus driver.
206 @retval EFI_SUCCESS The device specified by ControllerHandle and
207 RemainingDevicePath is supported by the
208 driver specified by This.
209 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
210 RemainingDevicePath is already being managed
211 by the driver specified by This.
212 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
213 RemainingDevicePath is already being managed
214 by a different driver or an application that
215 requires exclusive access.
216 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
217 RemainingDevicePath is not supported by the
218 driver specified by This.
223 SioBusDriverBindingSupported (
224 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
225 IN EFI_HANDLE Controller
,
226 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
230 Starts a device controller or a bus controller.
232 The Start() function is designed to be invoked from the EFI boot service
233 ConnectController(). As a result, much of the error checking on the
234 parameters to Start() has been moved into this common boot service. It is
235 legal to call Start() from other locations, but the following calling
236 restrictions must be followed or the system behavior will not be
238 1. ControllerHandle must be a valid EFI_HANDLE.
239 2. If RemainingDevicePath is not NULL, then it must be a pointer to a
240 naturally aligned EFI_DEVICE_PATH_PROTOCOL.
241 3. Prior to calling Start(), the Supported() function for the driver
242 specified by This must have been called with the same calling parameters,
243 and Supported() must have returned EFI_SUCCESS.
245 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL
247 @param[in] ControllerHandle The handle of the controller to start. This
248 handle must support a protocol interface
249 that supplies an I/O abstraction to the
251 @param[in] RemainingDevicePath A pointer to the remaining portion of a
252 device path. This parameter is ignored by
253 device drivers, and is optional for bus
254 drivers. For a bus driver, if this parameter
255 is NULL, then handles for all the children
256 of Controller are created by this driver. If
257 this parameter is not NULL and the first
258 Device Path Node is not the End of Device
259 Path Node, then only the handle for the
260 child device specified by the first Device
261 Path Node of RemainingDevicePath is created
262 by this driver. If the first Device Path
263 Node of RemainingDevicePath is the End of
264 Device Path Node, no child handle is created
267 @retval EFI_SUCCESS The device was started.
268 @retval EFI_DEVICE_ERROR The device could not be started due to a
270 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a
272 @retval Others The driver failded to start the device.
277 SioBusDriverBindingStart (
278 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
279 IN EFI_HANDLE Controller
,
280 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
284 Stops a device controller or a bus controller.
286 The Stop() function is designed to be invoked from the EFI boot service
287 DisconnectController(). As a result, much of the error checking on the
288 parameters to Stop() has been moved into this common boot service. It is
289 legal to call Stop() from other locations, but the following calling
290 restrictions must be followed or the system behavior will not be
292 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous
293 call to this same driver's Start() function.
294 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a
295 valid EFI_HANDLE. In addition, all of these handles must have been created
296 in this driver's Start() function, and the Start() function must have
297 called OpenProtocol() on ControllerHandle with an Attribute of
298 EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
300 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL
302 @param[in] ControllerHandle A handle to the device being stopped. The
303 handle must support a bus specific I/O
304 protocol for the driver to use to stop the
306 @param[in] NumberOfChildren The number of child device handles in
308 @param[in] ChildHandleBuffer An array of child handles to be freed. May be
309 NULL if NumberOfChildren is 0.
311 @retval EFI_SUCCESS The device was stopped.
312 @retval EFI_DEVICE_ERROR The device could not be stopped due to a
318 SioBusDriverBindingStop (
319 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
320 IN EFI_HANDLE Controller
,
321 IN UINTN NumberOfChildren
,
322 IN EFI_HANDLE
*ChildHandleBuffer
325 #endif // __SIO_BUS_DXE_H__