Add I2C related definition in PI 1.3 spec.
Signed-off-by: Elvin Li <elvin.li@intel.com> Reviewed-by: Leahy Leroy P <leroy.p.leahy@intel.com> git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@14548 6f19259b-4bc3-4df7-8a09-765794883524
This commit is contained in:
Elvin Li
li-elvin
160
MdePkg/Include/Protocol/I2cHost.h
Normal file
160
MdePkg/Include/Protocol/I2cHost.h
Normal file
@@ -0,0 +1,160 @@
|
||||
/** @file
|
||||
I2C Host Protocol as defined in the PI 1.3 specification.
|
||||
|
||||
This protocol provides callers with the ability to do I/O transactions
|
||||
to all of the devices on 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_HOST_H__
|
||||
#define __I2C_HOST_H__
|
||||
|
||||
#include <Pi/PiI2c.h>
|
||||
|
||||
#define EFI_I2C_HOST_PROTOCOL_GUID { 0xa5aab9e3, 0xc727, 0x48cd, { 0x8b, 0xbf, 0x42, 0x72, 0x33, 0x85, 0x49, 0x48 }}
|
||||
|
||||
///
|
||||
/// I2C Host Protocol
|
||||
///
|
||||
/// The I2C bus driver uses the services of the EFI_I2C_HOST_PROTOCOL
|
||||
/// to produce an instance of the EFI_I2C_IO_PROTOCOL for each I2C
|
||||
/// device on an I2C bus.
|
||||
///
|
||||
/// The EFI_I2C_HOST_PROTOCOL exposes an asynchronous interface to
|
||||
/// callers to perform transactions to any device on the I2C bus.
|
||||
/// Internally, the I2C host protocol manages the flow of the I2C
|
||||
/// transactions to the host controller, keeping them in FIFO order.
|
||||
/// Prior to each transaction, the I2C host protocol ensures that the
|
||||
/// switches and multiplexers are properly configured. The I2C host
|
||||
/// protocol then starts the transaction on the host controller using
|
||||
/// the EFI_I2C_MASTER_PROTOCOL.
|
||||
///
|
||||
typedef struct _EFI_I2C_HOST_PROTOCOL EFI_I2C_HOST_PROTOCOL;
|
||||
|
||||
|
||||
/**
|
||||
Queue an I2C transaction 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.
|
||||
|
||||
The I2C host protocol 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 bus frequency differences, the
|
||||
I2C bus configuration management protocol defines an I2C bus
|
||||
configuration for the I2C devices on each side of the switch.
|
||||
When using a multiplexer, the I2C bus configuration management
|
||||
defines an I2C bus configuration for each of the selector values
|
||||
required to control the multiplexer. See Figure 1 in the I2C -bus
|
||||
specification and user manual for a complex I2C bus configuration.
|
||||
|
||||
The I2C host protocol processes all transactions in FIFO order.
|
||||
Prior to performing the transaction, the I2C host protocol calls
|
||||
EnableI2cBusConfiguration to reconfigure the switches and
|
||||
multiplexers in the I2C bus enabling access to the specified I2C
|
||||
device. The EnableI2cBusConfiguration also selects the I2C bus
|
||||
frequency for the I2C device. After the I2C bus is configured,
|
||||
the I2C host protocol calls the I2C master protocol to start the
|
||||
I2C transaction.
|
||||
|
||||
If the I2C host protocol has pending I2C transactions queued when
|
||||
the driver binding Stop() routine is called then the I2C host
|
||||
protocol completes all of the pending I2C transactions by returning
|
||||
EFI_ABORTED status. This notifies the upper layers allowing them
|
||||
to take corrective action or prepare to stop.
|
||||
|
||||
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 asynchronously 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.
|
||||
|
||||
@param[in] This Pointer to an EFI_I2C_HOST_PROTOCOL structure.
|
||||
@param[in] I2cBusConfiguration I2C bus configuration to access the I2C
|
||||
device
|
||||
@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] 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 Invalid I2cBusConfiguration value
|
||||
@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_HOST_PROTOCOL_QUEUE_REQUEST) (
|
||||
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
|
||||
);
|
||||
|
||||
///
|
||||
/// I2C Host Protocol
|
||||
///
|
||||
struct _EFI_I2C_HOST_PROTOCOL {
|
||||
///
|
||||
/// Queue an I2C transaction for execution on the I2C bus
|
||||
///
|
||||
EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST QueueRequest;
|
||||
|
||||
///
|
||||
/// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure
|
||||
/// containing the capabilities of the I2C host controller.
|
||||
///
|
||||
CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities;
|
||||
};
|
||||
|
||||
///
|
||||
/// Reference to variable defined in the .DEC file
|
||||
///
|
||||
extern EFI_GUID gEfiI2cHostProtocolGuid;
|
||||
|
||||
#endif // __I2C_HOST_H__
|
||||
Reference in New Issue
Block a user