MdePkg/Include/Protocol/TapeIo.h - edk2 - Git at Google

 /** @file
   EFI_TAPE_IO_PROTOCOL as defined in the UEFI 2.0.
   Provide services to control and access a tape device.

 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
 SPDX-License-Identifier: BSD-2-Clause-Patent

 **/

 #ifndef __EFI_TAPE_IO_PROTOCOL_H__
 #define __EFI_TAPE_IO_PROTOCOL_H__

 #define EFI_TAPE_IO_PROTOCOL_GUID \
   { \
     0x1e93e633, 0xd65a, 0x459e, {0xab, 0x84, 0x93, 0xd9, 0xec, 0x26, 0x6d, 0x18 } \
   }

 typedef struct _EFI_TAPE_IO_PROTOCOL EFI_TAPE_IO_PROTOCOL;

 typedef struct _EFI_TAPE_HEADER {
   UINT64      Signature;
   UINT32      Revision;
   UINT32      BootDescSize;
   UINT32      BootDescCRC;
   EFI_GUID    TapeGUID;
   EFI_GUID    TapeType;
   EFI_GUID    TapeUnique;
   UINT32      BLLocation;
   UINT32      BLBlocksize;
   UINT32      BLFilesize;
   CHAR8       OSVersion[40];
   CHAR8       AppVersion[40];
   CHAR8       CreationDate[10];
   CHAR8       CreationTime[10];
   CHAR8       SystemName[256]; // UTF-8
   CHAR8       TapeTitle[120];  // UTF-8
   CHAR8       pad[468];        // pad to 1024
 } EFI_TAPE_HEADER;

 /**
   Reads from the tape.

   @param  This       A pointer to the EFI_TAPE_IO_PROTOCOL instance.
   @param  BufferSize The size of the buffer in bytes pointed to by Buffer.
   @param  Buffer     The pointer to the buffer for data to be read into.

   @retval EFI_SUCCESS           Data was successfully transferred from the media.
   @retval EFI_END_OF_FILE       A filemark was encountered which limited the data
                                 transferred by the read operation or the head is positioned
                                 just after a filemark.
   @retval EFI_NO_MEDIA          No media is loaded in the device.
   @retval EFI_NOT_READY         The transfer failed since the device was not ready (e.g. not
                                 online). The transfer may be retried at a later time.
   @retval EFI_UNSUPPORTED       The device does not support this type of transfer.
   @retval EFI_TIMEOUT           The transfer failed to complete within the timeout specified.
   @retval EFI_MEDIA_CHANGED     The media in the device was changed since the last access.
                                 The transfer was aborted since the current position of the
                                 media may be incorrect.
   @retval EFI_INVALID_PARAMETER A NULL Buffer was specified with a non-zero
                                 BufferSize, or the device is operating in fixed block
                                 size mode and the BufferSize was not a multiple of
                                 device's fixed block size
   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to transfer data
                                 from the media.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_TAPE_READ)(
   IN EFI_TAPE_IO_PROTOCOL *This,
   IN OUT UINTN            *BufferSize,
   OUT VOID                *Buffer
   );

 /**
   Writes to the tape.

   @param  This       A pointer to the EFI_TAPE_IO_PROTOCOL instance.
   @param  BufferSize Size of the buffer in bytes pointed to by Buffer.
   @param  Buffer     The pointer to the buffer for data to be written from.

   @retval EFI_SUCCESS           Data was successfully transferred to the media.
   @retval EFI_END_OF_MEDIA      The logical end of media has been reached. Data may have
                                 been successfully transferred to the media.
   @retval EFI_NO_MEDIA          No media is loaded in the device.
   @retval EFI_NOT_READY         The transfer failed since the device was not ready (e.g. not
                                 online). The transfer may be retried at a later time.
   @retval EFI_UNSUPPORTED       The device does not support this type of transfer.
   @retval EFI_TIMEOUT           The transfer failed to complete within the timeout specified.
   @retval EFI_MEDIA_CHANGED     The media in the device was changed since the last access.
                                 The transfer was aborted since the current position of the
                                 media may be incorrect.
   @retval EFI_WRITE_PROTECTED   The media in the device is write-protected. The transfer
                                 was aborted since a write cannot be completed.
   @retval EFI_INVALID_PARAMETER A NULL Buffer was specified with a non-zero
                                 BufferSize, or the device is operating in fixed block
                                 size mode and the BufferSize was not a multiple of
                                 device's fixed block size
   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to transfer data
                                 from the media.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_TAPE_WRITE)(
   IN EFI_TAPE_IO_PROTOCOL *This,
   IN UINTN                *BufferSize,
   IN VOID                 *Buffer
   );

 /**
   Rewinds the tape.

   @param  This A pointer to the EFI_TAPE_IO_PROTOCOL instance.

   @retval EFI_SUCCESS      The media was successfully repositioned.
   @retval EFI_NO_MEDIA     No media is loaded in the device.
   @retval EFI_NOT_READY    Repositioning the media failed since the device was not
                            ready (e.g. not online). The transfer may be retried at a later time.
   @retval EFI_UNSUPPORTED  The device does not support this type of media repositioning.
   @retval EFI_TIMEOUT      Repositioning of the media did not complete within the timeout specified.
   @retval EFI_DEVICE_ERROR A device error occurred while attempting to reposition the media.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_TAPE_REWIND)(
   IN EFI_TAPE_IO_PROTOCOL *This
   );

 /**
   Positions the tape.

   @param  This      A pointer to the EFI_TAPE_IO_PROTOCOL instance.
   @param  Direction Direction and number of data blocks or filemarks to space over on media.
   @param  Type      Type of mark to space over on media.
                     The following Type marks are mandatory:
                     BLOCK type    : 0
                     FILEMARK type : 1

   @retval EFI_SUCCESS       The media was successfully repositioned.
   @retval EFI_END_OF_MEDIA  Beginning or end of media was reached before the
                             indicated number of data blocks or filemarks were found.
   @retval EFI_NO_MEDIA      No media is loaded in the device.
   @retval EFI_NOT_READY     The reposition failed since the device was not ready (e.g. not
                             online). The reposition may be retried at a later time.
   @retval EFI_UNSUPPORTED   The device does not support this type of repositioning.
   @retval EFI_TIMEOUT       The repositioning failed to complete within the timeout specified.
   @retval EFI_MEDIA_CHANGED The media in the device was changed since the last access.
                             Repositioning the media was aborted since the current
                             position of the media may be incorrect.
   @retval EFI_DEVICE_ERROR  A device error occurred while attempting to reposition the media.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_TAPE_SPACE)(
   IN EFI_TAPE_IO_PROTOCOL *This,
   IN INTN                 Direction,
   IN UINTN                Type
   );

 /**
   Writes filemarks to the media.

   @param  This  A pointer to the EFI_TAPE_IO_PROTOCOL instance.
   @param  Count Number of filemarks to write to the media.

   @retval EFI_SUCCESS       Data was successfully transferred from the media.
   @retval EFI_NO_MEDIA      No media is loaded in the device.
   @retval EFI_NOT_READY     The transfer failed since the device was not ready (e.g. not
                             online). The transfer may be retried at a later time.
   @retval EFI_UNSUPPORTED   The device does not support this type of repositioning.
   @retval EFI_TIMEOUT       The transfer failed to complete within the timeout specified.
   @retval EFI_MEDIA_CHANGED The media in the device was changed since the last access.
                             The transfer was aborted since the current position of the
                             media may be incorrect.
   @retval EFI_DEVICE_ERROR  A device error occurred while attempting to transfer data from the media.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_TAPE_WRITEFM)(
   IN EFI_TAPE_IO_PROTOCOL *This,
   IN UINTN                Count
   );

 /**
   Resets the tape device.

   @param  This                 A pointer to the EFI_TAPE_IO_PROTOCOL instance.
   @param  ExtendedVerification Indicates whether the parent bus should also be reset.

   @retval  EFI_SUCCESS      The bus and/or device were successfully reset.
   @retval  EFI_NO_MEDIA     No media is loaded in the device.
   @retval  EFI_NOT_READY    The reset failed since the device and/or bus was not ready.
                             The reset may be retried at a later time.
   @retval  EFI_UNSUPPORTED  The device does not support this type of reset.
   @retval  EFI_TIMEOUT      The reset did not complete within the timeout allowed.
   @retval  EFI_DEVICE_ERROR A device error occurred while attempting to reset the bus and/or device.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_TAPE_RESET)(
   IN EFI_TAPE_IO_PROTOCOL *This,
   IN BOOLEAN              ExtendedVerification
   );

 ///
 /// The EFI_TAPE_IO_PROTOCOL provides basic sequential operations for tape devices.
 /// These include read, write, rewind, space, write filemarks and reset functions.
 /// Per this specification, a boot application uses the services of this protocol
 /// to load the bootloader image from tape.
 ///
 struct _EFI_TAPE_IO_PROTOCOL {
   EFI_TAPE_READ       TapeRead;
   EFI_TAPE_WRITE      TapeWrite;
   EFI_TAPE_REWIND     TapeRewind;
   EFI_TAPE_SPACE      TapeSpace;
   EFI_TAPE_WRITEFM    TapeWriteFM;
   EFI_TAPE_RESET      TapeReset;
 };

 extern EFI_GUID  gEfiTapeIoProtocolGuid;

 #endif
	/** @file
	EFI_TAPE_IO_PROTOCOL as defined in the UEFI 2.0.
	Provide services to control and access a tape device.

	Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
	SPDX-License-Identifier: BSD-2-Clause-Patent

	**/

	#ifndef __EFI_TAPE_IO_PROTOCOL_H__
	#define __EFI_TAPE_IO_PROTOCOL_H__

	#define EFI_TAPE_IO_PROTOCOL_GUID \
	{ \
	0x1e93e633, 0xd65a, 0x459e, {0xab, 0x84, 0x93, 0xd9, 0xec, 0x26, 0x6d, 0x18 } \
	}

	typedef struct _EFI_TAPE_IO_PROTOCOL EFI_TAPE_IO_PROTOCOL;

	typedef struct _EFI_TAPE_HEADER {
	UINT64 Signature;
	UINT32 Revision;
	UINT32 BootDescSize;
	UINT32 BootDescCRC;
	EFI_GUID TapeGUID;
	EFI_GUID TapeType;
	EFI_GUID TapeUnique;
	UINT32 BLLocation;
	UINT32 BLBlocksize;
	UINT32 BLFilesize;
	CHAR8 OSVersion[40];
	CHAR8 AppVersion[40];
	CHAR8 CreationDate[10];
	CHAR8 CreationTime[10];
	CHAR8 SystemName[256]; // UTF-8
	CHAR8 TapeTitle[120]; // UTF-8
	CHAR8 pad[468]; // pad to 1024
	} EFI_TAPE_HEADER;

	/**
	Reads from the tape.

	@param This A pointer to the EFI_TAPE_IO_PROTOCOL instance.
	@param BufferSize The size of the buffer in bytes pointed to by Buffer.
	@param Buffer The pointer to the buffer for data to be read into.

	@retval EFI_SUCCESS Data was successfully transferred from the media.
	@retval EFI_END_OF_FILE A filemark was encountered which limited the data
	transferred by the read operation or the head is positioned
	just after a filemark.
	@retval EFI_NO_MEDIA No media is loaded in the device.
	@retval EFI_NOT_READY The transfer failed since the device was not ready (e.g. not
	online). The transfer may be retried at a later time.
	@retval EFI_UNSUPPORTED The device does not support this type of transfer.
	@retval EFI_TIMEOUT The transfer failed to complete within the timeout specified.
	@retval EFI_MEDIA_CHANGED The media in the device was changed since the last access.
	The transfer was aborted since the current position of the
	media may be incorrect.
	@retval EFI_INVALID_PARAMETER A NULL Buffer was specified with a non-zero
	BufferSize, or the device is operating in fixed block
	size mode and the BufferSize was not a multiple of
	device's fixed block size
	@retval EFI_DEVICE_ERROR A device error occurred while attempting to transfer data
	from the media.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_TAPE_READ)(
	IN EFI_TAPE_IO_PROTOCOL *This,
	IN OUT UINTN *BufferSize,
	OUT VOID *Buffer
	);

	/**
	Writes to the tape.

	@param This A pointer to the EFI_TAPE_IO_PROTOCOL instance.
	@param BufferSize Size of the buffer in bytes pointed to by Buffer.
	@param Buffer The pointer to the buffer for data to be written from.

	@retval EFI_SUCCESS Data was successfully transferred to the media.
	@retval EFI_END_OF_MEDIA The logical end of media has been reached. Data may have
	been successfully transferred to the media.
	@retval EFI_NO_MEDIA No media is loaded in the device.
	@retval EFI_NOT_READY The transfer failed since the device was not ready (e.g. not
	online). The transfer may be retried at a later time.
	@retval EFI_UNSUPPORTED The device does not support this type of transfer.
	@retval EFI_TIMEOUT The transfer failed to complete within the timeout specified.
	@retval EFI_MEDIA_CHANGED The media in the device was changed since the last access.
	The transfer was aborted since the current position of the
	media may be incorrect.
	@retval EFI_WRITE_PROTECTED The media in the device is write-protected. The transfer
	was aborted since a write cannot be completed.
	@retval EFI_INVALID_PARAMETER A NULL Buffer was specified with a non-zero
	BufferSize, or the device is operating in fixed block
	size mode and the BufferSize was not a multiple of
	device's fixed block size
	@retval EFI_DEVICE_ERROR A device error occurred while attempting to transfer data
	from the media.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_TAPE_WRITE)(
	IN EFI_TAPE_IO_PROTOCOL *This,
	IN UINTN *BufferSize,
	IN VOID *Buffer
	);

	/**
	Rewinds the tape.

	@param This A pointer to the EFI_TAPE_IO_PROTOCOL instance.

	@retval EFI_SUCCESS The media was successfully repositioned.
	@retval EFI_NO_MEDIA No media is loaded in the device.
	@retval EFI_NOT_READY Repositioning the media failed since the device was not
	ready (e.g. not online). The transfer may be retried at a later time.
	@retval EFI_UNSUPPORTED The device does not support this type of media repositioning.
	@retval EFI_TIMEOUT Repositioning of the media did not complete within the timeout specified.
	@retval EFI_DEVICE_ERROR A device error occurred while attempting to reposition the media.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_TAPE_REWIND)(
	IN EFI_TAPE_IO_PROTOCOL *This
	);

	/**
	Positions the tape.

	@param This A pointer to the EFI_TAPE_IO_PROTOCOL instance.
	@param Direction Direction and number of data blocks or filemarks to space over on media.
	@param Type Type of mark to space over on media.
	The following Type marks are mandatory:
	BLOCK type : 0
	FILEMARK type : 1

	@retval EFI_SUCCESS The media was successfully repositioned.
	@retval EFI_END_OF_MEDIA Beginning or end of media was reached before the
	indicated number of data blocks or filemarks were found.
	@retval EFI_NO_MEDIA No media is loaded in the device.
	@retval EFI_NOT_READY The reposition failed since the device was not ready (e.g. not
	online). The reposition may be retried at a later time.
	@retval EFI_UNSUPPORTED The device does not support this type of repositioning.
	@retval EFI_TIMEOUT The repositioning failed to complete within the timeout specified.
	@retval EFI_MEDIA_CHANGED The media in the device was changed since the last access.
	Repositioning the media was aborted since the current
	position of the media may be incorrect.
	@retval EFI_DEVICE_ERROR A device error occurred while attempting to reposition the media.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_TAPE_SPACE)(
	IN EFI_TAPE_IO_PROTOCOL *This,
	IN INTN Direction,
	IN UINTN Type
	);

	/**
	Writes filemarks to the media.

	@param This A pointer to the EFI_TAPE_IO_PROTOCOL instance.
	@param Count Number of filemarks to write to the media.

	@retval EFI_SUCCESS Data was successfully transferred from the media.
	@retval EFI_NO_MEDIA No media is loaded in the device.
	@retval EFI_NOT_READY The transfer failed since the device was not ready (e.g. not
	online). The transfer may be retried at a later time.
	@retval EFI_UNSUPPORTED The device does not support this type of repositioning.
	@retval EFI_TIMEOUT The transfer failed to complete within the timeout specified.
	@retval EFI_MEDIA_CHANGED The media in the device was changed since the last access.
	The transfer was aborted since the current position of the
	media may be incorrect.
	@retval EFI_DEVICE_ERROR A device error occurred while attempting to transfer data from the media.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_TAPE_WRITEFM)(
	IN EFI_TAPE_IO_PROTOCOL *This,
	IN UINTN Count
	);

	/**
	Resets the tape device.

	@param This A pointer to the EFI_TAPE_IO_PROTOCOL instance.
	@param ExtendedVerification Indicates whether the parent bus should also be reset.

	@retval EFI_SUCCESS The bus and/or device were successfully reset.
	@retval EFI_NO_MEDIA No media is loaded in the device.
	@retval EFI_NOT_READY The reset failed since the device and/or bus was not ready.
	The reset may be retried at a later time.
	@retval EFI_UNSUPPORTED The device does not support this type of reset.
	@retval EFI_TIMEOUT The reset did not complete within the timeout allowed.
	@retval EFI_DEVICE_ERROR A device error occurred while attempting to reset the bus and/or device.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_TAPE_RESET)(
	IN EFI_TAPE_IO_PROTOCOL *This,
	IN BOOLEAN ExtendedVerification
	);

	///
	/// The EFI_TAPE_IO_PROTOCOL provides basic sequential operations for tape devices.
	/// These include read, write, rewind, space, write filemarks and reset functions.
	/// Per this specification, a boot application uses the services of this protocol
	/// to load the bootloader image from tape.
	///
	struct _EFI_TAPE_IO_PROTOCOL {
	EFI_TAPE_READ TapeRead;
	EFI_TAPE_WRITE TapeWrite;
	EFI_TAPE_REWIND TapeRewind;
	EFI_TAPE_SPACE TapeSpace;
	EFI_TAPE_WRITEFM TapeWriteFM;
	EFI_TAPE_RESET TapeReset;
	};

	extern EFI_GUID gEfiTapeIoProtocolGuid;

	#endif