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