MdePkg/Include/Protocol/TapeIo.h

   1 /** @file
   2   EFI_TAPE_IO_PROTOCOL as defined in the UEFI 2.0.
   3   Provide services to control and access a tape device.
   4
   5 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef __EFI_TAPE_IO_PROTOCOL_H__
  11 #define __EFI_TAPE_IO_PROTOCOL_H__
  12
  13 #define EFI_TAPE_IO_PROTOCOL_GUID \
  14   { \
  15     0x1e93e633, 0xd65a, 0x459e, {0xab, 0x84, 0x93, 0xd9, 0xec, 0x26, 0x6d, 0x18 } \
  16   }
  17
  18 typedef struct _EFI_TAPE_IO_PROTOCOL EFI_TAPE_IO_PROTOCOL;
  19
  20 typedef struct _EFI_TAPE_HEADER {
  21   UINT64      Signature;
  22   UINT32      Revision;
  23   UINT32      BootDescSize;
  24   UINT32      BootDescCRC;
  25   EFI_GUID    TapeGUID;
  26   EFI_GUID    TapeType;
  27   EFI_GUID    TapeUnique;
  28   UINT32      BLLocation;
  29   UINT32      BLBlocksize;
  30   UINT32      BLFilesize;
  31   CHAR8       OSVersion[40];
  32   CHAR8       AppVersion[40];
  33   CHAR8       CreationDate[10];
  34   CHAR8       CreationTime[10];
  35   CHAR8       SystemName[256]; // UTF-8
  36   CHAR8       TapeTitle[120];  // UTF-8
  37   CHAR8       pad[468];        // pad to 1024
  38 } EFI_TAPE_HEADER;
  39
  40 /**
  41   Reads from the tape.
  42
  43   @param  This       A pointer to the EFI_TAPE_IO_PROTOCOL instance.
  44   @param  BufferSize The size of the buffer in bytes pointed to by Buffer.
  45   @param  Buffer     The pointer to the buffer for data to be read into.
  46
  47   @retval EFI_SUCCESS           Data was successfully transferred from the media.
  48   @retval EFI_END_OF_FILE       A filemark was encountered which limited the data
  49                                 transferred by the read operation or the head is positioned
  50                                 just after a filemark.
  51   @retval EFI_NO_MEDIA          No media is loaded in the device.
  52   @retval EFI_NOT_READY         The transfer failed since the device was not ready (e.g. not
  53                                 online). The transfer may be retried at a later time.
  54   @retval EFI_UNSUPPORTED       The device does not support this type of transfer.
  55   @retval EFI_TIMEOUT           The transfer failed to complete within the timeout specified.
  56   @retval EFI_MEDIA_CHANGED     The media in the device was changed since the last access.
  57                                 The transfer was aborted since the current position of the
  58                                 media may be incorrect.
  59   @retval EFI_INVALID_PARAMETER A NULL Buffer was specified with a non-zero
  60                                 BufferSize, or the device is operating in fixed block
  61                                 size mode and the BufferSize was not a multiple of
  62                                 device's fixed block size
  63   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to transfer data
  64                                 from the media.
  65
  66 **/
  67 typedef
  68 EFI_STATUS
  69 (EFIAPI *EFI_TAPE_READ)(
  70   IN EFI_TAPE_IO_PROTOCOL *This,
  71   IN OUT UINTN            *BufferSize,
  72   OUT VOID                *Buffer
  73   );
  74
  75 /**
  76   Writes to the tape.
  77
  78   @param  This       A pointer to the EFI_TAPE_IO_PROTOCOL instance.
  79   @param  BufferSize Size of the buffer in bytes pointed to by Buffer.
  80   @param  Buffer     The pointer to the buffer for data to be written from.
  81
  82   @retval EFI_SUCCESS           Data was successfully transferred to the media.
  83   @retval EFI_END_OF_MEDIA      The logical end of media has been reached. Data may have
  84                                 been successfully transferred to the media.
  85   @retval EFI_NO_MEDIA          No media is loaded in the device.
  86   @retval EFI_NOT_READY         The transfer failed since the device was not ready (e.g. not
  87                                 online). The transfer may be retried at a later time.
  88   @retval EFI_UNSUPPORTED       The device does not support this type of transfer.
  89   @retval EFI_TIMEOUT           The transfer failed to complete within the timeout specified.
  90   @retval EFI_MEDIA_CHANGED     The media in the device was changed since the last access.
  91                                 The transfer was aborted since the current position of the
  92                                 media may be incorrect.
  93   @retval EFI_WRITE_PROTECTED   The media in the device is write-protected. The transfer
  94                                 was aborted since a write cannot be completed.
  95   @retval EFI_INVALID_PARAMETER A NULL Buffer was specified with a non-zero
  96                                 BufferSize, or the device is operating in fixed block
  97                                 size mode and the BufferSize was not a multiple of
  98                                 device's fixed block size
  99   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to transfer data
 100                                 from the media.
 101
 102 **/
 103 typedef
 104 EFI_STATUS
 105 (EFIAPI *EFI_TAPE_WRITE)(
 106   IN EFI_TAPE_IO_PROTOCOL *This,
 107   IN UINTN                *BufferSize,
 108   IN VOID                 *Buffer
 109   );
 110
 111 /**
 112   Rewinds the tape.
 113
 114   @param  This A pointer to the EFI_TAPE_IO_PROTOCOL instance.
 115
 116   @retval EFI_SUCCESS      The media was successfully repositioned.
 117   @retval EFI_NO_MEDIA     No media is loaded in the device.
 118   @retval EFI_NOT_READY    Repositioning the media failed since the device was not
 119                            ready (e.g. not online). The transfer may be retried at a later time.
 120   @retval EFI_UNSUPPORTED  The device does not support this type of media repositioning.
 121   @retval EFI_TIMEOUT      Repositioning of the media did not complete within the timeout specified.
 122   @retval EFI_DEVICE_ERROR A device error occurred while attempting to reposition the media.
 123
 124 **/
 125 typedef
 126 EFI_STATUS
 127 (EFIAPI *EFI_TAPE_REWIND)(
 128   IN EFI_TAPE_IO_PROTOCOL *This
 129   );
 130
 131 /**
 132   Positions the tape.
 133
 134   @param  This      A pointer to the EFI_TAPE_IO_PROTOCOL instance.
 135   @param  Direction Direction and number of data blocks or filemarks to space over on media.
 136   @param  Type      Type of mark to space over on media.
 137                     The following Type marks are mandatory:
 138                     BLOCK type    : 0
 139                     FILEMARK type : 1
 140
 141   @retval EFI_SUCCESS       The media was successfully repositioned.
 142   @retval EFI_END_OF_MEDIA  Beginning or end of media was reached before the
 143                             indicated number of data blocks or filemarks were found.
 144   @retval EFI_NO_MEDIA      No media is loaded in the device.
 145   @retval EFI_NOT_READY     The reposition failed since the device was not ready (e.g. not
 146                             online). The reposition may be retried at a later time.
 147   @retval EFI_UNSUPPORTED   The device does not support this type of repositioning.
 148   @retval EFI_TIMEOUT       The repositioning failed to complete within the timeout specified.
 149   @retval EFI_MEDIA_CHANGED The media in the device was changed since the last access.
 150                             Repositioning the media was aborted since the current
 151                             position of the media may be incorrect.
 152   @retval EFI_DEVICE_ERROR  A device error occurred while attempting to reposition the media.
 153
 154 **/
 155 typedef
 156 EFI_STATUS
 157 (EFIAPI *EFI_TAPE_SPACE)(
 158   IN EFI_TAPE_IO_PROTOCOL *This,
 159   IN INTN                 Direction,
 160   IN UINTN                Type
 161   );
 162
 163 /**
 164   Writes filemarks to the media.
 165
 166   @param  This  A pointer to the EFI_TAPE_IO_PROTOCOL instance.
 167   @param  Count Number of filemarks to write to the media.
 168
 169   @retval EFI_SUCCESS       Data was successfully transferred from the media.
 170   @retval EFI_NO_MEDIA      No media is loaded in the device.
 171   @retval EFI_NOT_READY     The transfer failed since the device was not ready (e.g. not
 172                             online). The transfer may be retried at a later time.
 173   @retval EFI_UNSUPPORTED   The device does not support this type of repositioning.
 174   @retval EFI_TIMEOUT       The transfer failed to complete within the timeout specified.
 175   @retval EFI_MEDIA_CHANGED The media in the device was changed since the last access.
 176                             The transfer was aborted since the current position of the
 177                             media may be incorrect.
 178   @retval EFI_DEVICE_ERROR  A device error occurred while attempting to transfer data from the media.
 179
 180 **/
 181 typedef
 182 EFI_STATUS
 183 (EFIAPI *EFI_TAPE_WRITEFM)(
 184   IN EFI_TAPE_IO_PROTOCOL *This,
 185   IN UINTN                Count
 186   );
 187
 188 /**
 189   Resets the tape device.
 190
 191   @param  This                 A pointer to the EFI_TAPE_IO_PROTOCOL instance.
 192   @param  ExtendedVerification Indicates whether the parent bus should also be reset.
 193
 194   @retval  EFI_SUCCESS      The bus and/or device were successfully reset.
 195   @retval  EFI_NO_MEDIA     No media is loaded in the device.
 196   @retval  EFI_NOT_READY    The reset failed since the device and/or bus was not ready.
 197                             The reset may be retried at a later time.
 198   @retval  EFI_UNSUPPORTED  The device does not support this type of reset.
 199   @retval  EFI_TIMEOUT      The reset did not complete within the timeout allowed.
 200   @retval  EFI_DEVICE_ERROR A device error occurred while attempting to reset the bus and/or device.
 201
 202 **/
 203 typedef
 204 EFI_STATUS
 205 (EFIAPI *EFI_TAPE_RESET)(
 206   IN EFI_TAPE_IO_PROTOCOL *This,
 207   IN BOOLEAN              ExtendedVerification
 208   );
 209
 210 ///
 211 /// The EFI_TAPE_IO_PROTOCOL provides basic sequential operations for tape devices.
 212 /// These include read, write, rewind, space, write filemarks and reset functions.
 213 /// Per this specification, a boot application uses the services of this protocol
 214 /// to load the bootloader image from tape.
 215 ///
 216 struct _EFI_TAPE_IO_PROTOCOL {
 217   EFI_TAPE_READ       TapeRead;
 218   EFI_TAPE_WRITE      TapeWrite;
 219   EFI_TAPE_REWIND     TapeRewind;
 220   EFI_TAPE_SPACE      TapeSpace;
 221   EFI_TAPE_WRITEFM    TapeWriteFM;
 222   EFI_TAPE_RESET      TapeReset;
 223 };
 224
 225 extern EFI_GUID  gEfiTapeIoProtocolGuid;
 226
 227 #endif