I2cDxe.h 48 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091
  1. /** @file
  2. Private data structures for the I2C DXE driver.
  3. This file defines common data structures, macro definitions and some module
  4. internal function header files.
  5. Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
  6. SPDX-License-Identifier: BSD-2-Clause-Patent
  7. **/
  8. #ifndef __I2C_DXE_H__
  9. #define __I2C_DXE_H__
  10. #include <Uefi.h>
  11. #include <Library/BaseMemoryLib.h>
  12. #include <Library/DebugLib.h>
  13. #include <Library/DevicePathLib.h>
  14. #include <Library/MemoryAllocationLib.h>
  15. #include <Library/TimerLib.h>
  16. #include <Library/UefiBootServicesTableLib.h>
  17. #include <Library/UefiDriverEntryPoint.h>
  18. #include <Library/UefiLib.h>
  19. #include <Protocol/DriverBinding.h>
  20. #include <Protocol/I2cEnumerate.h>
  21. #include <Protocol/I2cHost.h>
  22. #include <Protocol/I2cIo.h>
  23. #include <Protocol/I2cMaster.h>
  24. #include <Protocol/I2cBusConfigurationManagement.h>
  25. #include <Protocol/LoadedImage.h>
  26. #define I2C_DEVICE_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'D')
  27. #define I2C_HOST_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'H')
  28. #define I2C_REQUEST_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'R')
  29. //
  30. // Synchronize access to the list of requests
  31. //
  32. #define TPL_I2C_SYNC TPL_NOTIFY
  33. //
  34. // I2C bus context
  35. //
  36. typedef struct {
  37. EFI_I2C_ENUMERATE_PROTOCOL *I2cEnumerate;
  38. EFI_I2C_HOST_PROTOCOL *I2cHost;
  39. EFI_HANDLE Controller;
  40. EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath;
  41. EFI_HANDLE DriverBindingHandle;
  42. } I2C_BUS_CONTEXT;
  43. //
  44. // I2C device context
  45. //
  46. typedef struct {
  47. //
  48. // Structure identification
  49. //
  50. UINT32 Signature;
  51. //
  52. // I2c device handle
  53. //
  54. EFI_HANDLE Handle;
  55. //
  56. // Upper level API to support the I2C device I/O
  57. //
  58. EFI_I2C_IO_PROTOCOL I2cIo;
  59. //
  60. // Device path for this device
  61. //
  62. EFI_DEVICE_PATH_PROTOCOL *DevicePath;
  63. //
  64. // Platform specific data for this device
  65. //
  66. CONST EFI_I2C_DEVICE *I2cDevice;
  67. //
  68. // Context for the common I/O support including the
  69. // lower level API to the host controller.
  70. //
  71. I2C_BUS_CONTEXT *I2cBusContext;
  72. } I2C_DEVICE_CONTEXT;
  73. #define I2C_DEVICE_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_DEVICE_CONTEXT, I2cIo, I2C_DEVICE_SIGNATURE)
  74. //
  75. // I2C Request
  76. //
  77. typedef struct {
  78. //
  79. // Signature
  80. //
  81. UINT32 Signature;
  82. //
  83. // Next request in the pending request list
  84. //
  85. LIST_ENTRY Link;
  86. //
  87. // I2C bus configuration for the operation
  88. //
  89. UINTN I2cBusConfiguration;
  90. //
  91. // I2C slave address for the operation
  92. //
  93. UINTN SlaveAddress;
  94. //
  95. // Event to set for asynchronous operations, NULL for
  96. // synchronous operations
  97. //
  98. EFI_EVENT Event;
  99. //
  100. // I2C operation description
  101. //
  102. EFI_I2C_REQUEST_PACKET *RequestPacket;
  103. //
  104. // Optional buffer to receive the I2C operation completion status
  105. //
  106. EFI_STATUS *Status;
  107. } I2C_REQUEST;
  108. #define I2C_REQUEST_FROM_ENTRY(a) CR (a, I2C_REQUEST, Link, I2C_REQUEST_SIGNATURE);
  109. //
  110. // I2C host context
  111. //
  112. typedef struct {
  113. //
  114. // Structure identification
  115. //
  116. UINTN Signature;
  117. //
  118. // Current I2C bus configuration
  119. //
  120. UINTN I2cBusConfiguration;
  121. //
  122. // I2C bus configuration management event
  123. //
  124. EFI_EVENT I2cBusConfigurationEvent;
  125. //
  126. // I2C operation completion event
  127. //
  128. EFI_EVENT I2cEvent;
  129. //
  130. // I2C operation and I2C bus configuration management status
  131. //
  132. EFI_STATUS Status;
  133. //
  134. // I2C bus configuration management operation pending
  135. //
  136. BOOLEAN I2cBusConfigurationManagementPending;
  137. //
  138. // I2C request list maintained by I2C Host
  139. //
  140. LIST_ENTRY RequestList;
  141. //
  142. // Upper level API
  143. //
  144. EFI_I2C_HOST_PROTOCOL I2cHost;
  145. //
  146. // I2C bus configuration management protocol
  147. //
  148. EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL *I2cBusConfigurationManagement;
  149. //
  150. // Lower level API for I2C master (controller)
  151. //
  152. EFI_I2C_MASTER_PROTOCOL *I2cMaster;
  153. } I2C_HOST_CONTEXT;
  154. #define I2C_HOST_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_HOST_CONTEXT, I2cHost, I2C_HOST_SIGNATURE)
  155. //
  156. // Global Variables
  157. //
  158. extern EFI_COMPONENT_NAME_PROTOCOL gI2cBusComponentName;
  159. extern EFI_COMPONENT_NAME2_PROTOCOL gI2cBusComponentName2;
  160. extern EFI_DRIVER_BINDING_PROTOCOL gI2cBusDriverBinding;
  161. extern EFI_COMPONENT_NAME_PROTOCOL gI2cHostComponentName;
  162. extern EFI_COMPONENT_NAME2_PROTOCOL gI2cHostComponentName2;
  163. extern EFI_DRIVER_BINDING_PROTOCOL gI2cHostDriverBinding;
  164. /**
  165. Start the I2C driver
  166. This routine allocates the necessary resources for the driver.
  167. This routine is called by I2cBusDriverStart to complete the driver
  168. initialization.
  169. @param[in] I2cBus Address of an I2C_BUS_CONTEXT structure
  170. @param[in] Controller Handle to the controller
  171. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path.
  172. @retval EFI_SUCCESS Driver API properly initialized
  173. **/
  174. EFI_STATUS
  175. RegisterI2cDevice (
  176. IN I2C_BUS_CONTEXT *I2cBus,
  177. IN EFI_HANDLE Controller,
  178. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
  179. );
  180. /**
  181. Unregister an I2C device.
  182. This function removes the protocols installed on the controller handle and
  183. frees the resources allocated for the I2C device.
  184. @param This The pointer to EFI_DRIVER_BINDING_PROTOCOL instance.
  185. @param Controller The controller handle of the I2C device.
  186. @param Handle The child handle.
  187. @retval EFI_SUCCESS The I2C device is successfully unregistered.
  188. @return Others Some error occurs when unregistering the I2C device.
  189. **/
  190. EFI_STATUS
  191. UnRegisterI2cDevice (
  192. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  193. IN EFI_HANDLE Controller,
  194. IN EFI_HANDLE Handle
  195. );
  196. /**
  197. Create a path for the I2C device
  198. Append the I2C slave path to the I2C master controller path.
  199. @param[in] I2cDeviceContext Address of an I2C_DEVICE_CONTEXT structure.
  200. @param[in] BuildControllerNode Flag to build controller node in device path.
  201. @retval EFI_SUCCESS The I2C device path is built successfully.
  202. @return Others It is failed to built device path.
  203. **/
  204. EFI_STATUS
  205. I2cBusDevicePathAppend (
  206. IN I2C_DEVICE_CONTEXT *I2cDeviceContext,
  207. IN BOOLEAN BuildControllerNode
  208. );
  209. /**
  210. Queue an I2C transaction for execution on the I2C device.
  211. This routine must be called at or below TPL_NOTIFY. For synchronous
  212. requests this routine must be called at or below TPL_CALLBACK.
  213. This routine queues an I2C transaction to the I2C controller for
  214. execution on the I2C bus.
  215. When Event is NULL, QueueRequest() operates synchronously and returns
  216. the I2C completion status as its return value.
  217. When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS
  218. indicating that the asynchronous I2C transaction was queued. The values
  219. above are returned in the buffer pointed to by I2cStatus upon the
  220. completion of the I2C transaction when I2cStatus is not NULL.
  221. The upper layer driver writer provides the following to the platform
  222. vendor:
  223. 1. Vendor specific GUID for the I2C part
  224. 2. Guidance on proper construction of the slave address array when the
  225. I2C device uses more than one slave address. The I2C bus protocol
  226. uses the SlaveAddressIndex to perform relative to physical address
  227. translation to access the blocks of hardware within the I2C device.
  228. @param[in] This Pointer to an EFI_I2C_IO_PROTOCOL structure.
  229. @param[in] SlaveAddressIndex Index value into an array of slave addresses
  230. for the I2C device. The values in the array
  231. are specified by the board designer, with the
  232. third party I2C device driver writer providing
  233. the slave address order.
  234. For devices that have a single slave address,
  235. this value must be zero. If the I2C device
  236. uses more than one slave address then the
  237. third party (upper level) I2C driver writer
  238. needs to specify the order of entries in the
  239. slave address array.
  240. \ref ThirdPartyI2cDrivers "Third Party I2C
  241. Drivers" section in I2cMaster.h.
  242. @param[in] Event Event to signal for asynchronous transactions,
  243. NULL for synchronous transactions
  244. @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure
  245. describing the I2C transaction
  246. @param[out] I2cStatus Optional buffer to receive the I2C transaction
  247. completion status
  248. @retval EFI_SUCCESS The asynchronous transaction was successfully
  249. queued when Event is not NULL.
  250. @retval EFI_SUCCESS The transaction completed successfully when
  251. Event is NULL.
  252. @retval EFI_ABORTED The request did not complete because the driver
  253. binding Stop() routine was called.
  254. @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too
  255. large.
  256. @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the
  257. transaction.
  258. @retval EFI_INVALID_PARAMETER RequestPacket is NULL
  259. @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter
  260. @retval EFI_NO_MAPPING The EFI_I2C_HOST_PROTOCOL could not set the
  261. bus configuration required to access this I2C
  262. device.
  263. @retval EFI_NO_RESPONSE The I2C device is not responding to the slave
  264. address selected by SlaveAddressIndex.
  265. EFI_DEVICE_ERROR will be returned if the
  266. controller cannot distinguish when the NACK
  267. occurred.
  268. @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
  269. @retval EFI_UNSUPPORTED The controller does not support the requested
  270. transaction.
  271. **/
  272. EFI_STATUS
  273. EFIAPI
  274. I2cBusQueueRequest (
  275. IN CONST EFI_I2C_IO_PROTOCOL *This,
  276. IN UINTN SlaveAddressIndex,
  277. IN EFI_EVENT Event OPTIONAL,
  278. IN EFI_I2C_REQUEST_PACKET *RequestPacket,
  279. OUT EFI_STATUS *I2cStatus OPTIONAL
  280. );
  281. /**
  282. Tests to see if this driver supports a given controller. If a child device is provided,
  283. it further tests to see if this driver supports creating a handle for the specified child device.
  284. This function checks to see if the driver specified by This supports the device specified by
  285. ControllerHandle. Drivers will typically use the device path attached to
  286. ControllerHandle and/or the services from the bus I/O abstraction attached to
  287. ControllerHandle to determine if the driver supports ControllerHandle. This function
  288. may be called many times during platform initialization. In order to reduce boot times, the tests
  289. performed by this function must be very small, and take as little time as possible to execute. This
  290. function must not change the state of any hardware devices, and this function must be aware that the
  291. device specified by ControllerHandle may already be managed by the same driver or a
  292. different driver. This function must match its calls to AllocatePages() with FreePages(),
  293. AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
  294. Since ControllerHandle may have been previously started by the same driver, if a protocol is
  295. already in the opened state, then it must not be closed with CloseProtocol(). This is required
  296. to guarantee the state of ControllerHandle is not modified by this function.
  297. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  298. @param[in] ControllerHandle The handle of the controller to test. This handle
  299. must support a protocol interface that supplies
  300. an I/O abstraction to the driver.
  301. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
  302. parameter is ignored by device drivers, and is optional for bus
  303. drivers. For bus drivers, if this parameter is not NULL, then
  304. the bus driver must determine if the bus controller specified
  305. by ControllerHandle and the child controller specified
  306. by RemainingDevicePath are both supported by this
  307. bus driver.
  308. @retval EFI_SUCCESS The device specified by ControllerHandle and
  309. RemainingDevicePath is supported by the driver specified by This.
  310. @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
  311. RemainingDevicePath is already being managed by the driver
  312. specified by This.
  313. @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
  314. RemainingDevicePath is already being managed by a different
  315. driver or an application that requires exclusive access.
  316. Currently not implemented.
  317. @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
  318. RemainingDevicePath is not supported by the driver specified by This.
  319. **/
  320. EFI_STATUS
  321. EFIAPI
  322. I2cBusDriverSupported (
  323. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  324. IN EFI_HANDLE Controller,
  325. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
  326. );
  327. /**
  328. Starts a device controller or a bus controller.
  329. The Start() function is designed to be invoked from the EFI boot service ConnectController().
  330. As a result, much of the error checking on the parameters to Start() has been moved into this
  331. common boot service. It is legal to call Start() from other locations,
  332. but the following calling restrictions must be followed or the system behavior will not be deterministic.
  333. 1. ControllerHandle must be a valid EFI_HANDLE.
  334. 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
  335. EFI_DEVICE_PATH_PROTOCOL.
  336. 3. Prior to calling Start(), the Supported() function for the driver specified by This must
  337. have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
  338. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  339. @param[in] ControllerHandle The handle of the controller to start. This handle
  340. must support a protocol interface that supplies
  341. an I/O abstraction to the driver.
  342. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
  343. parameter is ignored by device drivers, and is optional for bus
  344. drivers. For a bus driver, if this parameter is NULL, then handles
  345. for all the children of Controller are created by this driver.
  346. If this parameter is not NULL and the first Device Path Node is
  347. not the End of Device Path Node, then only the handle for the
  348. child device specified by the first Device Path Node of
  349. RemainingDevicePath is created by this driver.
  350. If the first Device Path Node of RemainingDevicePath is
  351. the End of Device Path Node, no child handle is created by this
  352. driver.
  353. @retval EFI_SUCCESS The device was started.
  354. @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
  355. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
  356. @retval Others The driver failded to start the device.
  357. **/
  358. EFI_STATUS
  359. EFIAPI
  360. I2cBusDriverStart (
  361. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  362. IN EFI_HANDLE Controller,
  363. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
  364. );
  365. /**
  366. Stops a device controller or a bus controller.
  367. The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
  368. As a result, much of the error checking on the parameters to Stop() has been moved
  369. into this common boot service. It is legal to call Stop() from other locations,
  370. but the following calling restrictions must be followed or the system behavior will not be deterministic.
  371. 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
  372. same driver's Start() function.
  373. 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
  374. EFI_HANDLE. In addition, all of these handles must have been created in this driver's
  375. Start() function, and the Start() function must have called OpenProtocol() on
  376. ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
  377. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  378. @param[in] ControllerHandle A handle to the device being stopped. The handle must
  379. support a bus specific I/O protocol for the driver
  380. to use to stop the device.
  381. @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
  382. @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
  383. if NumberOfChildren is 0.
  384. @retval EFI_SUCCESS The device was stopped.
  385. @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
  386. **/
  387. EFI_STATUS
  388. EFIAPI
  389. I2cBusDriverStop (
  390. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  391. IN EFI_HANDLE Controller,
  392. IN UINTN NumberOfChildren,
  393. IN EFI_HANDLE *ChildHandleBuffer
  394. );
  395. /**
  396. Retrieves a Unicode string that is the user readable name of the driver.
  397. This function retrieves the user readable name of a driver in the form of a
  398. Unicode string. If the driver specified by This has a user readable name in
  399. the language specified by Language, then a pointer to the driver name is
  400. returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
  401. by This does not support the language specified by Language,
  402. then EFI_UNSUPPORTED is returned.
  403. @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
  404. EFI_COMPONENT_NAME_PROTOCOL instance.
  405. @param Language[in] A pointer to a Null-terminated ASCII string
  406. array indicating the language. This is the
  407. language of the driver name that the caller is
  408. requesting, and it must match one of the
  409. languages specified in SupportedLanguages. The
  410. number of languages supported by a driver is up
  411. to the driver writer. Language is specified
  412. in RFC 4646 or ISO 639-2 language code format.
  413. @param DriverName[out] A pointer to the Unicode string to return.
  414. This Unicode string is the name of the
  415. driver specified by This in the language
  416. specified by Language.
  417. @retval EFI_SUCCESS The Unicode string for the Driver specified by
  418. This and the language specified by Language was
  419. returned in DriverName.
  420. @retval EFI_INVALID_PARAMETER Language is NULL.
  421. @retval EFI_INVALID_PARAMETER DriverName is NULL.
  422. @retval EFI_UNSUPPORTED The driver specified by This does not support
  423. the language specified by Language.
  424. **/
  425. EFI_STATUS
  426. EFIAPI
  427. I2cBusComponentNameGetDriverName (
  428. IN EFI_COMPONENT_NAME2_PROTOCOL *This,
  429. IN CHAR8 *Language,
  430. OUT CHAR16 **DriverName
  431. );
  432. /**
  433. Retrieves a Unicode string that is the user readable name of the controller
  434. that is being managed by a driver.
  435. This function retrieves the user readable name of the controller specified by
  436. ControllerHandle and ChildHandle in the form of a Unicode string. If the
  437. driver specified by This has a user readable name in the language specified by
  438. Language, then a pointer to the controller name is returned in ControllerName,
  439. and EFI_SUCCESS is returned. If the driver specified by This is not currently
  440. managing the controller specified by ControllerHandle and ChildHandle,
  441. then EFI_UNSUPPORTED is returned. If the driver specified by This does not
  442. support the language specified by Language, then EFI_UNSUPPORTED is returned.
  443. @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
  444. EFI_COMPONENT_NAME_PROTOCOL instance.
  445. @param ControllerHandle[in] The handle of a controller that the driver
  446. specified by This is managing. This handle
  447. specifies the controller whose name is to be
  448. returned.
  449. @param ChildHandle[in] The handle of the child controller to retrieve
  450. the name of. This is an optional parameter that
  451. may be NULL. It will be NULL for device
  452. drivers. It will also be NULL for a bus drivers
  453. that wish to retrieve the name of the bus
  454. controller. It will not be NULL for a bus
  455. driver that wishes to retrieve the name of a
  456. child controller.
  457. @param Language[in] A pointer to a Null-terminated ASCII string
  458. array indicating the language. This is the
  459. language of the driver name that the caller is
  460. requesting, and it must match one of the
  461. languages specified in SupportedLanguages. The
  462. number of languages supported by a driver is up
  463. to the driver writer. Language is specified in
  464. RFC 4646 or ISO 639-2 language code format.
  465. @param ControllerName[out] A pointer to the Unicode string to return.
  466. This Unicode string is the name of the
  467. controller specified by ControllerHandle and
  468. ChildHandle in the language specified by
  469. Language from the point of view of the driver
  470. specified by This.
  471. @retval EFI_SUCCESS The Unicode string for the user readable name in
  472. the language specified by Language for the
  473. driver specified by This was returned in
  474. DriverName.
  475. @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
  476. @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
  477. EFI_HANDLE.
  478. @retval EFI_INVALID_PARAMETER Language is NULL.
  479. @retval EFI_INVALID_PARAMETER ControllerName is NULL.
  480. @retval EFI_UNSUPPORTED The driver specified by This is not currently
  481. managing the controller specified by
  482. ControllerHandle and ChildHandle.
  483. @retval EFI_UNSUPPORTED The driver specified by This does not support
  484. the language specified by Language.
  485. **/
  486. EFI_STATUS
  487. EFIAPI
  488. I2cBusComponentNameGetControllerName (
  489. IN EFI_COMPONENT_NAME2_PROTOCOL *This,
  490. IN EFI_HANDLE ControllerHandle,
  491. IN EFI_HANDLE ChildHandle OPTIONAL,
  492. IN CHAR8 *Language,
  493. OUT CHAR16 **ControllerName
  494. );
  495. /**
  496. The user entry point for the I2C bus module. The user code starts with
  497. this function.
  498. @param[in] ImageHandle The firmware allocated handle for the EFI image.
  499. @param[in] SystemTable A pointer to the EFI System Table.
  500. @retval EFI_SUCCESS The entry point is executed successfully.
  501. @retval other Some error occurs when executing this entry point.
  502. **/
  503. EFI_STATUS
  504. EFIAPI
  505. InitializeI2cBus(
  506. IN EFI_HANDLE ImageHandle,
  507. IN EFI_SYSTEM_TABLE *SystemTable
  508. );
  509. /**
  510. This is the unload handle for I2C bus module.
  511. Disconnect the driver specified by ImageHandle from all the devices in the handle database.
  512. Uninstall all the protocols installed in the driver entry point.
  513. @param[in] ImageHandle The drivers' driver image.
  514. @retval EFI_SUCCESS The image is unloaded.
  515. @retval Others Failed to unload the image.
  516. **/
  517. EFI_STATUS
  518. EFIAPI
  519. I2cBusUnload (
  520. IN EFI_HANDLE ImageHandle
  521. );
  522. /**
  523. Release all the resources allocated for the I2C device.
  524. This function releases all the resources allocated for the I2C device.
  525. @param I2cDeviceContext The I2C child device involved for the operation.
  526. **/
  527. VOID
  528. ReleaseI2cDeviceContext (
  529. IN I2C_DEVICE_CONTEXT *I2cDeviceContext
  530. );
  531. /**
  532. Complete the current request
  533. @param[in] I2cHost Address of an I2C_HOST_CONTEXT structure.
  534. @param[in] Status Status of the I<sub>2</sub>C operation.
  535. @return This routine returns the input status value.
  536. **/
  537. EFI_STATUS
  538. I2cHostRequestComplete (
  539. I2C_HOST_CONTEXT *I2cHost,
  540. EFI_STATUS Status
  541. );
  542. /**
  543. Enable access to the I2C bus configuration
  544. @param[in] I2cHostContext Address of an I2C_HOST_CONTEXT structure
  545. @retval EFI_SUCCESS The operation completed successfully.
  546. @retval EFI_ABORTED The request did not complete because the driver
  547. was shutdown.
  548. @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.
  549. @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.
  550. This could indicate the slave device is not present.
  551. @retval EFI_INVALID_PARAMETER RequestPacket is NULL
  552. @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value
  553. @retval EFI_NO_RESPONSE The I2C device is not responding to the
  554. slave address. EFI_DEVICE_ERROR may also be
  555. returned if the controller can not distinguish
  556. when the NACK occurred.
  557. @retval EFI_NOT_FOUND I2C slave address exceeds maximum address
  558. @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for
  559. the event and then read status.
  560. @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation
  561. @retval EFI_TIMEOUT The transaction did not complete within an internally
  562. specified timeout period.
  563. **/
  564. EFI_STATUS
  565. I2cHostRequestEnable (
  566. I2C_HOST_CONTEXT *I2cHost
  567. );
  568. /**
  569. Tests to see if this driver supports a given controller. If a child device is provided,
  570. it further tests to see if this driver supports creating a handle for the specified child device.
  571. This function checks to see if the driver specified by This supports the device specified by
  572. ControllerHandle. Drivers will typically use the device path attached to
  573. ControllerHandle and/or the services from the bus I/O abstraction attached to
  574. ControllerHandle to determine if the driver supports ControllerHandle. This function
  575. may be called many times during platform initialization. In order to reduce boot times, the tests
  576. performed by this function must be very small, and take as little time as possible to execute. This
  577. function must not change the state of any hardware devices, and this function must be aware that the
  578. device specified by ControllerHandle may already be managed by the same driver or a
  579. different driver. This function must match its calls to AllocatePages() with FreePages(),
  580. AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
  581. Since ControllerHandle may have been previously started by the same driver, if a protocol is
  582. already in the opened state, then it must not be closed with CloseProtocol(). This is required
  583. to guarantee the state of ControllerHandle is not modified by this function.
  584. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  585. @param[in] ControllerHandle The handle of the controller to test. This handle
  586. must support a protocol interface that supplies
  587. an I/O abstraction to the driver.
  588. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
  589. parameter is ignored by device drivers, and is optional for bus
  590. drivers. For bus drivers, if this parameter is not NULL, then
  591. the bus driver must determine if the bus controller specified
  592. by ControllerHandle and the child controller specified
  593. by RemainingDevicePath are both supported by this
  594. bus driver.
  595. @retval EFI_SUCCESS The device specified by ControllerHandle and
  596. RemainingDevicePath is supported by the driver specified by This.
  597. @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
  598. RemainingDevicePath is already being managed by the driver
  599. specified by This.
  600. @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
  601. RemainingDevicePath is already being managed by a different
  602. driver or an application that requires exclusive access.
  603. Currently not implemented.
  604. @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
  605. RemainingDevicePath is not supported by the driver specified by This.
  606. **/
  607. EFI_STATUS
  608. EFIAPI
  609. I2cHostDriverSupported (
  610. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  611. IN EFI_HANDLE Controller,
  612. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
  613. );
  614. /**
  615. Starts a device controller or a bus controller.
  616. The Start() function is designed to be invoked from the EFI boot service ConnectController().
  617. As a result, much of the error checking on the parameters to Start() has been moved into this
  618. common boot service. It is legal to call Start() from other locations,
  619. but the following calling restrictions must be followed, or the system behavior will not be deterministic.
  620. 1. ControllerHandle must be a valid EFI_HANDLE.
  621. 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
  622. EFI_DEVICE_PATH_PROTOCOL.
  623. 3. Prior to calling Start(), the Supported() function for the driver specified by This must
  624. have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
  625. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  626. @param[in] ControllerHandle The handle of the controller to start. This handle
  627. must support a protocol interface that supplies
  628. an I/O abstraction to the driver.
  629. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
  630. parameter is ignored by device drivers, and is optional for bus
  631. drivers. For a bus driver, if this parameter is NULL, then handles
  632. for all the children of Controller are created by this driver.
  633. If this parameter is not NULL and the first Device Path Node is
  634. not the End of Device Path Node, then only the handle for the
  635. child device specified by the first Device Path Node of
  636. RemainingDevicePath is created by this driver.
  637. If the first Device Path Node of RemainingDevicePath is
  638. the End of Device Path Node, no child handle is created by this
  639. driver.
  640. @retval EFI_SUCCESS The device was started.
  641. @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
  642. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
  643. @retval Others The driver failded to start the device.
  644. **/
  645. EFI_STATUS
  646. EFIAPI
  647. I2cHostDriverStart (
  648. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  649. IN EFI_HANDLE Controller,
  650. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
  651. );
  652. /**
  653. Stops a device controller or a bus controller.
  654. The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
  655. As a result, much of the error checking on the parameters to Stop() has been moved
  656. into this common boot service. It is legal to call Stop() from other locations,
  657. but the following calling restrictions must be followed, or the system behavior will not be deterministic.
  658. 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
  659. same driver's Start() function.
  660. 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
  661. EFI_HANDLE. In addition, all of these handles must have been created in this driver's
  662. Start() function, and the Start() function must have called OpenProtocol() on
  663. ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
  664. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  665. @param[in] ControllerHandle A handle to the device being stopped. The handle must
  666. support a bus specific I/O protocol for the driver
  667. to use to stop the device.
  668. @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
  669. @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
  670. if NumberOfChildren is 0.
  671. @retval EFI_SUCCESS The device was stopped.
  672. @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
  673. **/
  674. EFI_STATUS
  675. EFIAPI
  676. I2cHostDriverStop (
  677. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  678. IN EFI_HANDLE Controller,
  679. IN UINTN NumberOfChildren,
  680. IN EFI_HANDLE *ChildHandleBuffer
  681. );
  682. /**
  683. Retrieves a Unicode string that is the user readable name of the driver.
  684. This function retrieves the user readable name of a driver in the form of a
  685. Unicode string. If the driver specified by This has a user readable name in
  686. the language specified by Language, then a pointer to the driver name is
  687. returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
  688. by This does not support the language specified by Language,
  689. then EFI_UNSUPPORTED is returned.
  690. @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
  691. EFI_COMPONENT_NAME_PROTOCOL instance.
  692. @param Language[in] A pointer to a Null-terminated ASCII string
  693. array indicating the language. This is the
  694. language of the driver name that the caller is
  695. requesting, and it must match one of the
  696. languages specified in SupportedLanguages. The
  697. number of languages supported by a driver is up
  698. to the driver writer. Language is specified
  699. in RFC 4646 or ISO 639-2 language code format.
  700. @param DriverName[out] A pointer to the Unicode string to return.
  701. This Unicode string is the name of the
  702. driver specified by This in the language
  703. specified by Language.
  704. @retval EFI_SUCCESS The Unicode string for the Driver specified by
  705. This and the language specified by Language was
  706. returned in DriverName.
  707. @retval EFI_INVALID_PARAMETER Language is NULL.
  708. @retval EFI_INVALID_PARAMETER DriverName is NULL.
  709. @retval EFI_UNSUPPORTED The driver specified by This does not support
  710. the language specified by Language.
  711. **/
  712. EFI_STATUS
  713. EFIAPI
  714. I2cHostComponentNameGetDriverName (
  715. IN EFI_COMPONENT_NAME2_PROTOCOL *This,
  716. IN CHAR8 *Language,
  717. OUT CHAR16 **DriverName
  718. );
  719. /**
  720. Retrieves a Unicode string that is the user readable name of the controller
  721. that is being managed by a driver.
  722. This function retrieves the user readable name of the controller specified by
  723. ControllerHandle and ChildHandle in the form of a Unicode string. If the
  724. driver specified by This has a user readable name in the language specified by
  725. Language, then a pointer to the controller name is returned in ControllerName,
  726. and EFI_SUCCESS is returned. If the driver specified by This is not currently
  727. managing the controller specified by ControllerHandle and ChildHandle,
  728. then EFI_UNSUPPORTED is returned. If the driver specified by This does not
  729. support the language specified by Language, then EFI_UNSUPPORTED is returned.
  730. @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
  731. EFI_COMPONENT_NAME_PROTOCOL instance.
  732. @param ControllerHandle[in] The handle of a controller that the driver
  733. specified by This is managing. This handle
  734. specifies the controller whose name is to be
  735. returned.
  736. @param ChildHandle[in] The handle of the child controller to retrieve
  737. the name of. This is an optional parameter that
  738. may be NULL. It will be NULL for device
  739. drivers. It will also be NULL for a bus drivers
  740. that wish to retrieve the name of the bus
  741. controller. It will not be NULL for a bus
  742. driver that wishes to retrieve the name of a
  743. child controller.
  744. @param Language[in] A pointer to a Null-terminated ASCII string
  745. array indicating the language. This is the
  746. language of the driver name that the caller is
  747. requesting, and it must match one of the
  748. languages specified in SupportedLanguages. The
  749. number of languages supported by a driver is up
  750. to the driver writer. Language is specified in
  751. RFC 4646 or ISO 639-2 language code format.
  752. @param ControllerName[out] A pointer to the Unicode string to return.
  753. This Unicode string is the name of the
  754. controller specified by ControllerHandle and
  755. ChildHandle in the language specified by
  756. Language from the point of view of the driver
  757. specified by This.
  758. @retval EFI_SUCCESS The Unicode string for the user readable name in
  759. the language specified by Language for the
  760. driver specified by This was returned in
  761. DriverName.
  762. @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
  763. @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
  764. EFI_HANDLE.
  765. @retval EFI_INVALID_PARAMETER Language is NULL.
  766. @retval EFI_INVALID_PARAMETER ControllerName is NULL.
  767. @retval EFI_UNSUPPORTED The driver specified by This is not currently
  768. managing the controller specified by
  769. ControllerHandle and ChildHandle.
  770. @retval EFI_UNSUPPORTED The driver specified by This does not support
  771. the language specified by Language.
  772. **/
  773. EFI_STATUS
  774. EFIAPI
  775. I2cHostComponentNameGetControllerName (
  776. IN EFI_COMPONENT_NAME2_PROTOCOL *This,
  777. IN EFI_HANDLE ControllerHandle,
  778. IN EFI_HANDLE ChildHandle OPTIONAL,
  779. IN CHAR8 *Language,
  780. OUT CHAR16 **ControllerName
  781. );
  782. /**
  783. Handle the bus available event
  784. This routine is called at TPL_I2C_SYNC.
  785. @param[in] Event Address of an EFI_EVENT handle
  786. @param[in] Context Address of an I2C_HOST_CONTEXT structure
  787. **/
  788. VOID
  789. EFIAPI
  790. I2cHostRequestCompleteEvent (
  791. IN EFI_EVENT Event,
  792. IN VOID *Context
  793. );
  794. /**
  795. Handle the I2C bus configuration available event
  796. This routine is called at TPL_I2C_SYNC.
  797. @param[in] Event Address of an EFI_EVENT handle
  798. @param[in] Context Address of an I2C_HOST_CONTEXT structure
  799. **/
  800. VOID
  801. EFIAPI
  802. I2cHostI2cBusConfigurationAvailable (
  803. IN EFI_EVENT Event,
  804. IN VOID *Context
  805. );
  806. /**
  807. Queue an I2C operation for execution on the I2C controller.
  808. This routine must be called at or below TPL_NOTIFY. For synchronous
  809. requests this routine must be called at or below TPL_CALLBACK.
  810. N.B. The typical consumers of this API are the I2C bus driver and
  811. on rare occasions the I2C test application. Extreme care must be
  812. taken by other consumers of this API to prevent confusing the
  813. third party I2C drivers due to a state change at the I2C device
  814. which the third party I2C drivers did not initiate. I2C platform
  815. drivers may use this API within these guidelines.
  816. This layer uses the concept of I2C bus configurations to describe
  817. the I2C bus. An I2C bus configuration is defined as a unique
  818. setting of the multiplexers and switches in the I2C bus which
  819. enable access to one or more I2C devices. When using a switch
  820. to divide a bus, due to speed differences, the I2C platform layer
  821. would define an I2C bus configuration for the I2C devices on each
  822. side of the switch. When using a multiplexer, the I2C platform
  823. layer defines an I2C bus configuration for each of the selector
  824. values required to control the multiplexer. See Figure 1 in the
  825. <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C
  826. Specification</a> for a complex I2C bus configuration.
  827. The I2C host driver processes all operations in FIFO order. Prior to
  828. performing the operation, the I2C host driver calls the I2C platform
  829. driver to reconfigure the switches and multiplexers in the I2C bus
  830. enabling access to the specified I2C device. The I2C platform driver
  831. also selects the maximum bus speed for the device. After the I2C bus
  832. is configured, the I2C host driver calls the I2C port driver to
  833. initialize the I2C controller and start the I2C operation.
  834. @param[in] This Address of an EFI_I2C_HOST_PROTOCOL instance.
  835. @param[in] I2cBusConfiguration I2C bus configuration to access the I2C
  836. device.
  837. @param[in] SlaveAddress Address of the device on the I2C bus.
  838. @param[in] Event Event to set for asynchronous operations,
  839. NULL for synchronous operations
  840. @param[in] RequestPacket Address of an EFI_I2C_REQUEST_PACKET
  841. structure describing the I2C operation
  842. @param[out] I2cStatus Optional buffer to receive the I2C operation
  843. completion status
  844. @retval EFI_SUCCESS The operation completed successfully.
  845. @retval EFI_ABORTED The request did not complete because the driver
  846. was shutdown.
  847. @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.
  848. @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.
  849. This could indicate the slave device is not present.
  850. @retval EFI_INVALID_PARAMETER RequestPacket is NULL
  851. @retval EFI_INVALID_PARAMETER TPL is too high
  852. @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value
  853. @retval EFI_NO_RESPONSE The I2C device is not responding to the
  854. slave address. EFI_DEVICE_ERROR may also be
  855. returned if the controller can not distinguish
  856. when the NACK occurred.
  857. @retval EFI_NOT_FOUND I2C slave address exceeds maximum address
  858. @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for
  859. the event and then read status pointed to by
  860. the request packet.
  861. @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation
  862. @retval EFI_TIMEOUT The transaction did not complete within an internally
  863. specified timeout period.
  864. **/
  865. EFI_STATUS
  866. EFIAPI
  867. I2cHostQueueRequest (
  868. IN CONST EFI_I2C_HOST_PROTOCOL *This,
  869. IN UINTN I2cBusConfiguration,
  870. IN UINTN SlaveAddress,
  871. IN EFI_EVENT Event OPTIONAL,
  872. IN EFI_I2C_REQUEST_PACKET *RequestPacket,
  873. OUT EFI_STATUS *I2cStatus OPTIONAL
  874. );
  875. /**
  876. The user Entry Point for I2C host module. The user code starts with this function.
  877. @param[in] ImageHandle The firmware allocated handle for the EFI image.
  878. @param[in] SystemTable A pointer to the EFI System Table.
  879. @retval EFI_SUCCESS The entry point is executed successfully.
  880. @retval other Some error occurs when executing this entry point.
  881. **/
  882. EFI_STATUS
  883. EFIAPI
  884. InitializeI2cHost(
  885. IN EFI_HANDLE ImageHandle,
  886. IN EFI_SYSTEM_TABLE *SystemTable
  887. );
  888. /**
  889. This is the unload handle for I2C host module.
  890. Disconnect the driver specified by ImageHandle from all the devices in the handle database.
  891. Uninstall all the protocols installed in the driver entry point.
  892. @param[in] ImageHandle The drivers' driver image.
  893. @retval EFI_SUCCESS The image is unloaded.
  894. @retval Others Failed to unload the image.
  895. **/
  896. EFI_STATUS
  897. EFIAPI
  898. I2cHostUnload (
  899. IN EFI_HANDLE ImageHandle
  900. );
  901. #endif // __I2C_DXE_H__