[mirror_edk2.git] / MdePkg / Include / Protocol / TapeIo.h

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