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