Ronak Kanabar | 1ae366f | 2023-06-07 01:21:56 +0530 | [diff] [blame^] | 1 | /** @file |
| 2 | This file declares Smbus2 PPI. |
| 3 | This PPI provides the basic I/O interfaces that a PEIM uses to access its |
| 4 | SMBus controller and the slave devices attached to it. |
| 5 | |
| 6 | Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> |
| 7 | SPDX-License-Identifier: BSD-2-Clause-Patent |
| 8 | |
| 9 | @par Revision Reference: |
| 10 | This PPI is introduced in PI Version 1.0. |
| 11 | |
| 12 | **/ |
| 13 | |
| 14 | #ifndef __PEI_SMBUS2_PPI_H__ |
| 15 | #define __PEI_SMBUS2_PPI_H__ |
| 16 | |
| 17 | #include <IndustryStandard/SmBus.h> |
| 18 | |
| 19 | #define EFI_PEI_SMBUS2_PPI_GUID \ |
| 20 | { 0x9ca93627, 0xb65b, 0x4324, { 0xa2, 0x2, 0xc0, 0xb4, 0x61, 0x76, 0x45, 0x43 } } |
| 21 | |
| 22 | typedef struct _EFI_PEI_SMBUS2_PPI EFI_PEI_SMBUS2_PPI; |
| 23 | |
| 24 | /** |
| 25 | Executes an SMBus operation to an SMBus controller. Returns when either |
| 26 | the command has been executed or an error is encountered in doing the operation. |
| 27 | |
| 28 | @param This A pointer to the EFI_PEI_SMBUS2_PPI instance. |
| 29 | @param SlaveAddress The SMBUS hardware address to which the SMBUS device is preassigned or |
| 30 | allocated. |
| 31 | @param Command This command is transmitted by the SMBus host controller to the SMBus slave |
| 32 | device and the interpretation is SMBus slave device specific. |
| 33 | It can mean the offset to a list of functions inside |
| 34 | an SMBus slave device. Not all operations or slave devices support |
| 35 | this command's registers. |
| 36 | @param Operation Signifies which particular SMBus hardware protocol instance that it |
| 37 | will use to execute the SMBus transactions. |
| 38 | This SMBus hardware protocol is defined by the System Management Bus (SMBus) |
| 39 | Specification and is not related to UEFI. |
| 40 | @param PecCheck Defines if Packet Error Code (PEC) checking is required for this operation. |
| 41 | @param Length Signifies the number of bytes that this operation will do. |
| 42 | The maximum number of bytes can be revision specific and operation specific. |
| 43 | This parameter will contain the actual number of bytes that are executed |
| 44 | for this operation. Not all operations require this argument. |
| 45 | @param Buffer Contains the value of data to execute to the SMBus slave device. |
| 46 | Not all operations require this argument. |
| 47 | The length of this buffer is identified by Length. |
| 48 | |
| 49 | |
| 50 | @retval EFI_SUCCESS The last data that was returned from the access |
| 51 | matched the poll exit criteria. |
| 52 | @retval EFI_CRC_ERROR The checksum is not correct (PEC is incorrect) |
| 53 | @retval EFI_TIMEOUT Timeout expired before the operation was completed. |
| 54 | Timeout is determined by the SMBus host controller device. |
| 55 | @retval EFI_OUT_OF_RESOURCES The request could not be completed |
| 56 | due to a lack of resources. |
| 57 | @retval EFI_DEVICE_ERROR The request was not completed because |
| 58 | a failure reflected in the Host Status Register bit. |
| 59 | @retval EFI_INVALID_PARAMETER Operation is not defined in EFI_SMBUS_OPERATION. |
| 60 | Or Length/Buffer is NULL for operations except for EfiSmbusQuickRead and |
| 61 | EfiSmbusQuickWrite. Or Length is outside the range of valid values. |
| 62 | @retval EFI_UNSUPPORTED The SMBus operation or PEC is not supported. |
| 63 | @retval EFI_BUFFER_TOO_SMALL Buffer is not sufficient for this operation. |
| 64 | |
| 65 | **/ |
| 66 | typedef |
| 67 | EFI_STATUS |
| 68 | (EFIAPI *EFI_PEI_SMBUS2_PPI_EXECUTE_OPERATION)( |
| 69 | IN CONST EFI_PEI_SMBUS2_PPI *This, |
| 70 | IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress, |
| 71 | IN EFI_SMBUS_DEVICE_COMMAND Command, |
| 72 | IN EFI_SMBUS_OPERATION Operation, |
| 73 | IN BOOLEAN PecCheck, |
| 74 | IN OUT UINTN *Length, |
| 75 | IN OUT VOID *Buffer |
| 76 | ); |
| 77 | |
| 78 | /** |
| 79 | The ArpDevice() function enumerates the entire bus or enumerates a specific |
| 80 | device that is identified by SmbusUdid. |
| 81 | |
| 82 | @param This A pointer to the EFI_PEI_SMBUS2_PPI instance. |
| 83 | @param ArpAll A Boolean expression that indicates if the host drivers need |
| 84 | to enumerate all the devices or enumerate only the device that is identified |
| 85 | by SmbusUdid. If ArpAll is TRUE, SmbusUdid and SlaveAddress are optional. |
| 86 | If ArpAll is FALSE, ArpDevice will enumerate SmbusUdid and the address |
| 87 | will be at SlaveAddress. |
| 88 | @param SmbusUdid The targeted SMBus Unique Device Identifier (UDID). |
| 89 | The UDID may not exist for SMBus devices with fixed addresses. |
| 90 | @param SlaveAddress The new SMBus address for the slave device for |
| 91 | which the operation is targeted. |
| 92 | |
| 93 | @retval EFI_SUCCESS The SMBus slave device address was set. |
| 94 | @retval EFI_INVALID_PARAMETER SlaveAddress is NULL. |
| 95 | @retval EFI_OUT_OF_RESOURCES The request could not be completed |
| 96 | due to a lack of resources. |
| 97 | @retval EFI_TIMEOUT The SMBus slave device did not respond. |
| 98 | @retval EFI_DEVICE_ERROR The request was not completed because the transaction failed. |
| 99 | @retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are not implemented by this PEIM. |
| 100 | |
| 101 | **/ |
| 102 | typedef |
| 103 | EFI_STATUS |
| 104 | (EFIAPI *EFI_PEI_SMBUS2_PPI_ARP_DEVICE)( |
| 105 | IN CONST EFI_PEI_SMBUS2_PPI *This, |
| 106 | IN BOOLEAN ArpAll, |
| 107 | IN EFI_SMBUS_UDID *SmbusUdid OPTIONAL, |
| 108 | IN OUT EFI_SMBUS_DEVICE_ADDRESS *SlaveAddress OPTIONAL |
| 109 | ); |
| 110 | |
| 111 | /** |
| 112 | The GetArpMap() function returns the mapping of all the SMBus devices |
| 113 | that are enumerated by the SMBus host driver. |
| 114 | |
| 115 | @param This A pointer to the EFI_PEI_SMBUS2_PPI instance. |
| 116 | @param Length Size of the buffer that contains the SMBus device map. |
| 117 | @param SmbusDeviceMap The pointer to the device map as enumerated |
| 118 | by the SMBus controller driver. |
| 119 | |
| 120 | @retval EFI_SUCCESS The device map was returned correctly in the buffer. |
| 121 | @retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are not implemented by this PEIM. |
| 122 | |
| 123 | **/ |
| 124 | typedef |
| 125 | EFI_STATUS |
| 126 | (EFIAPI *EFI_PEI_SMBUS2_PPI_GET_ARP_MAP)( |
| 127 | IN CONST EFI_PEI_SMBUS2_PPI *This, |
| 128 | IN OUT UINTN *Length, |
| 129 | IN OUT EFI_SMBUS_DEVICE_MAP **SmbusDeviceMap |
| 130 | ); |
| 131 | |
| 132 | /** |
| 133 | CallBack function can be registered in EFI_PEI_SMBUS2_PPI_NOTIFY. |
| 134 | |
| 135 | @param This A pointer to the EFI_PEI_SMBUS2_PPI instance. |
| 136 | @param SlaveAddress The SMBUS hardware address to which the SMBUS |
| 137 | device is preassigned or allocated. |
| 138 | @param Data Data of the SMBus host notify command that |
| 139 | the caller wants to be called. |
| 140 | |
| 141 | @retval EFI_SUCCESS NotifyFunction has been registered. |
| 142 | @retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are not |
| 143 | implemented by this PEIM. |
| 144 | |
| 145 | **/ |
| 146 | typedef |
| 147 | EFI_STATUS |
| 148 | (EFIAPI *EFI_PEI_SMBUS_NOTIFY2_FUNCTION)( |
| 149 | IN CONST EFI_PEI_SMBUS2_PPI *SmbusPpi, |
| 150 | IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress, |
| 151 | IN UINTN Data |
| 152 | ); |
| 153 | |
| 154 | /** |
| 155 | The Notify() function registers all the callback functions to allow the |
| 156 | bus driver to call these functions when the SlaveAddress/Data pair happens. |
| 157 | |
| 158 | @param This A pointer to the EFI_PEI_SMBUS2_PPI instance. |
| 159 | @param SlaveAddress Address that the host controller detects as |
| 160 | sending a message and calls all the registered functions. |
| 161 | @param Data Data that the host controller detects as sending a message |
| 162 | and calls all the registered functions. |
| 163 | @param NotifyFunction The function to call when the bus driver |
| 164 | detects the SlaveAddress and Data pair. |
| 165 | |
| 166 | @retval EFI_SUCCESS NotifyFunction has been registered. |
| 167 | @retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are not |
| 168 | implemented by this PEIM. |
| 169 | **/ |
| 170 | typedef |
| 171 | EFI_STATUS |
| 172 | (EFIAPI *EFI_PEI_SMBUS2_PPI_NOTIFY)( |
| 173 | IN CONST EFI_PEI_SMBUS2_PPI *This, |
| 174 | IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress, |
| 175 | IN UINTN Data, |
| 176 | IN EFI_PEI_SMBUS_NOTIFY2_FUNCTION NotifyFunction |
| 177 | ); |
| 178 | |
| 179 | /// |
| 180 | /// Provides the basic I/O interfaces that a PEIM uses to access |
| 181 | /// its SMBus controller and the slave devices attached to it. |
| 182 | /// |
| 183 | struct _EFI_PEI_SMBUS2_PPI { |
| 184 | EFI_PEI_SMBUS2_PPI_EXECUTE_OPERATION Execute; |
| 185 | EFI_PEI_SMBUS2_PPI_ARP_DEVICE ArpDevice; |
| 186 | EFI_PEI_SMBUS2_PPI_GET_ARP_MAP GetArpMap; |
| 187 | EFI_PEI_SMBUS2_PPI_NOTIFY Notify; |
| 188 | /// |
| 189 | /// Identifier which uniquely identifies this SMBus controller in a system. |
| 190 | /// |
| 191 | EFI_GUID Identifier; |
| 192 | }; |
| 193 | |
| 194 | extern EFI_GUID gEfiPeiSmbus2PpiGuid; |
| 195 | |
| 196 | #endif |