Other useful kernel service

Collaboration diagram for Other useful kernel service:

Macros
#define	RT_HW_BACKTRACE_FRAME_GET_SELF(frame)
#define	rt_container_of(ptr, type, member)    ((type *)((char *)(ptr) - (unsigned long)(&((type *)0)->member)))
#define	RT_LIST_OBJECT_INIT(object)   { &(object), &(object) }
#define	rt_list_entry(node, type, member)    rt_container_of(node, type, member)
#define	rt_list_for_each(pos, head)    for (pos = (head)->next; pos != (head); pos = pos->next)
#define	rt_list_for_each_safe(pos, n, head)
#define	rt_list_for_each_entry(pos, head, member)
#define	rt_list_for_each_entry_safe(pos, n, head, member)
#define	rt_list_first_entry(ptr, type, member)    rt_list_entry((ptr)->next, type, member)
#define	rt_slist_entry(node, type, member)    rt_container_of(node, type, member)
#define	rt_slist_for_each(pos, head)    for (pos = (head)->next; pos != RT_NULL; pos = pos->next)
#define	rt_slist_for_each_entry(pos, head, member)
#define	rt_slist_first_entry(ptr, type, member)    rt_slist_entry((ptr)->next, type, member)
#define	rt_slist_tail_entry(ptr, type, member)    rt_slist_entry(rt_slist_tail(ptr), type, member)

Functions
rt_weak rt_err_t	rt_hw_backtrace_frame_get (rt_thread_t thread, struct rt_hw_backtrace_frame *frame)
rt_weak rt_err_t	rt_hw_backtrace_frame_unwind (rt_thread_t thread, struct rt_hw_backtrace_frame *frame)
void	rt_show_version (void)
rt_weak rt_err_t	rt_backtrace (void)
rt_weak rt_err_t	rt_backtrace_frame (rt_thread_t thread, struct rt_hw_backtrace_frame *frame)
rt_weak rt_err_t	rt_backtrace_formatted_print (rt_ubase_t *buffer, long buflen)
rt_weak rt_err_t	rt_backtrace_to_buffer (rt_thread_t thread, struct rt_hw_backtrace_frame *frame, long skip, rt_ubase_t *buffer, long buflen)
rt_err_t	rt_backtrace_thread (rt_thread_t thread)
void	rt_system_heap_init_generic (void *begin_addr, void *end_addr)
rt_weak void	rt_system_heap_init (void *begin_addr, void *end_addr)
rt_weak void *	rt_malloc (rt_size_t size)
rt_weak void *	rt_realloc (void *ptr, rt_size_t newsize)
rt_weak void *	rt_calloc (rt_size_t count, rt_size_t size)
rt_weak void	rt_free (void *ptr)
rt_weak void	rt_memory_info (rt_size_t *total, rt_size_t *used, rt_size_t *max_used)
rt_weak void *	rt_malloc_align (rt_size_t size, rt_size_t align)
rt_weak void	rt_free_align (void *ptr)
int	__rt_ffs (int value)
rt_inline void	rt_list_init (rt_list_t *l)
rt_inline void	rt_list_insert_after (rt_list_t *l, rt_list_t *n)
rt_inline void	rt_list_insert_before (rt_list_t *l, rt_list_t *n)
rt_inline void	rt_list_remove (rt_list_t *n)
rt_inline int	rt_list_isempty (const rt_list_t *l)
rt_inline unsigned int	rt_list_len (const rt_list_t *l)
rt_inline void	rt_slist_init (rt_slist_t *l)
void	rt_realloc_set_entry_hook (void(*hook)(void **ptr, rt_size_t size))
void	rt_realloc_set_exit_hook (void(*hook)(void **ptr, rt_size_t size))
void	rt_free_sethook (void(*hook)(void **ptr))

Detailed Description

other useful service in the kernel

Macro Definition Documentation

RT_HW_BACKTRACE_FRAME_GET_SELF

#define RT_HW_BACKTRACE_FRAME_GET_SELF

(

frame

)

Value:

        do {  \
        (frame)->fp = 0;                                \
        (frame)->pc = 0;                                \
    } while (0)

Note

can be overridden by cpuport.h which is defined by a specific arch

rt_container_of

#define rt_container_of	(		ptr,
			type,
			member
	)		((type *)((char *)(ptr) - (unsigned long)(&((type *)0)->member)))

rt_container_of - return the start address of struct type, while ptr is the member of struct type.

RT_LIST_OBJECT_INIT

#define RT_LIST_OBJECT_INIT

(

object

)

{ &(object), &(object) }

initialize a list object

rt_list_entry

#define rt_list_entry	(		node,
			type,
			member
	)		rt_container_of(node, type, member)

get the struct for this entry

Parameters

node	the entry point
type	the type of structure
member	the name of list in structure

rt_list_for_each

#define rt_list_for_each	(		pos,
			head
	)		for (pos = (head)->next; pos != (head); pos = pos->next)

rt_list_for_each - iterate over a list

Parameters

pos	the rt_list_t * to use as a loop cursor.
head	the head for your list.

rt_list_for_each_safe

#define rt_list_for_each_safe	(		pos,
			n,
			head
	)

Value:

    for (pos = (head)->next, n = pos->next; pos != (head); \
        pos = n, n = pos->next)

rt_list_for_each_safe - iterate over a list safe against removal of list entry

Parameters

pos	the rt_list_t * to use as a loop cursor.
n	another rt_list_t * to use as temporary storage
head	the head for your list.

rt_list_for_each_entry

#define rt_list_for_each_entry	(		pos,
			head,
			member
	)

Value:

    for (pos = rt_list_entry((head)->next, rt_typeof(*pos), member); \
         &pos->member != (head); \
         pos = rt_list_entry(pos->member.next, rt_typeof(*pos), member))

rt_list_for_each_entry - iterate over list of given type

Parameters

pos	the type * to use as a loop cursor.
head	the head for your list.
member	the name of the list_struct within the struct.

rt_list_for_each_entry_safe

#define rt_list_for_each_entry_safe	(		pos,
			n,
			head,
			member
	)

Value:

    for (pos = rt_list_entry((head)->next, rt_typeof(*pos), member), \
         n = rt_list_entry(pos->member.next, rt_typeof(*pos), member); \
         &pos->member != (head); \
         pos = n, n = rt_list_entry(n->member.next, rt_typeof(*n), member))

rt_list_for_each_entry_safe - iterate over list of given type safe against removal of list entry

Parameters

pos	the type * to use as a loop cursor.
n	another type * to use as temporary storage
head	the head for your list.
member	the name of the list_struct within the struct.

rt_list_first_entry

#define rt_list_first_entry	(		ptr,
			type,
			member
	)		rt_list_entry((ptr)->next, type, member)

rt_list_first_entry - get the first element from a list

Parameters

ptr	the list head to take the element from.
type	the type of the struct this is embedded in.
member	the name of the list_struct within the struct.

Note, that list is expected to be not empty.

rt_slist_entry

#define rt_slist_entry	(		node,
			type,
			member
	)		rt_container_of(node, type, member)

get the struct for this single list node

Parameters

node	the entry point
type	the type of structure
member	the name of list in structure

rt_slist_for_each

#define rt_slist_for_each	(		pos,
			head
	)		for (pos = (head)->next; pos != RT_NULL; pos = pos->next)

rt_slist_for_each - iterate over a single list

Parameters

pos	the rt_slist_t * to use as a loop cursor.
head	the head for your single list.

rt_slist_for_each_entry

#define rt_slist_for_each_entry	(		pos,
			head,
			member
	)

Value:

    for (pos = ((head)->next == (RT_NULL) ? (RT_NULL) : rt_slist_entry((head)->next, rt_typeof(*pos), member)); \
         pos != (RT_NULL) && &pos->member != (RT_NULL); \
         pos = (pos->member.next == (RT_NULL) ? (RT_NULL) : rt_slist_entry(pos->member.next, rt_typeof(*pos), member)))

rt_slist_for_each_entry - iterate over single list of given type

Parameters

pos	the type * to use as a loop cursor.
head	the head for your single list.
member	the name of the list_struct within the struct.

rt_slist_first_entry

#define rt_slist_first_entry	(		ptr,
			type,
			member
	)		rt_slist_entry((ptr)->next, type, member)

rt_slist_first_entry - get the first element from a slist

Parameters

ptr	the slist head to take the element from.
type	the type of the struct this is embedded in.
member	the name of the slist_struct within the struct.

Note, that slist is expected to be not empty.

rt_slist_tail_entry

#define rt_slist_tail_entry	(		ptr,
			type,
			member
	)		rt_slist_entry(rt_slist_tail(ptr), type, member)

rt_slist_tail_entry - get the tail element from a slist

Parameters

ptr	the slist head to take the element from.
type	the type of the struct this is embedded in.
member	the name of the slist_struct within the struct.

Note, that slist is expected to be not empty.

Function Documentation

rt_hw_backtrace_frame_get()

rt_weak rt_err_t rt_hw_backtrace_frame_get	(	rt_thread_t	thread,
		struct rt_hw_backtrace_frame *	frame
	)

Get the inner most frame of target thread.

Parameters

thread	the thread which frame belongs to
frame	the specified frame to be unwound

Returns

rt_err_t 0 is succeed, otherwise a failure

rt_hw_backtrace_frame_unwind()

rt_weak rt_err_t rt_hw_backtrace_frame_unwind	(	rt_thread_t	thread,
		struct rt_hw_backtrace_frame *	frame
	)

Unwind the target frame.

Parameters

thread	the thread which frame belongs to
frame	the specified frame to be unwound

Returns

rt_err_t 0 is succeed, otherwise a failure

rt_show_version()

void rt_show_version

(

void

)

This function will show the version of rt-thread rtos.

rt_backtrace()

rt_err_t rt_backtrace

(

void

)

Print backtrace of current thread to system console device.

Returns

rt_err_t 0 is success, otherwise a failure

rt_backtrace_frame()

rt_err_t rt_backtrace_frame	(	rt_thread_t	thread,
		struct rt_hw_backtrace_frame *	frame
	)

Print backtrace from frame to system console device.

Parameters

thread	the thread which frame belongs to
frame	where backtrace starts from

Returns

rt_err_t 0 is success, otherwise a failure

rt_backtrace_formatted_print()

rt_err_t rt_backtrace_formatted_print	(	rt_ubase_t *	buffer,
		long	buflen
	)

Print backtrace from buffer to system console.

Parameters

buffer	where traced frames saved
buflen	number of items in buffer

Returns

rt_err_t 0 is success, otherwise a failure

rt_backtrace_to_buffer()

rt_err_t rt_backtrace_to_buffer	(	rt_thread_t	thread,
		struct rt_hw_backtrace_frame *	frame,
		long	skip,
		rt_ubase_t *	buffer,
		long	buflen
	)

Print backtrace from frame to the given buffer.

Parameters

thread	the thread which frame belongs to
frame	where backtrace starts from. NULL if it's the current one
skip	the number of frames to discarded counted from calling function. Noted that the inner most frame is always discarded and not counted, which is obviously reasonable since that's this function itself.
buffer	where traced frames saved
buflen	max number of items can be saved in buffer. If there are no more than buflen items to be saved, there will be a NULL after the last saved item in the buffer.

Returns

rt_err_t 0 is success, otherwise a failure

rt_backtrace_thread()

rt_err_t rt_backtrace_thread

(

rt_thread_t

thread

)

Print backtrace of a thread to system console device.

Parameters

thread

which call stack is traced

Returns

rt_err_t 0 is success, otherwise a failure

rt_realloc_set_entry_hook()

void rt_realloc_set_entry_hook

(

void(*)(void **ptr, rt_size_t size)

hook

)

This function will set a hook function, which will be invoked when a memory block is allocated from heap memory.

Parameters

hook	the hook function.

rt_realloc_set_exit_hook()

void rt_realloc_set_exit_hook

(

void(*)(void **ptr, rt_size_t size)

hook

)

This function will set a hook function, which will be invoked when a memory block is allocated from heap memory.

Parameters

hook	the hook function.

rt_free_sethook()

void rt_free_sethook

(

void(*)(void **ptr)

hook

)

This function will set a hook function, which will be invoked when a memory block is released to heap memory.

Parameters

hook	the hook function

rt_system_heap_init_generic()

void rt_system_heap_init_generic	(	void *	begin_addr,
		void *	end_addr
	)

This function will do the generic system heap initialization.

Parameters

begin_addr	the beginning address of system page.
end_addr	the end address of system page.

rt_system_heap_init()

rt_weak void rt_system_heap_init	(	void *	begin_addr,
		void *	end_addr
	)

This function will init system heap. User can override this API to complete other works, like heap sanitizer initialization.

Parameters

begin_addr	the beginning address of system page.
end_addr	the end address of system page.

rt_malloc()

rt_weak void* rt_malloc

(

rt_size_t

size

)

Allocate a block of memory with a minimum of 'size' bytes.

Parameters

size	is the minimum size of the requested block in bytes.

Returns

the pointer to allocated memory or NULL if no free memory was found.

rt_realloc()

rt_weak void* rt_realloc	(	void *	ptr,
		rt_size_t	newsize
	)

This function will change the size of previously allocated memory block.

Parameters

ptr	is the pointer to memory allocated by rt_malloc.
newsize	is the required new size.

Returns

the changed memory block address.

rt_calloc()

rt_weak void* rt_calloc	(	rt_size_t	count,
		rt_size_t	size
	)

This function will contiguously allocate enough space for count objects that are size bytes of memory each and returns a pointer to the allocated memory.

Note

The allocated memory is filled with bytes of value zero.

Parameters

count	is the number of objects to allocate.
size	is the size of one object to allocate.

Returns

pointer to allocated memory / NULL pointer if there is an error.

rt_free()

rt_weak void rt_free

(

void *

ptr

)

This function will release the previously allocated memory block by rt_malloc. The released memory block is taken back to system heap.

Parameters

ptr	the address of memory which will be released.

rt_memory_info()

rt_weak void rt_memory_info	(	rt_size_t *	total,
		rt_size_t *	used,
		rt_size_t *	max_used
	)

This function will caculate the total memory, the used memory, and the max used memory.

Parameters

total	is a pointer to get the total size of the memory.
used	is a pointer to get the size of memory used.
max_used	is a pointer to get the maximum memory used.

rt_malloc_align()

rt_weak void* rt_malloc_align	(	rt_size_t	size,
		rt_size_t	align
	)

This function allocates a memory block, which address is aligned to the specified alignment size.

Parameters

size	is the allocated memory block size.
align	is the alignment size.

Returns

The memory block address was returned successfully, otherwise it was returned empty RT_NULL.

rt_free_align()

rt_weak void rt_free_align

(

void *

ptr

)

This function release the memory block, which is allocated by rt_malloc_align function and address is aligned.

Parameters

ptr	is the memory block pointer.

__rt_ffs()

int __rt_ffs

(

int

value

)

This function finds the first bit set (beginning with the least significant bit) in value and return the index of that bit.

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.

Parameters

value

is the value to find the first bit set in.

Returns

Return the index of the first bit set. If value is 0, then this function shall return 0.

rt_list_init()

rt_inline void rt_list_init

(

rt_list_t *

l

)

initialize a list

Parameters

l	list to be initialized

rt_list_insert_after()

rt_inline void rt_list_insert_after	(	rt_list_t *	l,
		rt_list_t *	n
	)

insert a node after a list

Parameters

l	list to insert it
n	new node to be inserted

rt_list_insert_before()

rt_inline void rt_list_insert_before	(	rt_list_t *	l,
		rt_list_t *	n
	)

insert a node before a list

Parameters

n	new node to be inserted
l	list to insert it

rt_list_remove()

rt_inline void rt_list_remove

(

rt_list_t *

n

)

remove node from list.

Parameters

n	the node to remove from the list.

rt_list_isempty()

rt_inline int rt_list_isempty

(

const rt_list_t *

l

)

tests whether a list is empty

Parameters

l	the list to test.

rt_list_len()

rt_inline unsigned int rt_list_len

(

const rt_list_t *

l

)

get the list length

Parameters

l	the list to get.

rt_slist_init()

rt_inline void rt_slist_init

(

rt_slist_t *

l

)

initialize a single list

Parameters

l	the single list to be initialized