MdeModulePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdeModulePkg / Include / Protocol / UfsHostController.h

/** @file\r
\r
  EDKII Universal Flash Storage Host Controller Protocol.\r
\r
Copyright (c) 2014 - 2018, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
\r
#ifndef __EDKII_UFS_HC_PROTOCOL_H__\r
#define __EDKII_UFS_HC_PROTOCOL_H__\r
\r
//\r
// UFS Host Controller Protocol GUID value\r
//\r
#define EDKII_UFS_HOST_CONTROLLER_PROTOCOL_GUID \\r
    { \\r
      0xebc01af5, 0x7a9, 0x489e, { 0xb7, 0xce, 0xdc, 0x8, 0x9e, 0x45, 0x9b, 0x2f } \\r
    }\r
\r
//\r
// Forward reference for pure ANSI compatability\r
//\r
typedef struct _EDKII_UFS_HOST_CONTROLLER_PROTOCOL  EDKII_UFS_HOST_CONTROLLER_PROTOCOL;\r
\r
\r
/**\r
  Get the MMIO base address of UFS host controller.\r
\r
  @param  This          The protocol instance pointer.\r
  @param  MmioBar       Pointer to the UFS host controller MMIO base address.\r
\r
  @retval EFI_SUCCESS            The operation succeeds.\r
  @retval EFI_INVALID_PARAMETER  The parameters are invalid.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EDKII_UFS_HC_GET_MMIO_BAR)(\r
  IN     EDKII_UFS_HOST_CONTROLLER_PROTOCOL     *This,\r
     OUT UINTN                                  *MmioBar\r
  );\r
\r
///\r
/// *******************************************************\r
/// EFI_UFS_HOST_CONTROLLER_OPERATION\r
/// *******************************************************\r
///\r
typedef enum {\r
  ///\r
  /// A read operation from system memory by a bus master.\r
  ///\r
  EdkiiUfsHcOperationBusMasterRead,\r
  ///\r
  /// A write operation from system memory by a bus master.\r
  ///\r
  EdkiiUfsHcOperationBusMasterWrite,\r
  ///\r
  /// Provides both read and write access to system memory by both the processor and a\r
  /// bus master. The buffer is coherent from both the processor's and the bus master's point of view.\r
  ///\r
  EdkiiUfsHcOperationBusMasterCommonBuffer,\r
  EdkiiUfsHcOperationMaximum\r
} EDKII_UFS_HOST_CONTROLLER_OPERATION;\r
\r
/**\r
  Provides the UFS controller-specific addresses needed to access system memory.\r
\r
  @param  This                  A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance.\r
  @param  Operation             Indicates if the bus master is going to read or write to system memory.\r
  @param  HostAddress           The system memory address to map to the UFS controller.\r
  @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes\r
                                that were mapped.\r
  @param  DeviceAddress         The resulting map address for the bus master UFS controller to use to\r
                                access the hosts HostAddress.\r
  @param  Mapping               A resulting value to pass to Unmap().\r
\r
  @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.\r
  @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.\r
  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.\r
  @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EDKII_UFS_HC_MAP)(\r
  IN     EDKII_UFS_HOST_CONTROLLER_PROTOCOL   *This,\r
  IN     EDKII_UFS_HOST_CONTROLLER_OPERATION  Operation,\r
  IN     VOID                                 *HostAddress,\r
  IN OUT UINTN                                *NumberOfBytes,\r
     OUT EFI_PHYSICAL_ADDRESS                 *DeviceAddress,\r
     OUT VOID                                 **Mapping\r
  );\r
\r
/**\r
  Completes the Map() operation and releases any corresponding resources.\r
\r
  @param  This                  A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance.\r
  @param  Mapping               The mapping value returned from Map().\r
\r
  @retval EFI_SUCCESS           The range was unmapped.\r
  @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EDKII_UFS_HC_UNMAP)(\r
  IN  EDKII_UFS_HOST_CONTROLLER_PROTOCOL     *This,\r
  IN  VOID                                   *Mapping\r
  );\r
\r
/**\r
  Allocates pages that are suitable for an EfiUfsHcOperationBusMasterCommonBuffer\r
  mapping.\r
\r
  @param  This                  A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance.\r
  @param  Type                  This parameter is not used and must be ignored.\r
  @param  MemoryType            The type of memory to allocate, EfiBootServicesData or\r
                                EfiRuntimeServicesData.\r
  @param  Pages                 The number of pages to allocate.\r
  @param  HostAddress           A pointer to store the base system memory address of the\r
                                allocated range.\r
  @param  Attributes            The requested bit mask of attributes for the allocated range.\r
\r
  @retval EFI_SUCCESS           The requested memory pages were allocated.\r
  @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are\r
                                MEMORY_WRITE_COMBINE and MEMORY_CACHED.\r
  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
  @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EDKII_UFS_HC_ALLOCATE_BUFFER)(\r
  IN     EDKII_UFS_HOST_CONTROLLER_PROTOCOL   *This,\r
  IN     EFI_ALLOCATE_TYPE                    Type,\r
  IN     EFI_MEMORY_TYPE                      MemoryType,\r
  IN     UINTN                                Pages,\r
     OUT VOID                                 **HostAddress,\r
  IN     UINT64                               Attributes\r
  );\r
\r
/**\r
  Frees memory that was allocated with AllocateBuffer().\r
\r
  @param  This                  A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance.\r
  @param  Pages                 The number of pages to free.\r
  @param  HostAddress           The base system memory address of the allocated range.\r
\r
  @retval EFI_SUCCESS           The requested memory pages were freed.\r
  @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages\r
                                was not allocated with AllocateBuffer().\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EDKII_UFS_HC_FREE_BUFFER)(\r
  IN  EDKII_UFS_HOST_CONTROLLER_PROTOCOL   *This,\r
  IN  UINTN                                Pages,\r
  IN  VOID                                 *HostAddress\r
  );\r
\r
/**\r
  Flushes all posted write transactions from the UFS bus to attached UFS device.\r
\r
  @param  This                  A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance.\r
\r
  @retval EFI_SUCCESS           The posted write transactions were flushed from the UFS bus\r
                                to attached UFS device.\r
  @retval EFI_DEVICE_ERROR      The posted write transactions were not flushed from the UFS\r
                                bus to attached UFS device due to a hardware error.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EDKII_UFS_HC_FLUSH)(\r
  IN  EDKII_UFS_HOST_CONTROLLER_PROTOCOL   *This\r
  );\r
\r
typedef enum {\r
  EfiUfsHcWidthUint8      = 0,\r
  EfiUfsHcWidthUint16,\r
  EfiUfsHcWidthUint32,\r
  EfiUfsHcWidthUint64,\r
  EfiUfsHcWidthMaximum\r
} EDKII_UFS_HOST_CONTROLLER_PROTOCOL_WIDTH;\r
\r
/**\r
  Enable a UFS bus driver to access UFS MMIO registers in the UFS Host Controller memory space.\r
\r
  @param  This                  A pointer to the EDKII_UFS_HOST_CONTROLLER_PROTOCOL instance.\r
  @param  Width                 Signifies the width of the memory operations.\r
  @param  Offset                The offset within the UFS Host Controller MMIO space to start the\r
                                memory operation.\r
  @param  Count                 The number of memory operations to perform.\r
  @param  Buffer                For read operations, the destination buffer to store the results.\r
                                For write operations, the source buffer to write data from.\r
\r
  @retval EFI_SUCCESS           The data was read from or written to the UFS host controller.\r
  @retval EFI_UNSUPPORTED       The address range specified by Offset, Width, and Count is not\r
                                valid for the UFS Host Controller memory space.\r
  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.\r
  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EDKII_UFS_HC_MMIO_READ_WRITE)(\r
  IN     EDKII_UFS_HOST_CONTROLLER_PROTOCOL        *This,\r
  IN     EDKII_UFS_HOST_CONTROLLER_PROTOCOL_WIDTH  Width,\r
  IN     UINT64                                    Offset,\r
  IN     UINTN                                     Count,\r
  IN OUT VOID                                      *Buffer\r
  );\r
\r
///\r
///  UFS Host Controller Protocol structure.\r
///\r
struct _EDKII_UFS_HOST_CONTROLLER_PROTOCOL {\r
  EDKII_UFS_HC_GET_MMIO_BAR           GetUfsHcMmioBar;\r
  EDKII_UFS_HC_ALLOCATE_BUFFER        AllocateBuffer;\r
  EDKII_UFS_HC_FREE_BUFFER            FreeBuffer;\r
  EDKII_UFS_HC_MAP                    Map;\r
  EDKII_UFS_HC_UNMAP                  Unmap;\r
  EDKII_UFS_HC_FLUSH                  Flush;\r
  EDKII_UFS_HC_MMIO_READ_WRITE        Read;\r
  EDKII_UFS_HC_MMIO_READ_WRITE        Write;\r
};\r
\r
///\r
///  UFS Host Controller Protocol GUID variable.\r
///\r
extern EFI_GUID gEdkiiUfsHostControllerProtocolGuid;\r
\r
#endif\r