diff options
Diffstat (limited to 'src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/I2cMaster.h')
| -rw-r--r-- | src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/I2cMaster.h | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/I2cMaster.h b/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/I2cMaster.h new file mode 100644 index 0000000000..26f689788c --- /dev/null +++ b/src/vendorcode/intel/edk2/UDK2017/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__ |