MdeModulePkg/Bus/Usb/UsbBotPei/UsbBotPeim.h

   1 /** @file
   2 Usb BOT Peim definition.
   3
   4 Copyright (c) 2006, Intel Corporation. All rights reserved.<BR>
   5
   6 This program and the accompanying materials
   7 are licensed and made available under the terms and conditions
   8 of the BSD License which accompanies this distribution.  The
   9 full text of the license may be found at
  10 http://opensource.org/licenses/bsd-license.php
  11
  12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #ifndef _PEI_USB_BOT_PEIM_H_
  18 #define _PEI_USB_BOT_PEIM_H_
  19
  20 #include <PiPei.h>
  21
  22 #include <Ppi/UsbIo.h>
  23 #include <Ppi/UsbHostController.h>
  24 #include <Ppi/BlockIo.h>
  25
  26 #include <Library/DebugLib.h>
  27
  28 #include <IndustryStandard/Usb.h>
  29 #include <IndustryStandard/Atapi.h>
  30
  31 #define PEI_FAT_MAX_USB_IO_PPI  127
  32
  33 /**
  34   Gets the count of block I/O devices that one specific block driver detects.
  35
  36   This function is used for getting the count of block I/O devices that one
  37   specific block driver detects.  To the PEI ATAPI driver, it returns the number
  38   of all the detected ATAPI devices it detects during the enumeration process.
  39   To the PEI legacy floppy driver, it returns the number of all the legacy
  40   devices it finds during its enumeration process. If no device is detected,
  41   then the function will return zero.
  42
  43   @param[in]  PeiServices          General-purpose services that are available
  44                                    to every PEIM.
  45   @param[in]  This                 Indicates the EFI_PEI_RECOVERY_BLOCK_IO_PPI
  46                                    instance.
  47   @param[out] NumberBlockDevices   The number of block I/O devices discovered.
  48
  49   @retval     EFI_SUCCESS          Operation performed successfully.
  50
  51 **/
  52 EFI_STATUS
  53 EFIAPI
  54 BotGetNumberOfBlockDevices (
  55   IN  EFI_PEI_SERVICES                         **PeiServices,
  56   IN  EFI_PEI_RECOVERY_BLOCK_IO_PPI            *This,
  57   OUT UINTN                                    *NumberBlockDevices
  58   );
  59
  60 /**
  61   Gets a block device's media information.
  62
  63   This function will provide the caller with the specified block device's media
  64   information. If the media changes, calling this function will update the media
  65   information accordingly.
  66
  67   @param[in]  PeiServices   General-purpose services that are available to every
  68                             PEIM
  69   @param[in]  This          Indicates the EFI_PEI_RECOVERY_BLOCK_IO_PPI instance.
  70   @param[in]  DeviceIndex   Specifies the block device to which the function wants
  71                             to talk. Because the driver that implements Block I/O
  72                             PPIs will manage multiple block devices, the PPIs that
  73                             want to talk to a single device must specify the
  74                             device index that was assigned during the enumeration
  75                             process. This index is a number from one to
  76                             NumberBlockDevices.
  77   @param[out] MediaInfo     The media information of the specified block media.
  78                             The caller is responsible for the ownership of this
  79                             data structure.
  80
  81   @retval EFI_SUCCESS        Media information about the specified block device
  82                              was obtained successfully.
  83   @retval EFI_DEVICE_ERROR   Cannot get the media information due to a hardware
  84                              error.
  85
  86 **/
  87 EFI_STATUS
  88 EFIAPI
  89 BotGetMediaInfo (
  90   IN  EFI_PEI_SERVICES                          **PeiServices,
  91   IN  EFI_PEI_RECOVERY_BLOCK_IO_PPI             *This,
  92   IN  UINTN                                     DeviceIndex,
  93   OUT EFI_PEI_BLOCK_IO_MEDIA                    *MediaInfo
  94   );
  95
  96 /**
  97   Reads the requested number of blocks from the specified block device.
  98
  99   The function reads the requested number of blocks from the device. All the
 100   blocks are read, or an error is returned. If there is no media in the device,
 101   the function returns EFI_NO_MEDIA.
 102
 103   @param[in]  PeiServices   General-purpose services that are available to
 104                             every PEIM.
 105   @param[in]  This          Indicates the EFI_PEI_RECOVERY_BLOCK_IO_PPI instance.
 106   @param[in]  DeviceIndex   Specifies the block device to which the function wants
 107                             to talk. Because the driver that implements Block I/O
 108                             PPIs will manage multiple block devices, the PPIs that
 109                             want to talk to a single device must specify the device
 110                             index that was assigned during the enumeration process.
 111                             This index is a number from one to NumberBlockDevices.
 112   @param[in]  StartLBA      The starting logical block address (LBA) to read from
 113                             on the device
 114   @param[in]  BufferSize    The size of the Buffer in bytes. This number must be
 115                             a multiple of the intrinsic block size of the device.
 116   @param[out] Buffer        A pointer to the destination buffer for the data.
 117                             The caller is responsible for the ownership of the
 118                             buffer.
 119
 120   @retval EFI_SUCCESS             The data was read correctly from the device.
 121   @retval EFI_DEVICE_ERROR        The device reported an error while attempting
 122                                   to perform the read operation.
 123   @retval EFI_INVALID_PARAMETER   The read request contains LBAs that are not
 124                                   valid, or the buffer is not properly aligned.
 125   @retval EFI_NO_MEDIA            There is no media in the device.
 126   @retval EFI_BAD_BUFFER_SIZE     The BufferSize parameter is not a multiple of
 127                                   the intrinsic block size of the device.
 128
 129 **/
 130 EFI_STATUS
 131 EFIAPI
 132 BotReadBlocks (
 133   IN  EFI_PEI_SERVICES                          **PeiServices,
 134   IN  EFI_PEI_RECOVERY_BLOCK_IO_PPI             *This,
 135   IN  UINTN                                     DeviceIndex,
 136   IN  EFI_PEI_LBA                               StartLBA,
 137   IN  UINTN                                     BufferSize,
 138   OUT VOID                                      *Buffer
 139   );
 140
 141 /**
 142   UsbIo installation notification function.
 143
 144   This function finds out all the current USB IO PPIs in the system and add them
 145   into private data.
 146
 147   @param  PeiServices      Indirect reference to the PEI Services Table.
 148   @param  NotifyDesc       Address of the notification descriptor data structure.
 149   @param  InvokePpi        Address of the PPI that was invoked.
 150
 151   @retval EFI_SUCCESS      The function completes successfully.
 152
 153 **/
 154 EFI_STATUS
 155 EFIAPI
 156 NotifyOnUsbIoPpi (
 157   IN  EFI_PEI_SERVICES                              **PeiServices,
 158   IN  EFI_PEI_NOTIFY_DESCRIPTOR                     *NotifyDesc,
 159   IN  VOID                                          *InvokePpi
 160   );
 161
 162 /**
 163   Initialize the usb bot device.
 164
 165   @param[in]  PeiServices   General-purpose services that are available to every
 166                             PEIM.
 167   @param[in]  UsbIoPpi      Indicates the PEI_USB_IO_PPI instance.
 168
 169   @retval EFI_SUCCESS       The usb bot device is initialized successfully.
 170   @retval Other             Failed to initialize media.
 171
 172 **/
 173 EFI_STATUS
 174 InitUsbBot (
 175   IN  EFI_PEI_SERVICES                          **PeiServices,
 176   IN  PEI_USB_IO_PPI                            *UsbIoPpi
 177   );
 178
 179 #define USBCDROM    1 // let the device type value equal to USBCDROM, which is defined by PI spec.
 180                       // Therefore the CdExpressPei module can do recovery on UsbCdrom.
 181 #define USBFLOPPY   2 // for those that use ReadCapacity(0x25) command to retrieve media capacity
 182 #define USBFLOPPY2  3 // for those that use ReadFormatCapacity(0x23) command to retrieve media capacity
 183
 184 //
 185 // Bot device structure
 186 //
 187 #define PEI_BOT_DEVICE_SIGNATURE  SIGNATURE_32 ('U', 'B', 'O', 'T')
 188 typedef struct {
 189   UINTN                           Signature;
 190   EFI_PEI_RECOVERY_BLOCK_IO_PPI   BlkIoPpi;
 191   EFI_PEI_PPI_DESCRIPTOR          BlkIoPpiList;
 192   EFI_PEI_BLOCK_IO_MEDIA          Media;
 193   PEI_USB_IO_PPI                  *UsbIoPpi;
 194   EFI_USB_INTERFACE_DESCRIPTOR    *BotInterface;
 195   EFI_USB_ENDPOINT_DESCRIPTOR     *BulkInEndpoint;
 196   EFI_USB_ENDPOINT_DESCRIPTOR     *BulkOutEndpoint;
 197   UINTN                           AllocateAddress;
 198   UINTN                           DeviceType;
 199   ATAPI_REQUEST_SENSE_DATA              *SensePtr;
 200 } PEI_BOT_DEVICE;
 201
 202 #define PEI_BOT_DEVICE_FROM_THIS(a) CR (a, PEI_BOT_DEVICE, BlkIoPpi, PEI_BOT_DEVICE_SIGNATURE)
 203
 204 /**
 205   Send ATAPI command using BOT protocol.
 206
 207   @param  PeiServices            The pointer of EFI_PEI_SERVICES.
 208   @param  PeiBotDev              The instance to PEI_BOT_DEVICE.
 209   @param  Command                The command to be sent to ATAPI device.
 210   @param  CommandSize            The length of the data to be sent.
 211   @param  DataBuffer             The pointer to the data.
 212   @param  BufferLength           The length of the data.
 213   @param  Direction              The direction of the data.
 214   @param  TimeOutInMilliSeconds  Indicates the maximum time, in millisecond, which the
 215                                  transfer is allowed to complete.
 216
 217   @retval EFI_DEVICE_ERROR       Successful to get the status of device.
 218   @retval EFI_SUCCESS            Failed to get the status of device.
 219
 220 **/
 221 EFI_STATUS
 222 PeiAtapiCommand (
 223   IN  EFI_PEI_SERVICES            **PeiServices,
 224   IN  PEI_BOT_DEVICE              *PeiBotDev,
 225   IN  VOID                        *Command,
 226   IN  UINT8                       CommandSize,
 227   IN  VOID                        *DataBuffer,
 228   IN  UINT32                      BufferLength,
 229   IN  EFI_USB_DATA_DIRECTION      Direction,
 230   IN  UINT16                      TimeOutInMilliSeconds
 231   );
 232
 233 #endif