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 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 ///
 225 ///  UFS Host Controller Protocol structure.
 226 ///
 227 struct _EDKII_UFS_HOST_CONTROLLER_PROTOCOL {
 228   EDKII_UFS_HC_GET_MMIO_BAR           GetUfsHcMmioBar;
 229   EDKII_UFS_HC_ALLOCATE_BUFFER        AllocateBuffer;
 230   EDKII_UFS_HC_FREE_BUFFER            FreeBuffer;
 231   EDKII_UFS_HC_MAP                    Map;
 232   EDKII_UFS_HC_UNMAP                  Unmap;
 233   EDKII_UFS_HC_FLUSH                  Flush;
 234   EDKII_UFS_HC_MMIO_READ_WRITE        Read;
 235   EDKII_UFS_HC_MMIO_READ_WRITE        Write;
 236 };
 237
 238 ///
 239 ///  UFS Host Controller Protocol GUID variable.
 240 ///
 241 extern EFI_GUID gEdkiiUfsHostControllerProtocolGuid;
 242
 243 #endif