/** @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
+ Copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>\r
\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
+ 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
-SemihostFsSupported(\r
- IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
- IN EFI_HANDLE Controller,\r
- IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
- );\r
-\r
-EFI_STATUS\r
-SemihostFsStart(\r
- IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
- IN EFI_HANDLE Controller,\r
- IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
- );\r
+#ifndef SEMIHOST_FS_H_\r
+#define SEMIHOST_FS_H_\r
\r
EFI_STATUS\r
-SemihostFsStop(\r
- IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
- IN EFI_HANDLE Controller,\r
- IN UINTN NumberOfChildren,\r
- IN EFI_HANDLE *ChildHandleBuffer\r
+VolumeOpen (\r
+ IN EFI_SIMPLE_FILE_SYSTEM_PROTOCOL *This,\r
+ OUT EFI_FILE **Root\r
);\r
\r
-EFI_STATUS\r
-VolumeOpen(\r
- IN EFI_SIMPLE_FILE_SYSTEM_PROTOCOL *This,\r
- OUT EFI_FILE **Root\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 *File,\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 *File\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 *File\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 *File,\r
- IN OUT UINTN *BufferSize,\r
- OUT VOID *Buffer\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 *File,\r
- IN OUT UINTN *BufferSize,\r
- IN VOID *Buffer\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
+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
+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 *File,\r
- IN EFI_GUID *InformationType,\r
- IN OUT UINTN *BufferSize,\r
- OUT VOID *Buffer\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 *File,\r
- IN EFI_GUID *InformationType,\r
- IN UINTN BufferSize,\r
- IN VOID *Buffer\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
+FileFlush (\r
+ IN EFI_FILE *File\r
);\r
\r
-#endif // __SEMIHOST_FS_H__\r
-\r
+#endif // SEMIHOST_FS_H_\r
projects / mirror_edk2.git / blobdiff