12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091 |
- /** @file
- Private data structures for the I2C DXE driver.
- This file defines common data structures, macro definitions and some module
- internal function header files.
- Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
- SPDX-License-Identifier: BSD-2-Clause-Patent
- **/
- #ifndef __I2C_DXE_H__
- #define __I2C_DXE_H__
- #include <Uefi.h>
- #include <Library/BaseMemoryLib.h>
- #include <Library/DebugLib.h>
- #include <Library/DevicePathLib.h>
- #include <Library/MemoryAllocationLib.h>
- #include <Library/TimerLib.h>
- #include <Library/UefiBootServicesTableLib.h>
- #include <Library/UefiDriverEntryPoint.h>
- #include <Library/UefiLib.h>
- #include <Protocol/DriverBinding.h>
- #include <Protocol/I2cEnumerate.h>
- #include <Protocol/I2cHost.h>
- #include <Protocol/I2cIo.h>
- #include <Protocol/I2cMaster.h>
- #include <Protocol/I2cBusConfigurationManagement.h>
- #include <Protocol/LoadedImage.h>
- #define I2C_DEVICE_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'D')
- #define I2C_HOST_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'H')
- #define I2C_REQUEST_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'R')
- //
- // Synchronize access to the list of requests
- //
- #define TPL_I2C_SYNC TPL_NOTIFY
- //
- // I2C bus context
- //
- typedef struct {
- EFI_I2C_ENUMERATE_PROTOCOL *I2cEnumerate;
- EFI_I2C_HOST_PROTOCOL *I2cHost;
- EFI_HANDLE Controller;
- EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath;
- EFI_HANDLE DriverBindingHandle;
- } I2C_BUS_CONTEXT;
- //
- // I2C device context
- //
- typedef struct {
- //
- // Structure identification
- //
- UINT32 Signature;
- //
- // I2c device handle
- //
- EFI_HANDLE Handle;
- //
- // Upper level API to support the I2C device I/O
- //
- EFI_I2C_IO_PROTOCOL I2cIo;
- //
- // Device path for this device
- //
- EFI_DEVICE_PATH_PROTOCOL *DevicePath;
- //
- // Platform specific data for this device
- //
- CONST EFI_I2C_DEVICE *I2cDevice;
- //
- // Context for the common I/O support including the
- // lower level API to the host controller.
- //
- I2C_BUS_CONTEXT *I2cBusContext;
- } I2C_DEVICE_CONTEXT;
- #define I2C_DEVICE_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_DEVICE_CONTEXT, I2cIo, I2C_DEVICE_SIGNATURE)
- //
- // I2C Request
- //
- typedef struct {
- //
- // Signature
- //
- UINT32 Signature;
- //
- // Next request in the pending request list
- //
- LIST_ENTRY Link;
- //
- // I2C bus configuration for the operation
- //
- UINTN I2cBusConfiguration;
- //
- // I2C slave address for the operation
- //
- UINTN SlaveAddress;
- //
- // Event to set for asynchronous operations, NULL for
- // synchronous operations
- //
- EFI_EVENT Event;
- //
- // I2C operation description
- //
- EFI_I2C_REQUEST_PACKET *RequestPacket;
- //
- // Optional buffer to receive the I2C operation completion status
- //
- EFI_STATUS *Status;
- } I2C_REQUEST;
- #define I2C_REQUEST_FROM_ENTRY(a) CR (a, I2C_REQUEST, Link, I2C_REQUEST_SIGNATURE);
- //
- // I2C host context
- //
- typedef struct {
- //
- // Structure identification
- //
- UINTN Signature;
- //
- // Current I2C bus configuration
- //
- UINTN I2cBusConfiguration;
- //
- // I2C bus configuration management event
- //
- EFI_EVENT I2cBusConfigurationEvent;
- //
- // I2C operation completion event
- //
- EFI_EVENT I2cEvent;
- //
- // I2C operation and I2C bus configuration management status
- //
- EFI_STATUS Status;
- //
- // I2C bus configuration management operation pending
- //
- BOOLEAN I2cBusConfigurationManagementPending;
- //
- // I2C request list maintained by I2C Host
- //
- LIST_ENTRY RequestList;
- //
- // Upper level API
- //
- EFI_I2C_HOST_PROTOCOL I2cHost;
- //
- // I2C bus configuration management protocol
- //
- EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL *I2cBusConfigurationManagement;
- //
- // Lower level API for I2C master (controller)
- //
- EFI_I2C_MASTER_PROTOCOL *I2cMaster;
- } I2C_HOST_CONTEXT;
- #define I2C_HOST_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_HOST_CONTEXT, I2cHost, I2C_HOST_SIGNATURE)
- //
- // Global Variables
- //
- extern EFI_COMPONENT_NAME_PROTOCOL gI2cBusComponentName;
- extern EFI_COMPONENT_NAME2_PROTOCOL gI2cBusComponentName2;
- extern EFI_DRIVER_BINDING_PROTOCOL gI2cBusDriverBinding;
- extern EFI_COMPONENT_NAME_PROTOCOL gI2cHostComponentName;
- extern EFI_COMPONENT_NAME2_PROTOCOL gI2cHostComponentName2;
- extern EFI_DRIVER_BINDING_PROTOCOL gI2cHostDriverBinding;
- /**
- Start the I2C driver
- This routine allocates the necessary resources for the driver.
- This routine is called by I2cBusDriverStart to complete the driver
- initialization.
- @param[in] I2cBus Address of an I2C_BUS_CONTEXT structure
- @param[in] Controller Handle to the controller
- @param[in] RemainingDevicePath A pointer to the remaining portion of a device path.
- @retval EFI_SUCCESS Driver API properly initialized
- **/
- EFI_STATUS
- RegisterI2cDevice (
- IN I2C_BUS_CONTEXT *I2cBus,
- IN EFI_HANDLE Controller,
- IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
- );
- /**
- Unregister an I2C device.
- This function removes the protocols installed on the controller handle and
- frees the resources allocated for the I2C device.
- @param This The pointer to EFI_DRIVER_BINDING_PROTOCOL instance.
- @param Controller The controller handle of the I2C device.
- @param Handle The child handle.
- @retval EFI_SUCCESS The I2C device is successfully unregistered.
- @return Others Some error occurs when unregistering the I2C device.
- **/
- EFI_STATUS
- UnRegisterI2cDevice (
- IN EFI_DRIVER_BINDING_PROTOCOL *This,
- IN EFI_HANDLE Controller,
- IN EFI_HANDLE Handle
- );
- /**
- Create a path for the I2C device
- Append the I2C slave path to the I2C master controller path.
- @param[in] I2cDeviceContext Address of an I2C_DEVICE_CONTEXT structure.
- @param[in] BuildControllerNode Flag to build controller node in device path.
- @retval EFI_SUCCESS The I2C device path is built successfully.
- @return Others It is failed to built device path.
- **/
- EFI_STATUS
- I2cBusDevicePathAppend (
- IN I2C_DEVICE_CONTEXT *I2cDeviceContext,
- IN BOOLEAN BuildControllerNode
- );
- /**
- Queue an I2C transaction for execution on the I2C device.
- This routine must be called at or below TPL_NOTIFY. For synchronous
- requests this routine must be called at or below TPL_CALLBACK.
- This routine queues an I2C transaction to the I2C controller for
- execution on the I2C bus.
- When Event is NULL, QueueRequest() operates synchronously and returns
- the I2C completion status as its return value.
- When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS
- indicating that the asynchronous I2C transaction was queued. The values
- above are returned in the buffer pointed to by I2cStatus upon the
- completion of the I2C transaction when I2cStatus is not NULL.
- The upper layer driver writer provides the following to the platform
- vendor:
- 1. Vendor specific GUID for the I2C part
- 2. Guidance on proper construction of the slave address array when the
- I2C device uses more than one slave address. The I2C bus protocol
- uses the SlaveAddressIndex to perform relative to physical address
- translation to access the blocks of hardware within the I2C device.
- @param[in] This Pointer to an EFI_I2C_IO_PROTOCOL structure.
- @param[in] SlaveAddressIndex Index value into an array of slave addresses
- for the I2C device. The values in the array
- are specified by the board designer, with the
- third party I2C device driver writer providing
- the slave address order.
- For devices that have a single slave address,
- this value must be zero. If the I2C device
- uses more than one slave address then the
- third party (upper level) I2C driver writer
- needs to specify the order of entries in the
- slave address array.
- \ref ThirdPartyI2cDrivers "Third Party I2C
- Drivers" section in I2cMaster.h.
- @param[in] Event Event to signal for asynchronous transactions,
- NULL for synchronous transactions
- @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure
- describing the I2C transaction
- @param[out] I2cStatus Optional buffer to receive the I2C transaction
- completion status
- @retval EFI_SUCCESS The asynchronous transaction was successfully
- queued when Event is not NULL.
- @retval EFI_SUCCESS The transaction completed successfully when
- Event is NULL.
- @retval EFI_ABORTED The request did not complete because the driver
- binding Stop() routine was called.
- @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too
- large.
- @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the
- transaction.
- @retval EFI_INVALID_PARAMETER RequestPacket is NULL
- @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter
- @retval EFI_NO_MAPPING The EFI_I2C_HOST_PROTOCOL could not set the
- bus configuration required to access this I2C
- device.
- @retval EFI_NO_RESPONSE The I2C device is not responding to the slave
- address selected by SlaveAddressIndex.
- EFI_DEVICE_ERROR will be returned if the
- controller cannot distinguish when the NACK
- occurred.
- @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
- @retval EFI_UNSUPPORTED The controller does not support the requested
- transaction.
- **/
- EFI_STATUS
- EFIAPI
- I2cBusQueueRequest (
- IN CONST EFI_I2C_IO_PROTOCOL *This,
- IN UINTN SlaveAddressIndex,
- IN EFI_EVENT Event OPTIONAL,
- IN EFI_I2C_REQUEST_PACKET *RequestPacket,
- OUT EFI_STATUS *I2cStatus OPTIONAL
- );
- /**
- Tests to see if this driver supports a given controller. If a child device is provided,
- it further tests to see if this driver supports creating a handle for the specified child device.
- This function checks to see if the driver specified by This supports the device specified by
- ControllerHandle. Drivers will typically use the device path attached to
- ControllerHandle and/or the services from the bus I/O abstraction attached to
- ControllerHandle to determine if the driver supports ControllerHandle. This function
- may be called many times during platform initialization. In order to reduce boot times, the tests
- performed by this function must be very small, and take as little time as possible to execute. This
- function must not change the state of any hardware devices, and this function must be aware that the
- device specified by ControllerHandle may already be managed by the same driver or a
- different driver. This function must match its calls to AllocatePages() with FreePages(),
- AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
- Since ControllerHandle may have been previously started by the same driver, if a protocol is
- already in the opened state, then it must not be closed with CloseProtocol(). This is required
- to guarantee the state of ControllerHandle is not modified by this function.
- @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
- @param[in] ControllerHandle The handle of the controller to test. This handle
- must support a protocol interface that supplies
- an I/O abstraction to the driver.
- @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
- parameter is ignored by device drivers, and is optional for bus
- drivers. For bus drivers, if this parameter is not NULL, then
- the bus driver must determine if the bus controller specified
- by ControllerHandle and the child controller specified
- by RemainingDevicePath are both supported by this
- bus driver.
- @retval EFI_SUCCESS The device specified by ControllerHandle and
- RemainingDevicePath is supported by the driver specified by This.
- @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
- RemainingDevicePath is already being managed by the driver
- specified by This.
- @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
- RemainingDevicePath is already being managed by a different
- driver or an application that requires exclusive access.
- Currently not implemented.
- @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
- RemainingDevicePath is not supported by the driver specified by This.
- **/
- EFI_STATUS
- EFIAPI
- I2cBusDriverSupported (
- IN EFI_DRIVER_BINDING_PROTOCOL *This,
- IN EFI_HANDLE Controller,
- IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
- );
- /**
- Starts a device controller or a bus controller.
- The Start() function is designed to be invoked from the EFI boot service ConnectController().
- As a result, much of the error checking on the parameters to Start() has been moved into this
- common boot service. It is legal to call Start() from other locations,
- but the following calling restrictions must be followed or the system behavior will not be deterministic.
- 1. ControllerHandle must be a valid EFI_HANDLE.
- 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
- EFI_DEVICE_PATH_PROTOCOL.
- 3. Prior to calling Start(), the Supported() function for the driver specified by This must
- have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
- @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
- @param[in] ControllerHandle The handle of the controller to start. This handle
- must support a protocol interface that supplies
- an I/O abstraction to the driver.
- @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
- parameter is ignored by device drivers, and is optional for bus
- drivers. For a bus driver, if this parameter is NULL, then handles
- for all the children of Controller are created by this driver.
- If this parameter is not NULL and the first Device Path Node is
- not the End of Device Path Node, then only the handle for the
- child device specified by the first Device Path Node of
- RemainingDevicePath is created by this driver.
- If the first Device Path Node of RemainingDevicePath is
- the End of Device Path Node, no child handle is created by this
- driver.
- @retval EFI_SUCCESS The device was started.
- @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
- @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
- @retval Others The driver failded to start the device.
- **/
- EFI_STATUS
- EFIAPI
- I2cBusDriverStart (
- IN EFI_DRIVER_BINDING_PROTOCOL *This,
- IN EFI_HANDLE Controller,
- IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
- );
- /**
- Stops a device controller or a bus controller.
- The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
- As a result, much of the error checking on the parameters to Stop() has been moved
- into this common boot service. It is legal to call Stop() from other locations,
- but the following calling restrictions must be followed or the system behavior will not be deterministic.
- 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
- same driver's Start() function.
- 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
- EFI_HANDLE. In addition, all of these handles must have been created in this driver's
- Start() function, and the Start() function must have called OpenProtocol() on
- ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
- @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
- @param[in] ControllerHandle A handle to the device being stopped. The handle must
- support a bus specific I/O protocol for the driver
- to use to stop the device.
- @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
- @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
- if NumberOfChildren is 0.
- @retval EFI_SUCCESS The device was stopped.
- @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
- **/
- EFI_STATUS
- EFIAPI
- I2cBusDriverStop (
- IN EFI_DRIVER_BINDING_PROTOCOL *This,
- IN EFI_HANDLE Controller,
- IN UINTN NumberOfChildren,
- IN EFI_HANDLE *ChildHandleBuffer
- );
- /**
- Retrieves a Unicode string that is the user readable name of the driver.
- This function retrieves the user readable name of a driver in the form of a
- Unicode string. If the driver specified by This has a user readable name in
- the language specified by Language, then a pointer to the driver name is
- returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
- by This does not support the language specified by Language,
- then EFI_UNSUPPORTED is returned.
- @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
- EFI_COMPONENT_NAME_PROTOCOL instance.
- @param Language[in] A pointer to a Null-terminated ASCII string
- array indicating the language. This is the
- language of the driver name that the caller is
- requesting, and it must match one of the
- languages specified in SupportedLanguages. The
- number of languages supported by a driver is up
- to the driver writer. Language is specified
- in RFC 4646 or ISO 639-2 language code format.
- @param DriverName[out] A pointer to the Unicode string to return.
- This Unicode string is the name of the
- driver specified by This in the language
- specified by Language.
- @retval EFI_SUCCESS The Unicode string for the Driver specified by
- This and the language specified by Language was
- returned in DriverName.
- @retval EFI_INVALID_PARAMETER Language is NULL.
- @retval EFI_INVALID_PARAMETER DriverName is NULL.
- @retval EFI_UNSUPPORTED The driver specified by This does not support
- the language specified by Language.
- **/
- EFI_STATUS
- EFIAPI
- I2cBusComponentNameGetDriverName (
- IN EFI_COMPONENT_NAME2_PROTOCOL *This,
- IN CHAR8 *Language,
- OUT CHAR16 **DriverName
- );
- /**
- Retrieves a Unicode string that is the user readable name of the controller
- that is being managed by a driver.
- This function retrieves the user readable name of the controller specified by
- ControllerHandle and ChildHandle in the form of a Unicode string. If the
- driver specified by This has a user readable name in the language specified by
- Language, then a pointer to the controller name is returned in ControllerName,
- and EFI_SUCCESS is returned. If the driver specified by This is not currently
- managing the controller specified by ControllerHandle and ChildHandle,
- then EFI_UNSUPPORTED is returned. If the driver specified by This does not
- support the language specified by Language, then EFI_UNSUPPORTED is returned.
- @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
- EFI_COMPONENT_NAME_PROTOCOL instance.
- @param ControllerHandle[in] The handle of a controller that the driver
- specified by This is managing. This handle
- specifies the controller whose name is to be
- returned.
- @param ChildHandle[in] The handle of the child controller to retrieve
- the name of. This is an optional parameter that
- may be NULL. It will be NULL for device
- drivers. It will also be NULL for a bus drivers
- that wish to retrieve the name of the bus
- controller. It will not be NULL for a bus
- driver that wishes to retrieve the name of a
- child controller.
- @param Language[in] A pointer to a Null-terminated ASCII string
- array indicating the language. This is the
- language of the driver name that the caller is
- requesting, and it must match one of the
- languages specified in SupportedLanguages. The
- number of languages supported by a driver is up
- to the driver writer. Language is specified in
- RFC 4646 or ISO 639-2 language code format.
- @param ControllerName[out] A pointer to the Unicode string to return.
- This Unicode string is the name of the
- controller specified by ControllerHandle and
- ChildHandle in the language specified by
- Language from the point of view of the driver
- specified by This.
- @retval EFI_SUCCESS The Unicode string for the user readable name in
- the language specified by Language for the
- driver specified by This was returned in
- DriverName.
- @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
- @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
- EFI_HANDLE.
- @retval EFI_INVALID_PARAMETER Language is NULL.
- @retval EFI_INVALID_PARAMETER ControllerName is NULL.
- @retval EFI_UNSUPPORTED The driver specified by This is not currently
- managing the controller specified by
- ControllerHandle and ChildHandle.
- @retval EFI_UNSUPPORTED The driver specified by This does not support
- the language specified by Language.
- **/
- EFI_STATUS
- EFIAPI
- I2cBusComponentNameGetControllerName (
- IN EFI_COMPONENT_NAME2_PROTOCOL *This,
- IN EFI_HANDLE ControllerHandle,
- IN EFI_HANDLE ChildHandle OPTIONAL,
- IN CHAR8 *Language,
- OUT CHAR16 **ControllerName
- );
- /**
- The user entry point for the I2C bus module. The user code starts with
- this function.
- @param[in] ImageHandle The firmware allocated handle for the EFI image.
- @param[in] SystemTable A pointer to the EFI System Table.
- @retval EFI_SUCCESS The entry point is executed successfully.
- @retval other Some error occurs when executing this entry point.
- **/
- EFI_STATUS
- EFIAPI
- InitializeI2cBus(
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable
- );
- /**
- This is the unload handle for I2C bus module.
- Disconnect the driver specified by ImageHandle from all the devices in the handle database.
- Uninstall all the protocols installed in the driver entry point.
- @param[in] ImageHandle The drivers' driver image.
- @retval EFI_SUCCESS The image is unloaded.
- @retval Others Failed to unload the image.
- **/
- EFI_STATUS
- EFIAPI
- I2cBusUnload (
- IN EFI_HANDLE ImageHandle
- );
- /**
- Release all the resources allocated for the I2C device.
- This function releases all the resources allocated for the I2C device.
- @param I2cDeviceContext The I2C child device involved for the operation.
- **/
- VOID
- ReleaseI2cDeviceContext (
- IN I2C_DEVICE_CONTEXT *I2cDeviceContext
- );
- /**
- Complete the current request
- @param[in] I2cHost Address of an I2C_HOST_CONTEXT structure.
- @param[in] Status Status of the I<sub>2</sub>C operation.
- @return This routine returns the input status value.
- **/
- EFI_STATUS
- I2cHostRequestComplete (
- I2C_HOST_CONTEXT *I2cHost,
- EFI_STATUS Status
- );
- /**
- Enable access to the I2C bus configuration
- @param[in] I2cHostContext Address of an I2C_HOST_CONTEXT structure
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_ABORTED The request did not complete because the driver
- was shutdown.
- @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.
- @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.
- This could indicate the slave device is not present.
- @retval EFI_INVALID_PARAMETER RequestPacket is NULL
- @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value
- @retval EFI_NO_RESPONSE The I2C device is not responding to the
- slave address. EFI_DEVICE_ERROR may also be
- returned if the controller can not distinguish
- when the NACK occurred.
- @retval EFI_NOT_FOUND I2C slave address exceeds maximum address
- @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for
- the event and then read status.
- @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation
- @retval EFI_TIMEOUT The transaction did not complete within an internally
- specified timeout period.
- **/
- EFI_STATUS
- I2cHostRequestEnable (
- I2C_HOST_CONTEXT *I2cHost
- );
- /**
- Tests to see if this driver supports a given controller. If a child device is provided,
- it further tests to see if this driver supports creating a handle for the specified child device.
- This function checks to see if the driver specified by This supports the device specified by
- ControllerHandle. Drivers will typically use the device path attached to
- ControllerHandle and/or the services from the bus I/O abstraction attached to
- ControllerHandle to determine if the driver supports ControllerHandle. This function
- may be called many times during platform initialization. In order to reduce boot times, the tests
- performed by this function must be very small, and take as little time as possible to execute. This
- function must not change the state of any hardware devices, and this function must be aware that the
- device specified by ControllerHandle may already be managed by the same driver or a
- different driver. This function must match its calls to AllocatePages() with FreePages(),
- AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
- Since ControllerHandle may have been previously started by the same driver, if a protocol is
- already in the opened state, then it must not be closed with CloseProtocol(). This is required
- to guarantee the state of ControllerHandle is not modified by this function.
- @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
- @param[in] ControllerHandle The handle of the controller to test. This handle
- must support a protocol interface that supplies
- an I/O abstraction to the driver.
- @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
- parameter is ignored by device drivers, and is optional for bus
- drivers. For bus drivers, if this parameter is not NULL, then
- the bus driver must determine if the bus controller specified
- by ControllerHandle and the child controller specified
- by RemainingDevicePath are both supported by this
- bus driver.
- @retval EFI_SUCCESS The device specified by ControllerHandle and
- RemainingDevicePath is supported by the driver specified by This.
- @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
- RemainingDevicePath is already being managed by the driver
- specified by This.
- @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
- RemainingDevicePath is already being managed by a different
- driver or an application that requires exclusive access.
- Currently not implemented.
- @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
- RemainingDevicePath is not supported by the driver specified by This.
- **/
- EFI_STATUS
- EFIAPI
- I2cHostDriverSupported (
- IN EFI_DRIVER_BINDING_PROTOCOL *This,
- IN EFI_HANDLE Controller,
- IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
- );
- /**
- Starts a device controller or a bus controller.
- The Start() function is designed to be invoked from the EFI boot service ConnectController().
- As a result, much of the error checking on the parameters to Start() has been moved into this
- common boot service. It is legal to call Start() from other locations,
- but the following calling restrictions must be followed, or the system behavior will not be deterministic.
- 1. ControllerHandle must be a valid EFI_HANDLE.
- 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
- EFI_DEVICE_PATH_PROTOCOL.
- 3. Prior to calling Start(), the Supported() function for the driver specified by This must
- have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
- @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
- @param[in] ControllerHandle The handle of the controller to start. This handle
- must support a protocol interface that supplies
- an I/O abstraction to the driver.
- @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
- parameter is ignored by device drivers, and is optional for bus
- drivers. For a bus driver, if this parameter is NULL, then handles
- for all the children of Controller are created by this driver.
- If this parameter is not NULL and the first Device Path Node is
- not the End of Device Path Node, then only the handle for the
- child device specified by the first Device Path Node of
- RemainingDevicePath is created by this driver.
- If the first Device Path Node of RemainingDevicePath is
- the End of Device Path Node, no child handle is created by this
- driver.
- @retval EFI_SUCCESS The device was started.
- @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
- @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
- @retval Others The driver failded to start the device.
- **/
- EFI_STATUS
- EFIAPI
- I2cHostDriverStart (
- IN EFI_DRIVER_BINDING_PROTOCOL *This,
- IN EFI_HANDLE Controller,
- IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
- );
- /**
- Stops a device controller or a bus controller.
- The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
- As a result, much of the error checking on the parameters to Stop() has been moved
- into this common boot service. It is legal to call Stop() from other locations,
- but the following calling restrictions must be followed, or the system behavior will not be deterministic.
- 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
- same driver's Start() function.
- 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
- EFI_HANDLE. In addition, all of these handles must have been created in this driver's
- Start() function, and the Start() function must have called OpenProtocol() on
- ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
- @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
- @param[in] ControllerHandle A handle to the device being stopped. The handle must
- support a bus specific I/O protocol for the driver
- to use to stop the device.
- @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
- @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
- if NumberOfChildren is 0.
- @retval EFI_SUCCESS The device was stopped.
- @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
- **/
- EFI_STATUS
- EFIAPI
- I2cHostDriverStop (
- IN EFI_DRIVER_BINDING_PROTOCOL *This,
- IN EFI_HANDLE Controller,
- IN UINTN NumberOfChildren,
- IN EFI_HANDLE *ChildHandleBuffer
- );
- /**
- Retrieves a Unicode string that is the user readable name of the driver.
- This function retrieves the user readable name of a driver in the form of a
- Unicode string. If the driver specified by This has a user readable name in
- the language specified by Language, then a pointer to the driver name is
- returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
- by This does not support the language specified by Language,
- then EFI_UNSUPPORTED is returned.
- @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
- EFI_COMPONENT_NAME_PROTOCOL instance.
- @param Language[in] A pointer to a Null-terminated ASCII string
- array indicating the language. This is the
- language of the driver name that the caller is
- requesting, and it must match one of the
- languages specified in SupportedLanguages. The
- number of languages supported by a driver is up
- to the driver writer. Language is specified
- in RFC 4646 or ISO 639-2 language code format.
- @param DriverName[out] A pointer to the Unicode string to return.
- This Unicode string is the name of the
- driver specified by This in the language
- specified by Language.
- @retval EFI_SUCCESS The Unicode string for the Driver specified by
- This and the language specified by Language was
- returned in DriverName.
- @retval EFI_INVALID_PARAMETER Language is NULL.
- @retval EFI_INVALID_PARAMETER DriverName is NULL.
- @retval EFI_UNSUPPORTED The driver specified by This does not support
- the language specified by Language.
- **/
- EFI_STATUS
- EFIAPI
- I2cHostComponentNameGetDriverName (
- IN EFI_COMPONENT_NAME2_PROTOCOL *This,
- IN CHAR8 *Language,
- OUT CHAR16 **DriverName
- );
- /**
- Retrieves a Unicode string that is the user readable name of the controller
- that is being managed by a driver.
- This function retrieves the user readable name of the controller specified by
- ControllerHandle and ChildHandle in the form of a Unicode string. If the
- driver specified by This has a user readable name in the language specified by
- Language, then a pointer to the controller name is returned in ControllerName,
- and EFI_SUCCESS is returned. If the driver specified by This is not currently
- managing the controller specified by ControllerHandle and ChildHandle,
- then EFI_UNSUPPORTED is returned. If the driver specified by This does not
- support the language specified by Language, then EFI_UNSUPPORTED is returned.
- @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
- EFI_COMPONENT_NAME_PROTOCOL instance.
- @param ControllerHandle[in] The handle of a controller that the driver
- specified by This is managing. This handle
- specifies the controller whose name is to be
- returned.
- @param ChildHandle[in] The handle of the child controller to retrieve
- the name of. This is an optional parameter that
- may be NULL. It will be NULL for device
- drivers. It will also be NULL for a bus drivers
- that wish to retrieve the name of the bus
- controller. It will not be NULL for a bus
- driver that wishes to retrieve the name of a
- child controller.
- @param Language[in] A pointer to a Null-terminated ASCII string
- array indicating the language. This is the
- language of the driver name that the caller is
- requesting, and it must match one of the
- languages specified in SupportedLanguages. The
- number of languages supported by a driver is up
- to the driver writer. Language is specified in
- RFC 4646 or ISO 639-2 language code format.
- @param ControllerName[out] A pointer to the Unicode string to return.
- This Unicode string is the name of the
- controller specified by ControllerHandle and
- ChildHandle in the language specified by
- Language from the point of view of the driver
- specified by This.
- @retval EFI_SUCCESS The Unicode string for the user readable name in
- the language specified by Language for the
- driver specified by This was returned in
- DriverName.
- @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
- @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
- EFI_HANDLE.
- @retval EFI_INVALID_PARAMETER Language is NULL.
- @retval EFI_INVALID_PARAMETER ControllerName is NULL.
- @retval EFI_UNSUPPORTED The driver specified by This is not currently
- managing the controller specified by
- ControllerHandle and ChildHandle.
- @retval EFI_UNSUPPORTED The driver specified by This does not support
- the language specified by Language.
- **/
- EFI_STATUS
- EFIAPI
- I2cHostComponentNameGetControllerName (
- IN EFI_COMPONENT_NAME2_PROTOCOL *This,
- IN EFI_HANDLE ControllerHandle,
- IN EFI_HANDLE ChildHandle OPTIONAL,
- IN CHAR8 *Language,
- OUT CHAR16 **ControllerName
- );
- /**
- Handle the bus available event
- This routine is called at TPL_I2C_SYNC.
- @param[in] Event Address of an EFI_EVENT handle
- @param[in] Context Address of an I2C_HOST_CONTEXT structure
- **/
- VOID
- EFIAPI
- I2cHostRequestCompleteEvent (
- IN EFI_EVENT Event,
- IN VOID *Context
- );
- /**
- Handle the I2C bus configuration available event
- This routine is called at TPL_I2C_SYNC.
- @param[in] Event Address of an EFI_EVENT handle
- @param[in] Context Address of an I2C_HOST_CONTEXT structure
- **/
- VOID
- EFIAPI
- I2cHostI2cBusConfigurationAvailable (
- IN EFI_EVENT Event,
- IN VOID *Context
- );
- /**
- Queue an I2C operation for execution on the I2C controller.
- This routine must be called at or below TPL_NOTIFY. For synchronous
- requests this routine must be called at or below TPL_CALLBACK.
- N.B. The typical consumers of this API are the I2C bus driver and
- on rare occasions the I2C test application. Extreme care must be
- taken by other consumers of this API to prevent confusing the
- third party I2C drivers due to a state change at the I2C device
- which the third party I2C drivers did not initiate. I2C platform
- drivers may use this API within these guidelines.
- This layer uses the concept of I2C bus configurations to describe
- the I2C bus. An I2C bus configuration is defined as a unique
- setting of the multiplexers and switches in the I2C bus which
- enable access to one or more I2C devices. When using a switch
- to divide a bus, due to speed differences, the I2C platform layer
- would define an I2C bus configuration for the I2C devices on each
- side of the switch. When using a multiplexer, the I2C platform
- layer defines an I2C bus configuration for each of the selector
- values required to control the multiplexer. See Figure 1 in the
- <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C
- Specification</a> for a complex I2C bus configuration.
- The I2C host driver processes all operations in FIFO order. Prior to
- performing the operation, the I2C host driver calls the I2C platform
- driver to reconfigure the switches and multiplexers in the I2C bus
- enabling access to the specified I2C device. The I2C platform driver
- also selects the maximum bus speed for the device. After the I2C bus
- is configured, the I2C host driver calls the I2C port driver to
- initialize the I2C controller and start the I2C operation.
- @param[in] This Address of an EFI_I2C_HOST_PROTOCOL instance.
- @param[in] I2cBusConfiguration I2C bus configuration to access the I2C
- device.
- @param[in] SlaveAddress Address of the device on the I2C bus.
- @param[in] Event Event to set for asynchronous operations,
- NULL for synchronous operations
- @param[in] RequestPacket Address of an EFI_I2C_REQUEST_PACKET
- structure describing the I2C operation
- @param[out] I2cStatus Optional buffer to receive the I2C operation
- completion status
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_ABORTED The request did not complete because the driver
- was shutdown.
- @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.
- @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.
- This could indicate the slave device is not present.
- @retval EFI_INVALID_PARAMETER RequestPacket is NULL
- @retval EFI_INVALID_PARAMETER TPL is too high
- @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value
- @retval EFI_NO_RESPONSE The I2C device is not responding to the
- slave address. EFI_DEVICE_ERROR may also be
- returned if the controller can not distinguish
- when the NACK occurred.
- @retval EFI_NOT_FOUND I2C slave address exceeds maximum address
- @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for
- the event and then read status pointed to by
- the request packet.
- @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation
- @retval EFI_TIMEOUT The transaction did not complete within an internally
- specified timeout period.
- **/
- EFI_STATUS
- EFIAPI
- I2cHostQueueRequest (
- IN CONST EFI_I2C_HOST_PROTOCOL *This,
- IN UINTN I2cBusConfiguration,
- IN UINTN SlaveAddress,
- IN EFI_EVENT Event OPTIONAL,
- IN EFI_I2C_REQUEST_PACKET *RequestPacket,
- OUT EFI_STATUS *I2cStatus OPTIONAL
- );
- /**
- The user Entry Point for I2C host module. The user code starts with this function.
- @param[in] ImageHandle The firmware allocated handle for the EFI image.
- @param[in] SystemTable A pointer to the EFI System Table.
- @retval EFI_SUCCESS The entry point is executed successfully.
- @retval other Some error occurs when executing this entry point.
- **/
- EFI_STATUS
- EFIAPI
- InitializeI2cHost(
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable
- );
- /**
- This is the unload handle for I2C host module.
- Disconnect the driver specified by ImageHandle from all the devices in the handle database.
- Uninstall all the protocols installed in the driver entry point.
- @param[in] ImageHandle The drivers' driver image.
- @retval EFI_SUCCESS The image is unloaded.
- @retval Others Failed to unload the image.
- **/
- EFI_STATUS
- EFIAPI
- I2cHostUnload (
- IN EFI_HANDLE ImageHandle
- );
- #endif // __I2C_DXE_H__
|