Annotation of src/share/lkm/README, Revision 1.3
1.3 ! fgsch 1: # $OpenBSD: README,v 1.2 2000/03/02 14:46:35 todd 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:
47: 1.0 About this build heirarchy
48:
49: This is the build heirarchy for the loadable kernel modules
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
76: doing developement, this will end up happening (hopefully)
77: less frequently than changing, recompiling, installing, and
78: rebooting would normally occur. This should speed developement
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:
85: There are 6 loadable modules types supported; 5 of these are
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
88: or extend apropriate tables in the kernel.
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
105: calls. Good candiates are calls which the user is attempting
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
111: contents of the call slot it was loaded in. If this was an
112: allocable slot, it is now reallocable; if it was a particular
113: call slot, the previous function is restored.
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.1 deraadt 138: are converned).
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
147: insuring the creation of the device node. The current approach
148: to this is executing a module specific shell script upon a
149: successful load.
150:
151: A potentially better soloution is encoding the device name in
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
166: the streams implementation is ready, it wil be restored as a
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.
179: The reasoning behind this is to effectively allow user space
180: developement of changes in exec format to support, among
181: other things, shared libraries.
182:
183: Another portential use requires changing the references to
184: the "sysent[]" system call table from direct references to
185: indirect through a pointer in the proc struct. This allows
186: the execution interpreter to, among other things, support
187: (statically linked) executables from other environments,
188: like Xenix, SVR3, SVR4, and Linux.
189:
190: There is no example of a loadable execution interpreter
191: provided with this distribution.
192:
193:
194: 4.6 Miscellaneous modules
195:
196: Miscellaneous modules are modules for which there is not a
197: current, well defined, or well used interface for extension.
198: They are provided for extension, and the user is expected to
199: write their own loader to handle the kernel pointer/table
200: manipulation to "wire in" their loaded module (and "unwire"
201: it on uload).
202:
203: One example of a "miscellaneous module" might be a loader for
204: card-specific VGA drivers or alternate terminal emualtions in
205: an appropriately layered console driver.
206:
207: The table manipulations required are specific to the console
208: interface, yet a loadable module may be used if code is written
209: to tell it how to manipulate the interfaces within the internal
210: console interfaces.
211:
212: An example of a "miscellaneous module" is provided to show how
213: to write "miscellaneous modules"; it duplicates the functionality
214: of the "system call" module type, and is not intended to be
215: seriously used, as it could interfere with the "system call"
216: module type. The sample code is located in ./sample/misc.
217:
218:
219:
220: 5.0 END OF DOCUMENT
![[BACK]](/icons/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / share / lkm