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 /**
 113   Rewinds the tape.
 114
 115   @param  This A pointer to the EFI_TAPE_IO_PROTOCOL instance.
 116
 117   @retval EFI_SUCCESS      The media was successfully repositioned.
 118   @retval EFI_NO_MEDIA     No media is loaded in the device.
 119   @retval EFI_NOT_READY    Repositioning the media failed since the device was not
 120                            ready (e.g. not online). The transfer may be retried at a later time.
 121   @retval EFI_UNSUPPORTED  The device does not support this type of media repositioning.
 122   @retval EFI_TIMEOUT      Repositioning of the media did not complete within the timeout specified.
 123   @retval EFI_DEVICE_ERROR A device error occurred while attempting to reposition the media.
 124
 125 **/
 126 typedef
 127 EFI_STATUS
 128 (EFIAPI *EFI_TAPE_REWIND)(
 129   IN EFI_TAPE_IO_PROTOCOL *This
 130   );
 131
 132
 133 /**
 134   Positions the tape.
 135
 136   @param  This      A pointer to the EFI_TAPE_IO_PROTOCOL instance.
 137   @param  Direction Direction and number of data blocks or filemarks to space over on media.
 138   @param  Type      Type of mark to space over on media.
 139                     The following Type marks are mandatory:
 140                     BLOCK type    : 0
 141                     FILEMARK type : 1
 142
 143   @retval EFI_SUCCESS       The media was successfully repositioned.
 144   @retval EFI_END_OF_MEDIA  Beginning or end of media was reached before the
 145                             indicated number of data blocks or filemarks were found.
 146   @retval EFI_NO_MEDIA      No media is loaded in the device.
 147   @retval EFI_NOT_READY     The reposition failed since the device was not ready (e.g. not
 148                             online). The reposition may be retried at a later time.
 149   @retval EFI_UNSUPPORTED   The device does not support this type of repositioning.
 150   @retval EFI_TIMEOUT       The repositioning failed to complete within the timeout specified.
 151   @retval EFI_MEDIA_CHANGED The media in the device was changed since the last access.
 152                             Repositioning the media was aborted since the current
 153                             position of the media may be incorrect.
 154   @retval EFI_DEVICE_ERROR  A device error occurred while attempting to reposition the media.
 155
 156 **/
 157 typedef
 158 EFI_STATUS
 159 (EFIAPI *EFI_TAPE_SPACE)(
 160   IN EFI_TAPE_IO_PROTOCOL *This,
 161   IN INTN                 Direction,
 162   IN UINTN                Type
 163   );
 164
 165
 166 /**
 167   Writes filemarks to the media.
 168
 169   @param  This  A pointer to the EFI_TAPE_IO_PROTOCOL instance.
 170   @param  Count Number of filemarks to write to the media.
 171
 172   @retval EFI_SUCCESS       Data was successfully transferred from the media.
 173   @retval EFI_NO_MEDIA      No media is loaded in the device.
 174   @retval EFI_NOT_READY     The transfer failed since the device was not ready (e.g. not
 175                             online). The transfer may be retried at a later time.
 176   @retval EFI_UNSUPPORTED   The device does not support this type of repositioning.
 177   @retval EFI_TIMEOUT       The transfer failed to complete within the timeout specified.
 178   @retval EFI_MEDIA_CHANGED The media in the device was changed since the last access.
 179                             The transfer was aborted since the current position of the
 180                             media may be incorrect.
 181   @retval EFI_DEVICE_ERROR  A device error occurred while attempting to transfer data from the media.
 182
 183 **/
 184 typedef
 185 EFI_STATUS
 186 (EFIAPI *EFI_TAPE_WRITEFM)(
 187   IN EFI_TAPE_IO_PROTOCOL *This,
 188   IN UINTN                Count
 189   );
 190
 191
 192 /**
 193   Resets the tape device.
 194
 195   @param  This                 A pointer to the EFI_TAPE_IO_PROTOCOL instance.
 196   @param  ExtendedVerification Indicates whether the parent bus should also be reset.
 197
 198   @retval  EFI_SUCCESS      The bus and/or device were successfully reset.
 199   @retval  EFI_NO_MEDIA     No media is loaded in the device.
 200   @retval  EFI_NOT_READY    The reset failed since the device and/or bus was not ready.
 201                             The reset may be retried at a later time.
 202   @retval  EFI_UNSUPPORTED  The device does not support this type of reset.
 203   @retval  EFI_TIMEOUT      The reset did not complete within the timeout allowed.
 204   @retval  EFI_DEVICE_ERROR A device error occurred while attempting to reset the bus and/or device.
 205
 206 **/
 207 typedef
 208 EFI_STATUS
 209 (EFIAPI *EFI_TAPE_RESET)(
 210   IN EFI_TAPE_IO_PROTOCOL *This,
 211   IN BOOLEAN              ExtendedVerification
 212   );
 213
 214 ///
 215 /// The EFI_TAPE_IO_PROTOCOL provides basic sequential operations for tape devices.
 216 /// These include read, write, rewind, space, write filemarks and reset functions.
 217 /// Per this specification, a boot application uses the services of this protocol
 218 /// to load the bootloader image from tape.
 219 ///
 220 struct _EFI_TAPE_IO_PROTOCOL {
 221   EFI_TAPE_READ           TapeRead;
 222   EFI_TAPE_WRITE          TapeWrite;
 223   EFI_TAPE_REWIND         TapeRewind;
 224   EFI_TAPE_SPACE          TapeSpace;
 225   EFI_TAPE_WRITEFM        TapeWriteFM;
 226   EFI_TAPE_RESET          TapeReset;
 227 };
 228
 229 extern EFI_GUID gEfiTapeIoProtocolGuid;
 230
 231 #endif