ArpDriver.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330
  1. /** @file
  2. ARP driver header file.
  3. Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
  4. SPDX-License-Identifier: BSD-2-Clause-Patent
  5. **/
  6. #ifndef _ARP_DRIVER_H_
  7. #define _ARP_DRIVER_H_
  8. #include <Uefi.h>
  9. #include <Protocol/Arp.h>
  10. #include <Protocol/ManagedNetwork.h>
  11. #include <Protocol/ServiceBinding.h>
  12. #include <Library/DebugLib.h>
  13. #include <Library/UefiDriverEntryPoint.h>
  14. #include <Library/UefiBootServicesTableLib.h>
  15. #include <Library/UefiLib.h>
  16. //
  17. // Global variables
  18. //
  19. extern EFI_DRIVER_BINDING_PROTOCOL gArpDriverBinding;
  20. extern EFI_COMPONENT_NAME_PROTOCOL gArpComponentName;
  21. extern EFI_COMPONENT_NAME2_PROTOCOL gArpComponentName2;
  22. //
  23. // Function prototypes for the Driver Binding Protocol
  24. //
  25. /**
  26. Tests to see if this driver supports a given controller.
  27. If a child device is provided, it further tests to see if this driver supports
  28. creating a handle for the specified child device.
  29. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  30. @param[in] ControllerHandle The handle of the controller to test. This handle
  31. must support a protocol interface that supplies
  32. an I/O abstraction to the driver.
  33. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path.
  34. This parameter is ignored by device drivers,
  35. and is optional for bus drivers.
  36. @retval EFI_SUCCESS The device specified by ControllerHandle and
  37. RemainingDevicePath is supported by the driver
  38. specified by This.
  39. @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
  40. RemainingDevicePath is already being managed
  41. by the driver specified by This.
  42. @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
  43. RemainingDevicePath is already being managed by
  44. a different driver or an application that
  45. requires exclusive access. Currently not implemented.
  46. @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
  47. RemainingDevicePath is not supported by the
  48. driver specified by This.
  49. **/
  50. EFI_STATUS
  51. EFIAPI
  52. ArpDriverBindingSupported (
  53. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  54. IN EFI_HANDLE ControllerHandle,
  55. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
  56. );
  57. /**
  58. Start this driver on ControllerHandle.
  59. The Start() function is designed to be invoked from the EFI boot service ConnectController().
  60. As a result, much of the error checking on the parameters to Start() has been
  61. moved into this common boot service. It is legal to call Start() from other locations,
  62. but the following calling restrictions must be followed or the system behavior
  63. will not be deterministic.
  64. 1. ControllerHandle must be a valid EFI_HANDLE.
  65. 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally
  66. aligned EFI_DEVICE_PATH_PROTOCOL.
  67. 3. Prior to calling Start(), the Supported() function for the driver specified
  68. by This must have been called with the same calling parameters, and Supported()
  69. must have returned EFI_SUCCESS.
  70. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  71. @param[in] ControllerHandle The handle of the controller to start. This handle
  72. must support a protocol interface that supplies
  73. an I/O abstraction to the driver.
  74. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path.
  75. This parameter is ignored by device drivers,
  76. and is optional for bus drivers.
  77. @retval EFI_SUCCESS The device was started.
  78. @retval EFI_DEVICE_ERROR The device could not be started due to a device error.
  79. Currently not implemented.
  80. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of
  81. resources.
  82. @retval Others The driver failed to start the device.
  83. **/
  84. EFI_STATUS
  85. EFIAPI
  86. ArpDriverBindingStart (
  87. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  88. IN EFI_HANDLE ControllerHandle,
  89. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
  90. );
  91. /**
  92. Stop this driver on ControllerHandle.
  93. Release the control of this controller and remove the IScsi functions. The Stop()
  94. function is designed to be invoked from the EFI boot service DisconnectController().
  95. As a result, much of the error checking on the parameters to Stop() has been moved
  96. into this common boot service. It is legal to call Stop() from other locations,
  97. but the following calling restrictions must be followed or the system behavior
  98. will not be deterministic.
  99. 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
  100. same driver's Start() function.
  101. 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
  102. EFI_HANDLE. In addition, all of these handles must have been created in this driver's
  103. Start() function, and the Start() function must have called OpenProtocol() on
  104. ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
  105. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  106. @param[in] ControllerHandle A handle to the device being stopped. The handle must
  107. support a bus specific I/O protocol for the driver
  108. to use to stop the device.
  109. @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
  110. Not used.
  111. @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
  112. if NumberOfChildren is 0.Not used.
  113. @retval EFI_SUCCESS The device was stopped.
  114. @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
  115. **/
  116. EFI_STATUS
  117. EFIAPI
  118. ArpDriverBindingStop (
  119. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  120. IN EFI_HANDLE ControllerHandle,
  121. IN UINTN NumberOfChildren,
  122. IN EFI_HANDLE *ChildHandleBuffer
  123. );
  124. /**
  125. Creates a child handle and installs a protocol.
  126. The CreateChild() function installs a protocol on ChildHandle.
  127. If ChildHandle is a pointer to NULL, then a new handle is created and returned
  128. in ChildHandle. If ChildHandle is not a pointer to NULL, then the protocol
  129. installs on the existing ChildHandle.
  130. @param This Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
  131. @param ChildHandle Pointer to the handle of the child to create. If it is NULL,
  132. then a new handle is created. If it is a pointer to an existing
  133. UEFI handle, then the protocol is added to the existing UEFI handle.
  134. @retval EFI_SUCCESS The protocol was added to ChildHandle.
  135. @retval EFI_INVALID_PARAMETER ChildHandle is NULL.
  136. @retval EFI_OUT_OF_RESOURCES There are not enough resources available to create
  137. the child
  138. @retval other The child handle was not created
  139. **/
  140. EFI_STATUS
  141. EFIAPI
  142. ArpServiceBindingCreateChild (
  143. IN EFI_SERVICE_BINDING_PROTOCOL *This,
  144. IN EFI_HANDLE *ChildHandle
  145. );
  146. /**
  147. Destroys a child handle with a protocol installed on it.
  148. The DestroyChild() function does the opposite of CreateChild(). It removes a protocol
  149. that was installed by CreateChild() from ChildHandle. If the removed protocol is the
  150. last protocol on ChildHandle, then ChildHandle is destroyed.
  151. @param This Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
  152. @param ChildHandle Handle of the child to destroy
  153. @retval EFI_SUCCESS The protocol was removed from ChildHandle.
  154. @retval EFI_UNSUPPORTED ChildHandle does not support the protocol that is
  155. being removed.
  156. @retval EFI_INVALID_PARAMETER Child handle is NULL.
  157. @retval EFI_ACCESS_DENIED The protocol could not be removed from the ChildHandle
  158. because its services are being used.
  159. @retval other The child handle was not destroyed
  160. **/
  161. EFI_STATUS
  162. EFIAPI
  163. ArpServiceBindingDestroyChild (
  164. IN EFI_SERVICE_BINDING_PROTOCOL *This,
  165. IN EFI_HANDLE ChildHandle
  166. );
  167. //
  168. // EFI Component Name Functions
  169. //
  170. /**
  171. Retrieves a Unicode string that is the user readable name of the driver.
  172. This function retrieves the user readable name of a driver in the form of a
  173. Unicode string. If the driver specified by This has a user readable name in
  174. the language specified by Language, then a pointer to the driver name is
  175. returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
  176. by This does not support the language specified by Language,
  177. then EFI_UNSUPPORTED is returned.
  178. @param[in] This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
  179. EFI_COMPONENT_NAME_PROTOCOL instance.
  180. @param[in] Language A pointer to a Null-terminated ASCII string
  181. array indicating the language. This is the
  182. language of the driver name that the caller is
  183. requesting, and it must match one of the
  184. languages specified in SupportedLanguages. The
  185. number of languages supported by a driver is up
  186. to the driver writer. Language is specified
  187. in RFC 4646 or ISO 639-2 language code format.
  188. @param[out] DriverName A pointer to the Unicode string to return.
  189. This Unicode string is the name of the
  190. driver specified by This in the language
  191. specified by Language.
  192. @retval EFI_SUCCESS The Unicode string for the Driver specified by
  193. This and the language specified by Language was
  194. returned in DriverName.
  195. @retval EFI_INVALID_PARAMETER Language is NULL.
  196. @retval EFI_INVALID_PARAMETER DriverName is NULL.
  197. @retval EFI_UNSUPPORTED The driver specified by This does not support
  198. the language specified by Language.
  199. **/
  200. EFI_STATUS
  201. EFIAPI
  202. ArpComponentNameGetDriverName (
  203. IN EFI_COMPONENT_NAME_PROTOCOL *This,
  204. IN CHAR8 *Language,
  205. OUT CHAR16 **DriverName
  206. );
  207. /**
  208. Retrieves a Unicode string that is the user readable name of the controller
  209. that is being managed by a driver.
  210. This function retrieves the user readable name of the controller specified by
  211. ControllerHandle and ChildHandle in the form of a Unicode string. If the
  212. driver specified by This has a user readable name in the language specified by
  213. Language, then a pointer to the controller name is returned in ControllerName,
  214. and EFI_SUCCESS is returned. If the driver specified by This is not currently
  215. managing the controller specified by ControllerHandle and ChildHandle,
  216. then EFI_UNSUPPORTED is returned. If the driver specified by This does not
  217. support the language specified by Language, then EFI_UNSUPPORTED is returned.
  218. @param[in] This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
  219. EFI_COMPONENT_NAME_PROTOCOL instance.
  220. @param[in] ControllerHandle The handle of a controller that the driver
  221. specified by This is managing. This handle
  222. specifies the controller whose name is to be
  223. returned.
  224. @param[in] ChildHandle The handle of the child controller to retrieve
  225. the name of. This is an optional parameter that
  226. may be NULL. It will be NULL for device
  227. drivers. It will also be NULL for a bus drivers
  228. that wish to retrieve the name of the bus
  229. controller. It will not be NULL for a bus
  230. driver that wishes to retrieve the name of a
  231. child controller.
  232. @param[in] Language A pointer to a Null-terminated ASCII string
  233. array indicating the language. This is the
  234. language of the driver name that the caller is
  235. requesting, and it must match one of the
  236. languages specified in SupportedLanguages. The
  237. number of languages supported by a driver is up
  238. to the driver writer. Language is specified in
  239. RFC 4646 or ISO 639-2 language code format.
  240. @param[out] ControllerName A pointer to the Unicode string to return.
  241. This Unicode string is the name of the
  242. controller specified by ControllerHandle and
  243. ChildHandle in the language specified by
  244. Language from the point of view of the driver
  245. specified by This.
  246. @retval EFI_SUCCESS The Unicode string for the user readable name in
  247. the language specified by Language for the
  248. driver specified by This was returned in
  249. DriverName.
  250. @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
  251. @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
  252. EFI_HANDLE.
  253. @retval EFI_INVALID_PARAMETER Language is NULL.
  254. @retval EFI_INVALID_PARAMETER ControllerName is NULL.
  255. @retval EFI_UNSUPPORTED The driver specified by This is not currently
  256. managing the controller specified by
  257. ControllerHandle and ChildHandle.
  258. @retval EFI_UNSUPPORTED The driver specified by This does not support
  259. the language specified by Language.
  260. **/
  261. EFI_STATUS
  262. EFIAPI
  263. ArpComponentNameGetControllerName (
  264. IN EFI_COMPONENT_NAME_PROTOCOL *This,
  265. IN EFI_HANDLE ControllerHandle,
  266. IN EFI_HANDLE ChildHandle OPTIONAL,
  267. IN CHAR8 *Language,
  268. OUT CHAR16 **ControllerName
  269. );
  270. #endif