diff options
Diffstat (limited to 'MdePkg/Include/Protocol/I2cMaster.h')
| -rw-r--r-- | MdePkg/Include/Protocol/I2cMaster.h | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/MdePkg/Include/Protocol/I2cMaster.h b/MdePkg/Include/Protocol/I2cMaster.h new file mode 100644 index 0000000000..26137344af --- /dev/null +++ b/MdePkg/Include/Protocol/I2cMaster.h @@ -0,0 +1,192 @@ +/** @file
+ I2C Master Protocol as defined in the PI 1.3 specification.
+
+ 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.
+
+ Copyright (c) 2013, 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
+ which 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.
+
+ @par Revision Reference:
+ This protocol is from PI Version 1.3.
+
+**/
+
+#ifndef __I2C_MASTER_H__
+#define __I2C_MASTER_H__
+
+#include <Pi/PiI2c.h>
+
+#define EFI_I2C_MASTER_PROTOCOL_GUID { 0xcd72881f, 0x45b5, 0x4feb, { 0x98, 0xc8, 0x31, 0x3d, 0xa8, 0x11, 0x74, 0x62 }}
+
+typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL;
+
+/**
+ Set the frequency for the I2C clock line.
+
+ 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 I2C master protocol selects the next 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 I2C master protocol selects 398
+ KHz. If there are not lower frequencies available, then return
+ EFI_UNSUPPORTED.
+
+ @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure
+ @param[in] BusClockHertz Pointer to the requested I2C bus clock frequency
+ in Hertz. Upon return this value contains the
+ actual frequency in use by the I2C controller.
+
+ @retval EFI_SUCCESS The bus frequency was set successfully.
+ @retval EFI_ALREADY_STARTED The controller is busy with another transaction.
+ @retval EFI_INVALID_PARAMETER BusClockHertz is NULL
+ @retval EFI_UNSUPPORTED The controller does not support this frequency.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY) (
+ IN CONST EFI_I2C_MASTER_PROTOCOL *This,
+ IN OUT 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. The caller must call SetBusFrequench() after
+ calling Reset().
+
+ @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure.
+
+ @retval EFI_SUCCESS The reset completed successfully.
+ @retval EFI_ALREADY_STARTED The controller is busy with another transaction.
+ @retval EFI_DEVICE_ERROR The reset operation failed.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_I2C_MASTER_PROTOCOL_RESET) (
+ IN CONST EFI_I2C_MASTER_PROTOCOL *This
+ );
+
+/**
+ Start an I2C transaction 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 transaction on the controller. To
+ enable proper error handling by the I2C protocol stack, the I2C
+ master protocol does not support queuing but instead only manages
+ one I2C transaction at a time. This API requires that the I2C bus
+ is in the correct configuration for the I2C transaction.
+
+ The transaction is performed by sending a start-bit and selecting the
+ I2C device with the specified I2C slave address and then performing
+ the specified I2C operations. When multiple operations are requested
+ they are separated with a repeated start bit and the slave address.
+ The transaction is terminated with a stop bit.
+
+ When Event is NULL, StartRequest operates synchronously and returns
+ the I2C completion status as its return value.
+
+ When Event is not NULL, StartRequest synchronously returns EFI_SUCCESS
+ indicating that the I2C transaction was started asynchronously. The
+ transaction status value is returned in the buffer pointed to by
+ I2cStatus upon the completion of the I2C transaction when I2cStatus
+ is not NULL. After the transaction status is returned the Event is
+ signaled.
+
+ Note: The typical consumer of this API is the I2C host protocol.
+ 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 specific code may use this API within these guidelines.
+
+ @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure.
+ @param[in] SlaveAddress Address of the device on the I2C bus. Set the
+ I2C_ADDRESSING_10_BIT when using 10-bit addresses,
+ clear this bit for 7-bit addressing. Bits 0-6
+ are used for 7-bit I2C slave addresses and bits
+ 0-9 are used for 10-bit I2C slave addresses.
+ @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET
+ structure describing the I2C transaction.
+ @param[in] Event Event to signal for asynchronous transactions,
+ NULL for asynchronous transactions
+ @param[out] I2cStatus Optional buffer to receive the I2C transaction
+ completion status
+
+ @retval EFI_SUCCESS The asynchronous transaction was successfully
+ started when Event is not NULL.
+ @retval EFI_SUCCESS The transaction completed successfully when
+ Event is NULL.
+ @retval EFI_ALREADY_STARTED The controller is busy with another transaction.
+ @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_RESPONSE The I2C device is not responding to the slave
+ address. 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.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_I2C_MASTER_PROTOCOL_START_REQUEST) (
+ IN CONST EFI_I2C_MASTER_PROTOCOL *This,
+ IN UINTN SlaveAddress,
+ IN EFI_I2C_REQUEST_PACKET *RequestPacket,
+ IN EFI_EVENT Event OPTIONAL,
+ 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_PROTOCOL_SET_BUS_FREQUENCY SetBusFrequency;
+
+ ///
+ /// Reset the I2C host controller.
+ ///
+ EFI_I2C_MASTER_PROTOCOL_RESET Reset;
+
+ ///
+ /// Start an I2C transaction in master mode on the host controller.
+ ///
+ EFI_I2C_MASTER_PROTOCOL_START_REQUEST StartRequest;
+
+ ///
+ /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing
+ /// the capabilities of the I2C host controller.
+ ///
+ CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities;
+};
+
+extern EFI_GUID gEfiI2cMasterProtocolGuid;
+
+#endif // __I2C_MASTER_H__
|