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