I2cMasterMcg.h - Android社区 - https://www.androidos.net.cn/

/*++

This program and the accompanying materials are licensed and made available under

the terms and conditions of the BSD License that accompanies this distribution.

The full text of the license may be found at

http://opensource.org/licenses/bsd-license.php.

THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

\section I2cDriverStack I2C Driver Stack

The following is a representation of the I<sup>2</sup>C (I2C)
driver stack and an I2C bus layout.

<code><pre>
+-----------------+
| Application |
+-----------------+
|
| Third Party or UEFI
|
V
+--------+ +-----------------+
| Slave | | Third Party |
| Driver | | I2C Device |
| | | Driver |
+--------+ +-----------------+
| |
| BUS |
| |
| V
| +-----------------+
| | I2C Bus Driver |------------------.
| +-----------------+ |
| | |
| HOST | BUS |
| | CONFIGURATION |
SLAVE | V MANAGEMENT | ACPI
| +-----------------+ |
| | I2C Host Driver |----------. |
| +-----------------+ | |
| | | |
| MASTER | V V
| | +-------=-------------+
| V | I2C Platform Driver |
| +-----------------+ +---------------------+
`------>| I2C Port Driver | | |
+-----------------+ | |
| | |
Software | | |
--------------------------------------------------
Hardware | | |
| | |
V | |
+-----------------+ | |
| I2C Controller | | |
+-----------------+ | |
| | |
----------------------- | |
I2C Bus | | |
| +------------+ | |
+----| High speed | | |
| | I2C device | | |
| | 0x01 | | |
| +------------+ | |
| | |
+---------+ 0 | |
| Switch |<------------------` |
+---------+ 1 |
| |
| +------------+ |
+----| Fast speed | |
| | I2C device | |
| | 0x02 | |
| +------------+ |
| |
+-------------+ |
| Multiplexer |<-----------------------`
+-------------+
0 | | 1
| |
| |
| | +-------------+
| +----| Third Party |
| | | I2C Device |
| | | 0x03, 0x04 |
| | +-------------+
| |
|
| +-------------+
+------------| Third Party |
| | I2C Device |
| | 0x03, 0x04 |
| +-------------+
|
</pre></code>

The platform hardware designer chooses the bus layout based upon
the platform, I2C chip and software requirements. The design uses
switches to truncate the bus to enable higher speed operation for a
subset of devices which are placed closer to the controller. When the
switch is on, the extended bus must operate at a lower speed. The
design uses multiplexer to create separate address spaces enabling
the use of multiple devices which would otherwise have conflicting
addresses. See the
<a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C
Specification</a> for more details.

N.B. Some operating systems may prohibit the changing of switches
and multiplexers in the I2C bus. In this case the platform hardware
and software designers must select a single I2C bus configuration
consisting of constant input values for the switches and multiplexers.
The platform software designer must then ensure that this I2C bus
configuration is enabled prior to passing control to the operating
system.

The platform hardware designer needs to provide the platform software
designer the following data for each I2C bus:

1. Which controller controls this bus

2. A list of logic blocks contained in one or more I2C devices:

a. I2C device which contains this logic block

b. Logic block slave address

c. Logic block name

3. For each configuration of the switches and multiplexer

a. What is the maximum speed of operation

b. What devices are accessible

4. The settings for the switches and multiplexers when control is
given to the operating system.

\section ThirdPartyI2cDrivers Third Party I2C Drivers

This layer is I2C chip specific but platform and host controller
independent.

Third party I2C driver writers, typically silicon vendors, need
to provide:

1. The device path node data that is used to select their
driver.

2. The order for the blocks of logic that get referenced
by the entries in the slave address array.

3. The hardware version of the I2C device, this value is passed
to the third party I2C driver to enable it to perform work
arounds for the specific hardware version. This value should
match the value in the ACPI _HRV tag.

The third party I2C driver uses relative addressing to abstract
the platform specific details of the I2C device. Using an
example I2C device containing an accelerometer and a magnetometer
which consumes two slave addresses, one for each logic block. The
third party I2C driver writer may choose to write two drivers, one
for each block of logic, in which case each driver refers to the
single I2C slave address using the relative value of zero (0).
However if the third party I2C driver writer chooses to write a
single driver which consumes multiple slave addresses then the
third party I2C driver writer needs to convey the order of the
I2C slave address entries in the slave address array to the
platform software designer. For the example:

0: Accelerometer

1: Magnetometer

The platform hardware designer picks the actual slave addresses
from the I2C device's data sheet and provides this information
to the platform software designer. The platform software designer
then places the slave addresses into the slave address array in the
order specified by the third party I2C driver writer. The third
party driver I2C writer then indirectly references this array by
specifying the index value as the relative slave address. The
relative value always starts at zero (0) and its maximum value is
the number of entries in slave address array minus one.

The slave address is specified as a 32-bit integer to allow room
for future slave address expansion. Only the port driver knows
the maximum slave address value. All other drivers and
applications must look for the EFI_NOT_FOUND status for the
indication that the maximum slave address was exceeded.

\section I2cBusDriver I2C Bus Driver

This layer is platform, host controller, and I2C chip independent.

The I2C bus driver creates a handle for each of the I2C devices
described within the platform driver. The I2C controller's device
path is extended with the device path node provided by the platform
driver and attached to the handle. The third party I2C device driver
uses the device path to determine if it may connect. For ACPI nodes,
the third party I2C driver should use the CID or CidString value.

The I2C bus driver validates the relative address for the I2C device
and then converts the relative value to an actual I2C slave address.
The request is then passed to the I2C host driver.

\section I2cHostDriver I2C Host Driver

This layer is platform, host controller, and I2C chip independent.

N.B. For proper operation of the I2C bus, only the I2C bus driver
and the I2C test application should connect to the I2C host driver
via the EFI_I2C_HOST_DRIVER_PROTOCOL.

The I2C host driver may access any device on the I2C bus. The I2C
host driver has the following responsibilities:

1. Limits the number of requests to the I2C port driver to one.
The I2C host driver holds on to additional requests until the
I2C port driver is available to process the request. The I2C
requests are issued in FIFO order to the I2C port driver.

2. Enable the proper I2C bus configuration before starting the
I2C request on the I2C port driver

I2C devices are addressed as the tuple: BusConfiguration:SlaveAddress.
I2C bus configuration zero (0) is the portion of the I2C bus that
connects to the host controller. The bus configuration specifies
the control values for the switches and multiplexers in the I2C bus.
After the switches and multiplexers are properly configured, the I2C
controller uses the slave address to access the requested I2C device.

Since the I2C driver stack supports asynchronous operations this
layer maintains a queue of I2C requests until the I2C controller
is available them. When a request reaches the head of the queue
the necessary bus configuration is enabled and then the request
is sent to the I2C port driver.

\section I2cPortDriver I2C Port Driver

This layer is I2C controller specific but platform independent.

This layer manipulates the I2C controller to perform an operation
on the I2C bus. This layer does not configure the I2C bus so it
is up to the caller to ensure that the I2C bus is in the proper
configuration before issuing the I2C request.

This layer typically needs the following information:

1. Host controller address
2. Controller's input clock frequency

Depending upon the I2C controller, more data may be necessary.
This layer may use any method to get these values: hard coded
values, PCD values, or may choose to communicate with the platform
layer using an undefined mechanism to get these values.

If the I2C port driver requires data from the platform driver then
the I2C port driver writer needs to provide the platform interface
details to the platform software designer.

\section I2cPlatformDriver I2C Platform Driver

When enabling access to I2C devices within UEFI, this driver
installs the EFI_I2C_ACPI_PROTOCOL to provide the I2C device
descriptions to the I2C bus driver using the EFI_I2C_DEVICE
structure. These descriptions include the bus configuration
number required for the I2C device, the slave address array
and the device path.

The EFI_I2C_BUS_CONFIGURATION_MANAGEMENT protocol is optional.
This protocol needs to be specified under the following conditions:

1. The I2C bus must operate at a frequency greater than 100 KHz
2. The I2C bus contains switches or multiplexers.

The EFI_I2C_BUS_CONFIGURATION_MANAGEMENT protocol enables the
I2C host driver to call into the I2C platform driver to enable
a specific I2C bus configuration and set its maximum clock speed.

The platform software designer collects the data requirements
from third party I2C driver writers, the I2C controller
driver writer, the EFI_I2C_ACPI_PROTOCOL and
EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL. The platform
software designer gets the necessary data from the platform
hardware designer. The platform software designer then builds
the data structures and implements the necessary routines to
construct the I2C platform driver.

\section I2cSwitches Switches and Multiplexers

There are some I2C switches and I2C multiplexers where the control
is done via I2C commands. When the control inputs come via the
same I2C bus that is being configured then the platform driver must
use the EFI_I2C_MASTER_PROTOCOL that is passed to the platform
driver. While the I2C host driver makes the call to the I2C
platform driver to configure the bus, the host driver keeps the
I2C port driver idle, to allow the I2C platform driver preform
the necessary configuration operations.

If however the configuration control is done via and I2C device
connected to a different I2C bus (host controller), then it is
possible for the platform software designer may choose between
the following:

1. Call into a third party I2C driver to manipulate the I2C
bus control device.
2. Call into the EFI_I2C_BUS_PROTOCOL if no third party I2C
driver exists for the I2C bus control device
3. Call into the EFI_I2C_HOST_PROTOCOL if the platform does
not expose the I2C bus control device.

**/

#ifndef __I2C_MASTER_H__
#define __I2C_MASTER_H__

/**
Declare the forward references

**/
typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL; ///< I2C master protocol

///
/// I2C device operation
///
/// This structure provides the information necessary for an operation
/// on an I2C device
///
typedef struct {
///
/// Number of bytes to send to the I2C device
///
UINT32 WriteBytes;

///
/// Number of bytes to read, set to zero for write only operations
///
UINT32 ReadBytes;

///
/// Address of the buffer containing the data to send to the I2C device.
/// The WriteBuffer must be at least WriteBytes in length.
///
UINT8 *WriteBuffer;

///
/// Address of the buffer to receive data from the I2C device. Use NULL
/// for write only operations. The ReadBuffer must be at least ReadBytes
/// in length.
///
UINT8 *ReadBuffer;

///
/// Timeout for the I2C operation in 100 ns units
///
UINT32 Timeout;
} EFI_I2C_REQUEST_PACKET;

/**
Set the I2C controller bus clock frequency.

This routine must be called at or below TPL_NOTIFY.

The software and controller do a best case effort of using the specified
frequency for the I2C bus. If the frequency does not match exactly then
the controller will use a slightly lower frequency to avoid
exceeding the operating conditions for any of the I2C devices on the bus.
For example if 400 KHz was specified and the controller's divide network
only supports 402 KHz or 398 KHz then the controller would be set to 398
KHz. However if the desired frequency is 400 KHz and the controller only
supports 1 MHz and 100 KHz then this routine would return EFI_UNSUPPORTED.

@param[in] This Address of an EFI_I2C_MASTER_PROTOCOL
structure
@param[in] BusClockHertz New I2C bus clock frequency in Hertz

@retval EFI_SUCCESS The bus frequency was set successfully.
@retval EFI_UNSUPPORTED The controller does not support this frequency.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_I2C_MASTER_BUS_FREQUENCY_SET) (
IN CONST EFI_I2C_MASTER_PROTOCOL *This,
IN UINTN BusClockHertz
);

/**
Reset the I2C controller and configure it for use

This routine must be called at or below TPL_NOTIFY.

The I2C controller is reset and the I2C bus frequency is set to 100 KHz.

@param[in] This Address of an EFI_I2C_MASTER_PROTOCOL
structure

**/
typedef
VOID
(EFIAPI *EFI_I2C_MASTER_RESET) (
IN CONST EFI_I2C_MASTER_PROTOCOL *This
);

/**
Start an I2C operation on the host controller

This routine must be called at or below TPL_NOTIFY. For synchronous
requests this routine must be called at or below TPL_CALLBACK.

This function initiates an I2C operation on the controller.

The operation is performed by selecting the I2C device with its slave
address and then sending all write data to the I2C device. If read data
is requested, a restart is sent followed by the slave address and then
the read data is clocked into the I2C controller and placed in the read
buffer. When the operation completes, the status value is returned and
then the event is set.

N.B. The typical consumer of this API is the I2C host driver.
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.

N.B. This API supports only one operation, no queuing support
exists at this layer. This API assumes that the I2C bus is in
the correct configuration for the I2C request.

@param[in] This Address of an EFI_I2C_MASTER_PROTOCOL
structure
@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_NOT_FOUND SlaveAddress 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_NO_RESPONSE The I2C device is not responding to the
slave address. EFI_DEVICE_ERROR may also be
returned if the controller cannot distinguish
when the NACK occurred.
@retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation
@retval EFI_TIMEOUT The transaction did not complete within an internally
specified timeout period.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_I2C_MASTER_START_REQUEST) (
IN CONST EFI_I2C_MASTER_PROTOCOL *This,
IN UINTN SlaveAddress,
IN EFI_EVENT Event OPTIONAL,
IN CONST EFI_I2C_REQUEST_PACKET *RequestPacket,
OUT EFI_STATUS *I2cStatus OPTIONAL
);

///
/// I2C master mode protocol
///
/// This protocol manipulates the I2C host controller to perform transactions as a
/// master on the I2C bus using the current state of any switches or multiplexers
/// in the I2C bus.
///
struct _EFI_I2C_MASTER_PROTOCOL {
///
/// Set the clock frequency for the I2C bus
///
EFI_I2C_MASTER_BUS_FREQUENCY_SET BusFrequencySet;

///
/// Reset the I2C host controller
///
EFI_I2C_MASTER_RESET Reset;

///
/// Start an I2C transaction in master mode on the host controller
///
EFI_I2C_MASTER_START_REQUEST StartRequest;

///
/// The maximum number of bytes the I2C host controller
/// is able to receive from the I2C bus.
///
UINT32 MaximumReceiveBytes;

///
/// The maximum number of bytes the I2C host controller
/// is able to send on the I2C bus.
///
UINT32 MaximumTransmitBytes;

///
/// The maximum number of bytes in the I2C bus transaction.
///
UINT32 MaximumTotalBytes;
};

///
/// GUID for the EFI_I2C_MASTER_PROTOCOL
///
extern EFI_GUID gEfiI2cMasterProtocolGuid;

#endif // __I2C_MASTER_H__