1 /** @file 2 3 EDKII Universal Flash Storage Host Controller Protocol. 4 5 Copyright (c) 2014 - 2015, Intel Corporation. All rights reserved.<BR> 6 This program and the accompanying materials are licensed and made available under 7 the terms and conditions of the BSD License that accompanies this distribution. 8 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 __EDKII_UFS_HC_PROTOCOL_H__ 18 #define __EDKII_UFS_HC_PROTOCOL_H__ 19 20 // 21 // UFS Host Controller Protocol GUID value 22 // 23 #define EDKII_UFS_HOST_CONTROLLER_PROTOCOL_GUID \ 24 { \ 25 0xebc01af5, 0x7a9, 0x489e, { 0xb7, 0xce, 0xdc, 0x8, 0x9e, 0x45, 0x9b, 0x2f } \ 26 } 27 28 // 29 // Forward reference for pure ANSI compatability 30 // 31 typedef struct _EDKII_UFS_HOST_CONTROLLER_PROTOCOL EDKII_UFS_HOST_CONTROLLER_PROTOCOL; 32 33 34 /** 35 Get the MMIO base address of UFS host controller. 36 37 @param This The protocol instance pointer. 38 @param MmioBar Pointer to the UFS host controller MMIO base address. 39 40 @retval EFI_SUCCESS The operation succeeds. 41 @retval EFI_INVALID_PARAMETER The parameters are invalid. 42 43 **/ 44 typedef 45 EFI_STATUS 46 (EFIAPI *EDKII_UFS_HC_GET_MMIO_BAR)( 47 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 48 OUT UINTN *MmioBar 49 ); 50 51 /// 52 /// ******************************************************* 53 /// EFI_UFS_HOST_CONTROLLER_OPERATION 54 /// ******************************************************* 55 /// 56 typedef enum { 57 /// 58 /// A read operation from system memory by a bus master. 59 /// 60 EdkiiUfsHcOperationBusMasterRead, 61 /// 62 /// A write operation from system memory by a bus master. 63 /// 64 EdkiiUfsHcOperationBusMasterWrite, 65 /// 66 /// Provides both read and write access to system memory by both the processor and a 67 /// bus master. The buffer is coherent from both the processor's and the bus master's point of view. 68 /// 69 EdkiiUfsHcOperationBusMasterCommonBuffer, 70 EdkiiUfsHcOperationMaximum 71 } EDKII_UFS_HOST_CONTROLLER_OPERATION; 72 73 /** 74 Provides the UFS controller-specific addresses needed to access system memory. 75 76 @param This A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance. 77 @param Operation Indicates if the bus master is going to read or write to system memory. 78 @param HostAddress The system memory address to map to the UFS controller. 79 @param NumberOfBytes On input the number of bytes to map. On output the number of bytes 80 that were mapped. 81 @param DeviceAddress The resulting map address for the bus master UFS controller to use to 82 access the hosts HostAddress. 83 @param Mapping A resulting value to pass to Unmap(). 84 85 @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes. 86 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer. 87 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 88 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 89 @retval EFI_DEVICE_ERROR The system hardware could not map the requested address. 90 91 **/ 92 typedef 93 EFI_STATUS 94 (EFIAPI *EDKII_UFS_HC_MAP)( 95 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 96 IN EDKII_UFS_HOST_CONTROLLER_OPERATION Operation, 97 IN VOID *HostAddress, 98 IN OUT UINTN *NumberOfBytes, 99 OUT EFI_PHYSICAL_ADDRESS *DeviceAddress, 100 OUT VOID **Mapping 101 ); 102 103 /** 104 Completes the Map() operation and releases any corresponding resources. 105 106 @param This A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance. 107 @param Mapping The mapping value returned from Map(). 108 109 @retval EFI_SUCCESS The range was unmapped. 110 @retval EFI_DEVICE_ERROR The data was not committed to the target system memory. 111 112 **/ 113 typedef 114 EFI_STATUS 115 (EFIAPI *EDKII_UFS_HC_UNMAP)( 116 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 117 IN VOID *Mapping 118 ); 119 120 /** 121 Allocates pages that are suitable for an EfiUfsHcOperationBusMasterCommonBuffer 122 mapping. 123 124 @param This A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance. 125 @param Type This parameter is not used and must be ignored. 126 @param MemoryType The type of memory to allocate, EfiBootServicesData or 127 EfiRuntimeServicesData. 128 @param Pages The number of pages to allocate. 129 @param HostAddress A pointer to store the base system memory address of the 130 allocated range. 131 @param Attributes The requested bit mask of attributes for the allocated range. 132 133 @retval EFI_SUCCESS The requested memory pages were allocated. 134 @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are 135 MEMORY_WRITE_COMBINE and MEMORY_CACHED. 136 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 137 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated. 138 139 **/ 140 typedef 141 EFI_STATUS 142 (EFIAPI *EDKII_UFS_HC_ALLOCATE_BUFFER)( 143 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 144 IN EFI_ALLOCATE_TYPE Type, 145 IN EFI_MEMORY_TYPE MemoryType, 146 IN UINTN Pages, 147 OUT VOID **HostAddress, 148 IN UINT64 Attributes 149 ); 150 151 /** 152 Frees memory that was allocated with AllocateBuffer(). 153 154 @param This A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance. 155 @param Pages The number of pages to free. 156 @param HostAddress The base system memory address of the allocated range. 157 158 @retval EFI_SUCCESS The requested memory pages were freed. 159 @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages 160 was not allocated with AllocateBuffer(). 161 162 **/ 163 typedef 164 EFI_STATUS 165 (EFIAPI *EDKII_UFS_HC_FREE_BUFFER)( 166 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 167 IN UINTN Pages, 168 IN VOID *HostAddress 169 ); 170 171 /** 172 Flushes all posted write transactions from the UFS bus to attached UFS device. 173 174 @param This A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance. 175 176 @retval EFI_SUCCESS The posted write transactions were flushed from the UFS bus 177 to attached UFS device. 178 @retval EFI_DEVICE_ERROR The posted write transactions were not flushed from the UFS 179 bus to attached UFS device due to a hardware error. 180 181 **/ 182 typedef 183 EFI_STATUS 184 (EFIAPI *EDKII_UFS_HC_FLUSH)( 185 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This 186 ); 187 188 typedef enum { 189 EfiUfsHcWidthUint8 = 0, 190 EfiUfsHcWidthUint16, 191 EfiUfsHcWidthUint32, 192 EfiUfsHcWidthUint64, 193 EfiUfsHcWidthMaximum 194 } EDKII_UFS_HOST_CONTROLLER_PROTOCOL_WIDTH; 195 196 /** 197 Enable a UFS bus driver to access UFS MMIO registers in the UFS Host Controller memory space. 198 199 @param This A pointer to the EDKII_UFS_HOST_CONTROLLER_PROTOCOL instance. 200 @param Width Signifies the width of the memory operations. 201 @param Offset The offset within the UFS Host Controller MMIO space to start the 202 memory operation. 203 @param Count The number of memory operations to perform. 204 @param Buffer For read operations, the destination buffer to store the results. 205 For write operations, the source buffer to write data from. 206 207 @retval EFI_SUCCESS The data was read from or written to the UFS host controller. 208 @retval EFI_UNSUPPORTED The address range specified by Offset, Width, and Count is not 209 valid for the UFS Host Controller memory space. 210 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 211 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 212 213 **/ 214 typedef 215 EFI_STATUS 216 (EFIAPI *EDKII_UFS_HC_MMIO_READ_WRITE)( 217 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 218 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL_WIDTH Width, 219 IN UINT64 Offset, 220 IN UINTN Count, 221 IN OUT VOID *Buffer 222 ); 223 224 typedef 225 EFI_STATUS 226 (EFIAPI *EDKII_UFS_HC_PHY_INIT)( 227 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This 228 ); 229 230 typedef 231 EFI_STATUS 232 (EFIAPI *EDKII_UFS_HC_PHY_SET_POWER_MODE)( 233 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 234 IN UINT32 DevQuirks 235 ); 236 237 /// 238 /// UFS Host Controller Protocol structure. 239 /// 240 struct _EDKII_UFS_HOST_CONTROLLER_PROTOCOL { 241 EDKII_UFS_HC_GET_MMIO_BAR GetUfsHcMmioBar; 242 EDKII_UFS_HC_ALLOCATE_BUFFER AllocateBuffer; 243 EDKII_UFS_HC_FREE_BUFFER FreeBuffer; 244 EDKII_UFS_HC_MAP Map; 245 EDKII_UFS_HC_UNMAP Unmap; 246 EDKII_UFS_HC_FLUSH Flush; 247 EDKII_UFS_HC_MMIO_READ_WRITE Read; 248 EDKII_UFS_HC_MMIO_READ_WRITE Write; 249 EDKII_UFS_HC_PHY_INIT PhyInit; 250 EDKII_UFS_HC_PHY_SET_POWER_MODE PhySetPowerMode; 251 }; 252 253 /// 254 /// UFS Host Controller Protocol GUID variable. 255 /// 256 extern EFI_GUID gEdkiiUfsHostControllerProtocolGuid; 257 258 #endif 259