Annotation of src/share/lkm/README, Revision 1.1
1.1 ! deraadt 1: #
! 2: # Copyright (c) 1993 Terrence R. Lambert.
! 3: # All rights reserved.
! 4: #
! 5: # Redistribution and use in source and binary forms, with or without
! 6: # modification, are permitted provided that the following conditions
! 7: # are met:
! 8: # 1. Redistributions of source code must retain the above copyright
! 9: # notice, this list of conditions and the following disclaimer.
! 10: # 2. Redistributions in binary form must reproduce the above copyright
! 11: # notice, this list of conditions and the following disclaimer in the
! 12: # documentation and/or other materials provided with the distribution.
! 13: # 3. All advertising materials mentioning features or use of this software
! 14: # must display the following acknowledgement:
! 15: # This product includes software developed by Terrence R. Lambert.
! 16: # 4. The name Terrence R. Lambert may not be used to endorse or promote
! 17: # products derived from this software without specific prior written
! 18: # permission.
! 19: #
! 20: # THIS SOFTWARE IS PROVIDED BY TERRENCE R. LAMBERT ``AS IS'' AND ANY
! 21: # EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! 22: # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
! 23: # ARE DISCLAIMED. IN NO EVENT SHALL THE TERRENCE R. LAMBERT BE LIABLE
! 24: # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! 25: # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
! 26: # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 27: # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
! 28: # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
! 29: # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
! 30: # SUCH DAMAGE.
! 31: #
! 32: # $Id: README,v 1.3 1993/11/23 04:48:04 cgd Exp $
! 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
! 137: and introducing an incompatability as far as file system modules
! 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
! 156: compatability (probably using symbolic links).
! 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