mirror of https://github.com/RT-Thread/rt-thread
[components/dfs]add doxygen comments for dfs_mnt.c in dfs_v2.
This commit is contained in:
ligr
Rbb666
parent
a1c642aa3a
commit
dc89417229
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2006-2023, RT-Thread Development Team
|
||||
* Copyright (c) 2006-2025 RT-Thread Development Team
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*
|
||||
|
|
@ -38,6 +38,17 @@ RT_OBJECT_HOOKLIST_DEFINE(dfs_mnt_umnt);
|
|||
*
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief Create a new dfs_mnt structure instance.
|
||||
*
|
||||
* This function allocates memory to create a new dfs_mnt structure instance and initializes it.
|
||||
* If the memory allocation is successful, it copies the input path string into the instance and initializes related lists and flags.
|
||||
*
|
||||
* @param[in] path The path string to be mounted. This path information will be copied to the newly created dfs_mnt instance.
|
||||
*
|
||||
* @return If the memory allocation is successful, returns a pointer to the newly created dfs_mnt structure;
|
||||
* if the memory allocation fails, returns RT_NULL.
|
||||
*/
|
||||
struct dfs_mnt *dfs_mnt_create(const char *path)
|
||||
{
|
||||
struct dfs_mnt *mnt = rt_calloc(1, sizeof(struct dfs_mnt));
|
||||
|
|
@ -59,6 +70,18 @@ struct dfs_mnt *dfs_mnt_create(const char *path)
|
|||
return mnt;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Insert a child mount point into the mount tree.
|
||||
*
|
||||
* This function inserts a child mount point into the specified parent mount point's child list.
|
||||
* If the parent mount point is not provided, it will try to find the appropriate mount point based on the child's path.
|
||||
* If the child mount point is the root, it will update the global root mount point accordingly.
|
||||
*
|
||||
* @param[in,out] mnt Pointer to the parent dfs_mnt structure. If NULL, it will be updated to the appropriate mount point.
|
||||
* @param[in] child Pointer to the child dfs_mnt structure to be inserted.
|
||||
*
|
||||
* @return Always returns 0 to indicate success.
|
||||
*/
|
||||
int dfs_mnt_insert(struct dfs_mnt* mnt, struct dfs_mnt* child)
|
||||
{
|
||||
if (child)
|
||||
|
|
@ -112,7 +135,18 @@ int dfs_mnt_insert(struct dfs_mnt* mnt, struct dfs_mnt* child)
|
|||
return 0;
|
||||
}
|
||||
|
||||
/* remove mnt from mnt_tree */
|
||||
/**
|
||||
* @brief Remove a mount point from the mount tree.
|
||||
*
|
||||
* This function attempts to remove a specified mount point from the mount tree.
|
||||
* It can only remove a mount point if it has no child mount points. If the mount point
|
||||
* has children, it logs a warning message instead of performing the removal.
|
||||
*
|
||||
* @param[in] mnt Pointer to the dfs_mnt structure representing the mount point to be removed.
|
||||
*
|
||||
* @return Returns RT_EOK if the mount point is successfully removed.
|
||||
* Returns -RT_ERROR if the mount point has child mount points and cannot be removed.
|
||||
*/
|
||||
int dfs_mnt_remove(struct dfs_mnt* mnt)
|
||||
{
|
||||
int ret = -RT_ERROR;
|
||||
|
|
@ -136,6 +170,19 @@ int dfs_mnt_remove(struct dfs_mnt* mnt)
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Recursively search for a mount point associated with a specific device ID in the mount tree.
|
||||
*
|
||||
* This function traverses the mount tree starting from the given mount point `mnt` to find
|
||||
* a mount point that is associated with the specified device ID `dev_id`. It uses a depth-first
|
||||
* search algorithm to iterate through the child mount points.
|
||||
*
|
||||
* @param[in] mnt Pointer to the root dfs_mnt structure from which the search will start.
|
||||
* @param[in] dev_id Pointer to the device ID to search for.
|
||||
*
|
||||
* @return If a mount point associated with the given device ID is found, returns a pointer to the corresponding dfs_mnt structure.
|
||||
* Otherwise, returns RT_NULL.
|
||||
*/
|
||||
static struct dfs_mnt *_dfs_mnt_dev_lookup(struct dfs_mnt *mnt, rt_device_t dev_id)
|
||||
{
|
||||
struct dfs_mnt *ret = RT_NULL, *iter = RT_NULL;
|
||||
|
|
@ -160,6 +207,19 @@ static struct dfs_mnt *_dfs_mnt_dev_lookup(struct dfs_mnt *mnt, rt_device_t dev_
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Search for a mount point associated with a specific device ID in the mount tree.
|
||||
*
|
||||
* This function initiates a search for a mount point that is associated with the specified
|
||||
* device ID `dev_id` starting from the root mount point. It first checks the root mount point
|
||||
* directly, and if not found, it recursively searches the entire mount tree using the
|
||||
* internal helper function `_dfs_mnt_dev_lookup`.
|
||||
*
|
||||
* @param[in] dev_id Pointer to the device ID to search for.
|
||||
*
|
||||
* @return If a mount point associated with the given device ID is found, returns a pointer to the corresponding dfs_mnt structure.
|
||||
* Otherwise, returns RT_NULL.
|
||||
*/
|
||||
struct dfs_mnt *dfs_mnt_dev_lookup(rt_device_t dev_id)
|
||||
{
|
||||
struct dfs_mnt *mnt = _root_mnt;
|
||||
|
|
@ -184,12 +244,16 @@ struct dfs_mnt *dfs_mnt_dev_lookup(rt_device_t dev_id)
|
|||
}
|
||||
|
||||
/**
|
||||
* this function will return the file system mounted on specified path.
|
||||
* @brief Look up the mount point associated with a given full path.
|
||||
*
|
||||
* @param path the specified path string.
|
||||
* This function searches the mount tree starting from the root mount point to find
|
||||
* the most specific mount point that matches the given full path. It traverses down
|
||||
* the mount tree to identify the deepest mount point that is a prefix of the given path.
|
||||
*
|
||||
* @return the found file system or NULL if no file system mounted on
|
||||
* specified path
|
||||
* @param[in] fullpath The full path string for which to find the associated mount point.
|
||||
*
|
||||
* @return If a matching mount point is found, returns a pointer to the corresponding dfs_mnt structure.
|
||||
* Otherwise, returns RT_NULL.
|
||||
*/
|
||||
struct dfs_mnt *dfs_mnt_lookup(const char *fullpath)
|
||||
{
|
||||
|
|
@ -236,6 +300,18 @@ struct dfs_mnt *dfs_mnt_lookup(const char *fullpath)
|
|||
return mnt;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Increase the reference count of a dfs_mnt structure instance.
|
||||
*
|
||||
* This function increments the reference count of the specified dfs_mnt structure.
|
||||
* The reference count is used to track how many parts of the system are currently
|
||||
* using this mount point.
|
||||
*
|
||||
* @param[in,out] mnt Pointer to the dfs_mnt structure whose reference count is to be increased.
|
||||
* If the pointer is valid, the reference count within the structure will be modified.
|
||||
* @return Returns the same pointer to the dfs_mnt structure that was passed in.
|
||||
* If the input pointer is NULL, it simply returns NULL.
|
||||
*/
|
||||
struct dfs_mnt* dfs_mnt_ref(struct dfs_mnt* mnt)
|
||||
{
|
||||
if (mnt)
|
||||
|
|
@ -247,6 +323,18 @@ struct dfs_mnt* dfs_mnt_ref(struct dfs_mnt* mnt)
|
|||
return mnt;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Decrease the reference count of a dfs_mnt structure instance and free it if necessary.
|
||||
*
|
||||
* This function decrements the reference count of the specified dfs_mnt structure.
|
||||
* If the reference count reaches zero after the decrement, it will perform the unmount operation,
|
||||
* trigger the unmount hook, free the allocated path memory, and finally free the dfs_mnt structure itself.
|
||||
*
|
||||
* @param[in,out] mnt Pointer to the dfs_mnt structure whose reference count is to be decreased.
|
||||
* If the reference count reaches zero, the structure will be freed.
|
||||
*
|
||||
* @return returns RT_EOK to indicate success.
|
||||
*/
|
||||
int dfs_mnt_unref(struct dfs_mnt *mnt)
|
||||
{
|
||||
rt_err_t ret = RT_EOK;
|
||||
|
|
@ -286,6 +374,19 @@ int dfs_mnt_unref(struct dfs_mnt *mnt)
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Set specific flags for a dfs_mnt structure instance.
|
||||
*
|
||||
* This function sets specific flags for the given dfs_mnt structure.
|
||||
* If the MS_RDONLY flag is included in the input flags, it sets the MNT_RDONLY flag
|
||||
* for the mount point and cleans the page cache if the page cache feature is enabled.
|
||||
*
|
||||
* @param[in,out] mnt Pointer to the dfs_mnt structure for which flags are to be set.
|
||||
* The structure's `flags` member will be modified if necessary.
|
||||
* @param[in] flags The flags to be set for the mount point. This includes the MS_RDONLY flag.
|
||||
*
|
||||
* @return returns 0 to indicate success.
|
||||
*/
|
||||
int dfs_mnt_setflags(struct dfs_mnt *mnt, int flags)
|
||||
{
|
||||
int error = 0;
|
||||
|
|
@ -301,6 +402,19 @@ int dfs_mnt_setflags(struct dfs_mnt *mnt, int flags)
|
|||
return error;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Destroy a dfs_mnt structure instance and unmount it if necessary.
|
||||
*
|
||||
* This function attempts to destroy the specified dfs_mnt structure instance.
|
||||
* If the mount point is currently mounted, it marks the mount point as unmounted,
|
||||
* sets the unmount flag, and removes it from the mount list if it was added.
|
||||
* Finally, it decreases the reference count of the mount point and frees the
|
||||
* structure if the reference count reaches zero.
|
||||
*
|
||||
* @param[in,out] mnt Pointer to the dfs_mnt structure to be destroyed.
|
||||
*
|
||||
* @return Returns RT_EOK to indicate success.
|
||||
*/
|
||||
int dfs_mnt_destroy(struct dfs_mnt* mnt)
|
||||
{
|
||||
rt_err_t ret = RT_EOK;
|
||||
|
|
@ -324,6 +438,23 @@ int dfs_mnt_destroy(struct dfs_mnt* mnt)
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Recursively traverse the mount point tree and apply a callback function.
|
||||
*
|
||||
* This function performs a depth-first traversal of the mount point tree starting from the given mount point.
|
||||
* It applies the specified callback function to each mount point in the tree. If the callback function returns
|
||||
* a non-NULL pointer, the traversal stops and the result is returned immediately.
|
||||
*
|
||||
* @param[in] mnt Pointer to the root dfs_mnt structure from which the traversal will start.
|
||||
* If NULL, the function will return RT_NULL without performing any traversal.
|
||||
* @param[in] func Pointer to the callback function to be applied to each mount point.
|
||||
* The callback function takes a pointer to a dfs_mnt structure and a generic parameter,
|
||||
* and returns a pointer to a dfs_mnt structure or RT_NULL.
|
||||
* @param[in] parameter Generic pointer to a parameter that will be passed to the callback function.
|
||||
*
|
||||
* @return If the callback function returns a non-NULL pointer during the traversal, returns that pointer.
|
||||
* Otherwise, returns RT_NULL.
|
||||
*/
|
||||
static struct dfs_mnt* _dfs_mnt_foreach(struct dfs_mnt *mnt, struct dfs_mnt* (*func)(struct dfs_mnt *mnt, void *parameter), void *parameter)
|
||||
{
|
||||
struct dfs_mnt *iter, *ret = NULL;
|
||||
|
|
@ -355,6 +486,19 @@ static struct dfs_mnt* _dfs_mnt_foreach(struct dfs_mnt *mnt, struct dfs_mnt* (*f
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Compare a mount point's device ID with a given device object.
|
||||
*
|
||||
* This function checks if the device ID associated with a specified mount point
|
||||
* matches the given device object. If a match is found, it returns a pointer to
|
||||
* the corresponding dfs_mnt structure; otherwise, it returns RT_NULL.
|
||||
*
|
||||
* @param[in] mnt Pointer to the dfs_mnt structure representing the mount point to be checked.
|
||||
* @param[in] device Pointer to the device object to compare against the mount point's device ID.
|
||||
*
|
||||
* @return If the device ID of the mount point matches the given device object, returns a pointer to the dfs_mnt structure.
|
||||
* Otherwise, returns RT_NULL.
|
||||
*/
|
||||
static struct dfs_mnt* _mnt_cmp_devid(struct dfs_mnt *mnt, void *device)
|
||||
{
|
||||
struct dfs_mnt *ret = RT_NULL;
|
||||
|
|
@ -374,7 +518,7 @@ static struct dfs_mnt* _mnt_cmp_devid(struct dfs_mnt *mnt, void *device)
|
|||
/**
|
||||
* this function will return the mounted path for specified device.
|
||||
*
|
||||
* @param device the device object which is mounted.
|
||||
* @param[in] device the device object which is mounted.
|
||||
*
|
||||
* @return the mounted path or NULL if none device mounted.
|
||||
*/
|
||||
|
|
@ -396,6 +540,19 @@ const char *dfs_mnt_get_mounted_path(struct rt_device *device)
|
|||
return path;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Print information about a mount point to the console.
|
||||
*
|
||||
* This function is designed to be used as a callback in the mount point tree traversal.
|
||||
* It prints the file system name, device name (or `(NULL)` if no device is associated),
|
||||
* mount path, and reference count of the specified mount point to the console using `rt_kprintf`.
|
||||
*
|
||||
* @param[in] mnt Pointer to the dfs_mnt structure representing the mount point to be printed.
|
||||
* If NULL, the function does nothing.
|
||||
* @param[in] parameter A generic pointer to a parameter. This parameter is not used in this function.
|
||||
*
|
||||
* @return Always returns RT_NULL as it is a callback function mainly used for side - effects (printing).
|
||||
*/
|
||||
static struct dfs_mnt* _mnt_dump(struct dfs_mnt *mnt, void *parameter)
|
||||
{
|
||||
if (mnt)
|
||||
|
|
@ -415,6 +572,22 @@ static struct dfs_mnt* _mnt_dump(struct dfs_mnt *mnt, void *parameter)
|
|||
return RT_NULL;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Compare a mount point's full path with a given path.
|
||||
*
|
||||
* This function is designed to be used as a callback in the mount point tree traversal.
|
||||
* It compares the full path of the specified mount point with the given path.
|
||||
* If the mount point's full path starts with the given path, it returns a pointer to the dfs_mnt structure;
|
||||
* otherwise, it returns RT_NULL.
|
||||
*
|
||||
* @param[in] mnt Pointer to the dfs_mnt structure representing the mount point to be checked.
|
||||
* If NULL, the function will not perform the comparison and return RT_NULL.
|
||||
* @param[in] parameter A generic pointer to a parameter, which should be cast to a `const char*`
|
||||
* representing the path to compare against the mount point's full path.
|
||||
*
|
||||
* @return If the mount point's full path starts with the given path, returns a pointer to the dfs_mnt structure.
|
||||
* Otherwise, returns RT_NULL.
|
||||
*/
|
||||
static struct dfs_mnt* _mnt_cmp_path(struct dfs_mnt* mnt, void *parameter)
|
||||
{
|
||||
const char* fullpath = (const char*)parameter;
|
||||
|
|
@ -428,6 +601,22 @@ static struct dfs_mnt* _mnt_cmp_path(struct dfs_mnt* mnt, void *parameter)
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Check if a mount point has a child mount point matching the given path.
|
||||
*
|
||||
* This function checks whether the specified mount point has a child mount point
|
||||
* whose full path starts with the given path. It uses a depth-first traversal of
|
||||
* the mount point tree starting from the provided mount point and applies the
|
||||
* `_mnt_cmp_path` callback function to each mount point.
|
||||
*
|
||||
* @param[in] mnt Pointer to the root dfs_mnt structure from which the search will start.
|
||||
* If NULL, the function will return RT_FALSE without performing any search.
|
||||
* @param[in] fullpath The full path string to compare against the child mount points' paths.
|
||||
* If NULL, the function will return RT_FALSE without performing any search.
|
||||
*
|
||||
* @return Returns RT_TRUE if a child mount point with a matching path is found.
|
||||
* Returns RT_FALSE if no matching child mount point is found, or if either input parameter is NULL.
|
||||
*/
|
||||
rt_bool_t dfs_mnt_has_child_mnt(struct dfs_mnt *mnt, const char* fullpath)
|
||||
{
|
||||
int ret = RT_FALSE;
|
||||
|
|
@ -449,6 +638,19 @@ rt_bool_t dfs_mnt_has_child_mnt(struct dfs_mnt *mnt, const char* fullpath)
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief List all mount points starting from a specified mount point.
|
||||
*
|
||||
* This function lists information about all mount points in the mount point tree,
|
||||
* starting from the specified mount point. If the input mount point is NULL,
|
||||
* it starts from the root mount point. It uses the `_dfs_mnt_foreach` function
|
||||
* with the `_mnt_dump` callback to print mount point information.
|
||||
*
|
||||
* @param[in] mnt Pointer to the dfs_mnt structure from which to start listing mount points.
|
||||
* If NULL, the function will start from the root mount point.
|
||||
*
|
||||
* @return Always returns 0 to indicate success.
|
||||
*/
|
||||
int dfs_mnt_list(struct dfs_mnt *mnt)
|
||||
{
|
||||
if (!mnt) mnt = _root_mnt;
|
||||
|
|
@ -462,6 +664,16 @@ int dfs_mnt_list(struct dfs_mnt *mnt)
|
|||
return 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Traverse all mount points in the mount tree and apply a callback function.
|
||||
*
|
||||
* @param[in] func Pointer to the callback function to be applied to each mount point.
|
||||
* The callback function takes a pointer to a `dfs_mnt` structure and a generic parameter,
|
||||
* and returns a pointer to a `dfs_mnt` structure or `RT_NULL`.
|
||||
* @param[in] parameter Generic pointer to a parameter that will be passed to the callback function.
|
||||
*
|
||||
* @return Always returns 0.
|
||||
*/
|
||||
int dfs_mnt_foreach(struct dfs_mnt* (*func)(struct dfs_mnt *mnt, void *parameter), void *parameter)
|
||||
{
|
||||
/* lock file system */
|
||||
|
|
@ -471,4 +683,4 @@ int dfs_mnt_foreach(struct dfs_mnt* (*func)(struct dfs_mnt *mnt, void *parameter
|
|||
dfs_unlock();
|
||||
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue