Skip to content

Commit ca1d4e6

Browse files
GorrayLiRbb666
authored andcommitted
[components][ulog]add some comments to ulog for supplement.
1 parent 07999dc commit ca1d4e6

File tree

1 file changed

+39
-1
lines changed
  • components/utilities/ulog

1 file changed

+39
-1
lines changed

components/utilities/ulog/ulog.c

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2006-2022, RT-Thread Development Team
2+
* Copyright (c) 2006-2024 RT-Thread Development Team
33
*
44
* SPDX-License-Identifier: Apache-2.0
55
*
@@ -1262,6 +1262,24 @@ MSH_CMD_EXPORT(ulog_filter, Show ulog filter settings);
12621262
#endif /* RT_USING_FINSH */
12631263
#endif /* ULOG_USING_FILTER */
12641264

1265+
/**
1266+
* @brief register the backend device into the ulog.
1267+
*
1268+
* @param backend Backend device handle, a pointer to a "struct ulog_backend" obj.
1269+
* @param name Backend device name.
1270+
* @param support_color Whether it supports color logs.
1271+
* @return rt_err_t - return 0 on success.
1272+
*
1273+
* @note - This function is used to register the backend device into the ulog,
1274+
* ensuring that the function members in the backend device structure are set before registration.
1275+
* - about struct ulog_backend:
1276+
* 1. The name and support_color properties can be passed in through the ulog_backend_register() function.
1277+
* 2. output is the back-end specific output function, and all backends must implement the interface.
1278+
* 3. init/deinit is optional, init is called at register, and deinit is called at unregister or ulog_deinit.
1279+
* 4. flush is also optional, and some internal output cached backends need to implement this interface.
1280+
* For example, some file systems with RAM cache. The flush of the backend is usually called by
1281+
* ulog_flush in the case of an exception such as assertion or hardfault.
1282+
*/
12651283
rt_err_t ulog_backend_register(ulog_backend_t backend, const char *name, rt_bool_t support_color)
12661284
{
12671285
rt_base_t level;
@@ -1287,6 +1305,13 @@ rt_err_t ulog_backend_register(ulog_backend_t backend, const char *name, rt_bool
12871305
return RT_EOK;
12881306
}
12891307

1308+
/**
1309+
* @brief unregister a backend device that has already been registered.
1310+
*
1311+
* @param backend Backend device handle
1312+
* @return rt_err_t - return 0 on success.
1313+
* @note deinit function will be called at unregister.
1314+
*/
12901315
rt_err_t ulog_backend_unregister(ulog_backend_t backend)
12911316
{
12921317
rt_base_t level;
@@ -1460,6 +1485,14 @@ void ulog_flush(void)
14601485
}
14611486
}
14621487

1488+
/**
1489+
* @brief ulog initialization
1490+
*
1491+
* @return int return 0 on success, return -5 when failed of insufficient memory.
1492+
*
1493+
* @note This function must be called to complete ulog initialization before using ulog.
1494+
* This function will also be called automatically if component auto-initialization is turned on.
1495+
*/
14631496
int ulog_init(void)
14641497
{
14651498
if (ulog.init_ok)
@@ -1518,6 +1551,11 @@ int ulog_async_init(void)
15181551
INIT_PREV_EXPORT(ulog_async_init);
15191552
#endif /* ULOG_USING_ASYNC_OUTPUT */
15201553

1554+
/**
1555+
* @brief ulog deinitialization
1556+
*
1557+
* @note This deinit release resource can be executed when ulog is no longer used.
1558+
*/
15211559
void ulog_deinit(void)
15221560
{
15231561
rt_slist_t *node;

0 commit comments

Comments
 (0)