4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Device Abstraction Utility Routines
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This program and the accompanying materials are licensed and made available
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync under the terms and conditions of the BSD License which accompanies this
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync distribution. The full text of the license may be found at
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Depends upon: <kfile.h>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef enum {
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync LIST_ENTRY DevList; ///< List of registered device abstractions
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync void *InstanceList; ///< Array of instances for this device
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync UINT32 InstanceSize; ///< Size of each instance in the InstanceList
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync UINT32 NumInstances; ///< Number of instances in InstanceList
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncextern LIST_ENTRY daDeviceList; ///< List of registered devices.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncextern DeviceNode *daDefaultDevice; ///< Device to use if nothing else found
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncextern DeviceNode *daRootDevice; ///< Device containing the root file system
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncextern DeviceNode *daCurrentDevice; ///< Device currently being accessed
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/** Add a new device to the device list.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param DevName Name of the device to add.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param DevProto Pointer to the GUID identifying the protocol associated with this device.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If DevProto is NULL, startup code will not try to find instances
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of this device.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param OpenFunc Pointer to the device's Open function.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param InstanceList Optional pointer to the device's initialized instance list.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If InstanceList is NULL, the application startup code will
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync scan for instances of the protocol identified by DevProto and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync populate the InstanceList in the order those protocols are found.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param NumInstance Number of instances in InstanceList.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param Modes Bit-mapped flags indicating operations (R, W, RW, ...) permitted to this device.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncDeviceNode * EFIAPI __DevRegister( const CHAR16 *DevName, GUID *DevProto, FO_OPEN OpenFunc,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync void *InstanceList, int NumInstance, UINT32 InstanceSize, UINT32 Modes);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/** Find a DeviceNode matching DevName or DevProto, or both.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If DevName is NULL, then the device name is not used in the search.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If DevProto is NULL, then the protocol GUID is not used in the search.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If both are NULL, then INVALID_PARAMETER is returned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If both DevName and DevProto are specified, then both must match.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If both are specified but only one matches, then DEVICE_ERROR is returned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param DevName Name of the Device Abstraction to find.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param DevProto GUID of the Protocol associated with the Device Abstraction.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param Node Pointer to the pointer to receive the found Device Node's address.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_SUCCESS The desired Device Node was found.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_INVALID_PARAMETER Both DevName and DevProto are NULL or Node is NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_DEVICE_ERROR One, but not both, of DevNode and DevProto matched.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncEFI_STATUS EFIAPI __DevSearch( CHAR16 *DevName, GUID *DevProto, DeviceNode **Node);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/** Identify the type of path pointed to by Path.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Paths are classified based upon their initial character sequences.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ^\\ Absolute Path
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ^\. Relative Path
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ^[^:\\]: Mapping Path
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync .* Relative Path
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Mapping paths are broken into two parts at the ':'. The part to the left of the ':'
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync is the Map Name, pointed to by Path, and the part to the right of the ':' is pointed
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync to by NewPath.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If Path was not a Mapping Path, then NewPath is set to Path.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Path Pointer to the path to be classified.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] NewPath Pointer to the path portion of a mapping path.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval PathAbsolute Path is an absolute path. NewPath points to the first '\'.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval PathRelative Path is a relative path. NewPath = Path.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval PathMapping Path is a mapping path. NewPath points to the ':'.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval PathError Path is NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncPATH_CLASS EFIAPI ClassifyPath(IN wchar_t *Path, OUT wchar_t **NewPath, int * const Length);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/* Normalize a narrow-character path and produce a wide-character path
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync that has forward slashes replaced with backslashes.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Backslashes are directory separators in UEFI File Paths.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync It is the caller's responsibility to eventually free() the returned buffer.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] path A pointer to the narrow-character path to be normalized.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @return A pointer to a buffer containing the normalized, wide-character, path.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/** Process a MBCS path returning the final absolute path and the target device.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param path
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param FullPath
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param DevNode
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_SUCCESS
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_INVALID_PARAMETER
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_NOT_FOUND
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncParsePath( const char *path, wchar_t **FullPath, DeviceNode **DevNode, int *Which, wchar_t **MapPath);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/** Process a wide character string representing a Mapping Path and extract the instance number.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The instance number is the sequence of decimal digits immediately to the left
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of the ":" in the Map Name portion of a Mapping Path.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This function is called with a pointer to beginning of the Map Name.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Thus Path[Length] must be a ':' and Path[Length - 1] must be a decimal digit.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If either of these are not true, an instance value of 0 is returned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If Path is NULL, an instance value of 0 is returned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Path Points to the beginning of a Mapping Path
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Length Number of valid characters to the left of the ':'
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @return Returns either 0 or the value of the contiguous digits to the left of the ':'.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/** Transform a relative path into an absolute path.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If Path is NULL, return NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Otherwise, pre-pend the CWD to Path then process the resulting path to:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync - Replace "/./" with "/"
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync - Replace "/<dirname>/../" with "/"
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync - Do not allow one to back up past the root, "/"
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Also sets the Current Working Device to the Root Device.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Path must be a previously allocated buffer. PathAdjust will
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync allocate a new buffer to hold the results of the transformation
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync then free Path. A pointer to the newly allocated buffer is returned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Path A pointer to the path to be transformed. This buffer
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync will always be freed.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @return A pointer to a buffer containing the transformed path.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/** Replace the leading portion of Path with any aliases.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Aliases are read from /etc/fstab. If there is an associated device, the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Current Working Device is set to that device.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Path must be a previously allocated buffer. PathAlias will
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync allocate a new buffer to hold the results of the transformation
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync then free Path. A pointer to the newly allocated buffer is returned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Path A pointer to the original, unaliased, path. This
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync buffer is always freed.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] Node Filled in with a pointer to the Device Node describing
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the device abstraction associated with this path.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @return A pointer to a buffer containing the aliased path.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Parses a normalized wide character path and returns a pointer to the entry
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync following the last \. If a \ is not found in the path the return value will
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync be the same as the input value. All error conditions return NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The behavior when passing in a path that has not been normalized is undefined.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param Path - A pointer to a wide character string containing a path to a
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync directory or a file.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @return Pointer to the file name or terminal directory. NULL if an error is
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync#endif /* __DEV_UTILITY_H__ */