| @@ -1,134 +1,136 @@ | | | @@ -1,134 +1,136 @@ |
1 | .\" $NetBSD: rump.3,v 1.3 2009/05/24 23:13:49 pooka Exp $ | | 1 | .\" $NetBSD: rump.3,v 1.4 2009/05/28 09:41:05 wiz Exp $ |
2 | .\" | | 2 | .\" |
3 | .\" Copyright (c) 2008 Antti Kantee. All rights reserved. | | 3 | .\" Copyright (c) 2008 Antti Kantee. All rights reserved. |
4 | .\" | | 4 | .\" |
5 | .\" Redistribution and use in source and binary forms, with or without | | 5 | .\" Redistribution and use in source and binary forms, with or without |
6 | .\" modification, are permitted provided that the following conditions | | 6 | .\" modification, are permitted provided that the following conditions |
7 | .\" are met: | | 7 | .\" are met: |
8 | .\" 1. Redistributions of source code must retain the above copyright | | 8 | .\" 1. Redistributions of source code must retain the above copyright |
9 | .\" notice, this list of conditions and the following disclaimer. | | 9 | .\" notice, this list of conditions and the following disclaimer. |
10 | .\" 2. Redistributions in binary form must reproduce the above copyright | | 10 | .\" 2. Redistributions in binary form must reproduce the above copyright |
11 | .\" notice, this list of conditions and the following disclaimer in the | | 11 | .\" notice, this list of conditions and the following disclaimer in the |
12 | .\" documentation and/or other materials provided with the distribution. | | 12 | .\" documentation and/or other materials provided with the distribution. |
13 | .\" | | 13 | .\" |
14 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | | 14 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
15 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | | 15 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
16 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | | 16 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
17 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | | 17 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
18 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | | 18 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
19 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | | 19 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
20 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | | 20 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
21 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | | 21 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
22 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | | 22 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
23 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | | 23 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
24 | .\" SUCH DAMAGE. | | 24 | .\" SUCH DAMAGE. |
25 | .\" | | 25 | .\" |
26 | .Dd May 25, 2009 | | 26 | .Dd May 25, 2009 |
27 | .Dt RUMP 3 | | 27 | .Dt RUMP 3 |
28 | .Os | | 28 | .Os |
29 | .Sh NAME | | 29 | .Sh NAME |
30 | .Nm rump | | 30 | .Nm rump |
31 | .Nd Runnable Userspace Meta Program kernel | | 31 | .Nd Runnable Userspace Meta Program kernel |
32 | .Sh LIBRARY | | 32 | .Sh LIBRARY |
33 | rump Library (librump, \-lrump) | | 33 | rump Library (librump, \-lrump) |
34 | .Sh SYNOPSIS | | 34 | .Sh SYNOPSIS |
35 | .In rump/rump.h | | 35 | .In rump/rump.h |
36 | .In rump/rump_syscalls.h | | 36 | .In rump/rump_syscalls.h |
37 | .In rump/rumpvnode_if.h | | 37 | .In rump/rumpvnode_if.h |
38 | .Sh DESCRIPTION | | 38 | .Sh DESCRIPTION |
39 | .Nm | | 39 | .Nm |
40 | emulates portions of the kernel in order to be able to run kernel code | | 40 | emulates portions of the kernel in order to be able to run kernel code |
41 | from a userspace application. | | 41 | from a userspace application. |
42 | For most parts kernel code is directly used, but in some cases such as | | 42 | For most parts kernel code is directly used, but in some cases such as |
43 | with vm and device drivers a reimplementation suitable for userspace | | 43 | with vm and device drivers a reimplementation suitable for userspace |
44 | is provided. | | 44 | is provided. |
45 | All of the routines in | | 45 | All of the routines in |
46 | .Nm | | 46 | .Nm |
47 | have been compiled in the kernel namespace with | | 47 | have been compiled in the kernel namespace with |
48 | .Dv \-D_KERNEL . | | 48 | .Dv \-D_KERNEL . |
49 | .Pp | | 49 | .Pp |
50 | Although | | 50 | Although |
51 | .Nm | | 51 | .Nm |
52 | includes many kernel routines directly, userspace applications should | | 52 | includes many kernel routines directly, userspace applications should |
53 | not attempt to include | | 53 | not attempt to include |
54 | .Nx | | 54 | .Nx |
55 | system headers and call kernel functions directly. | | 55 | system headers and call kernel functions directly. |
56 | Instead, | | 56 | Instead, |
57 | .Nm | | 57 | .Nm |
58 | routines should be called. | | 58 | routines should be called. |
59 | In case applications attempt to include | | 59 | In case applications attempt to include |
60 | .In sys | | 60 | .In sys |
61 | headers from the | | 61 | headers from the |
62 | .Nx | | 62 | .Nx |
63 | tree, collisions will result on other platforms. | | 63 | tree, collisions will result on other platforms. |
64 | .Pp | | 64 | .Pp |
65 | Three classes of routines are provided by | | 65 | Three classes of routines are provided by |
66 | .Nm : | | 66 | .Nm : |
67 | .Bl -tag -width XXX -offset indent | | 67 | .Bl -tag -width XXX -offset indent |
68 | .It Native | | 68 | .It Native |
69 | These routines have been handwritten for | | 69 | These routines have been handwritten for |
70 | .Nm | | 70 | .Nm |
71 | operation. | | 71 | operation. |
72 | Some are useful purely for | | 72 | Some are useful purely for |
73 | .Nm , | | 73 | .Nm , |
74 | while others are merely interfaces to existing kernel routines. | | 74 | while others are merely interfaces to existing kernel routines. |
75 | An example of the former is | | 75 | An example of the former is |
76 | .Fn rump_fakeblk_register , | | 76 | .Fn rump_fakeblk_register , |
77 | while an example of the latter class is | | 77 | while an example of the latter class is |
78 | .Fn rump_vfs_unmount . | | 78 | .Fn rump_vfs_unmount . |
79 | .Pp | | 79 | .Pp |
80 | The routines available in this class can be found from the header | | 80 | The routines available in this class can be found from the header |
81 | .In rump.h . | | 81 | .In rump.h . |
82 | .It System Calls | | 82 | .It System Calls |
83 | It is possible to execute certain system calls from | | 83 | It is possible to execute certain system calls from |
84 | .Nm . | | 84 | .Nm . |
85 | However, contrary to real system calls, the kernel is never entered, | | 85 | However, contrary to real system calls, the kernel is never entered, |
86 | but the system call backend code compiled into | | 86 | but the system call backend code compiled into |
87 | .Nm | | 87 | .Nm |
88 | is merely called as a direct function call. | | 88 | is merely called as a direct function call. |
89 | .Pp | | 89 | .Pp |
90 | The autogenerated list of system calls currently available in | | 90 | The autogenerated list of system calls currently available in |
91 | .Nm | | 91 | .Nm |
92 | can be found from the header | | 92 | can be found from the header |
93 | .In rump_syscalls.h . | | 93 | .In rump_syscalls.h . |
94 | .It Vnode Interface | | 94 | .It Vnode Interface |
95 | To sort out namespace collisions for non-NetBSD platforms, the whole | | 95 | To sort out namespace collisions for |
| | | 96 | .Pf non- Nx |
| | | 97 | platforms, the whole |
96 | vnode interface set is provided under a special namespace. | | 98 | vnode interface set is provided under a special namespace. |
97 | The operation is the same as in the kernel, but the interface names | | 99 | The operation is the same as in the kernel, but the interface names |
98 | begin with the prefix RUMP_VOP. | | 100 | begin with the prefix RUMP_VOP. |
99 | .Pp | | 101 | .Pp |
100 | This class of routines is available from the autogenerated header | | 102 | This class of routines is available from the autogenerated header |
101 | .In rumpvnode_if.h . | | 103 | .In rumpvnode_if.h . |
102 | .El | | 104 | .El |
103 | .Pp | | 105 | .Pp |
104 | Before use | | 106 | Before use |
105 | .Nm | | 107 | .Nm |
106 | must be initialized by calling | | 108 | must be initialized by calling |
107 | .Fn rump_init . | | 109 | .Fn rump_init . |
108 | .Sh SEE ALSO | | 110 | .Sh SEE ALSO |
109 | .Xr p2k 3 , | | 111 | .Xr p2k 3 , |
110 | .Xr rumpuser 3 , | | 112 | .Xr rumpuser 3 , |
111 | .Xr ukfs 3 | | 113 | .Xr ukfs 3 |
112 | .Rs | | 114 | .Rs |
113 | .%A Antti Kantee | | 115 | .%A Antti Kantee |
114 | .%D March 2009 | | 116 | .%D March 2009 |
115 | .%J Proceedings of AsiaBSDCon 2009 | | 117 | .%J Proceedings of AsiaBSDCon 2009 |
116 | .%P pp. 71-80 | | 118 | .%P pp. 71-80 |
117 | .%T Environmental Independence: BSD Kernel TCP/IP in Userspace | | 119 | .%T Environmental Independence: BSD Kernel TCP/IP in Userspace |
118 | .Re | | 120 | .Re |
119 | .Rs | | 121 | .Rs |
120 | .%A Antti Kantee | | 122 | .%A Antti Kantee |
121 | .%D May 2009 | | 123 | .%D May 2009 |
122 | .%J BSDCan 2009 | | 124 | .%J BSDCan 2009 |
123 | .%T Kernel Development in Userspace - The Rump Approach | | 125 | .%T Kernel Development in Userspace - The Rump Approach |
124 | .Re | | 126 | .Re |
125 | .Sh HISTORY | | 127 | .Sh HISTORY |
126 | .Nm | | 128 | .Nm |
127 | first appeared in | | 129 | first appeared in |
128 | .Nx 5.0 . | | 130 | .Nx 5.0 . |
129 | .Sh AUTHORS | | 131 | .Sh AUTHORS |
130 | .An Antti Kantee Aq pooka@iki.fi | | 132 | .An Antti Kantee Aq pooka@iki.fi |
131 | .Sh NOTE | | 133 | .Sh NOTE |
132 | .Nm | | 134 | .Nm |
133 | is highly experimental and may change in header location, library | | 135 | is highly experimental and may change in header location, library |
134 | name, API and/or ABI without warning. | | 136 | name, API and/or ABI without warning. |