[kservice] 完善 API 注释
This commit is contained in:
Sherman
parent
45440d2456
commit
d586417bb7
226
src/kservice.c
226
src/kservice.c
|
|
@ -43,8 +43,8 @@ static volatile int __rt_errno;
|
|||
static rt_device_t _console_device = RT_NULL;
|
||||
#endif
|
||||
|
||||
/*
|
||||
* This function will get errno
|
||||
/**
|
||||
* This function gets the global errno for the current thread.
|
||||
*
|
||||
* @return errno
|
||||
*/
|
||||
|
|
@ -66,10 +66,10 @@ rt_err_t rt_get_errno(void)
|
|||
}
|
||||
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)
|
||||
{
|
||||
|
|
@ -96,9 +96,9 @@ void rt_set_errno(rt_err_t error)
|
|||
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)
|
||||
{
|
||||
|
|
@ -116,13 +116,16 @@ int *_rt_errno(void)
|
|||
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 c the value shall be set in content
|
||||
* @param count the copied length
|
||||
* @param s is the address of source memory, point to the memory block to be filled.
|
||||
*
|
||||
* @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)
|
||||
{
|
||||
|
|
@ -200,14 +203,15 @@ RTM_EXPORT(rt_memset);
|
|||
|
||||
#ifndef RT_USING_ASM_MEMCPY
|
||||
/**
|
||||
* This function will copy memory content from source address to destination
|
||||
* address.
|
||||
* This function will copy memory content from source address to destination address.
|
||||
*
|
||||
* @param dst the address of destination memory
|
||||
* @param src the address of source memory
|
||||
* @param count the copied length
|
||||
* @param dst is the address of destination memory, points to the copied content.
|
||||
*
|
||||
* @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)
|
||||
{
|
||||
|
|
@ -287,13 +291,16 @@ RTM_EXPORT(rt_memcpy);
|
|||
|
||||
/**
|
||||
* 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 src the address of source memory
|
||||
* @param n the copied length
|
||||
* @param dst is the address of destination memory, points to the copied content.
|
||||
*
|
||||
* @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)
|
||||
{
|
||||
|
|
@ -318,13 +325,18 @@ void *rt_memmove(void *dest, const void *src, rt_ubase_t n)
|
|||
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 ct another area of memory
|
||||
* @param count the size of the area
|
||||
* @param cs is a block of memory.
|
||||
*
|
||||
* @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)
|
||||
{
|
||||
|
|
@ -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);
|
||||
|
||||
/**
|
||||
* 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 s2 the find string
|
||||
* @param s1 is the source 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)
|
||||
{
|
||||
|
|
@ -370,10 +384,14 @@ RTM_EXPORT(rt_strstr);
|
|||
/**
|
||||
* This function will compare two strings while ignoring differences in case
|
||||
*
|
||||
* @param a the string to be compared
|
||||
* @param b the string to be compared
|
||||
* @param a is 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)
|
||||
{
|
||||
|
|
@ -397,11 +415,13 @@ RTM_EXPORT(rt_strcasecmp);
|
|||
/**
|
||||
* This function will copy string no more than n bytes.
|
||||
*
|
||||
* @param dst the string to copy
|
||||
* @param src the string to be copied
|
||||
* @param n the maximum copied length
|
||||
* @param dst points to the address used to store the copied content.
|
||||
*
|
||||
* @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)
|
||||
{
|
||||
|
|
@ -427,13 +447,18 @@ char *rt_strncpy(char *dst, const char *src, rt_ubase_t n)
|
|||
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 ct the string to be compared
|
||||
* @param count the maximum compare length
|
||||
* @param cs is the string to be compared.
|
||||
*
|
||||
* @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)
|
||||
{
|
||||
|
|
@ -451,12 +476,16 @@ rt_int32_t rt_strncmp(const char *cs, const char *ct, rt_ubase_t count)
|
|||
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 ct the string to be compared
|
||||
* @param cs is 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)
|
||||
{
|
||||
|
|
@ -477,9 +506,11 @@ RTM_EXPORT(rt_strcmp);
|
|||
* first maxlen characters in the string pointed to by s and never
|
||||
* beyond s+maxlen.
|
||||
*
|
||||
* @param s the string
|
||||
* @param maxlen the max size
|
||||
* @return the length of string
|
||||
* @param s is the string.
|
||||
*
|
||||
* @param maxlen is the max size.
|
||||
*
|
||||
* @return The length of string.
|
||||
*/
|
||||
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
|
||||
* 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)
|
||||
{
|
||||
|
|
@ -517,9 +548,9 @@ RTM_EXPORT(rt_strlen);
|
|||
/**
|
||||
* 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)
|
||||
{
|
||||
|
|
@ -556,6 +587,13 @@ RTM_EXPORT(rt_show_version);
|
|||
#define _ISDIGIT(c) ((unsigned)((c) - '0') < 10)
|
||||
|
||||
#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)
|
||||
{
|
||||
int res;
|
||||
|
|
@ -784,6 +822,19 @@ static char *print_number(char *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_size_t size,
|
||||
const char *fmt,
|
||||
|
|
@ -1051,11 +1102,15 @@ rt_int32_t rt_vsnprintf(char *buf,
|
|||
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 size the size of buffer
|
||||
* @param fmt the format
|
||||
* @param buf is the buffer to save formatted string.
|
||||
*
|
||||
* @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, ...)
|
||||
{
|
||||
|
|
@ -1071,11 +1126,15 @@ rt_int32_t rt_snprintf(char *buf, rt_size_t size, const char *fmt, ...)
|
|||
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 arg_ptr the arg_ptr
|
||||
* @param format the format
|
||||
* @param buf is the buffer to save formatted string.
|
||||
*
|
||||
* @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)
|
||||
{
|
||||
|
|
@ -1086,8 +1145,11 @@ RTM_EXPORT(rt_vsprintf);
|
|||
/**
|
||||
* This function will fill a formatted string to buffer
|
||||
*
|
||||
* @param buf the buffer to save formatted string
|
||||
* @param format the format
|
||||
* @param buf the buffer to save formatted string.
|
||||
*
|
||||
* @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, ...)
|
||||
{
|
||||
|
|
@ -1108,7 +1170,7 @@ RTM_EXPORT(rt_sprintf);
|
|||
/**
|
||||
* 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)
|
||||
{
|
||||
|
|
@ -1121,7 +1183,7 @@ RTM_EXPORT(rt_console_get_device);
|
|||
* After set a device to console, all output of rt_kprintf will be
|
||||
* 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.
|
||||
*/
|
||||
|
|
@ -1165,7 +1227,7 @@ RTM_EXPORT(rt_hw_console_output);
|
|||
/**
|
||||
* 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)
|
||||
{
|
||||
|
|
@ -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, ...)
|
||||
{
|
||||
|
|
@ -1227,10 +1289,12 @@ RTM_EXPORT(rt_kprintf);
|
|||
* This function allocates a memory block, which address is aligned to the
|
||||
* specified alignment size.
|
||||
*
|
||||
* @param size the allocated memory block size
|
||||
* @param align the alignment size
|
||||
* @param size is the allocated memory block 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)
|
||||
{
|
||||
|
|
@ -1276,7 +1340,7 @@ RTM_EXPORT(rt_malloc_align);
|
|||
* This function release the memory block, which is allocated by
|
||||
* 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)
|
||||
{
|
||||
|
|
@ -1316,8 +1380,8 @@ const rt_uint8_t __lowest_bit_bitmap[] =
|
|||
* 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.
|
||||
*
|
||||
* @return return the index of the first bit set. If value is 0, then this function
|
||||
* shall return 0.
|
||||
* @return Return the index of the first bit set. If value is 0, then this function
|
||||
* shall return 0.
|
||||
*/
|
||||
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.
|
||||
*
|
||||
* @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))
|
||||
{
|
||||
|
|
@ -1354,9 +1418,11 @@ void rt_assert_set_hook(void (*hook)(const char *ex, const char *func, rt_size_t
|
|||
/**
|
||||
* The RT_ASSERT function.
|
||||
*
|
||||
* @param ex the assertion condition string
|
||||
* @param func the function name when assertion.
|
||||
* @param line the file line number when assertion.
|
||||
* @param ex is the assertion condition string.
|
||||
*
|
||||
* @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)
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in New Issue