[mirror_edk2.git] / ArmPkg / Filesystem / SemihostFs / Arm / SemihostFs.h

/** @file\r
  Support a Semi Host file system over a debuggers JTAG\r
\r
  Copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef SEMIHOST_FS_H_\r
#define SEMIHOST_FS_H_\r
\r
EFI_STATUS\r
VolumeOpen (\r
  IN  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL *This,\r
  OUT EFI_FILE                        **Root\r
  );\r
\r
/**\r
  Open a file on the host system by means of the semihosting interface.\r
\r
  @param[in]   This        A pointer to the EFI_FILE_PROTOCOL instance that is\r
                           the file handle to source location.\r
  @param[out]  NewHandle   A pointer to the location to return the opened\r
                           handle for the new file.\r
  @param[in]   FileName    The Null-terminated string of the name of the file\r
                           to be opened.\r
  @param[in]   OpenMode    The mode to open the file : Read or Read/Write or\r
                           Read/Write/Create\r
  @param[in]   Attributes  Only valid for EFI_FILE_MODE_CREATE, in which case these\r
                           are the attribute bits for the newly created file. The\r
                           mnemonics of the attribute bits are : EFI_FILE_READ_ONLY,\r
                           EFI_FILE_HIDDEN, EFI_FILE_SYSTEM, EFI_FILE_RESERVED,\r
                           EFI_FILE_DIRECTORY and EFI_FILE_ARCHIVE.\r
\r
  @retval  EFI_SUCCESS            The file was open.\r
  @retval  EFI_NOT_FOUND          The specified file could not be found.\r
  @retval  EFI_DEVICE_ERROR       The last issued semi-hosting operation failed.\r
  @retval  EFI_WRITE_PROTECTED    Attempt to create a directory. This is not possible\r
                                  with the semi-hosting interface.\r
  @retval  EFI_OUT_OF_RESOURCES   Not enough resources were available to open the file.\r
  @retval  EFI_INVALID_PARAMETER  At least one of the parameters is invalid.\r
\r
**/\r
EFI_STATUS\r
FileOpen (\r
  IN  EFI_FILE  *This,\r
  OUT EFI_FILE  **NewHandle,\r
  IN  CHAR16    *FileName,\r
  IN  UINT64    OpenMode,\r
  IN  UINT64    Attributes\r
  );\r
\r
/**\r
  Close a specified file handle.\r
\r
  @param[in]  This  A pointer to the EFI_FILE_PROTOCOL instance that is the file\r
                    handle to close.\r
\r
  @retval  EFI_SUCCESS            The file was closed.\r
  @retval  EFI_INVALID_PARAMETER  The parameter "This" is NULL.\r
\r
**/\r
EFI_STATUS\r
FileClose (\r
  IN EFI_FILE  *This\r
  );\r
\r
/**\r
  Close and delete a file.\r
\r
  @param[in]  This  A pointer to the EFI_FILE_PROTOCOL instance that is the file\r
                    handle to delete.\r
\r
  @retval  EFI_SUCCESS              The file was closed and deleted.\r
  @retval  EFI_WARN_DELETE_FAILURE  The handle was closed, but the file was not deleted.\r
  @retval  EFI_INVALID_PARAMETER    The parameter "This" is NULL.\r
\r
**/\r
EFI_STATUS\r
FileDelete (\r
  IN EFI_FILE *This\r
  );\r
\r
/**\r
  Read data from an open file.\r
\r
  @param[in]      This        A pointer to the EFI_FILE_PROTOCOL instance that\r
                              is the file handle to read data from.\r
  @param[in out]  BufferSize  On input, the size of the Buffer. On output, the\r
                              amount of data returned in Buffer. In both cases,\r
                              the size is measured in bytes.\r
  @param[out]     Buffer      The buffer into which the data is read.\r
\r
  @retval  EFI_SUCCESS            The data was read.\r
  @retval  EFI_DEVICE_ERROR       On entry, the current file position is\r
                                  beyond the end of the file, or the semi-hosting\r
                                  interface reported an error while performing the\r
                                  read operation.\r
  @retval  EFI_INVALID_PARAMETER  The parameter "This" or the parameter "Buffer"\r
                                  is NULL.\r
**/\r
EFI_STATUS\r
FileRead (\r
  IN     EFI_FILE  *This,\r
  IN OUT UINTN     *BufferSize,\r
  OUT    VOID      *Buffer\r
  );\r
\r
/**\r
  Write data to an open file.\r
\r
  @param[in]      This        A pointer to the EFI_FILE_PROTOCOL instance that\r
                              is the file handle to write data to.\r
  @param[in out]  BufferSize  On input, the size of the Buffer. On output, the\r
                              size of the data actually written. In both cases,\r
                              the size is measured in bytes.\r
  @param[in]      Buffer      The buffer of data to write.\r
\r
  @retval  EFI_SUCCESS            The data was written.\r
  @retval  EFI_ACCESS_DENIED      Attempt to write into a read only file or\r
                                  in a file opened in read only mode.\r
  @retval  EFI_DEVICE_ERROR       The last issued semi-hosting operation failed.\r
  @retval  EFI_INVALID_PARAMETER  The parameter "This" or the parameter "Buffer"\r
                                  is NULL.\r
\r
**/\r
EFI_STATUS\r
FileWrite (\r
  IN     EFI_FILE *This,\r
  IN OUT UINTN    *BufferSize,\r
  IN     VOID     *Buffer\r
  );\r
\r
/**\r
  Return a file's current position.\r
\r
  @param[in]   This      A pointer to the EFI_FILE_PROTOCOL instance that is\r
                         the file handle to get the current position on.\r
  @param[out]  Position  The address to return the file's current position value.\r
\r
  @retval  EFI_SUCCESS            The position was returned.\r
  @retval  EFI_INVALID_PARAMETER  Position is a NULL pointer.\r
\r
**/\r
EFI_STATUS\r
FileGetPosition (\r
  IN  EFI_FILE    *File,\r
  OUT UINT64      *Position\r
  );\r
\r
/**\r
  Set a file's current position.\r
\r
  @param[in]  This      A pointer to the EFI_FILE_PROTOCOL instance that is\r
                        the file handle to set the requested position on.\r
  @param[in]  Position  The byte position from the start of the file to set.\r
\r
  @retval  EFI_SUCCESS       The position was set.\r
  @retval  EFI_DEVICE_ERROR  The semi-hosting positioning operation failed.\r
  @retval  EFI_UNSUPPORTED   The seek request for nonzero is not valid on open\r
                             directories.\r
\r
**/\r
EFI_STATUS\r
FileSetPosition (\r
  IN EFI_FILE *File,\r
  IN UINT64   Position\r
  );\r
\r
/**\r
  Return information about a file or a file system.\r
\r
  @param[in]      This             A pointer to the EFI_FILE_PROTOCOL instance that\r
                                   is the file handle the requested information is for.\r
  @param[in]      InformationType  The type identifier for the information being requested :\r
                                   EFI_FILE_INFO_ID or EFI_FILE_SYSTEM_INFO_ID or\r
                                   EFI_FILE_SYSTEM_VOLUME_LABEL_ID\r
  @param[in out]  BufferSize       The size, in bytes, of Buffer.\r
  @param[out]     Buffer           A pointer to the data buffer to return. The type of the\r
                                   data inside the buffer is indicated by InformationType.\r
\r
  @retval  EFI_SUCCESS           The information was returned.\r
  @retval  EFI_UNSUPPORTED       The InformationType is not known.\r
  @retval  EFI_BUFFER_TOO_SMALL  The BufferSize is too small to return the information.\r
                                 BufferSize has been updated with the size needed to\r
                                 complete the request.\r
  @retval  EFI_INVALID_PARAMETER  The parameter "This" or the parameter "Buffer"\r
                                  is NULL.\r
\r
**/\r
EFI_STATUS\r
FileGetInfo (\r
  IN     EFI_FILE  *This,\r
  IN     EFI_GUID  *InformationType,\r
  IN OUT UINTN     *BufferSize,\r
  OUT    VOID      *Buffer\r
  );\r
\r
/**\r
  Set information about a file or a file system.\r
\r
  @param[in]  This             A pointer to the EFI_FILE_PROTOCOL instance that\r
                               is the file handle the information is for.\r
  @param[in]  InformationType  The type identifier for the information being set :\r
                               EFI_FILE_INFO_ID or EFI_FILE_SYSTEM_INFO_ID or\r
                               EFI_FILE_SYSTEM_VOLUME_LABEL_ID\r
  @param[in]  BufferSize       The size, in bytes, of Buffer.\r
  @param[in]  Buffer           A pointer to the data buffer to write. The type of the\r
                               data inside the buffer is indicated by InformationType.\r
\r
  @retval  EFI_SUCCESS            The information was set.\r
  @retval  EFI_UNSUPPORTED        The InformationType is not known.\r
  @retval  EFI_DEVICE_ERROR       The last issued semi-hosting operation failed.\r
  @retval  EFI_ACCESS_DENIED      An attempt is being made to change the\r
                                  EFI_FILE_DIRECTORY Attribute.\r
  @retval  EFI_ACCESS_DENIED      InformationType is EFI_FILE_INFO_ID and\r
                                  the file is a read-only file or has been\r
                                  opened in read-only mode and an attempt is\r
                                  being made to modify a field other than\r
                                  Attribute.\r
  @retval  EFI_ACCESS_DENIED      An attempt is made to change the name of a file\r
                                  to a file that is already present.\r
  @retval  EFI_WRITE_PROTECTED    An attempt is being made to modify a\r
                                  read-only attribute.\r
  @retval  EFI_BAD_BUFFER_SIZE    The size of the buffer is lower than that indicated by\r
                                  the data inside the buffer.\r
  @retval  EFI_OUT_OF_RESOURCES   An allocation needed to process the request failed.\r
  @retval  EFI_INVALID_PARAMETER  At least one of the parameters is invalid.\r
\r
**/\r
EFI_STATUS\r
FileSetInfo (\r
  IN EFI_FILE  *This,\r
  IN EFI_GUID  *InformationType,\r
  IN UINTN     BufferSize,\r
  IN VOID      *Buffer\r
  );\r
\r
EFI_STATUS\r
FileFlush (\r
  IN EFI_FILE *File\r
  );\r
\r
#endif // SEMIHOST_FS_H_\r
\r
Commit	Line	Data
2ef2b01e A	1	/** @file\r
	2	Support a Semi Host file system over a debuggers JTAG\r
	3	\r
d6ebcab7	4	Copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>\r
2ef2b01e	5	\r
4059386c	6	SPDX-License-Identifier: BSD-2-Clause-Patent\r
2ef2b01e A	7	\r
	8	**/\r
	9	\r
cc15a619 PG	10	#ifndef SEMIHOST_FS_H_\r
cc15a619 PG	11	#define SEMIHOST_FS_H_\r
2ef2b01e A	12	\r
2ef2b01e A	13	EFI_STATUS\r
b34e4db3	14	VolumeOpen (\r
2ef2b01e A	15	IN EFI_SIMPLE_FILE_SYSTEM_PROTOCOL *This,\r
	16	OUT EFI_FILE **Root\r
	17	);\r
	18	\r
fdd12bd5 RC	19	/**\r
	20	Open a file on the host system by means of the semihosting interface.\r
	21	\r
	22	@param[in] This A pointer to the EFI_FILE_PROTOCOL instance that is\r
	23	the file handle to source location.\r
	24	@param[out] NewHandle A pointer to the location to return the opened\r
	25	handle for the new file.\r
	26	@param[in] FileName The Null-terminated string of the name of the file\r
	27	to be opened.\r
	28	@param[in] OpenMode The mode to open the file : Read or Read/Write or\r
	29	Read/Write/Create\r
	30	@param[in] Attributes Only valid for EFI_FILE_MODE_CREATE, in which case these\r
	31	are the attribute bits for the newly created file. The\r
	32	mnemonics of the attribute bits are : EFI_FILE_READ_ONLY,\r
	33	EFI_FILE_HIDDEN, EFI_FILE_SYSTEM, EFI_FILE_RESERVED,\r
	34	EFI_FILE_DIRECTORY and EFI_FILE_ARCHIVE.\r
	35	\r
	36	@retval EFI_SUCCESS The file was open.\r
	37	@retval EFI_NOT_FOUND The specified file could not be found.\r
	38	@retval EFI_DEVICE_ERROR The last issued semi-hosting operation failed.\r
	39	@retval EFI_WRITE_PROTECTED Attempt to create a directory. This is not possible\r
	40	with the semi-hosting interface.\r
	41	@retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the file.\r
	42	@retval EFI_INVALID_PARAMETER At least one of the parameters is invalid.\r
	43	\r
	44	**/\r
2ef2b01e	45	EFI_STATUS\r
b34e4db3	46	FileOpen (\r
fdd12bd5	47	IN EFI_FILE *This,\r
2ef2b01e A	48	OUT EFI_FILE **NewHandle,\r
	49	IN CHAR16 *FileName,\r
	50	IN UINT64 OpenMode,\r
	51	IN UINT64 Attributes\r
	52	);\r
	53	\r
daefd574 RC	54	/**\r
	55	Close a specified file handle.\r
	56	\r
	57	@param[in] This A pointer to the EFI_FILE_PROTOCOL instance that is the file\r
	58	handle to close.\r
	59	\r
	60	@retval EFI_SUCCESS The file was closed.\r
	61	@retval EFI_INVALID_PARAMETER The parameter "This" is NULL.\r
	62	\r
	63	**/\r
2ef2b01e	64	EFI_STATUS\r
b34e4db3	65	FileClose (\r
daefd574	66	IN EFI_FILE *This\r
2ef2b01e A	67	);\r
2ef2b01e A	68	\r
daefd574 RC	69	/**\r
	70	Close and delete a file.\r
	71	\r
	72	@param[in] This A pointer to the EFI_FILE_PROTOCOL instance that is the file\r
	73	handle to delete.\r
	74	\r
	75	@retval EFI_SUCCESS The file was closed and deleted.\r
	76	@retval EFI_WARN_DELETE_FAILURE The handle was closed, but the file was not deleted.\r
	77	@retval EFI_INVALID_PARAMETER The parameter "This" is NULL.\r
	78	\r
	79	**/\r
2ef2b01e	80	EFI_STATUS\r
daefd574 RC	81	FileDelete (\r
daefd574 RC	82	IN EFI_FILE *This\r
2ef2b01e A	83	);\r
2ef2b01e A	84	\r
daefd574 RC	85	/**\r
	86	Read data from an open file.\r
	87	\r
	88	@param[in] This A pointer to the EFI_FILE_PROTOCOL instance that\r
	89	is the file handle to read data from.\r
	90	@param[in out] BufferSize On input, the size of the Buffer. On output, the\r
	91	amount of data returned in Buffer. In both cases,\r
	92	the size is measured in bytes.\r
	93	@param[out] Buffer The buffer into which the data is read.\r
	94	\r
	95	@retval EFI_SUCCESS The data was read.\r
	96	@retval EFI_DEVICE_ERROR On entry, the current file position is\r
	97	beyond the end of the file, or the semi-hosting\r
	98	interface reported an error while performing the\r
	99	read operation.\r
	100	@retval EFI_INVALID_PARAMETER The parameter "This" or the parameter "Buffer"\r
	101	is NULL.\r
	102	**/\r
2ef2b01e	103	EFI_STATUS\r
b34e4db3	104	FileRead (\r
daefd574 RC	105	IN EFI_FILE *This,\r
	106	IN OUT UINTN *BufferSize,\r
	107	OUT VOID *Buffer\r
2ef2b01e A	108	);\r
2ef2b01e A	109	\r
daefd574 RC	110	/**\r
	111	Write data to an open file.\r
	112	\r
	113	@param[in] This A pointer to the EFI_FILE_PROTOCOL instance that\r
	114	is the file handle to write data to.\r
	115	@param[in out] BufferSize On input, the size of the Buffer. On output, the\r
	116	size of the data actually written. In both cases,\r
	117	the size is measured in bytes.\r
	118	@param[in] Buffer The buffer of data to write.\r
	119	\r
	120	@retval EFI_SUCCESS The data was written.\r
	121	@retval EFI_ACCESS_DENIED Attempt to write into a read only file or\r
	122	in a file opened in read only mode.\r
	123	@retval EFI_DEVICE_ERROR The last issued semi-hosting operation failed.\r
	124	@retval EFI_INVALID_PARAMETER The parameter "This" or the parameter "Buffer"\r
	125	is NULL.\r
	126	\r
	127	**/\r
2ef2b01e	128	EFI_STATUS\r
b34e4db3	129	FileWrite (\r
daefd574	130	IN EFI_FILE *This,\r
2ef2b01e A	131	IN OUT UINTN *BufferSize,\r
	132	IN VOID *Buffer\r
	133	);\r
	134	\r
daefd574 RC	135	/**\r
	136	Return a file's current position.\r
	137	\r
	138	@param[in] This A pointer to the EFI_FILE_PROTOCOL instance that is\r
	139	the file handle to get the current position on.\r
	140	@param[out] Position The address to return the file's current position value.\r
	141	\r
	142	@retval EFI_SUCCESS The position was returned.\r
	143	@retval EFI_INVALID_PARAMETER Position is a NULL pointer.\r
	144	\r
	145	**/\r
2ef2b01e	146	EFI_STATUS\r
b34e4db3	147	FileGetPosition (\r
daefd574 RC	148	IN EFI_FILE *File,\r
daefd574 RC	149	OUT UINT64 *Position\r
2ef2b01e A	150	);\r
2ef2b01e A	151	\r
daefd574 RC	152	/**\r
	153	Set a file's current position.\r
	154	\r
	155	@param[in] This A pointer to the EFI_FILE_PROTOCOL instance that is\r
	156	the file handle to set the requested position on.\r
	157	@param[in] Position The byte position from the start of the file to set.\r
	158	\r
	159	@retval EFI_SUCCESS The position was set.\r
ff5fef14	160	@retval EFI_DEVICE_ERROR The semi-hosting positioning operation failed.\r
daefd574 RC	161	@retval EFI_UNSUPPORTED The seek request for nonzero is not valid on open\r
	162	directories.\r
	163	\r
	164	**/\r
2ef2b01e	165	EFI_STATUS\r
b34e4db3	166	FileSetPosition (\r
2ef2b01e A	167	IN EFI_FILE *File,\r
	168	IN UINT64 Position\r
	169	);\r
	170	\r
daefd574 RC	171	/**\r
	172	Return information about a file or a file system.\r
	173	\r
	174	@param[in] This A pointer to the EFI_FILE_PROTOCOL instance that\r
	175	is the file handle the requested information is for.\r
	176	@param[in] InformationType The type identifier for the information being requested :\r
	177	EFI_FILE_INFO_ID or EFI_FILE_SYSTEM_INFO_ID or\r
	178	EFI_FILE_SYSTEM_VOLUME_LABEL_ID\r
	179	@param[in out] BufferSize The size, in bytes, of Buffer.\r
	180	@param[out] Buffer A pointer to the data buffer to return. The type of the\r
	181	data inside the buffer is indicated by InformationType.\r
	182	\r
	183	@retval EFI_SUCCESS The information was returned.\r
	184	@retval EFI_UNSUPPORTED The InformationType is not known.\r
	185	@retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to return the information.\r
	186	BufferSize has been updated with the size needed to\r
	187	complete the request.\r
	188	@retval EFI_INVALID_PARAMETER The parameter "This" or the parameter "Buffer"\r
	189	is NULL.\r
	190	\r
	191	**/\r
2ef2b01e	192	EFI_STATUS\r
b34e4db3	193	FileGetInfo (\r
daefd574 RC	194	IN EFI_FILE *This,\r
	195	IN EFI_GUID *InformationType,\r
	196	IN OUT UINTN *BufferSize,\r
	197	OUT VOID *Buffer\r
2ef2b01e A	198	);\r
2ef2b01e A	199	\r
daefd574 RC	200	/**\r
	201	Set information about a file or a file system.\r
	202	\r
	203	@param[in] This A pointer to the EFI_FILE_PROTOCOL instance that\r
	204	is the file handle the information is for.\r
	205	@param[in] InformationType The type identifier for the information being set :\r
	206	EFI_FILE_INFO_ID or EFI_FILE_SYSTEM_INFO_ID or\r
	207	EFI_FILE_SYSTEM_VOLUME_LABEL_ID\r
	208	@param[in] BufferSize The size, in bytes, of Buffer.\r
	209	@param[in] Buffer A pointer to the data buffer to write. The type of the\r
	210	data inside the buffer is indicated by InformationType.\r
	211	\r
	212	@retval EFI_SUCCESS The information was set.\r
	213	@retval EFI_UNSUPPORTED The InformationType is not known.\r
	214	@retval EFI_DEVICE_ERROR The last issued semi-hosting operation failed.\r
	215	@retval EFI_ACCESS_DENIED An attempt is being made to change the\r
	216	EFI_FILE_DIRECTORY Attribute.\r
	217	@retval EFI_ACCESS_DENIED InformationType is EFI_FILE_INFO_ID and\r
	218	the file is a read-only file or has been\r
	219	opened in read-only mode and an attempt is\r
	220	being made to modify a field other than\r
	221	Attribute.\r
	222	@retval EFI_ACCESS_DENIED An attempt is made to change the name of a file\r
	223	to a file that is already present.\r
	224	@retval EFI_WRITE_PROTECTED An attempt is being made to modify a\r
	225	read-only attribute.\r
	226	@retval EFI_BAD_BUFFER_SIZE The size of the buffer is lower than that indicated by\r
	227	the data inside the buffer.\r
	228	@retval EFI_OUT_OF_RESOURCES An allocation needed to process the request failed.\r
	229	@retval EFI_INVALID_PARAMETER At least one of the parameters is invalid.\r
	230	\r
	231	**/\r
2ef2b01e	232	EFI_STATUS\r
b34e4db3	233	FileSetInfo (\r
daefd574 RC	234	IN EFI_FILE *This,\r
	235	IN EFI_GUID *InformationType,\r
	236	IN UINTN BufferSize,\r
	237	IN VOID *Buffer\r
2ef2b01e A	238	);\r
	239	\r
	240	EFI_STATUS\r
b34e4db3	241	FileFlush (\r
2ef2b01e A	242	IN EFI_FILE *File\r
	243	);\r
	244	\r
cc15a619	245	#endif // SEMIHOST_FS_H_\r
2ef2b01e	246	\r