Xilkernel API函数介绍

URL: http://hi.baidu.com/firstm25/item/620a35f46d778714d7ff8cba

Xilkernel是Xilinx公司提供的用于EDK系统的小型、模块化的操作系统，支持MicroBlaze、PowerPC405以及PowerPC440处理器。支持可移植操作系统接口(POSIX）。

Xilkernel功能函数包括：线程管理、信号量、消息队列、共享内存、互斥锁、动态内存管理、软件定时、用户层中断处理API等几个方面。

-------------------------------------------------------------

1、线程管理包括如下API函数

Xilkernel支持基本的POSIX线程操作，需要配合线程设置共同作用。使用该类函数需要包含头文件pthread.h。

int pthread_create(pthread_t thread, pthread_attr_t* att, void*(*start_func)(void*),void* param)
参数：thread是存储线程ID的地址，attr存储线程属性结构体的地址，start_func线程函数名，param线程函数参数指针。
返回：0创建成功，-1线程ID无效，EINVAL无效属性，EAGAIN资源不足
创建线程并执行。

void pthread_exit(void *value_ptr)
参数：线程返回值的指针
结束一个线程，但这个函数并不是必须的。需要用到返回值时才使用。

int pthread_join(pthread_t thread, void **value_ptr)
参数：thread线程ID，value_ptr线程返回值地址指针
返回：0成功，ESRCH无效线程，EINVAL线程返回值已经被使用
停止当前线程等待目标线程执行完成并返回值。

pthread_t pthread_self(void)
返回：本线程ID

int pthread_detach(pthread_t target)
返回：0成功，ESRCH线程未创建
回收线程存储资源，但并不会结束线程。

int pthread_equal(pthread_t t1, pthread_t t2)
参数：t1和t2两个待比较线程的ID
返回：1两线程是同一线程，0其它情况

int pthread_getschedparam(pthread_t thread, int *policy, struct sched_param *param)
参数：thread线程ID，policy全局调度策略指针，param调度策略结构体地址
返回：0成功，ESRCH线程无效，EINVAL调度参数无效
函数返回个别线程的调度策略。

int pthread_setschedparam(pthread_t thread, int policy, const struct sched_param *param)
参数：thread线程ID，policy忽略，param调度策略结构体地址
返回：0成功，ESRCH线程无效，EINVAL调度参数无效
函数返回个别线程的调度策略。

int pthread_attr_init(pthread_attr_t* attr)
参数：线程属性指针
返回：0成功，1未成功，EINVAL属性无效
按照默认设置初始化线程属性对象attr

int pthread_attr_destroy (pthread_attr_t* attr)
参数：线程属性指针
返回：0成功，EINVAL错误
函数销毁线程指针对象，设置成未定义值。

int pthread_attr_setdetachstate(pthread_attr_t* attr, int dstate)
参数：attr属性结构体，dstate要设置的状态
返回：0成功，EINVAL无效参数
设置线程状态

int pthread_attr_getdetachstate(pthread_attr_t* attr, int *dstate)
参数：attr属性结构体，dstate获取的状态地址
返回：0成功，EINVAL无效参数
获取线程状态：PTHREAD_CREATE_DETACHED或者PTHREAD_CREATE_JOINABLE

int pthread_attr_setschedparam(pthread_attr_t* attr, struct sched_param *schedpar)
参数：attr属性结构体，schedpar调度参数存储地址
返回：0成功，EINVAL无效参数，ENOTSUP无效调度参数
设置线程优先级，sched_param在sched.h文件中定义

int pthread_attr_getschedparam(pthread_attr_t* attr, struct sched_param* schedpar)
参数：attr属性结构体，schedpar线程调度参数指针
返回：0成功，EINVAL无效参数
获取线程优先级。

int pthread_attr_setstack(const pthread_attr_t *attr, void *stackaddr, size_t stacksize)
参数：attr属性结构体，stacksize堆栈地址
返回：0成功，EINVAL堆栈设置不当
设置线程堆栈

int pthread_attr_getstack(const pthread_attr_t *attr, void **stackaddr, size_t *stacksize)
参数：attr属性结构体，stackaddr堆栈地址指针，stacksize堆栈空间以字节为单位
返回：0成功，EINVAL无效属性
获取线程的堆栈信息

pid_t get_currentPID(void)
返回：当前正在运行的线程或操作的ID

int kill(pid_t pid)
参数：pid线程或操作ID
返回：0成功，-1未成功
终止指定线程或操作

int process_status(pid_t pid, p_stat *ps)
参数：pid操作或线程ID，ps状态存储地址
返回：无
获取当前正在运行的县城或操作的状态

int xmk_add_static_thread(void* (*start_routine)(void *), int sched_priority)
参数：start_routine线程函数，sched_priority优先级
返回：0成功，-1未成功
该函数将线程加入到启动或静态线程列表中，这个函数要在xilkernel_main()函数之前调用

int yield(void)
迫使处理器运行下一个准备好的线程或操作，当前线程或操作今日任务准备完毕队列，等待再次获取时间片运行。

-------------------------------------------------------------

2、信号量包括API函数如下

Xilkernel支持信号量操作，信号量提供高速的任务间同比和互斥机制，遵循POSIX。Xilkernel的信号量分为有名信号量和无名信号量量化总。有名信号量基于文件系统实现，无名信号量基于内存实现。信号量是实现进程间通信（IPC）的重要手段，使用该类函数需要包含头文件semaphore.h。

int sem_init(sem_t *sem, int pshared, unsigned value)
参数：sem信号量ID，pshared共享状态，value初始值
返回：0成功，-1未成功。
初始化一个信号量，并初始化信号量的值，适用于无名信号量。

int sem_destroy(sem_t* sem)
参数：sem信号量ID
返回：0成功，-1未成功
释放一个信号量资源，适用于无名信号量

int sem_getvalue(sem_t* sem, int* value)
参数：sem信号量ID，value获取值地址
返回：0成功，-1未成功
获取信号量当前值

int sem_wait(sem_t* sem)
参数：sem信号量ID
返回：0成功，-1未成功
等待信号量的值大于0，并将信号量值减1。执行对信号量的锁操作

int sem_trywait(sem_t* sem)
参数：sem信号量ID
返回：0成功，-1未成功
功能与sem_trywait()函数相同，但不阻塞进程。

int sem_timedwait(sem_t* sem, unsigned ms)
参数：sem信号量ID，ms定时器时间
返回：0成功，-1未成功
功能与sem_trywait()函数相同，等待信号量大于0过程中，通过定时器超时来停止阻塞进程。

sem_t* sem_open(const char* name, int oflag,...)
参数：name信号量对象的字符串名，oflag控制信号量创建的标识
返回：创建的或已存在的信号量ID
创建一个信号量，适用于有名的信号量

int sem_close(sem_t* sem)
参数：sem信号量ID
返回：0成功，-1未成功
关闭信号量，适用于有名信号量

int sem_post(sem_t* sem)
参数：sem信号量ID
返回：0成功，-1未成功
增加信号量的值，执行该函数为制定信号量的值加1

int sem_unlink(const char* name)
参数：name信号量名
返回：0成功，-1未成功
移除信号量，适用于有名信号量

-------------------------------------------------------------

3、消息队列包含API函数如下

Xilkernel实现进程间同学（IPC）的另一重要手段是消息队列，使用该类函数需要包含文件sys/msg.h和sys/ipc.h

int msgget(key_t key, int msgflg)
参数：key消息队列的队列标识，msgflg消息队列创建选项
返回：唯一且非负的消息队列ID
穿件消息队列

int msgctl(int msqid, int cmd, struct msqid_ds* buf)
参数：msqid消息队列ID，cmd命令，buf数据指针
返回：0成功，-1未成功
以命令控制消息队列

int msgsnd(int msqid, const void *msgp, size_t msgsz, int msgflg)
参数：msqid消息队列ID，magp消息缓存指针，msgsz消息大小，msgflg消息发送选项
返回：0成功，-1未成功
向消息队列发送一个消息

ssize_t msgrcv(int msqid, void *msgp, size_t nbytes, long msgtyp, int msgflg)
参数：msqid消息队列ID，msgp复制接收的消息存放地址，nbytes指定接收消息的缓存大小，msgtyp不支持，msgflg控制接收消息操作
返回：接收到的字节数，-1不成功

-------------------------------------------------------------

4、共享内存包含API函数

共享内存是速度最快、效率最高的IPC方式，其基本原理是各进程把相同的内存映射到自己的地址空间，使它看起来好像同时为同一物理内存被多个进程所用。使用该类函数需要包含头文件sys/shm.h和sys/ipc.h

int shmget(key_t key, size_t size, int shmflg)
参数：key共享内存标识，size共享内存大小，shmflg创建选项
返回：非负唯一的共享内存ID，-1未成功
获取共享内存的ID

int shmctl(int shmid, int cmd, struct shmid_ds *buf)
参数：shmid共享内存ID，cmd命令，buf状态接收缓存
返回：0成功，-1未成功
实现对共享内存的控制操作

void* shmat(int shmid, const void *shmaddr, int flag)
参数：shmid共享内存ID，shmaddr未用，flag设置共享内存附属选项
返回：共享内存的起始地址，NULL未成功
把共享内存映射到调用该函数的地址空间，方便进程对其访问

int shm_dt(void *shmaddr)
参数：shmaddr共享内存地址
返回：0成功，-1未成功
解除进程对共享内存的映射

-------------------------------------------------------------

5、互斥锁包含API函数

在多线程程序中，通过互斥锁来保护共享数据是一种比较常用的方式。使用该类函数需要包含头文件pthread.h

int pthread_mutex_init(pthread_mutex_t* mutex, const pthread_mutexattr_t* attr)
参数：mutex互斥锁ID地址，attr互斥锁创建属性结构体
返回：0成功返回ID到地址中，EAGAIN资源不足
初始化互斥锁

int pthread_mutex_destroy(pthread_mutex_t* mutex)
参数：mutex互斥锁ID
返回：0成功，EINVAL无效ID
释放互斥资源，执行该函数后，互斥资源变为未初始化状态。

int pthread_mutex_lock(pthread_mutex_t* mutex)
参数：mutex互斥锁ID
返回：0成功锁定，-1未成功
枷锁操作，某个线程调用该函数为互斥锁资源枷锁，保证操作时其它线程不能访问这个资源。如果资源已被锁定，则阻塞调用。

int pthread_mutex_trylock(pthread_mutex_t* mutex)
参数：mutex互斥锁ID
返回：0成功，EINVAL无效ID，EBUSY资源已被锁定，-1其它错误
尝试锁定资源，若资源未被锁定则成功返回，若资源已被锁定，也不会阻塞调用

int pthread_mutex_unlock(pthread_mutex_t* mutex)
参数：mutex互斥锁ID
返回：0成功，EINVAL无效ID，-1其它错误
解锁互斥资源

int pthread_mutexattr_init(pthread_mutexattr_t* attr)
参数：attr属性结构体地址
返回：0成功，EINVAL无效属性
初始化互斥资源的属性

int pthread_mutexattr_destroy(pthread_mutexattr_t* attr)
参数：attr属性结构体
返回：0成功，EINVAL无效属性
拆除互斥资源的属性，使得互斥资源的属性变为未初始化状态

int pthread_mutexattr_settype(pthread_mutexattr_t* attr, int type)
参数：attr属性结构体，type互斥锁类型
返回：0成功，EINVAL无效属性或类型不支持
在共享资源的属性中设置资源类型

int pthread_mutexattr_gettype(pthread_mutexattr_t* attr, int *type)
参数：attr属性结构体，type类型存储地址
返回：0成功，EINVAL无效属性
获取属性中的资源类型

-------------------------------------------------------------

6、动态内存管理包含API函数

动态内存管理，是Xilkernel提供的一种内存管理接口，类似标准C语言中的malloc、free等函数执行的功能，但更简洁高效。使用该类函数要包含头文件sys/bufmalloc.h

int bufcreate(membuf_t *mbuf, void *memptr, int nblks, size_t blksiz)
参数：mbuf缓冲池ID地址，memptr可用缓冲池，nblks缓冲池内存储块数量，blksiz每个存储块字节数
返回：0成功并存储缓冲池ID，-1错误
建立一个缓冲池

int bufdestroy(membuf_t mbuf)
参数：mbuf缓冲池ID
返回：0成功，-1错误
拆除一个缓冲池

void* bufmalloc(membuf_t mbuf, size_t size)
参数：mbuf缓冲池ID，size所需内存块大小
返回：申请到的内存起始地址，NULL未成功
从缓冲池中申请一块内存

void buffree(membuf_t mbuf, void* mem)
参数：mbuf缓冲池ID，mem内存块地址
释放指定的内存，释放后内存回到缓冲池，等待其他线程申请

-------------------------------------------------------------

7、软件定时包含API函数

Xilkernel提供了软件定时器接口函数，方便用户访问软件计时器。使用该类函数需要包含头文件sys/timer.h

unsigned int xget_clock_ticks()
返回：节拍数
获取Xilkernel启动到该函数调用之间的时间节拍数

time_t time(time_t *timer)
参数：timer存储被要求的时间信息
返回：秒数
获取Xilkernel启动到该函数调用之间的时间秒数

unsigned sleep(unsigned int ms)
参数：ms毫秒数
返回：休眠间秒数
休眠进程（毫秒数）

-------------------------------------------------------------

8、用户中断API函数

unsigned int register_int_handler(int_id_t id, void *（handler)(void*), void *callback)
参数：id中断号；handler用户定义中断处理函数；callback是handler的参数
返回：XST_SUCCESS表示成功，其它表示出错（详见xstatus.h文件）
注册用户中断函数关联

void unregister_int_handler(int_id_t id)
参数：id中断号
取消用户中断函数关联

void enable_interrupt(int_id_t id)
参数：中断号
在中断控制器中使能对应中断

void disable_interrupt(int_id_t id)
参数：中断号
在中断控制器中禁止对应中断

void acknowledge_interrupt(int_id_t id)
参数：中断号
在中断控制器中应答对应中断

-------------------------------------------------------------