diff options
Diffstat (limited to 'Vlv2TbltDevicePkg/Include/Protocol/I2cMasterMcg.h')
| -rw-r--r-- | Vlv2TbltDevicePkg/Include/Protocol/I2cMasterMcg.h | 524 |
1 files changed, 524 insertions, 0 deletions
diff --git a/Vlv2TbltDevicePkg/Include/Protocol/I2cMasterMcg.h b/Vlv2TbltDevicePkg/Include/Protocol/I2cMasterMcg.h new file mode 100644 index 0000000000..f239b5ec2f --- /dev/null +++ b/Vlv2TbltDevicePkg/Include/Protocol/I2cMasterMcg.h @@ -0,0 +1,524 @@ +/*++
+
+ Copyright (c) 2004 - 2014, Intel Corporation. All rights reserved.<BR>
+
+ 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__
|