1 /** @file 2 Device Abstraction Utility Routines 3 4 Copyright (c) 2011, Intel Corporation. All rights reserved.<BR> 5 This program and the accompanying materials are licensed and made available 6 under the terms and conditions of the BSD License which accompanies this 7 distribution. The full text of the license may be found at 8 http://opensource.org/licenses/bsd-license.php. 9 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13 Depends upon: <kfile.h> 14 **/ 15 #ifndef __DEV_UTILITY_H__ 16 #define __DEV_UTILITY_H__ 17 18 #define CON_COOKIE 0x62416F49 ///< 'IoAb' 19 20 typedef enum { 21 PathAbsolute = 0, 22 PathRelative, 23 PathMapping, 24 PathError 25 } PATH_CLASS; 26 27 typedef struct _Device_Node { 28 LIST_ENTRY DevList; ///< List of registered device abstractions 29 const CHAR16 *DevName; 30 const GUID *DevProto; 31 void *InstanceList; ///< Array of instances for this device 32 FO_OPEN OpenFunc; 33 UINT32 InstanceSize; ///< Size of each instance in the InstanceList 34 UINT32 NumInstances; ///< Number of instances in InstanceList 35 UINT32 OpModes; ///< Supported modes of operation 36 } DeviceNode; 37 38 __BEGIN_DECLS 39 40 extern LIST_ENTRY daDeviceList; ///< List of registered devices. 41 extern DeviceNode *daDefaultDevice; ///< Device to use if nothing else found 42 extern DeviceNode *daRootDevice; ///< Device containing the root file system 43 extern DeviceNode *daCurrentDevice; ///< Device currently being accessed 44 45 /** Add a new device to the device list. 46 47 @param DevName Name of the device to add. 48 @param DevProto Pointer to the GUID identifying the protocol associated with this device. 49 If DevProto is NULL, startup code will not try to find instances 50 of this device. 51 @param OpenFunc Pointer to the device's Open function. 52 @param InstanceList Optional pointer to the device's initialized instance list. 53 If InstanceList is NULL, the application startup code will 54 scan for instances of the protocol identified by DevProto and 55 populate the InstanceList in the order those protocols are found. 56 @param NumInstance Number of instances in InstanceList. 57 @param Modes Bit-mapped flags indicating operations (R, W, RW, ...) permitted to this device. 58 59 **/ 60 DeviceNode * EFIAPI __DevRegister( const CHAR16 *DevName, GUID *DevProto, FO_OPEN OpenFunc, 61 void *InstanceList, int NumInstance, UINT32 InstanceSize, UINT32 Modes); 62 63 /** Find a DeviceNode matching DevName or DevProto, or both. 64 65 If DevName is NULL, then the device name is not used in the search. 66 If DevProto is NULL, then the protocol GUID is not used in the search. 67 If both are NULL, then INVALID_PARAMETER is returned. 68 If both DevName and DevProto are specified, then both must match. 69 If both are specified but only one matches, then DEVICE_ERROR is returned. 70 71 @param DevName Name of the Device Abstraction to find. 72 @param DevProto GUID of the Protocol associated with the Device Abstraction. 73 @param Node Pointer to the pointer to receive the found Device Node's address. 74 75 @retval RETURN_SUCCESS The desired Device Node was found. 76 @retval RETURN_INVALID_PARAMETER Both DevName and DevProto are NULL or Node is NULL. 77 @retval RETURN_DEVICE_ERROR One, but not both, of DevNode and DevProto matched. 78 **/ 79 EFI_STATUS EFIAPI __DevSearch( CHAR16 *DevName, GUID *DevProto, DeviceNode **Node); 80 81 /** Identify the type of path pointed to by Path. 82 83 Paths are classified based upon their initial character sequences. 84 ^\\ Absolute Path 85 ^\. Relative Path 86 ^[^:\\]: Mapping Path 87 .* Relative Path 88 89 Mapping paths are broken into two parts at the ':'. The part to the left of the ':' 90 is the Map Name, pointed to by Path, and the part to the right of the ':' is pointed 91 to by NewPath. 92 93 If Path was not a Mapping Path, then NewPath is set to Path. 94 95 @param[in] Path Pointer to the path to be classified. 96 @param[out] NewPath Pointer to the path portion of a mapping path. 97 98 @retval PathAbsolute Path is an absolute path. NewPath points to the first '\'. 99 @retval PathRelative Path is a relative path. NewPath = Path. 100 @retval PathMapping Path is a mapping path. NewPath points to the ':'. 101 @retval PathError Path is NULL. 102 **/ 103 PATH_CLASS EFIAPI ClassifyPath(IN wchar_t *Path, OUT wchar_t **NewPath, int * const Length); 104 105 /* Normalize a narrow-character path and produce a wide-character path 106 that has forward slashes replaced with backslashes. 107 Backslashes are directory separators in UEFI File Paths. 108 109 It is the caller's responsibility to eventually free() the returned buffer. 110 111 @param[in] path A pointer to the narrow-character path to be normalized. 112 113 @return A pointer to a buffer containing the normalized, wide-character, path. 114 */ 115 wchar_t * 116 NormalizePath( const char *path); 117 118 /** Process a MBCS path returning the final absolute path and the target device. 119 120 @param path 121 @param FullPath 122 @param DevNode 123 124 @retval RETURN_SUCCESS 125 @retval RETURN_INVALID_PARAMETER 126 @retval RETURN_NOT_FOUND 127 **/ 128 RETURN_STATUS 129 EFIAPI 130 ParsePath( const char *path, wchar_t **FullPath, DeviceNode **DevNode, int *Which, wchar_t **MapPath); 131 132 /** Process a wide character string representing a Mapping Path and extract the instance number. 133 134 The instance number is the sequence of decimal digits immediately to the left 135 of the ":" in the Map Name portion of a Mapping Path. 136 137 This function is called with a pointer to beginning of the Map Name. 138 Thus Path[Length] must be a ':' and Path[Length - 1] must be a decimal digit. 139 If either of these are not true, an instance value of 0 is returned. 140 141 If Path is NULL, an instance value of 0 is returned. 142 143 @param[in] Path Points to the beginning of a Mapping Path 144 @param[in] Length Number of valid characters to the left of the ':' 145 146 @return Returns either 0 or the value of the contiguous digits to the left of the ':'. 147 **/ 148 int 149 EFIAPI 150 PathInstance( const wchar_t *Path, int length); 151 152 /** Transform a relative path into an absolute path. 153 154 If Path is NULL, return NULL. 155 Otherwise, pre-pend the CWD to Path then process the resulting path to: 156 - Replace "/./" with "/" 157 - Replace "/<dirname>/../" with "/" 158 - Do not allow one to back up past the root, "/" 159 160 Also sets the Current Working Device to the Root Device. 161 162 Path must be a previously allocated buffer. PathAdjust will 163 allocate a new buffer to hold the results of the transformation 164 then free Path. A pointer to the newly allocated buffer is returned. 165 166 @param[in] Path A pointer to the path to be transformed. This buffer 167 will always be freed. 168 169 @return A pointer to a buffer containing the transformed path. 170 **/ 171 wchar_t * 172 EFIAPI 173 PathAdjust(wchar_t *Path); 174 175 /** Replace the leading portion of Path with any aliases. 176 177 Aliases are read from /etc/fstab. If there is an associated device, the 178 Current Working Device is set to that device. 179 180 Path must be a previously allocated buffer. PathAlias will 181 allocate a new buffer to hold the results of the transformation 182 then free Path. A pointer to the newly allocated buffer is returned. 183 184 @param[in] Path A pointer to the original, unaliased, path. This 185 buffer is always freed. 186 @param[out] Node Filled in with a pointer to the Device Node describing 187 the device abstraction associated with this path. 188 189 @return A pointer to a buffer containing the aliased path. 190 **/ 191 wchar_t * 192 EFIAPI 193 PathAlias(wchar_t *Path, DeviceNode **Node); 194 195 /** 196 Parses a normalized wide character path and returns a pointer to the entry 197 following the last \. If a \ is not found in the path the return value will 198 be the same as the input value. All error conditions return NULL. 199 200 The behavior when passing in a path that has not been normalized is undefined. 201 202 @param Path - A pointer to a wide character string containing a path to a 203 directory or a file. 204 205 @return Pointer to the file name or terminal directory. NULL if an error is 206 detected. 207 **/ 208 wchar_t * 209 EFIAPI 210 GetFileNameFromPath( 211 const wchar_t *Path 212 ); 213 214 __END_DECLS 215 216 #endif /* __DEV_UTILITY_H__ */ 217