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