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 - 2008, Intel Corporation
   6   All rights reserved. This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  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 {
  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 } 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 Size of the buffer in bytes pointed to by Buffer.
  51   @param  Buffer     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 /**
  83   Writes to the tape.
  84
  85   @param  This       A pointer to the EFI_TAPE_IO_PROTOCOL instance.
  86   @param  BufferSize Size of the buffer in bytes pointed to by Buffer.
  87   @param  Buffer     Pointer to the buffer for data to be written from.
  88
  89   @retval EFI_SUCCESS           Data was successfully transferred to the media.
  90   @retval EFI_END_OF_MEDIA      The logical end of media has been reached. Data may have
  91                                 been successfully transferred to the media.
  92   @retval EFI_NO_MEDIA          No media is loaded in the device.
  93   @retval EFI_NOT_READY         The transfer failed since the device was not ready (e.g. not
  94                                 online). The transfer may be retried at a later time.
  95   @retval EFI_UNSUPPORTED       The device does not support this type of transfer.
  96   @retval EFI_TIMEOUT           The transfer failed to complete within the timeout specified.
  97   @retval EFI_MEDIA_CHANGED     The media in the device was changed since the last access.
  98                                 The transfer was aborted since the current position of the
  99                                 media may be incorrect.
 100   @retval EFI_WRITE_PROTECTED   The media in the device is write-protected. The transfer
 101                                 was aborted since a write cannot be completed.
 102   @retval EFI_INVALID_PARAMETER A NULL Buffer was specified with a non-zero
 103                                 BufferSize or the device is operating in fixed block
 104                                 size mode and the BufferSize was not a multiple of
 105                                 device's fixed block size
 106   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to transfer data
 107                                 from the media.
 108
 109 **/
 110 typedef
 111 EFI_STATUS
 112 (EFIAPI *EFI_TAPE_WRITE)(
 113   IN EFI_TAPE_IO_PROTOCOL *This,
 114   IN UINTN                *BufferSize,
 115   IN VOID                 *Buffer
 116   )
 117 ;
 118
 119
 120 /**
 121   Rewinds the tape.
 122
 123   @param  This A pointer to the EFI_TAPE_IO_PROTOCOL instance.
 124
 125   @retval EFI_SUCCESS      The media was successfully repositioned.
 126   @retval EFI_NO_MEDIA     No media is loaded in the device.
 127   @retval EFI_NOT_READY    Repositioning the media failed since the device was not
 128                            ready (e.g. not online). The transfer may be retried at a later time.
 129   @retval EFI_UNSUPPORTED  The device does not support this type of media repositioning.
 130   @retval EFI_TIMEOUT      Repositioning of the media did not complete within the timeout specified.
 131   @retval EFI_DEVICE_ERROR A device error occurred while attempting to reposition the media.
 132
 133 **/
 134 typedef
 135 EFI_STATUS
 136 (EFIAPI *EFI_TAPE_REWIND)(
 137   IN EFI_TAPE_IO_PROTOCOL *This
 138   )
 139 ;
 140
 141
 142 /**
 143   Positions the tape.
 144
 145   @param  This      A pointer to the EFI_TAPE_IO_PROTOCOL instance.
 146   @param  Direction Direction and number of data blocks or filemarks to space over on media.
 147   @param  Type      Type of mark to space over on media.
 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   INTN                    Direction,
 168   UINTN                   Type
 169   )
 170 ;
 171
 172
 173 /**
 174   Writes filemarks to the media.
 175
 176   @param  This  A pointer to the EFI_TAPE_IO_PROTOCOL instance.
 177   @param  Count Number of filemarks to write to the media.
 178
 179   @retval EFI_SUCCESS       Data was successfully transferred from the media.
 180   @retval EFI_NO_MEDIA      No media is loaded in the device.
 181   @retval EFI_NOT_READY     The transfer failed since the device was not ready (e.g. not
 182                             online). The transfer may be retried at a later time.
 183   @retval EFI_UNSUPPORTED   The device does not support this type of repositioning.
 184   @retval EFI_TIMEOUT       The transfer failed to complete within the timeout specified.
 185   @retval EFI_MEDIA_CHANGED The media in the device was changed since the last access.
 186                             The transfer was aborted since the current position of the
 187                             media may be incorrect.
 188   @retval EFI_DEVICE_ERROR  A device error occurred while attempting to transfer data from the media.
 189
 190 **/
 191 typedef
 192 EFI_STATUS
 193 (EFIAPI *EFI_TAPE_WRITEFM)(
 194   IN EFI_TAPE_IO_PROTOCOL *This,
 195   IN UINTN                Count
 196   )
 197 ;
 198
 199
 200 /**
 201   Resets the tape device.
 202
 203   @param  This                 A pointer to the EFI_TAPE_IO_PROTOCOL instance.
 204   @param  ExtendedVerification Indicates whether the parent bus should also be reset.
 205
 206   @retval  EFI_SUCCESS      The bus and/or device were successfully reset.
 207   @retval  EFI_NO_MEDIA     No media is loaded in the device.
 208   @retval  EFI_NOT_READY    The reset failed since the device and/or bus was not ready.
 209                             The reset may be retried at a later time.
 210   @retval  EFI_UNSUPPORTED  The device does not support this type of reset.
 211   @retval  EFI_TIMEOUT      The reset did not complete within the timeout allowed.
 212   @retval  EFI_DEVICE_ERROR A device error occurred while attempting to reset the bus and/or device.
 213
 214 **/
 215 typedef
 216 EFI_STATUS
 217 (EFIAPI *EFI_TAPE_RESET)(
 218   IN EFI_TAPE_IO_PROTOCOL *This,
 219   IN BOOLEAN              ExtendedVerification
 220   )
 221 ;
 222
 223 /**
 224   @par Protocol Description:
 225   The EFI_TAPE_IO_PROTOCOL provides basic sequential operations for tape devices.
 226   These include read, write, rewind, space, write filemarks and reset functions.
 227   Per this specification, a boot application uses the services of this protocol
 228   to load the bootloader image from tape.
 229
 230   @param TapeRead
 231   Read a block of data from the tape.
 232
 233   @param TapeWrite
 234   Write a block of data to the tape.
 235
 236   @param TapeRewind
 237   Rewind the tape.
 238
 239   @param TapeSpace
 240   Position the tape.
 241
 242   @param TapeWriteFM
 243   Write filemarks to the tape.
 244
 245   @param TapeReset
 246   Reset the tape device or its parent bus.
 247 **/
 248 struct _EFI_TAPE_IO_PROTOCOL {
 249   EFI_TAPE_READ           TapeRead;
 250   EFI_TAPE_WRITE          TapeWrite;
 251   EFI_TAPE_REWIND         TapeRewind;
 252   EFI_TAPE_SPACE          TapeSpace;
 253   EFI_TAPE_WRITEFM        TapeWriteFM;
 254   EFI_TAPE_RESET          TapeReset;
 255 };
 256
 257 extern EFI_GUID gEfiTapeIoProtocolGuid;
 258
 259 #endif