12e77a4cce03f7dfc6b423d4b70aebaee0445066
[mirror_edk2.git] / MdePkg / Include / Protocol / I2cHost.h
1 /** @file
2 I2C Host Protocol as defined in the PI 1.3 specification.
3
4 This protocol provides callers with the ability to do I/O transactions
5 to all of the devices on the I2C bus.
6
7 Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
8 This program and the accompanying materials
9 are licensed and made available under the terms and conditions of the BSD License
10 which accompanies this distribution. The full text of the license may be found at
11 http://opensource.org/licenses/bsd-license.php
12
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15
16 @par Revision Reference:
17 This protocol is from PI Version 1.3.
18
19 **/
20
21 #ifndef __I2C_HOST_H__
22 #define __I2C_HOST_H__
23
24 #include <Pi/PiI2c.h>
25
26 #define EFI_I2C_HOST_PROTOCOL_GUID { 0xa5aab9e3, 0xc727, 0x48cd, { 0x8b, 0xbf, 0x42, 0x72, 0x33, 0x85, 0x49, 0x48 }}
27
28 ///
29 /// I2C Host Protocol
30 ///
31 /// The I2C bus driver uses the services of the EFI_I2C_HOST_PROTOCOL
32 /// to produce an instance of the EFI_I2C_IO_PROTOCOL for each I2C
33 /// device on an I2C bus.
34 ///
35 /// The EFI_I2C_HOST_PROTOCOL exposes an asynchronous interface to
36 /// callers to perform transactions to any device on the I2C bus.
37 /// Internally, the I2C host protocol manages the flow of the I2C
38 /// transactions to the host controller, keeping them in FIFO order.
39 /// Prior to each transaction, the I2C host protocol ensures that the
40 /// switches and multiplexers are properly configured. The I2C host
41 /// protocol then starts the transaction on the host controller using
42 /// the EFI_I2C_MASTER_PROTOCOL.
43 ///
44 typedef struct _EFI_I2C_HOST_PROTOCOL EFI_I2C_HOST_PROTOCOL;
45
46
47 /**
48 Queue an I2C transaction for execution on the I2C controller.
49
50 This routine must be called at or below TPL_NOTIFY. For
51 synchronous requests this routine must be called at or below
52 TPL_CALLBACK.
53
54 The I2C host protocol uses the concept of I2C bus configurations
55 to describe the I2C bus. An I2C bus configuration is defined as
56 a unique setting of the multiplexers and switches in the I2C bus
57 which enable access to one or more I2C devices. When using a
58 switch to divide a bus, due to bus frequency differences, the
59 I2C bus configuration management protocol defines an I2C bus
60 configuration for the I2C devices on each side of the switch.
61 When using a multiplexer, the I2C bus configuration management
62 defines an I2C bus configuration for each of the selector values
63 required to control the multiplexer. See Figure 1 in the I2C -bus
64 specification and user manual for a complex I2C bus configuration.
65
66 The I2C host protocol processes all transactions in FIFO order.
67 Prior to performing the transaction, the I2C host protocol calls
68 EnableI2cBusConfiguration to reconfigure the switches and
69 multiplexers in the I2C bus enabling access to the specified I2C
70 device. The EnableI2cBusConfiguration also selects the I2C bus
71 frequency for the I2C device. After the I2C bus is configured,
72 the I2C host protocol calls the I2C master protocol to start the
73 I2C transaction.
74
75 If the I2C host protocol has pending I2C transactions queued when
76 the driver binding Stop() routine is called then the I2C host
77 protocol completes all of the pending I2C transactions by returning
78 EFI_ABORTED status. This notifies the upper layers allowing them
79 to take corrective action or prepare to stop.
80
81 When Event is NULL, QueueRequest() operates synchronously and
82 returns the I2C completion status as its return value.
83
84 When Event is not NULL, QueueRequest() synchronously returns
85 EFI_SUCCESS indicating that the asynchronously I2C transaction was
86 queued. The values above are returned in the buffer pointed to by
87 I2cStatus upon the completion of the I2C transaction when I2cStatus
88 is not NULL.
89
90 @param[in] This Pointer to an EFI_I2C_HOST_PROTOCOL structure.
91 @param[in] I2cBusConfiguration I2C bus configuration to access the I2C
92 device
93 @param[in] SlaveAddress Address of the device on the I2C bus. Set
94 the I2C_ADDRESSING_10_BIT when using 10-bit
95 addresses, clear this bit for 7-bit addressing.
96 Bits 0-6 are used for 7-bit I2C slave addresses
97 and bits 0-9 are used for 10-bit I2C slave
98 addresses.
99 @param[in] Event Event to signal for asynchronous transactions,
100 NULL for synchronous transactions
101 @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure
102 describing the I2C transaction
103 @param[out] I2cStatus Optional buffer to receive the I2C transaction
104 completion status
105
106 @retval EFI_SUCCESS The asynchronous transaction was successfully
107 queued when Event is not NULL.
108 @retval EFI_SUCCESS The transaction completed successfully when
109 Event is NULL.
110 @retval EFI_ABORTED The request did not complete because the
111 driver binding Stop() routine was called.
112 @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is
113 too large.
114 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the
115 transaction.
116 @retval EFI_INVALID_PARAMETER RequestPacket is NULL
117 @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter
118 @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value
119 @retval EFI_NO_RESPONSE The I2C device is not responding to the slave
120 address. EFI_DEVICE_ERROR will be returned
121 if the controller cannot distinguish when the
122 NACK occurred.
123 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
124 @retval EFI_UNSUPPORTED The controller does not support the requested
125 transaction.
126
127 **/
128 typedef
129 EFI_STATUS
130 (EFIAPI *EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST) (
131 IN CONST EFI_I2C_HOST_PROTOCOL *This,
132 IN UINTN I2cBusConfiguration,
133 IN UINTN SlaveAddress,
134 IN EFI_EVENT Event OPTIONAL,
135 IN EFI_I2C_REQUEST_PACKET *RequestPacket,
136 OUT EFI_STATUS *I2cStatus OPTIONAL
137 );
138
139 ///
140 /// I2C Host Protocol
141 ///
142 struct _EFI_I2C_HOST_PROTOCOL {
143 ///
144 /// Queue an I2C transaction for execution on the I2C bus
145 ///
146 EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST QueueRequest;
147
148 ///
149 /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure
150 /// containing the capabilities of the I2C host controller.
151 ///
152 CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities;
153 };
154
155 ///
156 /// Reference to variable defined in the .DEC file
157 ///
158 extern EFI_GUID gEfiI2cHostProtocolGuid;
159
160 #endif // __I2C_HOST_H__