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