本文转载出处：http://git.oschina.net/kerndev/klite/wikis/API%E6%89%8B%E5%86%8C
#KLite API参考手册
##1.功能特性 KLite是一个为ARM Cortex-M微控制器设计的微内核,设计思想是"简洁易用".
-1- 支持动态内存管理;
-2- 支持256级线程抢占优先级;
-3- 支持线程同步:互斥锁,信号量,事件.
-4- 规范的编码风格.
##2.数据类型 KLite提供以下4种内核对象:
kthread_t 线程标识符
kmutex_t 互斥锁标识符
kevent_t 事件标识符
ksem_t 信号量标识符
##3.API参考 ###3.1 内核相关
原型:
void kernel_init(uint32_t addr, uint32_t size)
功能:
KLite内核初始化.
参数:
addr 内核动态管理内存起始地址
size 内核动态管理内存大小
返回值:
无
备注:在调用内核初始化时保证中断处于关闭状态,此函数只能执行一次,在初始化内核之前不能调用任何KLite相关的API.
原型:
void kernel_start(void)
功能:
启动KLite内核,内部调用底层函数cpu_tick_init,以启动滴答定时器.
参数:
无
返回值:
无
备注:
在启动KLite之前调用至少需要创建一个用户线程.
原型:
uint32_t kernel_version(void)
功能:
返回KLite内核的版本号
参数:
无
返回值:
版本号,BIT[31:24]主版本号,BIT[23:16]次版本号,BIT[15:0]修订号
原型:
uint32_t kernel_time(void)
功能:
返回内核自启动以来的节拍数,单位毫秒
参数:
无
返回值:
节拍数
###3.2 内存管理
原型:
void* kmem_alloc(uint32_t size)
功能:
向内核申请一段连续内存,功能和malloc一样
参数:
size 要申请的内存大小
返回值:
申请成功返回内存指针
申请失败返回NULL
备注:
使用kmem_alloc申请的内存,在使用完毕后,请使用kmem_free释放内存.
原型:
void kmem_free(void* mem)
功能:
释放由kmem_malloc申请的内存,功能和free一样
参数:
mem 由kmem_alloc申请的内存指针
返回值:
无
备注:
使用kmem_alloc申请的内存,在使用完毕后,请使用kmem_free释放内存.
原型:
void kmem_info(uint32_t* total, uint32_t* used)
功能:
获取内存用量信息
参数:
used 输出已使用的内存数量(字节)
total 输出总内存数量(字节)
返回值:
无
备注:
可使用此函数关注系统内存消耗,以适当调整内存分配.
###3.3 线程管理
原型:
kthread_t kthread_create(void(*func)(void*), void* arg, uint32_t stksize)
功能:
创建一个新的线程
参数:
func 线程入口函数
arg 线程入口函数的参数
stksize 线程拥有的栈空间大小,如果该值为0则使用系统默认的栈大小
返回值:
成功返回线程标识符
失败返回NULL
备注:
KLite自动为新线程分配内存空间包括栈空间,如果栈空间设置太小容易在运行过程中产
生错误,如果设置太大可能会由于系统内存不足而创建失败.
原型:
void kthread_destroy(kthread_t thread)
功能:
结束一个线程,并释放内存
参数:
thread 要结束的线程标识符
返回值:
无
备注:
该函数会直接停止线程运行,并释放线程所占用的内存.
原型:
void kthread_setprio(kthread_t thread, int prio)
功能:
设置线程优先级
参数:
thread 线程标识符
prio 新的优先级,最小-127,最大+127
返回值:
无
备注:
线程优先级决定线程调度次序,越高的优先级具有越高的实时性,线程默认优先级为0
原型:
int kthread_getprio(kthread_t thread)
功能:
获取线程当前优先级
参数:
thread 线程标识符
返回值:
该线程当前的优先级
原型:
kthread_t kthread_self(void)
功能:
获取当前线程标识符
参数:
无
返回值:
当前线程的标识符
原型:
void kthread_sleep(uint32_t ms)
功能:
将当前线程休眠一段时间,释放CPU控制权
参数:
ms 休眠时间,单位毫秒
返回值:
无
###3.4 互斥锁
原型:
kmutex_t kmutex_create(void)
功能:
创建一个新的互斥锁
参数:
无
返回值:
成功返回互斥锁标识符
失败返回NULL
原型:
void kmutex_lock(kmutex_t mutex)
功能:
将mutex指定的互斥锁标记为锁定状态
参数:
mutex 互斥锁标识符
返回值:
无
备注:
如果mutex指向的互斥锁已由其它线程锁定,则调用线程将会阻塞,直到另一个线程释放
这个互斥锁.
原型:
void kmutex_unlock(kmutex_t mutex)
功能:
释放由参数mutex指定的互斥锁
参数:
mutex 互斥锁标识符
返回值:
无
备注:
kmutex_lock和kmutex_unlock必须成对出现,否则可能产生死锁.
原型:
void kmutex_destroy(kmutex_t mutex)
功能:
销毁一个互斥锁,并释放内存
参数:
mutex 在注销的互斥锁标识符
返回值:
无
备注:
销毁互斥锁之前确认没有线程被它阻塞.
###3.5 信号量
原型:
ksem_t ksem_create(int value)
功能:
创建一个新的信号量.
参数:
value 信号量初始值,必须为正数.
返回值:
创建成功返回信号量标识符.
创建失败返回NULL.
备注:
无.
原型:
void ksem_wait(ksem_t sem)
功能:
等待该信号量为一个非零值,然后将信号量的值减去1.
参数:
sem 信号量标识符.
返回值:
无
备注:
无.
原型:
int ksem_timedwait(ksem_t sem, uint32_t ms)
功能:
超时等待该信号量为一个非零值,如果未超时则将信号量的值减去1.
参数:
sem 信号量标识符.
返回值:
等待成功返回1.
等待超时返回0.
备注:
无.
原型:
void ksem_post(ksem_t sem)
功能:
给信号量的值加一.
参数:
sem 信号量标识符.
返回值:
无.
备注:
无.
原型:
int ksem_getvalue(ksem_t sem)
功能:
返回信号量的计数值.
参数:
sem 信号量标识符.
返回值:
计数值.
备注:
该函数在返回时,可能内部计数值已经发生改变.
原型:
void ksem_destory(ksem_t sem)
功能:
销毁信号量对象,并释放内存.
参数:
sem 信号量标识符.
返回值:
无.
备注:
在没有线程使用它时才能销毁,否则可能产生错误.
###3.6 事件
原型:
kevent_t kevent_create(int state)
功能:
创建一个新的事件对象.
参数:
state 初始状态,0表示无效,非0表示有效.
返回值:
创建成功返回事件标识符.
创建失败返回NULL.
备注:
无.
原型:
void kevent_wait(kevent_t event)
功能:
等待事件.
参数:
event 事件标识符.
返回值:
无.
备注:
无.
原型:
int kevent_timedwait(kevent_t event, uint32_t ms)
功能:
定时等待事件.
参数:
event 事件标识符.
ms 等待时间,单位毫秒.
返回值:
等待成功返回1.
等待超时返回0.
备注:
无.
原型:
void kevent_post(kevent_t event)
功能:
标记事件有有效状态.
参数:
event 事件标识符.
返回值:
无.
备注:
所有等待这个事件的线程都会获得.
原型:
void kevent_destory(kevent_t event)
功能:
销毁事件对象,并释放内存.
参数:
event 事件标识符.
返回值:
无.
备注:
在没有线程使用它时才能销毁,否则可能产生错误.