API.TXT

参考手册  
KLite API参考手册 V4.0

1.功能特性
    KLite是一个基于ARM/Cortex-M微控制器设计的抢占式操作系统内核。
    其设计思想是“简洁易用”, 以降低学习和使用难度为目标。
    ->支持优先级抢占
    ->支持线程同步互斥
    ->支持动态内存管理

2.数据类型
    thread_t     线程标识符
    mutex_t      互斥锁标识符
    event_t      事件标识符
  
3.API参考
 3.1 内核相关
-------------------------------------------------------------------------------
    void kernel_init(uint32_t heap_addr, uint32_t heap_size)
    功能： 
        内核初始化.
    参数： 
        addr    动态管理内存起始地址
        size    动态管理内存大小 
    返回值： 
        无
    备注：
        在调用内核初始化时保证中断处于关闭状态,此函数只能执行一次,
        在初始化内核之前不可调用内核其它函数.
        
-------------------------------------------------------------------------------
    void kernel_start(void)
    功能： 
        启动内核,内部调用底层函数cpu_os_start,启动滴答定时器.
    参数： 
        无 
    返回值： 
        无
    备注：
        此函数不会返回,所以在调用之前应该创建一个用户线程.
        
-------------------------------------------------------------------------------
    void kernel_time_tick(uint32_t time)
    功能：
        内核时间计时
    参数：
        time 计时时间(毫秒)
    返回值：
        无
    备注：
        此函数由滴答时钟中断程序调用, 应用程序不应该调用此函数.
        
-------------------------------------------------------------------------------
    uint32_t kernel_version(void)
    功能：
        返回KLite内核的版本号
    参数：
        无
    返回值：
        版本号,BIT[31：24]主版本号,BIT[23：16]次版本号,BIT[15：0]修订号
        
------------------------------------------------------------------------------- 
    uint32_t kernel_time(void)
    功能：
        返回内核从启动到现在所经历的时间(毫秒).
    参数：
        无
    返回值：
        系统时间(毫秒)
        
------------------------------------------------------------------------------- 
    void kernel_idle(void)
    功能：
        处理内核空闲事务,回收线程资源
    参数：
        无
    返回值：
        无
    备注：
        此函数不会返回,需要单独创建一个用户线程,并直接调用.
        
------------------------------------------------------------------------------- 
    uint32_t kernel_idle_time(void)
    功能：
        返回内核从启动到现在空闲线程所运行的时间(毫秒).
    参数：
        无
    返回值：
        系统空闲时间(毫秒)

 3.2 内存管理
-------------------------------------------------------------------------------
    void* heap_alloc(uint32_t size)
    功能：
        向内核申请一段连续内存,功能和malloc一样
    参数：
        size    要申请的内存大小
    返回值：
        申请成功返回内存指针
        申请失败返回NULL
    备注：
        使用heap_alloc申请的内存,在使用完毕后,请使用heap_free释放内存.
        
-------------------------------------------------------------------------------
    void heap_free(void *mem)
    功能：
        释放由heap_malloc申请的内存,功能和free一样
    参数：
        mem     由heap_alloc申请的内存指针
    返回值：
        无
    备注：
        使用heap_alloc申请的内存,在使用完毕后,请使用heap_free释放内存. 
        
-------------------------------------------------------------------------------
    void heap_usage(uint32_t *total, uint32_t *used)
    功能：
        获取内存用量信息
    参数：
        used    输出已使用的内存数量(字节)
        total   输出总内存数量(字节)
    返回值：
        无
    备注：
        可使用此函数关注系统内存消耗,以适当调整内存分配.

 3.3 线程管理
-------------------------------------------------------------------------------
    thread_t thread_create(void(*entry)(void*), void *arg, uint32_t stack_size)
    功能：
        创建一个新的线程,并加入就绪队列
    参数：
        entry      线程入口函数
        arg        线程入口函数的参数
        stack_size 线程拥有的栈空间大小,如果该值为0则使用系统默认的栈大小
    返回值：
        成功返回线程标识符
        失败返回NULL
    备注：
        内核自动为新线程分配内存空间和栈空间,如果栈设置太小容易在运行过程中产
        生栈溢出错误,如果设置太大可能会由于系统内存不足而创建失败.
        
-------------------------------------------------------------------------------
    void thread_delete(thread_t thread)
    功能：
        结束一个线程,并释放内存
    参数：
        thread  要结束的线程标识符
    返回值：
        无
    备注：
        该函数会直接停止线程运行,并释放线程所占用的内存.
        该函数不能用来结束当前线程.
        如果想要结束当前线程请使用thread_exit()或直接使用return.
        
-------------------------------------------------------------------------------
    void thread_set_priority(thread_t thread, int prio)
    功能：
        设置线程优先级
    参数：
        thread      线程标识符
        prio        新的优先级
    返回值：
        无
    备注：
        线程优先级决定线程调度顺序,越高的优先级具有越高的实时性,线程默认优先级为0
        
-------------------------------------------------------------------------------
    int thread_get_priority(thread_t thread)
    功能：
        获取线程当前优先级
    参数：
        thread  线程标识符
    返回值：
        该线程当前的优先级
        
-------------------------------------------------------------------------------
    thread_t thread_self(void)
    功能：
        获取当前线程标识符
    参数：
        无
    返回值：
        当前线程的标识符
        
-------------------------------------------------------------------------------
    void thread_sleep(uint32_t time)
    功能：
        将当前线程休眠一段时间,释放CPU控制权
    参数：
        time    休眠时间(毫秒)
    返回值：
        无
    备注：
        如果time参数为0,则函数直接返回.
        
-------------------------------------------------------------------------------
    void thread_exit(void)
    功能：
        退出当前线程
    参数：
        无
    返回值：
        无
    备注：
        此函数不会立即释放线程资源,需等待系统空闲时释放.
        
-------------------------------------------------------------------------------
    void thread_suspend(void)
    功能：
        挂起当前线程
    参数：
        无
    返回值：
        无

-------------------------------------------------------------------------------
    void thread_resume(thread_t thread)
    功能：
        恢复被挂起的线程
    参数：
        thread  线程标识符
    返回值：
        无
    备注：
        只能用来恢复处于挂起状态的线程.
        
-------------------------------------------------------------------------------
    uint32_t thread_time(thread_t thread)
    功能：
        获取线程自创建以来所占用CPU的时间.
    参数：
        thread  线程标识符
    返回值：
        线程运行的时间(毫秒)
    备注：
        可以使用此函数来监控线程的CPU占用率
        

 3.4 互斥锁
-------------------------------------------------------------------------------
    mutex_t mutex_create(void)
    功能：
        创建一个新的互斥锁
    参数：
        无
    返回值：
        成功返回互斥锁标识符
        失败返回NULL
    备注：
        互斥锁暂不支持递归调用.
    
-------------------------------------------------------------------------------
    void mutex_lock(mutex_t mutex)
    功能：
        将mutex指定的互斥锁标记为锁定状态
    参数：
        mutex   互斥锁标识符
    返回值：
        无
    备注：
        如果mutex指向的互斥锁已被其它线程锁定,则调用线程将会被阻塞,直到另一个线程
        释放这个互斥锁.
        
-------------------------------------------------------------------------------
    bool mutex_try_lock(mutex_t mutex)
    功能：
        尝试将mutex指定的互斥锁标记为锁定状态
    参数：
        mutex   互斥锁标识符
    返回值：
        锁定成功，则返回true；锁定失败则返回false。
    备注：
        此函数是mutex_lock的非阻塞版本。
        
-------------------------------------------------------------------------------
    void mutex_unlock(mutex_t mutex)
    功能：
        释放由参数mutex指定的互斥锁
    参数：
        mutex   互斥锁标识符
    返回值：
        无
    备注：
        mutex_lock和mutex_unlock必须成对出现.
        
-------------------------------------------------------------------------------
    void mutex_delete(mutex_t mutex)
    功能：
        删除一个互斥锁,释放内存
    参数：
        mutex   被删除的互斥锁标识符
    返回值：
        无
    备注：
        在删除互斥锁的时候不会检查是否有线程拥有这个互斥锁。
        因此在删除之前请确认没有线程在使用。


 3.6 事件
-------------------------------------------------------------------------------
    event_t event_create(void)
    功能：
        创建一个新的事件对象。
    参数：
        无
    返回值：
        创建成功返回事件标识符。
        创建失败返回NULL。
    备注：
        事件对象用于线程之间的同步，提供三种唤醒模式分别应用于：
        1.二元信号量模式(event_post)
        2.条件变量模式(event_signal/event_broadcast)
        3.红绿灯模式(event_fire)
        请详细阅读下面的API函数说明。
        
-------------------------------------------------------------------------------
    void event_delete(event_t event)
    功能：
        删除事件对象,并释放内存。
    参数：
        event   事件标识符。
    返回值：
        无。
    备注：
        在没有线程使用它时才能删除,否则可能产生未知的异常。
        
-------------------------------------------------------------------------------
    void event_wait(event_t event)
    功能：
        等待事件。
    参数：
        event   事件标识符。
    返回值：
        无。
    备注：
        如果event当前为有信号状态，则此函数会把event置为无信号状态,然后退出函数，
        否则将会挂起当前线程，直到其它线程将event置为有信号状态。
        
-------------------------------------------------------------------------------
    bool event_timed_wait(event_t event, uint32_t timeout)
    功能：
        定时等待事件.
    参数：
        event   事件标识符.
        timeout 等待超时时间，单位为滴答节拍数.
    返回值：
        等待成功返回true.
        等待超时返回false.
    备注：
        功能与event_wait类似, 
        但event_wait会永久挂起线程直到被事件唤醒，
        而event_timedwait只会挂起线程一段时间。
        
-------------------------------------------------------------------------------
    void event_post(event_t event)
    功能：
        标记事件为一次有效状态.
    参数：
        event   事件标识符.
    返回值：
        无.
    备注：
        如果当前event等待队列中没有挂起线程，则将event标记为有信号状态；
        否则将唤醒等待队列中优先级最高的一个线程，但event依旧保持无信号状态。
        
-------------------------------------------------------------------------------
    void event_fire(event_t event)
    功能：
        标记事件为长期有效状态.
    参数：
        event   事件标识符.
    返回值：
        无.
    备注：
        将唤醒当前event等待队列中的所有线程，并且将事件标记为长期有效状态。
        在长期有效状态下，event的状态不会被event_wait函数改变。
        要想清除这种长期有效的状态，可以使用event_reset函数。
        
-------------------------------------------------------------------------------
    void event_reset(event_t event)
    功能：
        清除事件的有效状态.
    参数：
        event   事件标识符.
    返回值：
        无.
    备注：
        无论当前event处于什么状态，都会将event标记为无信号状态。
        此函数不会唤醒任何被event挂起的线程。

-------------------------------------------------------------------------------
    bool event_signal(event_t event)
    功能：
        唤醒等待队列中的优先级最高的一个线程.
    参数：
        event   事件标识符.
    返回值：
        如果成功唤醒线程则返回true。
        否则返回false，表明当前等待队列为空。
    备注：
        此函数只会唤醒一个等待队列中的高优先级线程。
        如果当前等待队列中没有线程，此函数不会改变event的状态。
        
-------------------------------------------------------------------------------
    bool event_broadcast(event_t event)
    功能：
        唤醒等待队列中的所有线程.
    参数：
        event   事件标识符.
    返回值：
        如果成功唤醒线程则返回true。
        否则返回false，表明当前等待队列为空。
    备注：
        此函数会唤醒等待队列中的所有线程。
        如果当前等待队列中没有线程，此函数不会改变event的状态。
        

#### 4 其它
下载地址： www.oschina.net/p/KLite