src/share/lkm/README - annotate

Return to README CVS log

Up to [local] / src / share / lkm

Annotation of src/share/lkm/README, Revision 1.5

1.5 ! tedu 1: # $OpenBSD: README,v 1.4 2003/03/06 04:19:45 david Exp $
1.1 deraadt 2: #
3: # Copyright (c) 1993 Terrence R. Lambert.
4: # All rights reserved.
5: #
6: # Redistribution and use in source and binary forms, with or without
7: # modification, are permitted provided that the following conditions
8: # are met:
9: # 1. Redistributions of source code must retain the above copyright
10: # notice, this list of conditions and the following disclaimer.
11: # 2. Redistributions in binary form must reproduce the above copyright
12: # notice, this list of conditions and the following disclaimer in the
13: # documentation and/or other materials provided with the distribution.
14: # 3. All advertising materials mentioning features or use of this software
15: # must display the following acknowledgement:
16: # This product includes software developed by Terrence R. Lambert.
17: # 4. The name Terrence R. Lambert may not be used to endorse or promote
18: # products derived from this software without specific prior written
19: # permission.
20: #
21: # THIS SOFTWARE IS PROVIDED BY TERRENCE R. LAMBERT ``AS IS'' AND ANY
22: # EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23: # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24: # ARE DISCLAIMED. IN NO EVENT SHALL THE TERRENCE R. LAMBERT BE LIABLE
25: # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26: # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27: # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28: # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29: # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30: # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31: # SUCH DAMAGE.
32: #
33: #
34:
35: 0.0 README
36:
37: README file for the loadable kernel modules interface.
38:
39: Direct questions and comments to:
40:
41: Terry Lambert
42: terry@cs.weber.edu
43:
44: Please do *not* mail me at Novell.
45:
46:
1.4 david 47: 1.0 About this build hierarchy
1.1 deraadt 48:
1.4 david 49: This is the build hierarchy for the loadable kernel modules
1.1 deraadt 50: (lkm) command line interface and test suite (including a
51: set of sample code for each possible module type).
52:
53: The procedures in this file assume you have installed the
54: kernel portions of the lkm system and have rebooted your
55: machine so that they are ready for use.
56:
57: If you have not done this, then there is no reason for you to
58: continue; please take the time to install the lkm system into
59: your kernel at this time.
60:
61:
62: 2.0 Compiler warnings
63:
64: Some compiler warnings will occur due to inclusion of kernel
65: and non-kernel header files in the same program that have had
66: the same function names ANSIfied and the prototypes for the
67: kernel and libc functions conflict. This needs to be resolved
68: by fixing the header files, which I haven't bothered to do (the
69: main conflict was "printf", and I made a dirty hack to get
70: around it until the header files have been fixed).
71:
72:
73: 3.0 Usage warnings
74:
75: Loading a bogus module will kill your machine, but if you are
1.4 david 76: doing development, this will end up happening (hopefully)
1.1 deraadt 77: less frequently than changing, recompiling, installing, and
1.4 david 78: rebooting would normally occur. This should speed development
1.1 deraadt 79: considerably for a lot of the in-kernel work that is currently
80: taking place.
81:
82:
83: 4.0 Loadable module types supported
84:
1.5 ! tedu 85: There are six loadable modules types supported; five of these are
1.1 deraadt 86: specific module types; the sixth is to allow the user to make
87: their own loader as part of the module and allow them to replace
1.5 ! tedu 88: or extend appropriate tables in the kernel.
1.1 deraadt 89:
90:
91: 4.1 System call modules
92:
93: System calls as loadable modules use one of two approaches.
94:
95: If the system call slot is unspecified (-1), it will attempt
96: to locate (and allocate) the next free call slot that points
97: to the address of the "lkmnosys" function (an alias for the
98: "nosys" function). It replaces this with the user's call;
99: the user can tell which slot was allocated using the "modstat"
100: command (the call slot is indicated by the value of "Off").
101:
102: If the system call slot is specified, it will replace that
103: specific call (assuming it is in range of the entries in the
104: sysent[] table). Care should be taken when replacing system
1.5 ! tedu 105: calls. Good candidates are calls that the user is attempting
1.1 deraadt 106: to repair or make POSIX compliant. It is possible to replace
107: all calls, although care should be taken with the "ioctl()"
108: call, as it is the interface for the lkm loader.
109:
110: When unloaded, the system call module replaces the previous
1.5 ! tedu 111: contents of the call slot. If this was an allocable slot, it
! 112: is now reallocable; if it was a particular call slot, the
! 113: previous function is restored.
1.1 deraadt 114:
115: The directory ./sample/syscall contains a sample implementation
116: of a loadable system call.
117:
118:
119: 4.2 Virtual file system modules
120:
121: A virtual file system can be loaded as a module. The example
122: provided is for the "kernfs" file system; this is the code in
123: NetBSD's /sys/kernfs combined in a single object with another
124: piece of code giving a module entry point for the file system;
125: with very little effort, any file system can be set up this way
126: (although I suggest you leave "ufs" statically linked, since
127: it is necessary for booting).
128:
129: The critical section of loading a VFS is to get the entry in
130: the right slot and mounted.
131:
132: Because of the dependency on the vfssw[] table index during
133: the mount, we can't simply mix and match file systems except
134: in their predefined locations with regard to mount. This
135: means that there are changes to vfssw[] and mount coming
136: down the road (which will end up incrementing the lkm version
1.3 fgsch 137: and introducing an incompatibility as far as file system modules
1.5 ! tedu 138: are concerned).
1.1 deraadt 139:
140: The directory ./sample/vfs contains the sample implementation
141: of the loadable kernfs vfs.
142:
143:
144: 4.3 Device driver modules
145:
146: The major issue to deal with when creating device drivers is
1.5 ! tedu 147: ensuring the creation of the device node. The current approach
1.1 deraadt 148: to this is executing a module specific shell script upon a
149: successful load.
150:
1.5 ! tedu 151: A potentially better solution is encoding the device name in
1.1 deraadt 152: the device switch, or, better, providing a functional interface
153: to the init routine, and then using a "/devices" file system
154: to export devices to the file system name space. Of course,
155: the default "/dev" directory would have to be maintained for
1.3 fgsch 156: compatibility (probably using symbolic links).
1.1 deraadt 157:
158: This distribution does not contain a loadable device driver
159: example. A potentially beneficial example could be made of
160: the "lpa" interruptless printer driver.
161:
162:
163: 4.4 Streams modules
164:
165: Streams module support has been removed from this release; when
1.5 ! tedu 166: the streams implementation is ready, it will be restored as a
1.1 deraadt 167: patch.
168:
169: Please do not ask me for early availability on my streams
170: implementation; until I have some non-proprietary modules
171: to distribute, I'm putting work on it on the back burner
172: while I finish shared libraries.
173:
174:
175: 4.5 Execution interpreters
176:
177: Execution interpreters allow loading of programs with magic
178: numbers other than the default numbers supported by NetBSD.
1.5 ! tedu 179: This allows user space development of changes in exec format
! 180: to support, among other things, shared libraries.
1.1 deraadt 181:
1.5 ! tedu 182: Another potential use requires changing the references to
1.1 deraadt 183: the "sysent[]" system call table from direct references to
184: indirect through a pointer in the proc struct. This allows
185: the execution interpreter to, among other things, support
186: (statically linked) executables from other environments,
1.5 ! tedu 187: like XENIX, SVR3, SVR4, and Linux.
1.1 deraadt 188:
189: There is no example of a loadable execution interpreter
190: provided with this distribution.
191:
192:
193: 4.6 Miscellaneous modules
194:
195: Miscellaneous modules are modules for which there is not a
1.5 ! tedu 196: current, well-defined, or well-used interface for extension.
1.1 deraadt 197: They are provided for extension, and the user is expected to
198: write their own loader to handle the kernel pointer/table
199: manipulation to "wire in" their loaded module (and "unwire"
1.5 ! tedu 200: it on unload).
1.1 deraadt 201:
202: One example of a "miscellaneous module" might be a loader for
1.5 ! tedu 203: card-specific VGA drivers or alternate terminal emulations in
1.1 deraadt 204: an appropriately layered console driver.
205:
206: The table manipulations required are specific to the console
207: interface, yet a loadable module may be used if code is written
208: to tell it how to manipulate the interfaces within the internal
209: console interfaces.
210:
211: An example of a "miscellaneous module" is provided to show how
212: to write "miscellaneous modules"; it duplicates the functionality
213: of the "system call" module type, and is not intended to be
214: seriously used, as it could interfere with the "system call"
215: module type. The sample code is located in ./sample/misc.
216:
217:
218:
219: 5.0 END OF DOCUMENT