9344f09215
https://bugzilla.tianocore.org/show_bug.cgi?id=1373 Replace BSD 2-Clause License with BSD+Patent License. This change is based on the following emails: https://lists.01.org/pipermail/edk2-devel/2019-February/036260.html https://lists.01.org/pipermail/edk2-devel/2018-October/030385.html RFCs with detailed process for the license change: V3: https://lists.01.org/pipermail/edk2-devel/2019-March/038116.html V2: https://lists.01.org/pipermail/edk2-devel/2019-March/037669.html V1: https://lists.01.org/pipermail/edk2-devel/2019-March/037500.html Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com> Reviewed-by: Liming Gao <liming.gao@intel.com>
147 lines
6.3 KiB
C
147 lines
6.3 KiB
C
/** @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 - 2018, Intel Corporation. All rights reserved.<BR>
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
@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.
|
|
|
|
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_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__
|