|
Prex Home > Document Index > Kernel API Reference | |||||||||||||||||
Prex Kernel API ReferenceVersion 1.7.0, 2007/12/24Table of ContentsIntroductionThe Prex Kernel API Reference define a programming interface for the Prex applications. This document includes the complete set of kernel services and the detailed description. General InformationData TypesThe following data types are supported by the Prex kernel. Each type represents ID of the kernel element.
Error NumbersThe definition of the Prex kernel error is compatible with the POSIX error number. However, unlike POSIX, Prex does not use an errno variable because errno is not MT-safe. So, most functions in kernel API will provide an error number as a return value. The following error names are used as the possible error number.
ObjectNAMEobject_create() - create a new objectSYNOPSISint object_create(const char *name, object_t *obj); DESCRIPTIONThe object_create() function creates a new object. The ID of the new object is stored in obj on success.The name of the object must be unique in the system. Or, the object can be created without name by setting NULL as name argument. This object can be used as a private object which can be accessed only by threads in the same task. ERRORS
NAMEobject_delete() - delete an objectSYNOPSISint object_delete(object_t obj); DESCRIPTIONThe object_delete() function deletes the object specified by obj.A thread can delete the object only when the target object is created by the thread of the same task. All pending messages related to the deleted object are automatically canceled. ERRORS
NAMEobject_lookup() - lookup an objectSYNOPSISint object_lookup(const char *name, object_t *obj); DESCRIPTIONThe object_lookup() function searches an object in the object name space. The name argument is the null-terminated string. The object ID is returned in obj on success.ERRORS
MessageNAMEmsg_send() - send a messageSYNOPSISint msg_send(object_t obj, void *msg, size_t size); DESCRIPTIONThe msg_send() function sends a message to an object. The caller thread will be blocked until any other thread receives the message and calls msg_reply() for this object. A thread can send a message to any object if it knows the object ID.The size argument specifies the size of the message buffer to send. The message is the binary data block which includes a message header. The kernel does not touch the message body, and it is necessary to recognize the predefined message format between sender and receiver. ERRORS
NAMEmsg_receive() - receive a messageSYNOPSISint msg_receive(object_t obj, void *msg, size_t size); DESCRIPTIONThe msg_receive() function receives a message from an object. A thread can receive a message from the object which was created by the thread in the same task. If the message has not arrived, the caller thread blocks until any message comes in.The size argument specifies the "maximum" size of the message buffer to receive. If the sent message is larger than this size, the kernel will automatically clip the message to the receive buffer size. A thread can not receive the multiple messages at once. ERRORS
NAMEmsg_reply() - reply to an objectSYNOPSISint msg_reply(object_t obj, void *msg, size_t size); DESCRIPTIONThe msg_reply() function sends a reply message to the object. A thread must reply to the correct object that the thread preciously received from. Otherwise, this function will be failed.The size argument specifies the size of the message buffer to reply. ERRORS
TaskNAMEtask_create() - create a new taskSYNOPSISint task_create(task_t parent, int vm_option, task_t *child); DESCRIPTIONThe task_create() function create a new task. If vm_option option can be one of the following:
vm_option flag is supported only with MMU system. The created task has always new memory map with NOMMU system. The function returns the created task ID in child, and child task will receive 0 as child. ERRORS
NAMEtask_terminate() - terminate a taskSYNOPSISint task_terminate(task_t task); DESCRIPTIONThe task_terminate() function terminates a task and deallocates all resource for the task.If the task argument point to the current task, this routine never returns. ERRORS
NAMEtask_self() - return task IDSYNOPSIStask_t task_self(void); DESCRIPTIONThe task_self() function returns ID of the current task.RETURN VALUECurrent task ID.NAMEtask_suspend() - suspend a taskSYNOPSISint task_suspend(task_t task); DESCRIPTIONThe task_suspend() function suspends all threads within the specified task.ERRORS
NAMEtask_resume() - resume a taskSYNOPSISint task_resume(task_t task); DESCRIPTIONThe task_resume() function resumes all threads within the specified task.ERRORS
NAMEtask_name() - set task nameSYNOPSISint task_name(task_t task, const char *name); DESCRIPTIONThe task_name() function set the name of the specified task. The task name can be changed at any time.This function does not returns error even if the same task name already exists in the system. ERRORS
NAMEtask_getcap() - get a task capabilitySYNOPSISint task_getcap(task_t task, cap_t *cap); DESCRIPTIONThe task_getcap() function returns the capability of the specified task. ERRORS
NAMEtask_setcap() - set a task capabilitySYNOPSISint task_setcap(task_t task, cap_t *cap); DESCRIPTIONThe task_setcap() function set the capability of the specified task. The following task capabilities are supported.
ERRORS
ThreadNAMEthread_create() - create a new threadSYNOPSISint thread_create(task_t task, thread_t *th); DESCRIPTIONThe thread_create() function creates a new thread within task. The new thread will start at the return address of the thread_create() call.Since the created thread is initially set to the suspended state, thread_resume() must be called to start it. ERRORS
NAMEthread_terminate() - terminate a threadSYNOPSISint thread_terminate(thread_t th); DESCRIPTIONThe thread_terminate() function terminates a thread. It will release all resources used by the target thread.If specified th is the current thread, this routine never returns. ERRORS
NAMEthread_load() - load the thread stateSYNOPSISint thread_load(thread_t th, void *entry, void *stack); DESCRIPTIONThe thread_load() function loads the thread state (program counter and stack pointer).The entry or stack argument can be set to NULL. In this case, the previous state is used. ERRORS
NAMEthread_self() - return thread IDSYNOPSISthread_t thread_self(void); DESCRIPTIONThe thread_self() function returns ID of the current thread.RETURN VALUECurrent thread ID.NAMEthread_yield() - yield the processorSYNOPSISvoid thread_yield(void); DESCRIPTIONThe thread_yield() function forces the current thread to release the processor.ERRORSNo errors are defined.NAMEthread_suspend() - suspend a threadSYNOPSISint thread_suspend(thread_t th); DESCRIPTIONThe thread_suspend() function suspends the specified thread. Although a thread can be suspended any number of times, it does not start to run unless it is resumed by the same number of suspend.ERRORS
NAMEthread_resume() - resume a threadSYNOPSISint thread_resume(thread_t th); DESCRIPTIONThe thread_resume() function resumes the specified thread. A thread does not begin to run, unless both a thread suspend count and a task suspend count are set to 0.ERRORS
NAMEthread_schedparam() - get/set scheduling parametersSYNOPSISint thread_schedparam(thread_t th, int op, int *param); DESCRIPTIONThe thread_schedparam() function gets/sets the various scheduling parameter. op argument is an operation ID which is one of the following value.
ERRORS
Virtual MemoryNAMEvm_allocate() - allocate memorySYNOPSISint vm_allocate(task_t task, void **addr, size_t size, int anywhere); DESCRIPTIONThe vm_allocate() function allocates a zero-filled memory in the task's memory space. If the anywhere option is false, the kernel try to allocate the memory to the address specified by addr. If addr is not aligned to the page boundary, it will be automatically round down to one. size argument is an allocation size in byte. It will also be adjusted to the page boundary.ERRORS
NAMEvm_free() - free memorySYNOPSISint vm_free(task_t task, void *addr); DESCRIPTIONThe vm_free() function deallocates the memory region. The addr argument must point to the memory region previously allocated by vm_allocate() or vm_map().ERRORS
NAMEvm_attribute() - change memory attributeSYNOPSISint vm_attribute(task_t task, void *addr, int attr); DESCRIPTIONThe vm_attribute() function changes the memory attribute. The addr argument must point to the memory region previously allocated by vm_allocate() or vm_map(). The attribute type can be chosen a combination of ATTR_READ, ATTR_WRITE. Note: ATTR_EXEC is not supported, yet.ERRORS
NAMEvm_map() - map memorySYNOPSISint vm_map(task_t task, void *addr, size_t size, void **alloc); DESCRIPTIONThe vm_map() function maps another task's memory to the current task. The task argument is the memory owner to map. The memory is automatically mapped to the free area of current task. The mapped address is stored in alloc on success.ERRORS
TimerNAMEtimer_sleep() - sleep for a whileSYNOPSISint timer_sleep(u_long delay, u_long *remain); DESCRIPTIONThe timer_sleep() function stops execution of the current thread until specified time passed. The delay argument is the delay time in milli second. If this function is canceled by some reason, the remaining time is stored in remain.ERRORS
NAMEtimer_alarm() - schedule an alarm exceptionSYNOPSISint timer_alarm(u_long delay, u_long *remain); DESCRIPTIONThe timer_alarm() function sends EXC_ALRM exception to the caller task after the specified delay milli seconds is passed. If delay is 0, it stops the alarm timer. When the previous alarm timer is already working, the remaining time is stored in remain.ERRORS
NAMEtimer_periodic() - set a periodic timerSYNOPSISint timer_periodic(thread_t th, u_long start, u_long period); DESCRIPTIONThe specified thread will be woken up in specified time interval. The start argument is the first wakeup time. If start is 0, current periodic timer is stopped. period is the time interval to wakeup. The unit of start/period is milli seconds.ERRORS
NAMEtimer_waitperiod() - wait timer periodSYNOPSISint timer_waitperiod(void); DESCRIPTIONThe timer_waitperiod() function waits the next period of the current running periodic timer.Since this routine returns by any exception, the control may return at non-period time. So, the caller must retry immediately if the error status is EINTR. ERRORS
ExceptionNAMEexception_setup() - setup exception handlerSYNOPSISint exception_setup(void (*handler)(int, void *)); DESCRIPTIONSetup an exception handler for the current task. NULL can be specified as handler to remove current handler. If the handler is removed, all pending exceptions are discarded and all exception_wait() are canceled. Only one exception handler can be set per task. If the previous handler exists in task, exception_setup() just overwrite the handler.The exception handler must have the following arguments. void exception_handler(int excpt, void *regs); excpt is an exception number, and regs are the machine dependent registers. The exception handler must call the exception_return() function after it processes the exception. ERRORS
NAMEexception_return() - return from exception handlerSYNOPSISint exception_return(void *regs); DESCRIPTIONThe exception_return() function is used to return from the exception handler. regs argument must be the same value which is passed to the handler.ERRORS
NAMEexception_raise() - raise an exceptionSYNOPSISint exception_raise(task_t task, int excpt); DESCRIPTIONThe exception_raise() function raises an exception for the specified task.ERRORS
NAMEexception_wait() - wait an exceptionSYNOPSISint exception_wait(int *excpt); DESCRIPTIONThe exception_wait() function blocks the caller thread until any exception is raised to the thread.This routine returns EINTR on success. ERRORS
DeviceNAMEdevice_open() - open a deviceSYNOPSISint device_open(const char *name, int mode, device_t *dev); DESCRIPTIONThe device_open() function opens the specified device. mode is one of the following open mode.
ERRORS
NAMEdevice_close() - close a deviceSYNOPSISint device_close(device_t dev); DESCRIPTIONThe device_close() function close the specified device.ERRORS
NAMEdevice_read() - read from a deviceSYNOPSISint device_read(device_t dev, void *buf, size_t *nbyte, int blkno); DESCRIPTIONThe device_read() function reads data from the specified device. nbyte is a read size in byte, and blkno is a start block of the target device. The unit of blkno is device specific.ERRORS
NAMEdevice_write() - write to a deviceSYNOPSISint device_write(device_t dev, void *buf, size_t *nbyte, int blkno); DESCRIPTIONThe device_read() function writes data to the specified device. nbytes is a write size in byte, and blkno is a start block of the target device. The unit of blkno is device specific.ERRORS
NAMEdevice_ioctl() - control a deviceSYNOPSISint device_ioctl(device_t dev, int cmd, u_long arg); DESCRIPTIONThe device_ioctl() function sends a command to the specified device. cmd and arg are device dependent.ERRORS
MutexNAMEmutex_init() - initialize a mutexSYNOPSISint mutex_init(mutex_t *mu); DESCRIPTIONThe mutex_init() function creates a new mutex and initializes it. The ID of the new mutex is stored in mu on success.If an initialized mutex is reinitialized, undefined behavior results. ERRORS
NAMEmutex_destroy() - destroy a mutexSYNOPSISint mutex_destroy(mutex_t *mu); DESCRIPTIONThe mutex_destroy() function destroys the specified mutex. The mutex must be unlock state, otherwise it fails with EBUSY.ERRORS
NAMEmutex_trylock() - try to lock a mutexSYNOPSISint mutex_trylock(mutex_t *mu); DESCRIPTIONThe mutex_trylock() tries to lock a mutex without blocking.ERRORS
NAMEmutex_lock() - lock a mutexSYNOPSISint mutex_lock(mutex_t *mu); DESCRIPTIONThe mutex_lock() locks the specified mutex. The caller thread is blocked if the mutex has already been locked. If the caller thread receives any exception while waiting a mutex, this routine returns with EINTR. The mutex is "recursive". It means a thread can lock the same mutex any number of times.ERRORS
NAMEmutex_unlock() - unlock a mutexSYNOPSISint mutex_unlock(mutex_t *mu); DESCRIPTIONThe mutex_unlock() function unlocks the specified mutex. The caller thread must be the current mutex owner.ERRORS
Condition VariableNAMEcond_init() - initialize a condition variableSYNOPSISint cond_init(cond_t *cond); DESCRIPTIONThe cond_init() function creates a new condition variable and initializes it.If an initialized condition variable is reinitialized, undefined behavior results. ERRORS
NAMEcond_destroy() - destroy a condition variableSYNOPSISint cond_destroy(cond_t *cond); DESCRIPTIONThe cond_destroy() function destroys the specified condition variable. If there are any blocked thread waiting for the specified CV, it returns EBUSY.ERRORS
NAMEcond_wait() - wait on a conditionSYNOPSISint cond_wait(cond_t *cond, mutex_t *mu); DESCRIPTIONThe cond_wait() function waits on the specified condition. If the caller thread receives any exception, this routine returns with EINTR.ERRORS
NAMEcond_signal() - signal conditionSYNOPSISint cond_signal(cond_t *cond); DESCRIPTIONThe cond_signal() function unblocks the thread that is waiting on the specified condition variable.ERRORS
NAMEcond_broadcast() - broadcast a conditionSYNOPSISint cond_broadcast(cond_t *cond); DESCRIPTIONThe cond_broadcast() function unblocks all threads that are blocked on the specified condition variable.ERRORS
SemaphoreNAMEsem_init() - initialize a semaphoreSYNOPSISint sem_init(sem_t *sem, u_int value); DESCRIPTIONThe sem_init() function initializes a semaphore. It will create a new semaphore if the specified sem does not exist. If the specified semaphore sem already exists, it is re-initialized only if nobody is waiting for it. The initial semaphore value is set to value value. The ID of the new semaphore is stored in sem on success.ERRORS
NAMEsem_destroy() - destroy a semaphoreSYNOPSISint sem_destroy(sem_t *sem); DESCRIPTIONThe sem_destroy() function destroys the specified semaphore. If some thread is waiting for the specified semaphore, this routine fails with EBUSY.ERRORS
NAMEsem_wait() - lock a semaphoreSYNOPSISint sem_wait(sem_t *sem, u_long timeout); DESCRIPTIONThe sem_wait() function locks the semaphore referred by sem only if the semaphore value is currently positive. The thread will sleep while the semaphore value is zero. It decrements the semaphore value in return. If timeout value is set if it is not 0.ERRORS
NAMEsem_trywait() - try to lock a semaphoreSYNOPSISint sem_trywait(sem_t *sem); DESCRIPTIONThe sem_trylock() tries to lock a semaphore without blocking.ERRORS
NAMEsem_post() - unlock a semaphoreSYNOPSISint sem_post(sem_t *sem); DESCRIPTIONThe sem_post() function unlock the specified semaphore. It increments the semaphore value. If the semaphore value becomes positive, one of the threads waiting to lock will be unblocked. The caller thread is not blocked by this function.ERRORS
NAMEsem_getvalue() - get the value of a semaphoreSYNOPSISint sem_getvalue(sem_t *sem, u_int *value); DESCRIPTIONThe sem_getvalue() function returns the current value of the specified semaphore.ERRORS
SystemNAMEsys_log() - log a messageSYNOPSISvoid sys_log(const char *buf); DESCRIPTIONThe sys_log() function puts the specified text message to the predefined device. This function is available only when the kernel is built with debug flag.ERRORS
NAMEsys_panic() - fatal errorSYNOPSISvoid sys_panic(const char *buf); DESCRIPTIONThe sys_panic() function shows the panic message and stops the system. The application should use this call only when it detects the unrecoverable error.ERRORSNo errors are defined.NAMEsys_info() - return system informationSYNOPSISint sys_info(int type, void *buf); DESCRIPTIONThe sys_info() function returns the specified system information. The kernel supports the following system infomation.
ERRORS
NAMEsys_time() - return system ticksSYNOPSISint sys_time(u_long *ticks); DESCRIPTIONThe sys_time() function returns the current system ticks.ERRORS
NAMEsys_debug() - kernel debugging interfaceSYNOPSISint sys_debug(int cmd, int param); DESCRIPTIONThe sys_debug() controls the kernel built-in debug functions. The kernel supports the following commands.
ERRORS
|
||||||||||||||||||
Copyright© 2005-2007 Kohsuke Ohtani |