1 /** @file 2 Header file for the defintions used in SMBus DXE driver. 3 4 Copyright (c) 2013-2015 Intel Corporation. 5 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 **/ 15 16 17 #ifndef _DXE_QNC_SMBUS_H_ 18 #define _DXE_QNC_SMBUS_H_ 19 #include "CommonHeader.h" 20 21 #include "QNCSmbus.h" 22 23 #define MAX_SMBUS_DEVICES 107 // Max number of SMBus devices (7 bit 24 // address yields 128 combinations but 21 25 // of those are reserved) 26 27 #define MICROSECOND 10 28 #define MILLISECOND (1000 * MICROSECOND) 29 #define ONESECOND (1000 * MILLISECOND) 30 31 #define STALL_TIME 1000000 // 1,000,000 microseconds = 1 second 32 #define BUS_TRIES 3 // How many times to retry on Bus Errors 33 #define SMBUS_NUM_RESERVED 21 // Number of device addresses that are 34 // reserved by the SMBus spec. 35 #define SMBUS_ADDRESS_ARP 0xC2 >> 1 36 #define SMBUS_DATA_PREPARE_TO_ARP 0x01 37 #define SMBUS_DATA_RESET_DEVICE 0x02 38 #define SMBUS_DATA_GET_UDID_GENERAL 0x03 39 #define SMBUS_DATA_ASSIGN_ADDRESS 0x04 40 #define SMBUS_GET_UDID_LENGTH 17 // 16 byte UDID + 1 byte address 41 42 /** 43 Executes an SMBus operation to an SMBus controller. Returns when either the command has been 44 executed or an error is encountered in doing the operation. 45 46 The Execute() function provides a standard way to execute an operation as defined in the System 47 Management Bus (SMBus) Specification. The resulting transaction will be either that the SMBus 48 slave devices accept this transaction or that this function returns with error. 49 50 @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. 51 @param SlaveAddress The SMBus slave address of the device with which to communicate. 52 @param Command This command is transmitted by the SMBus host controller to the 53 SMBus slave device and the interpretation is SMBus slave device 54 specific. It can mean the offset to a list of functions inside an 55 SMBus slave device. Not all operations or slave devices support 56 this command's registers. 57 @param Operation Signifies which particular SMBus hardware protocol instance that 58 it will use to execute the SMBus transactions. This SMBus 59 hardware protocol is defined by the SMBus Specification and is 60 not related to EFI. 61 @param PecCheck Defines if Packet Error Code (PEC) checking is required for this 62 operation. 63 @param Length Signifies the number of bytes that this operation will do. The 64 maximum number of bytes can be revision specific and operation 65 specific. This field will contain the actual number of bytes that 66 are executed for this operation. Not all operations require this 67 argument. 68 @param Buffer Contains the value of data to execute to the SMBus slave device. 69 Not all operations require this argument. The length of this 70 buffer is identified by Length. 71 72 @retval EFI_SUCCESS The last data that was returned from the access matched the poll 73 exit criteria. 74 @retval EFI_CRC_ERROR Checksum is not correct (PEC is incorrect). 75 @retval EFI_TIMEOUT Timeout expired before the operation was completed. Timeout is 76 determined by the SMBus host controller device. 77 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 78 @retval EFI_DEVICE_ERROR The request was not completed because a failure that was 79 reflected in the Host Status Register bit. Device errors are a 80 result of a transaction collision, illegal command field, 81 unclaimed cycle (host initiated), or bus errors (collisions). 82 @retval EFI_INVALID_PARAMETER Operation is not defined in EFI_SMBUS_OPERATION. 83 @retval EFI_INVALID_PARAMETER Length/Buffer is NULL for operations except for EfiSmbusQuickRead 84 and EfiSmbusQuickWrite. Length is outside the range of valid 85 values. 86 @retval EFI_UNSUPPORTED The SMBus operation or PEC is not supported. 87 @retval EFI_BUFFER_TOO_SMALL Buffer is not sufficient for this operation. 88 89 **/ 90 EFI_STATUS 91 EFIAPI 92 SmbusExecute ( 93 IN CONST EFI_SMBUS_HC_PROTOCOL *This, 94 IN CONST EFI_SMBUS_DEVICE_ADDRESS SlaveAddress, 95 IN CONST EFI_SMBUS_DEVICE_COMMAND Command, 96 IN CONST EFI_SMBUS_OPERATION Operation, 97 IN CONST BOOLEAN PecCheck, 98 IN OUT UINTN *Length, 99 IN OUT VOID *Buffer 100 ); 101 102 /** 103 Sets the SMBus slave device addresses for the device with a given unique ID or enumerates the 104 entire bus. 105 106 The ArpDevice() function provides a standard way for a device driver to enumerate the entire 107 SMBus or specific devices on the bus. 108 109 @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. 110 @param ArpAll A Boolean expression that indicates if the host drivers need to 111 enumerate all the devices or enumerate only the device that is 112 identified by SmbusUdid. If ArpAll is TRUE, SmbusUdid and 113 SlaveAddress are optional. If ArpAll is FALSE, ArpDevice will 114 enumerate SmbusUdid and the address will be at SlaveAddress. 115 @param SmbusUdid The Unique Device Identifier (UDID) that is associated with this 116 device. 117 @param SlaveAddress The SMBus slave address that is associated with an SMBus UDID. 118 119 @retval EFI_SUCCESS The last data that was returned from the access matched the poll 120 exit criteria. 121 @retval EFI_CRC_ERROR Checksum is not correct (PEC is incorrect). 122 @retval EFI_TIMEOUT Timeout expired before the operation was completed. Timeout is 123 determined by the SMBus host controller device. 124 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 125 @retval EFI_DEVICE_ERROR The request was not completed because a failure that was 126 reflected in the Host Status Register bit. Device errors are a 127 result of a transaction collision, illegal command field, 128 unclaimed cycle (host initiated), or bus errors (collisions). 129 @retval EFI_UNSUPPORTED The corresponding operation is not supported. 130 131 **/ 132 EFI_STATUS 133 EFIAPI 134 SmbusArpDevice ( 135 IN CONST EFI_SMBUS_HC_PROTOCOL *This, 136 IN BOOLEAN ArpAll, 137 IN EFI_SMBUS_UDID *SmbusUdid, OPTIONAL 138 IN OUT EFI_SMBUS_DEVICE_ADDRESS *SlaveAddress OPTIONAL 139 ); 140 141 /** 142 Returns a pointer to the Address Resolution Protocol (ARP) map that contains the ID/address pair 143 of the slave devices that were enumerated by the SMBus host controller driver. 144 145 The GetArpMap() function returns the mapping of all the SMBus devices that were enumerated by the 146 SMBus host driver. 147 148 @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. 149 @param Length Size of the buffer that contains the SMBus device map. 150 @param SmbusDeviceMap The pointer to the device map as enumerated by the SMBus 151 controller driver. 152 153 @retval EFI_SUCCESS The SMBus returned the current device map. 154 @retval EFI_UNSUPPORTED The corresponding operation is not supported. 155 156 **/ 157 EFI_STATUS 158 EFIAPI 159 SmbusGetArpMap ( 160 IN CONST EFI_SMBUS_HC_PROTOCOL *This, 161 IN OUT UINTN *Length, 162 IN OUT EFI_SMBUS_DEVICE_MAP **SmbusDeviceMap 163 ); 164 165 /** 166 Allows a device driver to register for a callback when the bus driver detects a state that it 167 needs to propagate to other drivers that are registered for a callback. 168 169 The Notify() function registers all the callback functions to allow the bus driver to call these 170 functions when the SlaveAddress/Data pair happens. 171 If NotifyFunction is NULL, then ASSERT (). 172 173 @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. 174 @param SlaveAddress The SMBUS hardware address to which the SMBUS device is 175 preassigned or allocated. 176 @param Data Data of the SMBus host notify command that the caller wants to be 177 called. 178 @param NotifyFunction The function to call when the bus driver detects the SlaveAddress 179 and Data pair. 180 181 @retval EFI_SUCCESS NotifyFunction was registered. 182 @retval EFI_UNSUPPORTED The corresponding operation is not supported. 183 184 **/ 185 EFI_STATUS 186 EFIAPI 187 SmbusNotify ( 188 IN CONST EFI_SMBUS_HC_PROTOCOL *This, 189 IN CONST EFI_SMBUS_DEVICE_ADDRESS SlaveAddress, 190 IN CONST UINTN Data, 191 IN CONST EFI_SMBUS_NOTIFY_FUNCTION NotifyFunction 192 ); 193 194 /** 195 Entry point to the DXE Driver that produces the SMBus Host Controller Protocol. 196 197 @param ImageHandle ImageHandle of the loaded driver. 198 @param SystemTable Pointer to the EFI System Table. 199 200 @retval EFI_SUCCESS The entry point of SMBus DXE driver is executed successfully. 201 @retval !EFI_SUCESS Some error occurs in the entry point of SMBus DXE driver. 202 203 **/ 204 EFI_STATUS 205 EFIAPI 206 InitializeQNCSmbus ( 207 IN EFI_HANDLE ImageHandle, 208 IN EFI_SYSTEM_TABLE *SystemTable 209 ); 210 211 #endif 212