SioBusDxe.h 16 KB

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