libs/rt-thread
libs
/
rt-thread
4
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[kservice] 完善 API 注释

This commit is contained in:
Sherman 2021-09-10 18:34:14 +08:00
parent 45440d2456
commit d586417bb7
1 changed files with 146 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

224
src/kservice.c
View File

@ -43,8 +43,8 @@ static volatile int __rt_errno;
static rt_device_t _console_device = RT_NULL; static rt_device_t _console_device = RT_NULL;
#endif #endif
/* /**
* This function will get errno * This function gets the global errno for the current thread.
* *
* @return errno * @return errno
*/ */
@ -66,10 +66,10 @@ rt_err_t rt_get_errno(void)
} }
RTM_EXPORT(rt_get_errno); RTM_EXPORT(rt_get_errno);
/* /**
* This function will set errno * This function sets the global errno for the current thread.
* *
* @param error the errno shall be set * @param error is the errno shall be set.
*/ */
void rt_set_errno(rt_err_t error) void rt_set_errno(rt_err_t error)
{ {
@ -96,9 +96,9 @@ void rt_set_errno(rt_err_t error)
RTM_EXPORT(rt_set_errno); RTM_EXPORT(rt_set_errno);
/** /**
* This function returns errno. * This function returns the address of the current thread errno.
* *
* @return the errno in the system * @return The errno address.
*/ */
int *_rt_errno(void) int *_rt_errno(void)
{ {
@ -116,13 +116,16 @@ int *_rt_errno(void)
RTM_EXPORT(_rt_errno); RTM_EXPORT(_rt_errno);
/** /**
* This function will set the content of memory to specified value * This function will set the content of memory to specified value.
* *
* @param s the address of source memory * @param s is the address of source memory, point to the memory block to be filled.
* @param c the value shall be set in content
* @param count the copied length
* *
* @return the address of source memory * @param c is the value to be set. The value is passed in int form, but the function
* uses the unsigned character form of the value when filling the memory block.
*
* @param count number of bytes to be set.
*
* @return The address of source memory.
*/ */
RT_WEAK void *rt_memset(void *s, int c, rt_ubase_t count) RT_WEAK void *rt_memset(void *s, int c, rt_ubase_t count)
{ {
@ -200,14 +203,15 @@ RTM_EXPORT(rt_memset);
#ifndef RT_USING_ASM_MEMCPY #ifndef RT_USING_ASM_MEMCPY
/** /**
* This function will copy memory content from source address to destination * This function will copy memory content from source address to destination address.
* address.
* *
* @param dst the address of destination memory * @param dst is the address of destination memory, points to the copied content.
* @param src the address of source memory
* @param count the copied length
* *
* @return the address of destination memory * @param src is the address of source memory, pointing to the data source to be copied.
*
* @param count is the copied length.
*
* @return The address of destination memory
*/ */
void *rt_memcpy(void *dst, const void *src, rt_ubase_t count) void *rt_memcpy(void *dst, const void *src, rt_ubase_t count)
{ {
@ -287,13 +291,16 @@ RTM_EXPORT(rt_memcpy);
/** /**
* This function will move memory content from source address to destination * This function will move memory content from source address to destination
* address. * address. If the destination memory does not overlap with the source memory,
* the function is the same as memcpy().
* *
* @param dest the address of destination memory * @param dst is the address of destination memory, points to the copied content.
* @param src the address of source memory
* @param n the copied length
* *
* @return the address of destination memory * @param src is the address of source memory, point to the data source to be copied.
*
* @param count is the copied length.
*
* @return The address of destination memory.
*/ */
void *rt_memmove(void *dest, const void *src, rt_ubase_t n) void *rt_memmove(void *dest, const void *src, rt_ubase_t n)
{ {
@ -318,13 +325,18 @@ void *rt_memmove(void *dest, const void *src, rt_ubase_t n)
RTM_EXPORT(rt_memmove); RTM_EXPORT(rt_memmove);
/** /**
* This function will compare two areas of memory * This function will compare two areas of memory.
* *
* @param cs one area of memory * @param cs is a block of memory.
* @param ct another area of memory
* @param count the size of the area
* *
* @return the result * @param ct is another block of memory.
*
* @param count is the size of the area.
*
* @return Compare the results:
* If the result < 0, cs is smaller than ct.
* If the result > 0, cs is greater than ct.
* If the result = 0, cs is equal to ct.
*/ */
RT_WEAK rt_int32_t rt_memcmp(const void *cs, const void *ct, rt_ubase_t count) RT_WEAK rt_int32_t rt_memcmp(const void *cs, const void *ct, rt_ubase_t count)
{ {
@ -340,12 +352,14 @@ RT_WEAK rt_int32_t rt_memcmp(const void *cs, const void *ct, rt_ubase_t count)
RTM_EXPORT(rt_memcmp); RTM_EXPORT(rt_memcmp);
/** /**
* This function will return the first occurrence of a string. * This function will return the first occurrence of a string, without the
* terminator '\0'.
* *
* @param s1 the source string * @param s1 is the source string.
* @param s2 the find string
* *
* @return the first occurrence of a s2 in s1, or RT_NULL if no found. * @param s2 is the find string.
*
* @return The first occurrence of a s2 in s1, or RT_NULL if no found.
*/ */
char *rt_strstr(const char *s1, const char *s2) char *rt_strstr(const char *s1, const char *s2)
{ {
@ -370,10 +384,14 @@ RTM_EXPORT(rt_strstr);
/** /**
* This function will compare two strings while ignoring differences in case * This function will compare two strings while ignoring differences in case
* *
* @param a the string to be compared * @param a is the string to be compared.
* @param b the string to be compared
* *
* @return the result * @param b is the string to be compared.
*
* @return Compare the results:
* If the result < 0, a is smaller than a.
* If the result > 0, a is greater than a.
* If the result = 0, a is equal to a.
*/ */
rt_int32_t rt_strcasecmp(const char *a, const char *b) rt_int32_t rt_strcasecmp(const char *a, const char *b)
{ {
@ -397,11 +415,13 @@ RTM_EXPORT(rt_strcasecmp);
/** /**
* This function will copy string no more than n bytes. * This function will copy string no more than n bytes.
* *
* @param dst the string to copy * @param dst points to the address used to store the copied content.
* @param src the string to be copied
* @param n the maximum copied length
* *
* @return the result * @param src is the string to be copied.
*
* @param n is the maximum copied length.
*
* @return The address where the copied content is stored.
*/ */
char *rt_strncpy(char *dst, const char *src, rt_ubase_t n) char *rt_strncpy(char *dst, const char *src, rt_ubase_t n)
{ {
@ -427,13 +447,18 @@ char *rt_strncpy(char *dst, const char *src, rt_ubase_t n)
RTM_EXPORT(rt_strncpy); RTM_EXPORT(rt_strncpy);
/** /**
* This function will compare two strings with specified maximum length * This function will compare two strings with specified maximum length.
* *
* @param cs the string to be compared * @param cs is the string to be compared.
* @param ct the string to be compared
* @param count the maximum compare length
* *
* @return the result * @param ct is the string to be compared.
*
* @param count is the maximum compare length.
*
* @return Compare the results:
* If the result < 0, cs is smaller than ct.
* If the result > 0, cs is greater than ct.
* If the result = 0, cs is equal to ct.
*/ */
rt_int32_t rt_strncmp(const char *cs, const char *ct, rt_ubase_t count) rt_int32_t rt_strncmp(const char *cs, const char *ct, rt_ubase_t count)
{ {
@ -451,12 +476,16 @@ rt_int32_t rt_strncmp(const char *cs, const char *ct, rt_ubase_t count)
RTM_EXPORT(rt_strncmp); RTM_EXPORT(rt_strncmp);
/** /**
* This function will compare two strings without specified length * This function will compare two strings without specified length.
* *
* @param cs the string to be compared * @param cs is the string to be compared.
* @param ct the string to be compared
* *
* @return the result * @param ct is the string to be compared.
*
* @return Compare the results:
* If the result < 0, cs is smaller than ct.
* If the result > 0, cs is greater than ct.
* If the result = 0, cs is equal to ct.
*/ */
rt_int32_t rt_strcmp(const char *cs, const char *ct) rt_int32_t rt_strcmp(const char *cs, const char *ct)
{ {
@ -477,9 +506,11 @@ RTM_EXPORT(rt_strcmp);
* first maxlen characters in the string pointed to by s and never * first maxlen characters in the string pointed to by s and never
* beyond s+maxlen. * beyond s+maxlen.
* *
* @param s the string * @param s is the string.
* @param maxlen the max size *
* @return the length of string * @param maxlen is the max size.
*
* @return The length of string.
*/ */
rt_size_t rt_strnlen(const char *s, rt_ubase_t maxlen) rt_size_t rt_strnlen(const char *s, rt_ubase_t maxlen)
{ {
@ -496,9 +527,9 @@ RTM_EXPORT(rt_strnlen);
* This function will return the length of a string, which terminate will * This function will return the length of a string, which terminate will
* null character. * null character.
* *
* @param s the string * @param s is the string
* *
* @return the length of string * @return The length of string.
*/ */
rt_size_t rt_strlen(const char *s) rt_size_t rt_strlen(const char *s)
{ {
@ -517,9 +548,9 @@ RTM_EXPORT(rt_strlen);
/** /**
* This function will duplicate a string. * This function will duplicate a string.
* *
* @param s the string to be duplicated * @param s is the string to be duplicated.
* *
* @return the duplicated string pointer * @return The string address of the copy.
*/ */
char *rt_strdup(const char *s) char *rt_strdup(const char *s)
{ {
@ -556,6 +587,13 @@ RTM_EXPORT(rt_show_version);
#define _ISDIGIT(c) ((unsigned)((c) - '0') < 10) #define _ISDIGIT(c) ((unsigned)((c) - '0') < 10)
#ifdef RT_PRINTF_LONGLONG #ifdef RT_PRINTF_LONGLONG
/**
* This function will duplicate a string.
*
* @param s the string to be duplicated
*
* @return the duplicated string pointer
*/
rt_inline int divide(long long *n, int base) rt_inline int divide(long long *n, int base)
{ {
int res; int res;
@ -784,6 +822,19 @@ static char *print_number(char *buf,
return buf; return buf;
} }
/**
* This function will fill a formatted string to buffer.
*
* @param buf is the buffer to save formatted string.
*
* @param size is the size of buffer.
*
* @param fmt is the format parameters.
*
* @param args is a list of variable parameters.
*
* @return The number of characters actually written to buffer.
*/
rt_int32_t rt_vsnprintf(char *buf, rt_int32_t rt_vsnprintf(char *buf,
rt_size_t size, rt_size_t size,
const char *fmt, const char *fmt,
@ -1051,11 +1102,15 @@ rt_int32_t rt_vsnprintf(char *buf,
RTM_EXPORT(rt_vsnprintf); RTM_EXPORT(rt_vsnprintf);
/** /**
* This function will fill a formatted string to buffer * This function will fill a formatted string to buffer.
* *
* @param buf the buffer to save formatted string * @param buf is the buffer to save formatted string.
* @param size the size of buffer *
* @param fmt the format * @param size is the size of buffer.
*
* @param fmt is the format parameters.
*
* @return The number of characters actually written to buffer.
*/ */
rt_int32_t rt_snprintf(char *buf, rt_size_t size, const char *fmt, ...) rt_int32_t rt_snprintf(char *buf, rt_size_t size, const char *fmt, ...)
{ {
@ -1071,11 +1126,15 @@ rt_int32_t rt_snprintf(char *buf, rt_size_t size, const char *fmt, ...)
RTM_EXPORT(rt_snprintf); RTM_EXPORT(rt_snprintf);
/** /**
* This function will fill a formatted string to buffer * This function will fill a formatted string to buffer.
* *
* @param buf the buffer to save formatted string * @param buf is the buffer to save formatted string.
* @param arg_ptr the arg_ptr *
* @param format the format * @param format is the format parameters.
*
* @param arg_ptr is a list of variable parameters.
*
* @return The number of characters actually written to buffer.
*/ */
rt_int32_t rt_vsprintf(char *buf, const char *format, va_list arg_ptr) rt_int32_t rt_vsprintf(char *buf, const char *format, va_list arg_ptr)
{ {
@ -1086,8 +1145,11 @@ RTM_EXPORT(rt_vsprintf);
/** /**
* This function will fill a formatted string to buffer * This function will fill a formatted string to buffer
* *
* @param buf the buffer to save formatted string * @param buf the buffer to save formatted string.
* @param format the format *
* @param format is the format parameters.
*
* @return The number of characters actually written to buffer.
*/ */
rt_int32_t rt_sprintf(char *buf, const char *format, ...) rt_int32_t rt_sprintf(char *buf, const char *format, ...)
{ {
@ -1108,7 +1170,7 @@ RTM_EXPORT(rt_sprintf);
/** /**
* This function returns the device using in console. * This function returns the device using in console.
* *
* @return the device using in console or RT_NULL * @return Returns the console device pointer or RT_NULL.
*/ */
rt_device_t rt_console_get_device(void) rt_device_t rt_console_get_device(void)
{ {
@ -1121,7 +1183,7 @@ RTM_EXPORT(rt_console_get_device);
* After set a device to console, all output of rt_kprintf will be * After set a device to console, all output of rt_kprintf will be
* redirected to this new device. * redirected to this new device.
* *
* @param name the name of new console device * @param name is the name of new console device.
* *
* @return the old console device handler on successful, or RT_NULL on failure. * @return the old console device handler on successful, or RT_NULL on failure.
*/ */
@ -1165,7 +1227,7 @@ RTM_EXPORT(rt_hw_console_output);
/** /**
* This function will put string to the console. * This function will put string to the console.
* *
* @param str the string output to the console. * @param str is the string output to the console.
*/ */
void rt_kputs(const char *str) void rt_kputs(const char *str)
{ {
@ -1186,9 +1248,9 @@ void rt_kputs(const char *str)
} }
/** /**
* This function will print a formatted string on system console * This function will print a formatted string on system console.
* *
* @param fmt the format * @param fmt is the format parameters.
*/ */
RT_WEAK void rt_kprintf(const char *fmt, ...) RT_WEAK void rt_kprintf(const char *fmt, ...)
{ {
@ -1227,10 +1289,12 @@ RTM_EXPORT(rt_kprintf);
* This function allocates a memory block, which address is aligned to the * This function allocates a memory block, which address is aligned to the
* specified alignment size. * specified alignment size.
* *
* @param size the allocated memory block size * @param size is the allocated memory block size.
* @param align the alignment size
* *
* @return the allocated memory block on successful, otherwise returns RT_NULL * @param align is the alignment size.
*
* @return The memory block address was returned successfully, otherwise it was
* returned empty RT_NULL.
*/ */
RT_WEAK void *rt_malloc_align(rt_size_t size, rt_size_t align) RT_WEAK void *rt_malloc_align(rt_size_t size, rt_size_t align)
{ {
@ -1276,7 +1340,7 @@ RTM_EXPORT(rt_malloc_align);
* This function release the memory block, which is allocated by * This function release the memory block, which is allocated by
* rt_malloc_align function and address is aligned. * rt_malloc_align function and address is aligned.
* *
* @param ptr the memory block pointer * @param ptr is the memory block pointer.
*/ */
RT_WEAK void rt_free_align(void *ptr) RT_WEAK void rt_free_align(void *ptr)
{ {
@ -1316,7 +1380,7 @@ const rt_uint8_t __lowest_bit_bitmap[] =
* Bits are numbered starting at 1 (the least significant bit). A return value of * Bits are numbered starting at 1 (the least significant bit). A return value of
* zero from any of these functions means that the argument was zero. * zero from any of these functions means that the argument was zero.
* *
* @return return the index of the first bit set. If value is 0, then this function * @return Return the index of the first bit set. If value is 0, then this function
* shall return 0. * shall return 0.
*/ */
int __rt_ffs(int value) int __rt_ffs(int value)
@ -1344,7 +1408,7 @@ void (*rt_assert_hook)(const char *ex, const char *func, rt_size_t line);
/** /**
* This function will set a hook function to RT_ASSERT(EX). It will run when the expression is false. * This function will set a hook function to RT_ASSERT(EX). It will run when the expression is false.
* *
* @param hook the hook function * @param hook is the hook function.
*/ */
void rt_assert_set_hook(void (*hook)(const char *ex, const char *func, rt_size_t line)) void rt_assert_set_hook(void (*hook)(const char *ex, const char *func, rt_size_t line))
{ {
@ -1354,9 +1418,11 @@ void rt_assert_set_hook(void (*hook)(const char *ex, const char *func, rt_size_t
/** /**
* The RT_ASSERT function. * The RT_ASSERT function.
* *
* @param ex the assertion condition string * @param ex is the assertion condition string.
* @param func the function name when assertion. *
* @param line the file line number when assertion. * @param func is the function name when assertion.
*
* @param line is the file line number when assertion.
*/ */
void rt_assert_handler(const char *ex_string, const char *func, rt_size_t line) void rt_assert_handler(const char *ex_string, const char *func, rt_size_t line)
{ {