Annotation of prex-old/doc/html/doc/kapi.html, Revision 1.1.1.1
1.1 nbrk 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2: <html>
3: <head>
4: <title>Prex Kernel API Reference</title>
5: <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
6: <meta name="keywords" content="Prex, embedded, real-time, operating system, RTOS, open source, free">
7: <meta name="author" content="Kohsuke Ohtani">
8: <link rel="stylesheet" type="text/css" href="../default.css" media="screen">
9: <link rel="stylesheet" type="text/css" href="../print.css" media="print">
10: </head>
11: <body>
12: <div id="top">
13: </div>
14: <div id="middle">
15:
16: <table id="content" cellpadding="0" cellspacing="0">
17: <tbody>
18:
19: <tr>
20: <td id="header" colspan="2" valign="top">
21: <table width="100%" border="0" cellspacing="0" cellpadding="0">
22: <tr>
23: <td id="logo">
24: <a href="http://prex.sourceforge.net/">
25: <img alt="Prex logo" src="../img/logo.gif" border="0"
26: style="width: 281px; height: 56px;"></a>
27: </td>
28: <td id="brief" align="right" valign="bottom">
29: An Open Source, Royalty-free,<br>
30: Real-time Operating System
31: </td>
32: </tr>
33: </table>
34: </td>
35: </tr
36:
37: <tr>
38: <td id="directory" style="vertical-align: top;">
39: <a href="http://prex.sourceforge.net/">Prex Home</a> >
40: <a href="index.html">Document Index</a> >
41: Kernel API Reference
42: </tr>
43: <tr><td class="pad" colspan="2" style="vertical-align: top;"></td></tr>
44:
45: <tr>
46: <td id="main" style="vertical-align: top;">
47: <h1>Prex Kernel API Reference</h1>
48:
49: <i>Version 1.7.0, 2007/12/24</i><br>
50: <br>
51:
52: <h3>Table of Contents</h3>
53:
54: <ul>
55: <li><a href="#intro">Introduction</a></li>
56: </ul>
57:
58: <ul>
59: <li><a href="#gen">General Information</a>
60: <ul>
61: <li><a href="#type">Data Types</a></li>
62: <li><a href="#err">Error Numbers</a></li>
63: </ul>
64: </li>
65: </ul>
66:
67: <ul>
68: <li><a href="#obj">Object</a>
69: <ul>
70: <li><a href="#obj0">object_create</a></li>
71: <li><a href="#obj1">object_delete</a></li>
72: <li><a href="#obj2">object_lookup</a></li>
73: </ul>
74: </li>
75: </ul>
76:
77: <ul>
78: <li><a href="#msg">Message</a>
79: <ul>
80: <li><a href="#msg0">msg_send</a></li>
81: <li><a href="#msg1">msg_receive</a></li>
82: <li><a href="#msg2">msg_reply</a></li>
83: </ul>
84: </li>
85: </ul>
86:
87: <ul>
88: <li><a href="#task">Task</a>
89: <ul>
90: <li><a href="#task0">task_create</a></li>
91: <li><a href="#task1">task_terminate</a></li>
92: <li><a href="#task2">task_self</a></li>
93: <li><a href="#task3">task_suspend</a></li>
94: <li><a href="#task4">task_resume</a></li>
95: <li><a href="#task5">task_name</a></li>
96: <li><a href="#task6">task_getcap</a></li>
97: <li><a href="#task7">task_setcap</a></li>
98: </ul>
99: </li>
100: </ul>
101:
102: <ul>
103: <li><a href="#thr">Thread</a>
104: <ul>
105: <li><a href="#thr0">thread_create</a></li>
106: <li><a href="#thr1">thread_terminate</a></li>
107: <li><a href="#thr2">thread_load</a></li>
108: <li><a href="#thr3">thread_self</a></li>
109: <li><a href="#thr4">thread_yield</a></li>
110: <li><a href="#thr5">thread_suspend</a></li>
111: <li><a href="#thr6">thread_resume</a></li>
112: <li><a href="#thr7">thread_schedparam</a></li>
113: </ul>
114: </li>
115: </ul>
116:
117: <ul>
118: <li><a href="#vm">Virtual Memory</a>
119: <ul>
120: <li><a href="#vm0">vm_allocate</a></li>
121: <li><a href="#vm1">vm_free</a></li>
122: <li><a href="#vm2">vm_attribute</a></li>
123: <li><a href="#vm3">vm_map</a></li>
124: </ul>
125: </li>
126: </ul>
127:
128: <ul>
129: <li><a href="#tmr">Timer</a>
130: <ul>
131: <li><a href="#tmr0">timer_sleep</a></li>
132: <li><a href="#tmr1">timer_alarm</a></li>
133: <li><a href="#tmr2">timer_periodic</a></li>
134: <li><a href="#tmr3">timer_waitperiod</a></li>
135: </ul>
136: </li>
137: </ul>
138:
139: <ul>
140: <li><a href="#ex">Exception</a>
141: <ul>
142: <li><a href="#ex0">exception_setup</a></li>
143: <li><a href="#ex1">exception_return</a></li>
144: <li><a href="#ex2">exception_raise</a></li>
145: <li><a href="#ex3">exception_wait</a></li>
146: </ul>
147: </li>
148: </ul>
149:
150: <ul>
151: <li><a href="#dev">Device</a>
152: <ul>
153: <li><a href="#dev0">device_open</a></li>
154: <li><a href="#dev1">device_close</a></li>
155: <li><a href="#dev2">device_read</a></li>
156: <li><a href="#dev3">device_write</a></li>
157: <li><a href="#dev4">device_ioctl</a></li>
158: </ul>
159: </li>
160: </ul>
161:
162: <ul>
163: <li><a href="#mu">Mutex</a>
164: <ul>
165: <li><a href="#mu0">mutex_init</a></li>
166: <li><a href="#mu1">mutex_destroy</a></li>
167: <li><a href="#mu2">mutex_trylock</a></li>
168: <li><a href="#mu3">mutex_lock</a></li>
169: <li><a href="#mu4">mutex_unlock</a></li>
170: </ul>
171: </li>
172: </ul>
173:
174: <ul>
175: <li><a href="#cv">Condition Variable</a>
176: <ul>
177: <li><a href="#cv0">cond_init</a></li>
178: <li><a href="#cv1">cond_destroy</a></li>
179: <li><a href="#cv2">cond_wait</a></li>
180: <li><a href="#cv3">cond_signal</a></li>
181: <li><a href="#cv4">cond_broadcast</a></li>
182: </ul>
183: </li>
184: </ul>
185:
186: <ul>
187: <li><a href="#sem">Semaphore</a>
188: <ul>
189: <li><a href="#sem0">sem_init</a></li>
190: <li><a href="#sem1">sem_destroy</a></li>
191: <li><a href="#sem2">sem_wait</a></li>
192: <li><a href="#sem3">sem_trywait</a></li>
193: <li><a href="#sem4">sem_post</a></li>
194: <li><a href="#sem5">sem_getvalue</a></li>
195: </ul>
196: </li>
197: </ul>
198:
199: <ul>
200: <li><a href="#sys">System</a>
201: <ul>
202: <li><a href="#sys0">sys_log</a></li>
203: <li><a href="#sys1">sys_panic</a></li>
204: <li><a href="#sys2">sys_info</a></li>
205: <li><a href="#sys3">sys_time</a></li>
206: <li><a href="#sys4">sys_debug</a></li>
207: </ul>
208:
209: </ul>
210:
211:
212: <h2 id="intro">Introduction</h2>
213: <p>
214: The Prex Kernel API Reference define a programming interface
215: for the Prex applications.
216: This document includes the complete set of kernel services and the detailed
217: description.
218: </p>
219:
220:
221: <h2 id="gen">General Information</h2>
222:
223: <h3 id="type">Data Types</h3>
224: <p>
225: The following data types are supported by the Prex kernel.
226: Each type represents ID of the kernel element.
227: </p>
228:
229: <table border="1" width="60%" cellspacing="0">
230: <tbody>
231: <tr>
232: <th>Data type</th>
233: <th>Description</th>
234: </tr>
235: <tr>
236: <td>object_t</td>
237: <td>Used to identify a object.</td>
238: </tr>
239: <tr>
240: <td>task_t</td>
241: <td>Used to identify a task.</td>
242: </tr>
243: <tr>
244: <td>thread_t</td>
245: <td>Used to identify a thread.</td>
246: </tr>
247: <tr>
248: <td>device_t</td>
249: <td>Used to identify a device.</td>
250: </tr>
251: <tr>
252: <td>mutex_t</td>
253: <td>Used to identify a mutex.</td>
254: </tr>
255: <tr>
256: <td>cond_t</td>
257: <td>Used to identify a condition variable.</td>
258: </tr>
259: <tr>
260: <td>sem_t</td>
261: <td>Used to identify a semaphore.</td>
262: </tr>
263: <tr>
264: <td>cap_t</td>
265: <td>Used to represent a task capability.</td>
266: </tr>
267:
268: </tbody>
269: </table>
270:
271:
272: <h3 id="err">Error Numbers</h3>
273: <p>
274: The definition of the Prex kernel error is compatible with the POSIX
275: error number. However, unlike POSIX, Prex does not use an errno variable
276: because errno is not MT-safe. So, most functions in kernel API will
277: provide an error number as a return value.
278: </p>
279: <p>
280: The following error names are used as the possible error number.
281: </p>
282: <dl>
283: <dt>[EPERM]</dt>
284: <dd>Operation not permitted.</dd>
285: <dt>[ENOENT]</dt>
286: <dd>No such file or directory.</dd>
287: <dt>[ESRCH]</dt>
288: <dd>No such process.</dd>
289: <dt>[EINTR]</dt>
290: <dd>Interrupted system call.</dd>
291: <dt>[EIO]</dt>
292: <dd>I/O error.</dd>
293: <dt>[ENXIO]</dt>
294: <dd>No such device or address.</dd>
295: <dt>[EAGAIN]</dt>
296: <dd>Try again.</dd>
297: <dt>[ENOMEM]</dt>
298: <dd>Out of memory.</dd>
299: <dt>[EACCES]</dt>
300: <dd>Permission denied.</dd>
301: <dt>[EFAULT]</dt>
302: <dd>Bad address.</dd>
303: <dt>[EBUSY]</dt>
304: <dd>Device or resource busy.</dd>
305: <dt>[EEXIST]</dt>
306: <dd>File exists.</dd>
307: <dt>[ENODEV]</dt>
308: <dd>No such device.</dd>
309: <dt>[EINVAL]</dt>
310: <dd>Invalid argument.</dd>
311: <dt>[ERANGE]</dt>
312: <dd>Math result not representable.</dd>
313: <dt>[EDEADLK]</dt>
314: <dd>Resource deadlock avoided.</dd>
315: <dt>[ENOSYS]</dt>
316: <dd>Function not implemented.</dd>
317: <dt>[ENAMETOOLONG]</dt>
318: <dd>File name too long.</dd>
319: <dt>[ETIMEDOUT]</dt>
320: <dd>Timed out.</dd>
321:
322: </dl>
323:
324: <h2 id="obj">Object</h2>
325:
326: <h3 id="obj0">NAME</h3>
327: object_create() - create a new object
328:
329: <h3>SYNOPSIS</h3>
330: <pre>
331: int object_create(const char *name, object_t *obj);
332: </pre>
333:
334: <h3>DESCRIPTION</h3>
335: The object_create() function creates a new object.
336: The ID of the new object is stored in <i>obj</i> on success.
337: <br><br>
338: The name of the object must be unique in the system.
339: Or, the object can be created without name by setting NULL
340: as <i>name</i> argument. This object can be used as a private object
341: which can be accessed only by threads in the same task.
342:
343: <h3>ERRORS</h3>
344: <dl>
345: <dt>[EFAULT]</dt>
346: <dd>The address of <i>name</i> or <i>obj</i> is inaccessible.</dd>
347: <dt>[ENAMETOOLONG]</dt>
348: <dd>The length of the <i>name</i> argument exceeds MAX_OBJNAME.</dd>
349: <dt>[EEXIST]</dt>
350: <dd>The named object already exists.</dd>
351: <dt>[ENOMEM]</dt>
352: <dd>The system is unable to allocate resources.</dd>
353: </dl>
354: <br>
355: <hr size="1">
356:
357:
358: <h3 id="obj1">NAME</h3>
359: object_delete() - delete an object
360:
361: <h3>SYNOPSIS</h3>
362: <pre>
363: int object_delete(object_t obj);
364: </pre>
365:
366: <h3>DESCRIPTION</h3>
367: The object_delete() function deletes the object specified by <i>obj</i>.
368: <br><br>
369: A thread can delete the object only when the target object is created
370: by the thread of the same task.
371: All pending messages related to the deleted object are automatically canceled.
372:
373: <h3>ERRORS</h3>
374: <dl>
375: <dt>[EINVAL]</dt>
376: <dd>The specified <i>obj</i> is not a valid object ID.</dd>
377: <dt>[EACCESS]</dt>
378: <dd>The thread is not allowed to delete the object.</dd>
379: </dl>
380: <br>
381: <hr size="1">
382:
383:
384: <h3 id="obj2">NAME</h3>
385: object_lookup() - lookup an object
386:
387: <h3>SYNOPSIS</h3>
388: <pre>
389: int object_lookup(const char *name, object_t *obj);
390: </pre>
391:
392: <h3>DESCRIPTION</h3>
393: The object_lookup() function searches an object in the object name space.
394: The <i>name</i> argument is the null-terminated string.
395: The object ID is returned in <i>obj</i> on success.
396:
397: <h3>ERRORS</h3>
398: <dl>
399: <dt>[EFAULT]</dt>
400: <dd>The address of <i>name</i> or <i>obj</i> is inaccessible.</dd>
401: <dt>[ESRCH]</dt>
402: <dd>The length of the <i>name</i> argument exceeds MAX_OBJNAME.</dd>
403: <dt>[ENOENT]</dt>
404: <dd>The specified object does not exist.</dd>
405: </dl>
406: <br>
407:
408:
409: <h2 id="msg">Message</h2>
410:
411: <h3 id="msg0">NAME</h3>
412: msg_send() - send a message
413:
414: <h3>SYNOPSIS</h3>
415: <pre>
416: int msg_send(object_t obj, void *msg, size_t size);
417: </pre>
418:
419: <h3>DESCRIPTION</h3>
420: The msg_send() function sends a message to an object.
421: The caller thread will be blocked until any other thread receives
422: the message and calls msg_reply() for this object.
423: A thread can send a message to any object if it knows the object ID.
424: <br><br>
425: The <i>size</i> argument specifies the size of the message buffer to send.
426: <br><br>
427: The message is the binary data block which includes a message header.
428: The kernel does not touch the message body, and it is
429: necessary to recognize the predefined message format between sender
430: and receiver.
431:
432: <h3>ERRORS</h3>
433: <dl>
434: <dt>[EINVAL]</dt>
435: <dd>The specified <i>obj</i> is not a valid object ID.</dd>
436: <dt>[EFAULT]</dt>
437: <dd>The buffer of <i>msg</i> is inaccessible.</dd>
438: <dt>[EDEADLK]</dt>
439: <dd><i>obj</i> is the object that the caller thread is receiving from now.</dd>
440: <dt>[EAGAIN]</dt>
441: <dd>The receiver thread has been terminated.</dd>
442: <dt>[EINTR]</dt>
443: <dd>The function was interrupted by an exception.</dd>
444: <dt>[EPERM]</dt>
445: <dd>The caller task is not an owner of the <i>obj</i>, but it
446: does not have CAP_IPC capability.</dd>
447: </dl>
448: <br>
449: <hr size="1">
450:
451:
452: <h3 id="msg1">NAME</h3>
453: msg_receive() - receive a message
454:
455: <h3>SYNOPSIS</h3>
456: <pre>
457: int msg_receive(object_t obj, void *msg, size_t size);
458: </pre>
459:
460: <h3>DESCRIPTION</h3>
461: The msg_receive() function receives a message from an object.
462: A thread can receive a message from the object which was created
463: by the thread in the same task. If the message has not arrived, the
464: caller thread blocks until any message comes in.
465: <br><br>
466: The <i>size</i> argument specifies the "maximum" size of the message
467: buffer to receive. If the sent message is larger than this size,
468: the kernel will automatically clip the message to the receive buffer size.
469: <br><br>
470: A thread can not receive the multiple messages at once.
471:
472: <h3>ERRORS</h3>
473: <dl>
474: <dt>[EINVAL]</dt>
475: <dd>The specified <i>obj</i> is not a valid object ID.</dd>
476: <dt>[EACCESS]</dt>
477: <dd>The caller task is not the owner of the target object.</dd>
478: <dt>[EBUSY]</dt>
479: <dd>The caller thread does not finish the previous receive operation.</dd>
480: <dt>[EFAULT]</dt>
481: <dd>The buffer of <i>msg</i> is inaccessible.</dd>
482: <dt>[EINTR]</dt>
483: <dd>The function was interrupted by an exception.</dd>
484: </dl>
485: <br>
486: <hr size="1">
487:
488:
489: <h3 id="msg2">NAME</h3>
490: msg_reply() - reply to an object
491:
492: <h3>SYNOPSIS</h3>
493: <pre>
494: int msg_reply(object_t obj, void *msg, size_t size);
495: </pre>
496:
497: <h3>DESCRIPTION</h3>
498: The msg_reply() function sends a reply message to the object.
499: A thread must reply to the correct object that the thread
500: preciously received from. Otherwise, this function will be failed.
501: <br><br>
502: The <i>size</i> argument specifies the size of the message buffer to reply.
503:
504: <h3>ERRORS</h3>
505: <dl>
506: <dt>[EINVAL]</dt>
507: <dd>The specified <i>obj</i> is not a valid object ID. Or, the sender
508: thread has been terminated.</dd>
509: <dt>[EFAULT]</dt>
510: <dd>The buffer of <i>msg</i> is inaccessible.</dd>
511: </dl>
512: <br>
513:
514:
515: <h2 id="task">Task</h2>
516:
517: <h3 id="task0">NAME</h3>
518: task_create() - create a new task
519:
520: <h3>SYNOPSIS</h3>
521: <pre>
522: int task_create(task_t parent, int vm_option, task_t *child);
523: </pre>
524:
525: <h3>DESCRIPTION</h3>
526: The task_create() function create a new task.
527: If <i>vm_option</i> option can be one of the following:
528: <ul>
529: <li>VM_NEW - The new task has clean memory image.</li>
530: <li>VM_COPY - The new task will have the duplicated memory image with the parent task.</li>
531: <li>VM_SHARE - The new task will share the same memory image with the parent task.</li>
532: </ul>
533: The child task initially contains no threads.
534: So, the caller task must create new thread under the child task to
535: run it.
536: <br><br>
537: <i>vm_option</i> flag is supported only with MMU system. The created
538: task has always new memory map with NOMMU system.
539: <br><br>
540: The function returns the created task ID in <i>child</i>,
541: and child task will receive 0 as <i>child</i>.
542:
543: <h3>ERRORS</h3>
544: <dl>
545: <dt>[ESRCH]</dt>
546: <dd>The specified <i>parent</i> is not a valid task ID.</dd>
547: <dt>[EFAULT]</dt>
548: <dd>The address of <i>child</i> is inaccessible.</dd>
549: <dt>[ENOMEM]</dt>
550: <dd>The system is unable to allocate resources.</dd>
551: <dt>[EPERM]</dt>
552: <dd>The specified <i>parent</i> is not a current task, but the caller
553: task does not have CAP_TASK capability.</dd>
554: </dl>
555: <br>
556: <hr size="1">
557:
558:
559: <h3 id="task1">NAME</h3>
560: task_terminate() - terminate a task
561:
562: <h3>SYNOPSIS</h3>
563: <pre>
564: int task_terminate(task_t task);
565: </pre>
566:
567: <h3>DESCRIPTION</h3>
568: The task_terminate() function terminates a task and deallocates all resource
569: for the task.
570: <br><br>
571: If the <i>task</i> argument point to the current task, this routine never returns.
572:
573: <h3>ERRORS</h3>
574: <dl>
575: <dt>[ESRCH]</dt>
576: <dd>The specified <i>task</i> is not a valid task ID.</dd>
577: <dt>[EPERM]</dt>
578: <dd>The specified <i>task</i> is not a current task, but the caller
579: task does not have CAP_TASK capability.</dd>
580: </dl>
581: <br>
582: <hr size="1">
583:
584:
585: <h3 id="task2">NAME</h3>
586: task_self() - return task ID
587:
588: <h3>SYNOPSIS</h3>
589: <pre>
590: task_t task_self(void);
591: </pre>
592:
593: <h3>DESCRIPTION</h3>
594: The task_self() function returns ID of the current task.
595:
596: <h3>RETURN VALUE</h3>
597: Current task ID.
598: <br>
599: <br>
600: <hr size="1">
601:
602:
603: <h3 id="task3">NAME</h3>
604: task_suspend() - suspend a task
605:
606: <h3>SYNOPSIS</h3>
607: <pre>
608: int task_suspend(task_t task);
609: </pre>
610:
611: <h3>DESCRIPTION</h3>
612: The task_suspend() function suspends all threads within the specified task.
613:
614: <h3>ERRORS</h3>
615: <dl>
616: <dt>[EINVAL]</dt>
617: <dd>The specified <i>task</i> is not a valid task ID.</dd>
618: <dt>[ESRCH]</dt>
619: <dd>The specified <i>task</i> is not a current task, but the caller
620: task does not have CAP_TASK capability.</dd>
621: </dl>
622: <br>
623: <hr size="1">
624:
625:
626: <h3 id="task4">NAME</h3>
627: task_resume() - resume a task
628:
629: <h3>SYNOPSIS</h3>
630: <pre>
631: int task_resume(task_t task);
632: </pre>
633:
634: <h3>DESCRIPTION</h3>
635: The task_resume() function resumes all threads within the specified task.
636:
637: <h3>ERRORS</h3>
638: <dl>
639: <dt>[ESRCH]</dt>
640: <dd>The specified <i>task</i> is not a valid task ID.</dd>
641: <dt>[EINVAL]</dt>
642: <dd>The specified <i>task</i> is not suspended now.</dd>
643: <dt>[EPERM]</dt>
644: <dd>The specified <i>task</i> is not a current task, but the caller
645: task does not have CAP_TASK capability.</dd>
646: </dl>
647: <br>
648: <hr size="1">
649:
650:
651: <h3 id="task5">NAME</h3>
652: task_name() - set task name
653:
654: <h3>SYNOPSIS</h3>
655: <pre>
656: int task_name(task_t task, const char *name);
657: </pre>
658:
659: <h3>DESCRIPTION</h3>
660: The task_name() function set the name of the specified task. The task name can
661: be changed at any time.
662: <br><br>
663: This function does not returns error even if the same task name already
664: exists in the system.
665:
666: <h3>ERRORS</h3>
667: <dl>
668: <dt>[ESRCH]</dt>
669: <dd>The specified <i>task</i> is not a valid task ID.</dd>
670: <dt>[EFAULT]</dt>
671: <dd>The address of <i>name</i> is inaccessible.</dd>
672: <dt>[ENAMETOOLONG]</dt>
673: <dd>The length of the <i>name</i> argument exceeds MAX_TASKNAME.</dd>
674: <dt>[EPERM]</dt>
675: <dd>The specified <i>task</i> is not a current task, but the caller
676: task does not have CAP_TASK capability.</dd>
677: </dl>
678: <br>
679: <hr size="1">
680:
681: <h3 id="task6">NAME</h3>
682: task_getcap() - get a task capability
683:
684: <h3>SYNOPSIS</h3>
685: <pre>
686: int task_getcap(task_t task, cap_t *cap);
687: </pre>
688:
689: <h3>DESCRIPTION</h3>
690: <p>
691: The task_getcap() function returns the capability of the
692: specified task.
693: </p>
694:
695:
696: <h3>ERRORS</h3>
697: <dl>
698: <dt>[ESRCH]</dt>
699: <dd>The specified <i>task</i> is not a valid task ID.</dd>
700: <dt>[EFAULT]</dt>
701: <dd>The address of <i>cap</i> is inaccessible.</dd>
702: </dl>
703: <br>
704:
705:
706: <hr size="1">
707:
708: <h3 id="task7">NAME</h3>
709: task_setcap() - set a task capability
710:
711: <h3>SYNOPSIS</h3>
712: <pre>
713: int task_setcap(task_t task, cap_t *cap);
714: </pre>
715:
716: <h3>DESCRIPTION</h3>
717: <p>
718: The task_setcap() function set the capability of the
719: specified task.
720: </p>
721: <p>
722: The following task capabilities are supported.
723: </p>
724: <dl>
725: <dt>CAP_SETPCAP</dt>
726: <dd>Allow setting capability.</dd>
727: <dt>CAP_TASK</dt>
728: <dd>Allow controlling another task's execution.</dd>
729: <dt>CAP_MEMORY</dt>
730: <dd>Allow touching another task's memory.</dd>
731: <dt>CAP_KILL</dt>
732: <dd>Allow raising exception to another task.</dd>
733: <dt>CAP_SEMAPHORE</dt>
734: <dd>Allow accessing another task's semaphore.</dd>
735: <dt>CAP_NICE</dt>
736: <dd>Allow changing scheduling parameter.</dd>
737: <dt>CAP_IPC</dt>
738: <dd>Allow accessing another task's IPC object.</dd>
739: <dt>CAP_DEVIO</dt>
740: <dd>Allow device I/O operations.</dd>
741: <dt>CAP_POWER</dt>
742: <dd>Allow power control including shutdown.</dd>
743: <dt>CAP_TIME</dt>
744: <dd>Allow setting system time.</dd>
745: <dt>CAP_RAWIO</dt>
746: <dd>Allow direct I/O access.</dd>
747: <dt>CAP_MOUNT</dt>
748: <dd>Allow mounting a file system.</dd>
749: <dt>CAP_CHROOT</dt>
750: <dd>Allow changing a root directory.</dd>
751: </dl>
752:
753: <h3>ERRORS</h3>
754: <dl>
755: <dt>[ESRCH]</dt>
756: <dd>The specified <i>task</i> is not a valid task ID.</dd>
757: <dt>[EFAULT]</dt>
758: <dd>The address of <i>cap</i> is inaccessible.</dd>
759: <dt>[EPERM]</dt>
760: <dd>The caller task does not have CAP_SETPCAP capability.</dd>
761: </dl>
762: <br>
763:
764:
765: <h2 id="thr">Thread</h2>
766:
767: <h3 id="thr0">NAME</h3>
768: thread_create() - create a new thread
769:
770: <h3>SYNOPSIS</h3>
771: <pre>
772: int thread_create(task_t task, thread_t *th);
773: </pre>
774:
775: <h3>DESCRIPTION</h3>
776: The thread_create() function creates a new thread within <i>task</i>.
777: The new thread will start at the return address of the thread_create() call.
778: <br><br>
779: Since the created thread is initially set to the suspended state,
780: thread_resume() must be called to start it.
781:
782: <h3>ERRORS</h3>
783: <dl>
784: <dt>[ESRCH]</dt>
785: <dd>The specified <i>task</i> is not a valid task ID.</dd>
786: <dt>[EFAULT]</dt>
787: <dd>The address of <i>th</i> is inaccessible.</dd>
788: <dt>[ENOMEM]</dt>
789: <dd>The system is unable to allocate resources.</dd>
790: <dt>[EPERM]</dt>
791: <dd>The specified <i>task</i> is not a current task, but the caller
792: task does not have CAP_TASK capability.</dd>
793: </dl>
794: <br>
795: <hr size="1">
796:
797:
798: <h3 id="thr1">NAME</h3>
799: thread_terminate() - terminate a thread
800:
801: <h3>SYNOPSIS</h3>
802: <pre>
803: int thread_terminate(thread_t th);
804: </pre>
805:
806: <h3>DESCRIPTION</h3>
807: The thread_terminate() function terminates a thread.
808: It will release all resources used by the target thread.
809: <br><br>
810: If specified <i>th</i> is the current thread, this routine never returns.
811:
812: <h3>ERRORS</h3>
813: <dl>
814: <dt>[ESRCH]</dt>
815: <dd>The specified thread <i>th</i> is not a valid thread ID.</dd>
816: <dt>[EPERM]</dt>
817: <dd>The caller task is not an owner of the specified <i>th</i>, but the caller
818: task does not have CAP_TASK capability.</dd>
819: </dl>
820: <br>
821: <hr size="1">
822:
823:
824: <h3 id="thr2">NAME</h3>
825: thread_load() - load the thread state
826:
827: <h3>SYNOPSIS</h3>
828: <pre>
829: int thread_load(thread_t th, void *entry, void *stack);
830: </pre>
831:
832: <h3>DESCRIPTION</h3>
833: The thread_load() function loads the thread state (program counter and
834: stack pointer).
835: <br><br>
836: The <i>entry</i> or <i>stack</i> argument can be set to NULL. In this
837: case, the previous state is used.
838:
839: <h3>ERRORS</h3>
840: <dl>
841: <dt>[ESRCH]</dt>
842: <dd>The specified <i>th</i> is not a valid thread ID.</dd>
843: <dt>[EINVAL]</dt>
844: <dd><i>entry</i> or <i>stack</i> is not a valid address.</dd>
845: <dt>[EPERM]</dt>
846: <dd>The caller task is not an owner of the specified <i>th</i>, but the caller
847: task does not have CAP_TASK capability.</dd>
848: </dl>
849: <br>
850: <hr size="1">
851:
852:
853: <h3 id="thr3">NAME</h3>
854: thread_self() - return thread ID
855:
856: <h3>SYNOPSIS</h3>
857: <pre>
858: thread_t thread_self(void);
859: </pre>
860:
861: <h3>DESCRIPTION</h3>
862: The thread_self() function returns ID of the current thread.
863:
864: <h3>RETURN VALUE</h3>
865: Current thread ID.
866: <br>
867: <br>
868: <hr size="1">
869:
870:
871: <h3 id="thr4">NAME</h3>
872: thread_yield() - yield the processor
873:
874: <h3>SYNOPSIS</h3>
875: <pre>
876: void thread_yield(void);
877: </pre>
878:
879: <h3>DESCRIPTION</h3>
880: The thread_yield() function forces the current thread to release
881: the processor.
882:
883: <h3>ERRORS</h3>
884: No errors are defined.
885: <br>
886: <br>
887: <hr size="1">
888:
889:
890: <h3 id="thr5">NAME</h3>
891: thread_suspend() - suspend a thread
892:
893: <h3>SYNOPSIS</h3>
894: <pre>
895: int thread_suspend(thread_t th);
896: </pre>
897:
898: <h3>DESCRIPTION</h3>
899: The thread_suspend() function suspends the specified thread.
900: Although a thread can be suspended any number of times,
901: it does not start to run unless it is resumed by the same
902: number of suspend.
903:
904: <h3>ERRORS</h3>
905: <dl>
906: <dt>[ESRCH]</dt>
907: <dd>The specified <i>th</i> is not a valid thread ID.</dd>
908: <dt>[EPERM]</dt>
909: <dd>The caller task is not an owner of the specified <i>th</i>, but the caller
910: task does not have CAP_TASK capability.</dd>
911: </dl>
912: <br>
913: <hr size="1">
914:
915:
916: <h3 id="thr6">NAME</h3>
917: thread_resume() - resume a thread
918:
919: <h3>SYNOPSIS</h3>
920: <pre>
921: int thread_resume(thread_t th);
922: </pre>
923:
924: <h3>DESCRIPTION</h3>
925: The thread_resume() function resumes the specified thread.
926: A thread does not begin to run, unless both a thread suspend
927: count and a task suspend count are set to 0.
928:
929: <h3>ERRORS</h3>
930: <dl>
931: <dt>[ESRCH]</dt>
932: <dd>The specified <i>th</i> is not a valid thread ID.</dd>
933: <dt>[EINVAL]</dt>
934: <dd>The specified <i>th</i> is not suspended now.</dd>
935: <dt>[EPERM]</dt>
936: <dd>The caller task is not an owner of the specified <i>th</i>, but the caller
937: task does not have CAP_TASK capability.</dd>
938: </dl>
939: <br>
940: <hr size="1">
941:
942:
943: <h3 id="thr7">NAME</h3>
944: thread_schedparam() - get/set scheduling parameters
945:
946: <h3>SYNOPSIS</h3>
947: <pre>
948: int thread_schedparam(thread_t th, int op, int *param);
949: </pre>
950:
951: <h3>DESCRIPTION</h3>
952: The thread_schedparam() function gets/sets the various scheduling parameter.
953: <i>op</i> argument is an operation ID which is one of the following value.
954: <ul>
955: <li>OP_GETPRIO - get the scheduling priority</li>
956: <li>OP_SETPRIO - set the scheduling priority</li>
957: <li>OP_GETPOLICY - get the scheduling policy</li>
958: <li>OP_SETPOLICY - set the scheduling policy</li>
959: </ul>
960: The kernel supports the following scheduling policy.
961: <ul>
962: <li>SCHED_FIFO - First-in First-out</li>
963: <li>SCHED_RR - Round Robin</li>
964: </ul>
965:
966: <h3>ERRORS</h3>
967: <dl>
968: <dt>[ESRCH]</dt>
969: <dd>The specified <i>th</i> is not a valid thread ID.</dd>
970: <dt>[EFAULT]</dt>
971: <dd>The address of <i>param</i> is inaccessible.</dd>
972: <dt>[EINVAL]</dt>
973: <dd>The kernel does not support the specified policy.</dd>
974: <dt>[EPERM]</dt>
975: <dd>The caller task is not an owner of the specified <i>th</i>, or the caller
976: task does not have CAP_NICE capability to change the parameter.</dd>
977: </dl>
978: <br>
979:
980:
981:
982: <h2 id="vm">Virtual Memory</h2>
983:
984: <h3 id="vm0">NAME</h3>
985: vm_allocate() - allocate memory
986:
987: <h3>SYNOPSIS</h3>
988: <pre>
989: int vm_allocate(task_t task, void **addr, size_t size, int anywhere);
990: </pre>
991:
992: <h3>DESCRIPTION</h3>
993: The vm_allocate() function allocates a zero-filled memory in the <i>task</i>'s
994: memory space.
995: If the <i>anywhere</i> option is false, the kernel try to allocate the
996: memory to the address specified by <i>addr</i>. If <i>addr</i> is not
997: aligned to the page boundary, it will be automatically round down to one.
998: <i>size</i> argument is an allocation size in byte. It will also be adjusted
999: to the page boundary.
1000:
1001: <h3>ERRORS</h3>
1002: <dl>
1003: <dt>[ESRCH]</dt>
1004: <dd>The specified <i>task</i> is not a valid task ID.</dd>
1005: <dt>[EACCESS]</dt>
1006: <dd>The task is not allowed to allocate the memory to the specified address.</dd>
1007: <dt>[EFAULT]</dt>
1008: <dd>The address of <i>addr</i> is inaccessible.</dd>
1009: <dt>[ENOMEM]</dt>
1010: <dd>Not enough space.</dd>
1011: <dt>[EINVAL]</dt>
1012: <dd>The specified location is already allocated.</dd>
1013: <dt>[EPERM]</dt>
1014: <dd>The specified <i>task</i> is not a current task, but the caller
1015: task does not have CAP_MEMORY capability.</dd>
1016: </dl>
1017: <hr size="1">
1018:
1019:
1020: <h3 id="vm1">NAME</h3>
1021: vm_free() - free memory
1022:
1023: <h3>SYNOPSIS</h3>
1024: <pre>
1025: int vm_free(task_t task, void *addr);
1026: </pre>
1027:
1028: <h3>DESCRIPTION</h3>
1029: The vm_free() function deallocates the memory region.
1030: The <i>addr</i> argument must point to the memory region previously
1031: allocated by vm_allocate() or vm_map().
1032:
1033: <h3>ERRORS</h3>
1034: <dl>
1035: <dt>[ESRCH]</dt>
1036: <dd>The specified <i>task</i> is not a valid task ID.</dd>
1037: <dt>[EFAULT]</dt>
1038: <dd>The address of <i>addr</i> is inaccessible.</dd>
1039: <dt>[EINVAL]</dt>
1040: <dd>The specified location is not allocated.</dd>
1041: <dt>[EPERM]</dt>
1042: <dd>The specified <i>task</i> is not a current task, but the caller
1043: task does not have CAP_MEMORY capability.</dd>
1044: </dl>
1045: <hr size="1">
1046:
1047:
1048: <h3 id="vm2">NAME</h3>
1049: vm_attribute() - change memory attribute
1050:
1051: <h3>SYNOPSIS</h3>
1052: <pre>
1053: int vm_attribute(task_t task, void *addr, int attr);
1054: </pre>
1055:
1056: <h3>DESCRIPTION</h3>
1057: The vm_attribute() function changes the memory attribute.
1058: The <i>addr</i> argument must point to the memory region previously
1059: allocated by vm_allocate() or vm_map().
1060: The attribute type can be chosen a combination of
1061: ATTR_READ, ATTR_WRITE.
1062: Note: ATTR_EXEC is not supported, yet.
1063:
1064: <h3>ERRORS</h3>
1065: <dl>
1066: <dt>[ESRCH]</dt>
1067: <dd>The specified <i>task</i> is not a valid task ID.</dd>
1068: <dt>[EFAULT]</dt>
1069: <dd>The address of <i>addr</i> is inaccessible.</dd>
1070: <dt>[EINVAL]</dt>
1071: <dd>The specified location is not allocated. Or, the kernel does not
1072: support the specified attribute.</dd>
1073: <dt>[EPERM]</dt>
1074: <dd>The specified <i>task</i> is not a current task, but the caller
1075: task does not have CAP_MEMORY capability.</dd>
1076: </dl>
1077: <hr size="1">
1078:
1079:
1080: <h3 id="vm3">NAME</h3>
1081: vm_map() - map memory
1082:
1083: <h3>SYNOPSIS</h3>
1084: <pre>
1085: int vm_map(task_t task, void *addr, size_t size, void **alloc);
1086: </pre>
1087:
1088: <h3>DESCRIPTION</h3>
1089: The vm_map() function maps another task's memory to the current
1090: task.
1091: The <i>task</i> argument is the memory owner to map. The memory is
1092: automatically mapped to the free area of current task. The mapped
1093: address is stored in <i>alloc</i> on success.
1094:
1095: <h3>ERRORS</h3>
1096: <dl>
1097: <dt>[ESRCH]</dt>
1098: <dd>The specified <i>task</i> is not a valid task ID.</dd>
1099: <dt>[EFAULT]</dt>
1100: <dd>The address of <i>addr</i> or <i>alloc</i> is inaccessible.</dd>
1101: <dt>[EINVAL]</dt>
1102: <dd>The specified location is not allocated.</dd>
1103: <dt>[ENOMEM]</dt>
1104: <dd>Not enough space.</dd>
1105: <dt>[EPERM]</dt>
1106: <dd>The specified <i>task</i> is not a current task, but the caller
1107: task does not have CAP_MEMORY capability.</dd>
1108: </dl>
1109: <br>
1110:
1111: <h2 id="tmr">Timer</h2>
1112:
1113:
1114: <h3 id="tmr0">NAME</h3>
1115: timer_sleep() - sleep for a while
1116:
1117: <h3>SYNOPSIS</h3>
1118: <pre>
1119: int timer_sleep(u_long delay, u_long *remain);
1120: </pre>
1121:
1122: <h3>DESCRIPTION</h3>
1123: The timer_sleep() function stops execution of the current thread
1124: until specified time passed.
1125: The <i>delay</i> argument is the delay time in milli second.
1126: If this function is canceled by some reason, the remaining time
1127: is stored in <i>remain</i>.
1128:
1129: <h3>ERRORS</h3>
1130: <dl>
1131: <dt>[EFAULT]</dt>
1132: <dd>The address of <i>remain</i> is inaccessible.</dd>
1133: <dt>[EINTR]</dt>
1134: <dd>The function was interrupted by an exception.</dd>
1135: </dl>
1136: <br>
1137: <hr size="1">
1138:
1139:
1140: <h3 id="tmr1">NAME</h3>
1141: timer_alarm() - schedule an alarm exception
1142:
1143: <h3>SYNOPSIS</h3>
1144: <pre>
1145: int timer_alarm(u_long delay, u_long *remain);
1146: </pre>
1147:
1148: <h3>DESCRIPTION</h3>
1149: The timer_alarm() function sends EXC_ALRM exception to the caller task
1150: after the specified <i>delay</i> milli seconds is passed.
1151: If <i>delay</i> is 0, it stops the alarm timer. When the previous alarm
1152: timer is already working, the remaining time is stored in <i>remain</i>.
1153:
1154: <h3>ERRORS</h3>
1155: <dl>
1156: <dt>[EFAULT]</dt>
1157: <dd>The address of <i>remain</i> is inaccessible.</dd>
1158: </dl>
1159: <br>
1160: <hr size="1">
1161:
1162:
1163: <h3 id="tmr2">NAME</h3>
1164: timer_periodic() - set a periodic timer
1165:
1166: <h3>SYNOPSIS</h3>
1167: <pre>
1168: int timer_periodic(thread_t th, u_long start, u_long period);
1169: </pre>
1170:
1171: <h3>DESCRIPTION</h3>
1172: The specified thread will be woken up in specified time interval.
1173: The <i>start</i> argument is the first wakeup time. If <i>start</i> is 0,
1174: current periodic timer is stopped. <i>period</i> is the time interval
1175: to wakeup. The unit of <i>start</i>/<i>period</i> is milli seconds.
1176:
1177: <h3>ERRORS</h3>
1178: <dl>
1179: <dt>[ESRCH]</dt>
1180: <dd>The specified thread <i>th</i> is not a valid thread ID.</dd>
1181: <dt>[EINVAL]</dt>
1182: <dd><i>start</i> is 0 even when the timer is not started.</dd>
1183: <dt>[ENOMEM]</dt>
1184: <dd>The system is unable to allocate resources.</dd>
1185: <dt>[EPERM]</dt>
1186: <dd>The specified thread <i>th</i> is not in the current task.</dd>
1187: </dl>
1188: <br>
1189: <hr size="1">
1190:
1191:
1192: <h3 id="tmr3">NAME</h3>
1193: timer_waitperiod() - wait timer period
1194:
1195: <h3>SYNOPSIS</h3>
1196: <pre>
1197: int timer_waitperiod(void);
1198: </pre>
1199:
1200: <h3>DESCRIPTION</h3>
1201: The timer_waitperiod() function waits the next period of the current
1202: running periodic timer.
1203: <br><br>
1204: Since this routine returns by any exception, the control
1205: may return at non-period time. So, the caller must retry
1206: immediately if the error status is EINTR.
1207:
1208: <h3>ERRORS</h3>
1209: <dl>
1210: <dt>[EINVAL]</dt>
1211: <dd>The periodic timer is not started for current thread.</dd>
1212: <dt>[EINTR]</dt>
1213: <dd>The function was interrupted by an exception.</dd>
1214: </dl>
1215: <br>
1216:
1217:
1218:
1219: <h2 id="ex">Exception</h2>
1220:
1221: <h3 id="ex0">NAME</h3>
1222: exception_setup() - setup exception handler
1223:
1224: <h3>SYNOPSIS</h3>
1225: <pre>
1226: int exception_setup(void (*handler)(int, void *));
1227: </pre>
1228:
1229: <h3>DESCRIPTION</h3>
1230: Setup an exception handler for the current task.
1231: NULL can be specified as <i>handler</i> to remove current handler.
1232: If the handler is removed, all pending exceptions are discarded
1233: and all exception_wait() are canceled.
1234: Only one exception handler can be set per task. If the previous
1235: handler exists in task, exception_setup() just overwrite the handler.
1236: <br><br>
1237: The exception handler must have the following arguments.<br>
1238: <br>
1239: void exception_handler(int excpt, void *regs);<br>
1240: <br>
1241: <i>excpt</i> is an exception number, and <i>regs</i> are the machine
1242: dependent registers. The exception handler must call the exception_return()
1243: function after it processes the exception.
1244:
1245: <h3>ERRORS</h3>
1246: <dl>
1247: <dt>[EFAULT]</dt>
1248: <dd>The address of <i>handler</i> is inaccessible.</dd>
1249: </dl>
1250: <br>
1251: <hr size="1">
1252:
1253:
1254: <h3 id="ex1">NAME</h3>
1255: exception_return() - return from exception handler
1256:
1257: <h3>SYNOPSIS</h3>
1258: <pre>
1259: int exception_return(void *regs);
1260: </pre>
1261:
1262: <h3>DESCRIPTION</h3>
1263: The exception_return() function is used to return from the exception
1264: handler. <i>regs</i> argument must be the same value which is passed
1265: to the handler.
1266:
1267: <h3>ERRORS</h3>
1268: <dl>
1269: <dt>[EFAULT]</dt>
1270: <dd>The address of <i>regs</i> is inaccessible.</dd>
1271: </dl>
1272: <br>
1273: <hr size="1">
1274:
1275:
1276: <h3 id="ex2">NAME</h3>
1277: exception_raise() - raise an exception
1278:
1279: <h3>SYNOPSIS</h3>
1280: <pre>
1281: int exception_raise(task_t task, int excpt);
1282: </pre>
1283:
1284: <h3>DESCRIPTION</h3>
1285: The exception_raise() function raises an exception for the specified task.
1286:
1287: <h3>ERRORS</h3>
1288: <dl>
1289: <dt>[ESRCH]</dt>
1290: <dd>The specified <i>task</i> is not a valid task ID.</dd>
1291: <dt>[EINVAL]</dt>
1292: <dd>The specified <i>excpt</i> is not a valid exception.</dd>
1293: <dt>[EPERM]</dt>
1294: <dd><i>task</i> is a kernel task, or the task does not register an
1295: exception handler.
1296: <dt>[EPERM]</dt>
1297: <dd>The specified <i>task</i> is not a current task, but the caller
1298: task does not have CAP_KILL capability.</dd>
1299: </dl>
1300: <br>
1301: <hr size="1">
1302:
1303:
1304: <h3 id="ex3">NAME</h3>
1305: exception_wait() - wait an exception
1306:
1307: <h3>SYNOPSIS</h3>
1308: <pre>
1309: int exception_wait(int *excpt);
1310: </pre>
1311:
1312: <h3>DESCRIPTION</h3>
1313: The exception_wait() function blocks the caller thread until
1314: any exception is raised to the thread.
1315: <br><br>
1316: This routine returns EINTR on success.
1317:
1318: <h3>ERRORS</h3>
1319: <dl>
1320: <dt>[EFAULT]</dt>
1321: <dd>The address of <i>excpt</i> is inaccessible.</dd>
1322: <dt>[EINVAL]</dt>
1323: <dd>The caller thread does not register an exception handler.</dd>
1324: </dl>
1325: <br>
1326:
1327:
1328: <h2 id="dev">Device</h2>
1329:
1330: <h3 id="dev0">NAME</h3>
1331: device_open() - open a device
1332:
1333: <h3>SYNOPSIS</h3>
1334: <pre>
1335: int device_open(const char *name, int mode, device_t *dev);
1336: </pre>
1337:
1338: <h3>DESCRIPTION</h3>
1339: The device_open() function opens the specified device.
1340: <i>mode</i> is one of the following open mode.
1341: <ul>
1342: <li>O_RDONLY - Read only</li>
1343: <li>O_WRONLY - Write only</li>
1344: <li>O_RDWR - Read & Write</li>
1345: </ul>
1346: The ID of the opened device is stored in <i>dev</i> on success.
1347:
1348: <h3>ERRORS</h3>
1349: <dl>
1350: <dt>[EFAULT]</dt>
1351: <dd>The address of <i>name</i> is inaccessible.</dd>
1352: <dt>[ENAMETOOLONG]</dt>
1353: <dd>The length of the <i>name</i> argument exceeds MAX_DEVNAME.</dd>
1354: <dt>[ENOENT]</dt>
1355: <dd>The length of the <i>name</i> argument is 0.</dd>
1356: <dt>[ENXIO]</dt>
1357: <dd>The device was not found.</dd>
1358: <dt>[EPERM]</dt>
1359: <dd>The caller task does not have CAP_DEVIO capability.</dd>
1360: </dl>
1361: Other device specific error may be returned.
1362: <br><br>
1363: <hr size="1">
1364:
1365:
1366: <h3 id="dev1">NAME</h3>
1367: device_close() - close a device
1368:
1369: <h3>SYNOPSIS</h3>
1370: <pre>
1371: int device_close(device_t dev);
1372: </pre>
1373:
1374: <h3>DESCRIPTION</h3>
1375: The device_close() function close the specified device.
1376:
1377: <h3>ERRORS</h3>
1378: <dl>
1379: <dt>[ENODEV]</dt>
1380: <dd>The specified device is not valid device.</dd>
1381: <dt>[EBADF]</dt>
1382: <dd>The specified device is not a valid device opened.</dd>
1383: <dt>[EPERM]</dt>
1384: <dd>The caller task does not have CAP_DEVIO capability.</dd>
1385: </dl>
1386: Other device specific error may be returned.
1387: <br><br>
1388: <hr size="1">
1389:
1390:
1391: <h3 id="dev2">NAME</h3>
1392: device_read() - read from a device
1393:
1394: <h3>SYNOPSIS</h3>
1395: <pre>
1396: int device_read(device_t dev, void *buf, size_t *nbyte, int blkno);
1397: </pre>
1398:
1399: <h3>DESCRIPTION</h3>
1400: The device_read() function reads data from the specified device.
1401: <i>nbyte</i> is a read size in byte, and <i>blkno</i> is a start block
1402: of the target device. The unit of <i>blkno</i> is device specific.
1403:
1404: <h3>ERRORS</h3>
1405: <dl>
1406: <dt>[ENODEV]</dt>
1407: <dd>The specified device is not valid device.</dd>
1408: <dt>[EBADF]</dt>
1409: <dd>The specified device is not a valid device opened for read.</dd>
1410: <dt>[EFAULT]</dt>
1411: <dd>The specified buffer is inaccessible, or not writable.</dd>
1412: <dt>[EPERM]</dt>
1413: <dd>The caller task does not have CAP_DEVIO capability.</dd>
1414: </dl>
1415: Other device specific error may be returned.
1416: <br><br>
1417: <hr size="1">
1418:
1419:
1420: <h3 id="dev3">NAME</h3>
1421: device_write() - write to a device
1422:
1423: <h3>SYNOPSIS</h3>
1424: <pre>
1425: int device_write(device_t dev, void *buf, size_t *nbyte, int blkno);
1426: </pre>
1427:
1428: <h3>DESCRIPTION</h3>
1429: The device_read() function writes data to the specified device.
1430: <i>nbytes</i> is a write size in byte, and <i>blkno</i> is a start block
1431: of the target device. The unit of <i>blkno</i> is device specific.
1432:
1433: <h3>ERRORS</h3>
1434: <dl>
1435: <dt>[ENODEV]</dt>
1436: <dd>The specified device is not valid device.</dd>
1437: <dt>[EBADF]</dt>
1438: <dd>The specified device is not a valid device opened for write.</dd>
1439: <dt>[EFAULT]</dt>
1440: <dd>The specified buffer is inaccessible</dd>
1441: <dt>[EPERM]</dt>
1442: <dd>The caller task does not have CAP_DEVIO capability.</dd>
1443: </dl>
1444: Other device specific error may be returned.
1445: <br><br>
1446: <hr size="1">
1447:
1448:
1449: <h3 id="dev4">NAME</h3>
1450: device_ioctl() - control a device
1451:
1452: <h3>SYNOPSIS</h3>
1453: <pre>
1454: int device_ioctl(device_t dev, int cmd, u_long arg);
1455: </pre>
1456:
1457: <h3>DESCRIPTION</h3>
1458: The device_ioctl() function sends a command to the specified device.
1459: <i>cmd</i> and <i>arg</i> are device dependent.
1460:
1461: <h3>ERRORS</h3>
1462: <dl>
1463: <dt>[ENODEV]</dt>
1464: <dd>The specified device is not valid device.</dd>
1465: <dt>[EBADF]</dt>
1466: <dd>The specified device is not a valid device opened for ioctl.</dd>
1467: <dt>[EPERM]</dt>
1468: <dd>The caller task does not have CAP_DEVIO capability.</dd>
1469: </dl>
1470: <br>
1471:
1472:
1473:
1474: <h2 id="mu">Mutex</h2>
1475:
1476: <h3 id="mu0">NAME</h3>
1477: mutex_init() - initialize a mutex
1478:
1479: <h3>SYNOPSIS</h3>
1480: <pre>
1481: int mutex_init(mutex_t *mu);
1482: </pre>
1483:
1484: <h3>DESCRIPTION</h3>
1485: The mutex_init() function creates a new mutex and initializes it.
1486: The ID of the new mutex is stored in <i>mu</i> on success.
1487: <br><br>
1488: If an initialized mutex is reinitialized, undefined behavior results.
1489:
1490: <h3>ERRORS</h3>
1491: <dl>
1492: <dt>[ENOMEM]</dt>
1493: <dd>The system is unable to allocate resources.</dd>
1494: <dt>[EFAULT]</dt>
1495: <dd>The address of <i>mu</i> is inaccessible.</dd>
1496: </dl>
1497: <br>
1498: <hr size="1">
1499:
1500:
1501: <h3 id="mu1">NAME</h3>
1502: mutex_destroy() - destroy a mutex
1503:
1504: <h3>SYNOPSIS</h3>
1505: <pre>
1506: int mutex_destroy(mutex_t *mu);
1507: </pre>
1508:
1509: <h3>DESCRIPTION</h3>
1510: The mutex_destroy() function destroys the specified mutex.
1511: The mutex must be unlock state, otherwise it fails with EBUSY.
1512:
1513: <h3>ERRORS</h3>
1514: <dl>
1515: <dt>[EINVAL]</dt>
1516: <dd>The specified mutex is not a valid mutex.</dd>
1517: <dt>[EBUSY]</dt>
1518: <dd>The mutex is still locked by some thread.</dd>
1519: </dl>
1520: <br>
1521: <hr size="1">
1522:
1523:
1524: <h3 id="mu2">NAME</h3>
1525: mutex_trylock() - try to lock a mutex
1526:
1527: <h3>SYNOPSIS</h3>
1528: <pre>
1529: int mutex_trylock(mutex_t *mu);
1530: </pre>
1531:
1532: <h3>DESCRIPTION</h3>
1533: The mutex_trylock() tries to lock a mutex without blocking.
1534:
1535: <h3>ERRORS</h3>
1536: <dl>
1537: <dt>[EINVAL]</dt>
1538: <dd>The specified mutex is not a valid mutex.</dd>
1539: <dt>[EBUSY]</dt>
1540: <dd>The mutex is already locked.</dd>
1541: </dl>
1542: <br>
1543: <hr size="1">
1544:
1545:
1546: <h3 id="mu3">NAME</h3>
1547: mutex_lock() - lock a mutex
1548:
1549: <h3>SYNOPSIS</h3>
1550: <pre>
1551: int mutex_lock(mutex_t *mu);
1552: </pre>
1553:
1554: <h3>DESCRIPTION</h3>
1555: The mutex_lock() locks the specified mutex.
1556: The caller thread is blocked if the mutex has already been locked.
1557: If the caller thread receives any exception while waiting a mutex,
1558: this routine returns with EINTR.
1559: The mutex is "recursive". It means a thread can lock the same mutex
1560: any number of times.
1561: <h3>ERRORS</h3>
1562: <dl>
1563: <dt>[EINVAL]</dt>
1564: <dd>The specified mutex is not a valid mutex.</dd>
1565: <dt>[EINTR]</dt>
1566: <dd>The function was interrupted by an exception.</dd>
1567: </dl>
1568: <br>
1569: <hr size="1">
1570:
1571:
1572: <h3 id="mu4">NAME</h3>
1573: mutex_unlock() - unlock a mutex
1574:
1575: <h3>SYNOPSIS</h3>
1576: <pre>
1577: int mutex_unlock(mutex_t *mu);
1578: </pre>
1579:
1580: <h3>DESCRIPTION</h3>
1581: The mutex_unlock() function unlocks the specified mutex.
1582: The caller thread must be the current mutex owner.
1583:
1584: <h3>ERRORS</h3>
1585: <dl>
1586: <dt>[EINVAL]</dt>
1587: <dd>The specified mutex is not a valid mutex.</dd>
1588: <dt>[EPERM]</dt>
1589: <dd>The caller thread is not the mutex owner.</dd>
1590: </dl>
1591: <br>
1592:
1593:
1594:
1595: <h2 id="cv">Condition Variable</h2>
1596:
1597: <h3 id="cv0">NAME</h3>
1598: cond_init() - initialize a condition variable
1599:
1600: <h3>SYNOPSIS</h3>
1601: <pre>
1602: int cond_init(cond_t *cond);
1603: </pre>
1604:
1605: <h3>DESCRIPTION</h3>
1606: The cond_init() function creates a new condition variable and initializes it.
1607: <br><br>
1608: If an initialized condition variable is reinitialized, undefined behavior results.
1609:
1610: <h3>ERRORS</h3>
1611: <dl>
1612: <dt>[EFAULT]</dt>
1613: <dd>The address of <i>cond</i> is inaccessible.</dd>
1614: <dt>[ENOMEM]</dt>
1615: <dd>The system is unable to allocate resources.</dd>
1616: </dl>
1617: <br>
1618: <hr size="1">
1619:
1620:
1621: <h3 id="cv1">NAME</h3>
1622: cond_destroy() - destroy a condition variable
1623:
1624: <h3>SYNOPSIS</h3>
1625: <pre>
1626: int cond_destroy(cond_t *cond);
1627: </pre>
1628:
1629: <h3>DESCRIPTION</h3>
1630: The cond_destroy() function destroys the specified condition variable.
1631: If there are any blocked thread waiting for the specified CV, it
1632: returns EBUSY.
1633:
1634: <h3>ERRORS</h3>
1635: <dl>
1636: <dt>[EINVAL]</dt>
1637: <dd>The specified condition variable is not valid.</dd>
1638: <dt>[EBUSY]</dt>
1639: <dd>The condition variable is still locked by some thread.</dd>
1640: </dl>
1641: <br>
1642: <hr size="1">
1643:
1644:
1645: <h3 id="cv2">NAME</h3>
1646: cond_wait() - wait on a condition
1647:
1648: <h3>SYNOPSIS</h3>
1649: <pre>
1650: int cond_wait(cond_t *cond, mutex_t *mu);
1651: </pre>
1652:
1653: <h3>DESCRIPTION</h3>
1654: The cond_wait() function waits on the specified condition.
1655: If the caller thread receives any exception, this routine returns
1656: with EINTR.
1657:
1658: <h3>ERRORS</h3>
1659: <dl>
1660: <dt>[EINVAL]</dt>
1661: <dd>The specified condition variable is not valid.</dd>
1662: <dt>[EINTR]</dt>
1663: <dd>The function was interrupted by an exception.</dd>
1664: </dl>
1665: <br>
1666: <hr size="1">
1667:
1668:
1669: <h3 id="cv3">NAME</h3>
1670: cond_signal() - signal condition
1671:
1672: <h3>SYNOPSIS</h3>
1673: <pre>
1674: int cond_signal(cond_t *cond);
1675: </pre>
1676:
1677: <h3>DESCRIPTION</h3>
1678: The cond_signal() function unblocks the thread that is waiting
1679: on the specified condition variable.
1680:
1681: <h3>ERRORS</h3>
1682: <dl>
1683: <dt>[EINVAL]</dt>
1684: <dd>The specified condition variable is not valid.</dd>
1685: </dl>
1686: <br>
1687: <hr size="1">
1688:
1689:
1690: <h3 id="cv4">NAME</h3>
1691: cond_broadcast() - broadcast a condition
1692:
1693: <h3>SYNOPSIS</h3>
1694: <pre>
1695: int cond_broadcast(cond_t *cond);
1696: </pre>
1697:
1698: <h3>DESCRIPTION</h3>
1699: The cond_broadcast() function unblocks all threads that are blocked
1700: on the specified condition variable.
1701:
1702: <h3>ERRORS</h3>
1703: <dl>
1704: <dt>[EINVAL]</dt>
1705: <dd>The specified condition variable is not valid.</dd>
1706: </dl>
1707: <br>
1708:
1709:
1710:
1711: <h2 id="sem">Semaphore</h2>
1712:
1713: <h3 id="sem0">NAME</h3>
1714: sem_init() - initialize a semaphore
1715:
1716: <h3>SYNOPSIS</h3>
1717: <pre>
1718: int sem_init(sem_t *sem, u_int value);
1719: </pre>
1720:
1721: <h3>DESCRIPTION</h3>
1722: The sem_init() function initializes a semaphore. It will create a
1723: new semaphore if the specified <i>sem</i> does not exist. If the
1724: specified semaphore <i>sem</i> already exists, it is re-initialized
1725: only if nobody is waiting for it.
1726: The initial semaphore value is set to <i>value</i> value.
1727: The ID of the new semaphore is stored in <i>sem</i> on success.
1728:
1729: <h3>ERRORS</h3>
1730: <dl>
1731: <dt>[EINVAL]</dt>
1732: <dd><i>value</i> value is larger than SEM_MAX.</dd>
1733: <dt>[ENOSPC]</dt>
1734: <dd>The system is unable to allocate resources.</dd>
1735: <dt>[EFAULT]</dt>
1736: <dd>The address of <i>sem</i> is inaccessible.</dd>
1737: <dt>[EBUSY]</dt>
1738: <dd>There are currently threads blocked on the semaphore.</dd>
1739: <dt>[EPERM]</dt>
1740: <dd>The caller task is not an owner of the <i>sem</i>, but it
1741: does not have CAP_SEMAPHORE capability.</dd>
1742: </dl>
1743: <br>
1744: <hr size="1">
1745:
1746:
1747: <h3 id="sem1">NAME</h3>
1748: sem_destroy() - destroy a semaphore
1749:
1750: <h3>SYNOPSIS</h3>
1751: <pre>
1752: int sem_destroy(sem_t *sem);
1753: </pre>
1754:
1755: <h3>DESCRIPTION</h3>
1756: The sem_destroy() function destroys the specified semaphore.
1757: If some thread is waiting for the specified semaphore, this routine
1758: fails with EBUSY.
1759:
1760: <h3>ERRORS</h3>
1761: <dl>
1762: <dt>[EINVAL]</dt>
1763: <dd>The specified semaphore is not a valid semaphore.</dd>
1764: <dt>[EBUSY]</dt>
1765: <dd>There are currently threads blocked on the semaphore.</dd>
1766: </dl>
1767: <br>
1768: <hr size="1">
1769:
1770:
1771: <h3 id="sem2">NAME</h3>
1772: sem_wait() - lock a semaphore
1773:
1774: <h3>SYNOPSIS</h3>
1775: <pre>
1776: int sem_wait(sem_t *sem, u_long timeout);
1777: </pre>
1778:
1779: <h3>DESCRIPTION</h3>
1780: The sem_wait() function locks the semaphore referred by <i>sem</i>
1781: only if the semaphore value is currently positive. The thread
1782: will sleep while the semaphore value is zero.
1783: It decrements the semaphore value in return.
1784: If <i>timeout</i> value is set if it is not 0.
1785:
1786: <h3>ERRORS</h3>
1787: <dl>
1788: <dt>[EINVAL]</dt>
1789: <dd>The specified semaphore is not a valid semaphore.</dd>
1790: <dt>[ETIMEDOUT]</dt>
1791: <dd>Time out.</dd>
1792: <dt>[EINTR]</dt>
1793: <dd>The function was interrupted by an exception.</dd>
1794: <dt>[EPERM]</dt>
1795: <dd>The caller task is not an owner of the <i>sem</i>, but it
1796: does not have CAP_SEMAPHORE capability.</dd>
1797: </dl>
1798: <br>
1799: <hr size="1">
1800:
1801:
1802: <h3 id="sem3">NAME</h3>
1803: sem_trywait() - try to lock a semaphore
1804:
1805: <h3>SYNOPSIS</h3>
1806: <pre>
1807: int sem_trywait(sem_t *sem);
1808: </pre>
1809:
1810: <h3>DESCRIPTION</h3>
1811: The sem_trylock() tries to lock a semaphore without blocking.
1812:
1813: <h3>ERRORS</h3>
1814: <dl>
1815: <dt>[EINVAL]</dt>
1816: <dd>The specified semaphore is not a valid semaphore.</dd>
1817: <dt>[EAGAIN]</dt>
1818: <dd>The semaphore is already locked.</dd>
1819: <dt>[EPERM]</dt>
1820: <dd>The caller task is not an owner of the <i>sem</i>, but it
1821: does not have CAP_SEMAPHORE capability.</dd>
1822: </dl>
1823: <br>
1824: <hr size="1">
1825:
1826:
1827: <h3 id="sem4">NAME</h3>
1828: sem_post() - unlock a semaphore
1829:
1830: <h3>SYNOPSIS</h3>
1831: <pre>
1832: int sem_post(sem_t *sem);
1833: </pre>
1834:
1835: <h3>DESCRIPTION</h3>
1836: The sem_post() function unlock the specified semaphore.
1837: It increments the semaphore value.
1838: If the semaphore value becomes positive, one of the threads waiting
1839: to lock will be unblocked.
1840: The caller thread is not blocked by this function.
1841:
1842: <h3>ERRORS</h3>
1843: <dl>
1844: <dt>[EINVAL]</dt>
1845: <dd>The specified semaphore is not a valid semaphore.</dd>
1846: <dt>[ERANGE]</dt>
1847: <dd>The semaphore value exceeds SEM_MAX.</dd>
1848: <dt>[EPERM]</dt>
1849: <dd>The caller task is not an owner of the <i>sem</i>, but it
1850: does not have CAP_SEMAPHORE capability.</dd>
1851: </dl>
1852: <br>
1853: <hr size="1">
1854:
1855:
1856: <h3 id="sem5">NAME</h3>
1857: sem_getvalue() - get the value of a semaphore
1858:
1859: <h3>SYNOPSIS</h3>
1860: <pre>
1861: int sem_getvalue(sem_t *sem, u_int *value);
1862: </pre>
1863:
1864: <h3>DESCRIPTION</h3>
1865: The sem_getvalue() function returns the current value of the specified semaphore.
1866:
1867: <h3>ERRORS</h3>
1868: <dl>
1869: <dt>[EINVAL]</dt>
1870: <dd>The specified semaphore is not a valid semaphore.</dd>
1871: <dt>[EFAULT]</dt>
1872: <dd>The address of <i>sem</i> is inaccessible.</dd>
1873: <dt>[EPERM]</dt>
1874: <dd>The caller task is not an owner of the <i>sem</i>, but it
1875: does not have CAP_SEMAPHORE capability.</dd>
1876: </dl>
1877: <br>
1878:
1879:
1880:
1881: <h2 id="sys">System</h2>
1882:
1883: <h3 id="sys0">NAME</h3>
1884: sys_log() - log a message
1885:
1886: <h3>SYNOPSIS</h3>
1887: <pre>
1888: void sys_log(const char *buf);
1889: </pre>
1890:
1891: <h3>DESCRIPTION</h3>
1892: The sys_log() function puts the specified text message to the
1893: predefined device.
1894: This function is available only when the kernel is built with debug flag.
1895:
1896: <h3>ERRORS</h3>
1897: <dl>
1898: <dt>[EINVAL]</dt>
1899: <dd>The message is too long.</dd>
1900: <dt>[EFAULT]</dt>
1901: <dd>The address of <i>buf</i> is inaccessible.</dd>
1902: </dl>
1903: <br>
1904: <hr size="1">
1905:
1906:
1907: <h3 id="sys1">NAME</h3>
1908: sys_panic() - fatal error
1909:
1910: <h3>SYNOPSIS</h3>
1911: <pre>
1912: void sys_panic(const char *buf);
1913: </pre>
1914:
1915: <h3>DESCRIPTION</h3>
1916: The sys_panic() function shows the panic message and stops the system.
1917: The application should use this call only when it detects the unrecoverable
1918: error.
1919:
1920: <h3>ERRORS</h3>
1921: No errors are defined.
1922: <br>
1923: <br>
1924: <hr size="1">
1925:
1926:
1927:
1928: <h3 id="sys2">NAME</h3>
1929: sys_info() - return system information
1930:
1931: <h3>SYNOPSIS</h3>
1932: <pre>
1933: int sys_info(int type, void *buf);
1934: </pre>
1935:
1936: <h3>DESCRIPTION</h3>
1937: The sys_info() function returns the specified system information.
1938: The kernel supports the following system infomation.
1939: <ul>
1940: <li>INFO_KERNEL - Get kernel information</li>
1941: <li>INFO_MEMORY - Get memory information</li>
1942: <li>INFO_SCHED - Get scheduling information</li>
1943: <li>INFO_THREAD - Get thread information</li>
1944: <li>INFO_DEVICE - Get device information</li>
1945: </ul>
1946:
1947: <h3>ERRORS</h3>
1948: <dl>
1949: <dt>[EINVAL]</dt>
1950: <dd><i>type</i> is not a valid type.</dd>
1951: <dt>[EFAULT]</dt>
1952: <dd>The address of <i>buf</i> is inaccessible.</dd>
1953: </dl>
1954: <br>
1955: <hr size="1">
1956:
1957:
1958:
1959: <h3 id="sys3">NAME</h3>
1960: sys_time() - return system ticks
1961:
1962: <h3>SYNOPSIS</h3>
1963: <pre>
1964: int sys_time(u_long *ticks);
1965: </pre>
1966:
1967: <h3>DESCRIPTION</h3>
1968: The sys_time() function returns the current system ticks.
1969:
1970: <h3>ERRORS</h3>
1971: <dl>
1972: <dt>[EFAULT]</dt>
1973: <dd>The address of <i>ticks</i> is inaccessible.</dd>
1974: </dl>
1975: <br>
1976: <hr size="1">
1977:
1978:
1979:
1980: <h3 id="sys4">NAME</h3>
1981: sys_debug() - kernel debugging interface
1982:
1983: <h3>SYNOPSIS</h3>
1984: <pre>
1985: int sys_debug(int cmd, int param);
1986: </pre>
1987:
1988: <h3>DESCRIPTION</h3>
1989: The sys_debug() controls the kernel built-in debug functions.
1990: The kernel supports the following commands.
1991: <ul>
1992: <li>DBGCMD_DUMP - Dump kernel information</li>
1993: </ul>
1994:
1995: <h3>ERRORS</h3>
1996: <dl>
1997: <dt>[EINVAL]</dt>
1998: <dd><i>cmd</i> is not a valid command.</dd>
1999: <dt>[ENOSYS]</dt>
2000: <dd>The function is not supported.</dd>
2001: </dl>
2002: <br>
2003:
2004: </td>
2005: </tr>
2006: <tr>
2007: <td id="footer" colspan="2" style="vertical-align: top;">
2008: <a href="http://sourceforge.net">
2009: <img src="http://sourceforge.net/sflogo.php?group_id=132028&type=1"
2010: alt="SourceForge.net Logo" border="0" height="31" width="88"></a><br>
2011: Copyright© 2005-2007 Kohsuke Ohtani
2012: </td>
2013: </tr>
2014:
2015: </tbody>
2016: </table>
2017:
2018: </div>
2019: <div id="bottom"></div>
2020:
2021: </body>
2022: </html>
CVSweb
![[BACK]](/icons/back.gif){kind=icon}
Return to kapi.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / prex-old / doc / html / doc