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