Subrata Banik | 20fe24b | 2021-12-09 02:46:38 +0530 | [diff] [blame] | 1 | /** @file |
| 2 | The file provides basic SMBus host controller management |
| 3 | and basic data transactions over the SMBus. |
| 4 | |
| 5 | Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> |
| 6 | SPDX-License-Identifier: BSD-2-Clause-Patent |
| 7 | |
| 8 | @par Revision Reference: PI |
| 9 | Version 1.00. |
| 10 | |
| 11 | **/ |
| 12 | |
| 13 | #ifndef __SMBUS_HC_H__ |
| 14 | #define __SMBUS_HC_H__ |
| 15 | |
| 16 | #include <IndustryStandard/SmBus.h> |
| 17 | |
| 18 | #define EFI_SMBUS_HC_PROTOCOL_GUID \ |
| 19 | {0xe49d33ed, 0x513d, 0x4634, { 0xb6, 0x98, 0x6f, 0x55, 0xaa, 0x75, 0x1c, 0x1b} } |
| 20 | |
| 21 | typedef struct _EFI_SMBUS_HC_PROTOCOL EFI_SMBUS_HC_PROTOCOL; |
| 22 | |
| 23 | /** |
| 24 | |
| 25 | The Execute() function provides a standard way to execute an |
| 26 | operation as defined in the System Management Bus (SMBus) |
| 27 | Specification. The resulting transaction will be either that |
| 28 | the SMBus slave devices accept this transaction or that this |
| 29 | function returns with error. |
| 30 | |
| 31 | @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. |
| 32 | SlaveAddress The SMBus slave address of the device |
| 33 | with which to communicate. Type |
| 34 | EFI_SMBUS_DEVICE_ADDRESS is defined in |
| 35 | EFI_PEI_SMBUS_PPI.Execute() in the Platform |
| 36 | Initialization SMBus PPI Specification. |
| 37 | |
| 38 | @param Command This command is transmitted by the SMBus host |
| 39 | controller to the SMBus slave device and the |
| 40 | interpretation is SMBus slave device specific. |
| 41 | It can mean the offset to a list of functions |
| 42 | inside an SMBus slave device. Not all |
| 43 | operations or slave devices support this |
| 44 | command's registers. Type |
| 45 | EFI_SMBUS_DEVICE_COMMAND is defined in |
| 46 | EFI_PEI_SMBUS_PPI.Execute() in the Platform |
| 47 | Initialization SMBus PPI Specification. |
| 48 | |
| 49 | @param Operation Signifies the particular SMBus |
| 50 | hardware protocol instance it will use to |
| 51 | execute the SMBus transactions. This SMBus |
| 52 | hardware protocol is defined by the SMBus |
| 53 | Specification and is not related to PI |
| 54 | Architecture. Type EFI_SMBUS_OPERATION is |
| 55 | defined in EFI_PEI_SMBUS_PPI.Execute() in the |
| 56 | Platform Initialization SMBus PPI |
| 57 | Specification. |
| 58 | |
| 59 | @param PecCheck Defines if Packet Error Code (PEC) checking |
| 60 | is required for this operation. SMBus Host |
| 61 | Controller Code Definitions Version 1.0 |
| 62 | August 21, 2006 13 |
| 63 | |
| 64 | @param Length Signifies the number of bytes that this operation will do. |
| 65 | The maximum number of bytes can be revision |
| 66 | specific and operation specific. This field |
| 67 | will contain the actual number of bytes that |
| 68 | are executed for this operation. Not all |
| 69 | operations require this argument. |
| 70 | |
| 71 | @param Buffer Contains the value of data to execute to the |
| 72 | SMBus slave device. Not all operations require |
| 73 | this argument. The length of this buffer is |
| 74 | identified by Length. |
| 75 | |
| 76 | |
| 77 | @retval EFI_SUCCESS The last data that was returned from the |
| 78 | access matched the poll exit criteria. |
| 79 | |
| 80 | @retval EFI_CRC_ERROR Checksum is not correct (PEC is incorrect). |
| 81 | |
| 82 | @retval EFI_TIMEOUT Timeout expired before the operation was |
| 83 | completed. Timeout is determined by the |
| 84 | SMBus host controller device. |
| 85 | |
| 86 | @retval EFI_OUT_OF_RESOURCES The request could not be |
| 87 | completed due to a lack of |
| 88 | resources. |
| 89 | |
| 90 | @retval EFI_DEVICE_ERROR The request was not completed |
| 91 | because a failure that was reflected |
| 92 | in the Host Status Register bit. |
| 93 | Device errors are a result of a |
| 94 | transaction collision, illegal |
| 95 | command field, unclaimed cycle (host |
| 96 | initiated), or bus errors |
| 97 | (collisions). |
| 98 | |
| 99 | @retval EFI_INVALID_PARAMETER Operation is not defined in |
| 100 | EFI_SMBUS_OPERATION. |
| 101 | |
| 102 | @retval EFI_INVALID_PARAMETER Length/Buffer is NULL for |
| 103 | operations except for |
| 104 | EfiSmbusQuickRead and |
| 105 | EfiSmbusQuickWrite. Length is |
| 106 | outside the range of valid |
| 107 | values. |
| 108 | |
| 109 | @retval EFI_UNSUPPORTED The SMBus operation or PEC is not |
| 110 | supported. |
| 111 | |
| 112 | @retval EFI_BUFFER_TOO_SMALL Buffer is not sufficient for |
| 113 | this operation. |
| 114 | |
| 115 | **/ |
| 116 | typedef |
| 117 | EFI_STATUS |
| 118 | (EFIAPI *EFI_SMBUS_HC_EXECUTE_OPERATION)( |
| 119 | IN CONST EFI_SMBUS_HC_PROTOCOL *This, |
| 120 | IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress, |
| 121 | IN EFI_SMBUS_DEVICE_COMMAND Command, |
| 122 | IN EFI_SMBUS_OPERATION Operation, |
| 123 | IN BOOLEAN PecCheck, |
| 124 | IN OUT UINTN *Length, |
| 125 | IN OUT VOID *Buffer |
| 126 | ); |
| 127 | |
| 128 | |
| 129 | |
| 130 | /** |
| 131 | |
| 132 | The ArpDevice() function provides a standard way for a device driver to |
| 133 | enumerate the entire SMBus or specific devices on the bus. |
| 134 | |
| 135 | @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. |
| 136 | |
| 137 | @param ArpAll A Boolean expression that indicates if the |
| 138 | host drivers need to enumerate all the devices |
| 139 | or enumerate only the device that is |
| 140 | identified by SmbusUdid. If ArpAll is TRUE, |
| 141 | SmbusUdid and SlaveAddress are optional. If |
| 142 | ArpAll is FALSE, ArpDevice will enumerate |
| 143 | SmbusUdid and the address will be at |
| 144 | SlaveAddress. |
| 145 | |
| 146 | @param SmbusUdid The Unique Device Identifier (UDID) that is |
| 147 | associated with this device. Type |
| 148 | EFI_SMBUS_UDID is defined in |
| 149 | EFI_PEI_SMBUS_PPI.ArpDevice() in the |
| 150 | Platform Initialization SMBus PPI |
| 151 | Specification. |
| 152 | |
| 153 | @param SlaveAddress The SMBus slave address that is |
| 154 | associated with an SMBus UDID. |
| 155 | |
| 156 | @retval EFI_SUCCESS The last data that was returned from the |
| 157 | access matched the poll exit criteria. |
| 158 | |
| 159 | @retval EFI_CRC_ERROR Checksum is not correct (PEC is |
| 160 | incorrect). |
| 161 | |
| 162 | @retval EFI_TIMEOUT Timeout expired before the operation was |
| 163 | completed. Timeout is determined by the |
| 164 | SMBus host controller device. |
| 165 | |
| 166 | @retval EFI_OUT_OF_RESOURCES The request could not be |
| 167 | completed due to a lack of |
| 168 | resources. |
| 169 | |
| 170 | @retval EFI_DEVICE_ERROR The request was not completed |
| 171 | because a failure was reflected in |
| 172 | the Host Status Register bit. Device |
| 173 | Errors are a result of a transaction |
| 174 | collision, illegal command field, |
| 175 | unclaimed cycle (host initiated), or |
| 176 | bus errors (collisions). |
| 177 | |
| 178 | @retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are |
| 179 | not implemented by this driver. |
| 180 | |
| 181 | **/ |
| 182 | typedef |
| 183 | EFI_STATUS |
| 184 | (EFIAPI *EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE)( |
| 185 | IN CONST EFI_SMBUS_HC_PROTOCOL *This, |
| 186 | IN BOOLEAN ArpAll, |
| 187 | IN EFI_SMBUS_UDID *SmbusUdid, OPTIONAL |
| 188 | IN OUT EFI_SMBUS_DEVICE_ADDRESS *SlaveAddress OPTIONAL |
| 189 | ); |
| 190 | |
| 191 | |
| 192 | /** |
| 193 | The GetArpMap() function returns the mapping of all the SMBus devices |
| 194 | that were enumerated by the SMBus host driver. |
| 195 | |
| 196 | @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. |
| 197 | |
| 198 | @param Length Size of the buffer that contains the SMBus |
| 199 | device map. |
| 200 | |
| 201 | @param SmbusDeviceMap The pointer to the device map as |
| 202 | enumerated by the SMBus controller |
| 203 | driver. |
| 204 | |
| 205 | @retval EFI_SUCCESS The SMBus returned the current device map. |
| 206 | |
| 207 | @retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are |
| 208 | not implemented by this driver. |
| 209 | |
| 210 | **/ |
| 211 | typedef |
| 212 | EFI_STATUS |
| 213 | (EFIAPI *EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP)( |
| 214 | IN CONST EFI_SMBUS_HC_PROTOCOL *This, |
| 215 | IN OUT UINTN *Length, |
| 216 | IN OUT EFI_SMBUS_DEVICE_MAP **SmbusDeviceMap |
| 217 | ); |
| 218 | |
| 219 | /** |
| 220 | The notify function does some actions. |
| 221 | |
| 222 | @param SlaveAddress |
| 223 | The SMBUS hardware address to which the SMBUS device is preassigned or allocated. |
| 224 | |
| 225 | @param Data |
| 226 | Data of the SMBus host notify command that the caller wants to be called. |
| 227 | |
| 228 | @return EFI_STATUS |
| 229 | **/ |
| 230 | typedef |
| 231 | EFI_STATUS |
| 232 | (EFIAPI *EFI_SMBUS_NOTIFY_FUNCTION)( |
| 233 | IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress, |
| 234 | IN UINTN Data |
| 235 | ); |
| 236 | |
| 237 | |
| 238 | /** |
| 239 | |
| 240 | The Notify() function registers all the callback functions to |
| 241 | allow the bus driver to call these functions when the |
| 242 | SlaveAddress/Data pair happens. |
| 243 | |
| 244 | @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. |
| 245 | |
| 246 | @param SlaveAddress Address that the host controller detects |
| 247 | as sending a message and calls all the registered function. |
| 248 | |
| 249 | @param Data Data that the host controller detects as sending |
| 250 | message and calls all the registered function. |
| 251 | |
| 252 | |
| 253 | @param NotifyFunction The function to call when the bus |
| 254 | driver detects the SlaveAddress and |
| 255 | Data pair. |
| 256 | |
| 257 | @retval EFI_SUCCESS NotifyFunction was registered. |
| 258 | |
| 259 | @retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are |
| 260 | not implemented by this driver. |
| 261 | |
| 262 | **/ |
| 263 | typedef |
| 264 | EFI_STATUS |
| 265 | (EFIAPI *EFI_SMBUS_HC_PROTOCOL_NOTIFY)( |
| 266 | IN CONST EFI_SMBUS_HC_PROTOCOL *This, |
| 267 | IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress, |
| 268 | IN UINTN Data, |
| 269 | IN EFI_SMBUS_NOTIFY_FUNCTION NotifyFunction |
| 270 | ); |
| 271 | |
| 272 | |
| 273 | /// |
| 274 | /// The EFI_SMBUS_HC_PROTOCOL provides SMBus host controller management and basic data |
| 275 | /// transactions over SMBus. There is one EFI_SMBUS_HC_PROTOCOL instance for each SMBus |
| 276 | /// host controller. |
| 277 | /// |
| 278 | struct _EFI_SMBUS_HC_PROTOCOL { |
| 279 | EFI_SMBUS_HC_EXECUTE_OPERATION Execute; |
| 280 | EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE ArpDevice; |
| 281 | EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP GetArpMap; |
| 282 | EFI_SMBUS_HC_PROTOCOL_NOTIFY Notify; |
| 283 | }; |
| 284 | |
| 285 | |
| 286 | extern EFI_GUID gEfiSmbusHcProtocolGuid; |
| 287 | |
| 288 | #endif |
| 289 | |