MdeModulePkg/Include/Protocol/UfsHostController.h

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