[mirror_edk2.git] / StdLibPrivateInternalFiles / Include / Device / Device.h

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