1abbcaa0aSDoug Rabson# Copyright (c) 1998 Rajesh Vaidheeswarran 2abbcaa0aSDoug Rabson# All rights reserved. 3abbcaa0aSDoug Rabson# 4abbcaa0aSDoug Rabson# Redistribution and use in source and binary forms, with or without 5abbcaa0aSDoug Rabson# modification, are permitted provided that the following conditions 6abbcaa0aSDoug Rabson# are met: 7abbcaa0aSDoug Rabson# 1. Redistributions of source code must retain the above copyright 8abbcaa0aSDoug Rabson# notice, this list of conditions and the following disclaimer. 9abbcaa0aSDoug Rabson# 2. Redistributions in binary form must reproduce the above copyright 10abbcaa0aSDoug Rabson# notice, this list of conditions and the following disclaimer in the 11abbcaa0aSDoug Rabson# documentation and/or other materials provided with the distribution. 12abbcaa0aSDoug Rabson# 3. All advertising materials mentioning features or use of this software 13abbcaa0aSDoug Rabson# must display the following acknowledgement: 14abbcaa0aSDoug Rabson# This product includes software developed by Rajesh Vaidheeswarran 15abbcaa0aSDoug Rabson# 4. The name Rajesh Vaidheeswarran may not be used to endorse or promote 16abbcaa0aSDoug Rabson# products derived from this software without specific prior written 17abbcaa0aSDoug Rabson# permission. 18abbcaa0aSDoug Rabson# 19abbcaa0aSDoug Rabson# THIS SOFTWARE IS PROVIDED BY RAJESH VAIDHEESWARRAN ``AS IS'' AND ANY 20abbcaa0aSDoug Rabson# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21abbcaa0aSDoug Rabson# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22abbcaa0aSDoug Rabson# ARE DISCLAIMED. IN NO EVENT SHALL THE RAJESH VAIDHEESWARRAN BE LIABLE 23abbcaa0aSDoug Rabson# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24abbcaa0aSDoug Rabson# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25abbcaa0aSDoug Rabson# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26abbcaa0aSDoug Rabson# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27abbcaa0aSDoug Rabson# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28abbcaa0aSDoug Rabson# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29abbcaa0aSDoug Rabson# SUCH DAMAGE. 30abbcaa0aSDoug Rabson# 31abbcaa0aSDoug Rabson# Copyright (c) 1993 Terrence R. Lambert. 32abbcaa0aSDoug Rabson# All rights reserved. 33abbcaa0aSDoug Rabson# 34abbcaa0aSDoug Rabson# Redistribution and use in source and binary forms, with or without 35abbcaa0aSDoug Rabson# modification, are permitted provided that the following conditions 36abbcaa0aSDoug Rabson# are met: 37abbcaa0aSDoug Rabson# 1. Redistributions of source code must retain the above copyright 38abbcaa0aSDoug Rabson# notice, this list of conditions and the following disclaimer. 39abbcaa0aSDoug Rabson# 2. Redistributions in binary form must reproduce the above copyright 40abbcaa0aSDoug Rabson# notice, this list of conditions and the following disclaimer in the 41abbcaa0aSDoug Rabson# documentation and/or other materials provided with the distribution. 42abbcaa0aSDoug Rabson# 3. All advertising materials mentioning features or use of this software 43abbcaa0aSDoug Rabson# must display the following acknowledgement: 44abbcaa0aSDoug Rabson# This product includes software developed by Terrence R. Lambert. 45abbcaa0aSDoug Rabson# 4. The name Terrence R. Lambert may not be used to endorse or promote 46abbcaa0aSDoug Rabson# products derived from this software without specific prior written 47abbcaa0aSDoug Rabson# permission. 48abbcaa0aSDoug Rabson# 49abbcaa0aSDoug Rabson# THIS SOFTWARE IS PROVIDED BY TERRENCE R. LAMBERT ``AS IS'' AND ANY 50abbcaa0aSDoug Rabson# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 51abbcaa0aSDoug Rabson# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 52abbcaa0aSDoug Rabson# ARE DISCLAIMED. IN NO EVENT SHALL THE TERRENCE R. LAMBERT BE LIABLE 53abbcaa0aSDoug Rabson# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 54abbcaa0aSDoug Rabson# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 55abbcaa0aSDoug Rabson# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 56abbcaa0aSDoug Rabson# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 57abbcaa0aSDoug Rabson# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 58abbcaa0aSDoug Rabson# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 59abbcaa0aSDoug Rabson# SUCH DAMAGE. 60abbcaa0aSDoug Rabson# 617320fd3aSMaxim Sobolev# 62abbcaa0aSDoug Rabson 63abbcaa0aSDoug Rabson1.0 Overview 64abbcaa0aSDoug Rabson 65abbcaa0aSDoug Rabson This is the README file for the sample kld module 66abbcaa0aSDoug Rabson that mimics a character device driver. 67abbcaa0aSDoug Rabson 68abbcaa0aSDoug Rabson A kld module may be used to load any data or 69abbcaa0aSDoug Rabson program into the kernel that can be made available by 70abbcaa0aSDoug Rabson modifying a table, pointer, or other kernel data to inform 71abbcaa0aSDoug Rabson the kernel that the module should be used instead of the 72abbcaa0aSDoug Rabson previous code/data path. 73abbcaa0aSDoug Rabson 74abbcaa0aSDoug Rabson Generally, it is assumed that a loadable module is one of 75abbcaa0aSDoug Rabson a set of similar modules (such as a file system or console 76abbcaa0aSDoug Rabson terminal emulation), and that the reference is through a 77abbcaa0aSDoug Rabson table (such as vfssw[]), and that a "special" value is 78abbcaa0aSDoug Rabson assigned to the slots which are allowed to be replaced. 79abbcaa0aSDoug Rabson This is not enforced, so you may use the kld module 80abbcaa0aSDoug Rabson any way you see fit. 81abbcaa0aSDoug Rabson 82abbcaa0aSDoug Rabson As with the loadable system calls, it may be desirable to 83abbcaa0aSDoug Rabson allow the module loader to replace an *existing* entry to 84abbcaa0aSDoug Rabson try out changes to kernel code without rebuilding and 85abbcaa0aSDoug Rabson booting from the new kernel. 86abbcaa0aSDoug Rabson 877320fd3aSMaxim Sobolev The idea behind this example is to show some interaction 887320fd3aSMaxim Sobolev with the device driver. Therefore the flow of the code that 897320fd3aSMaxim Sobolev this driver is aimed at is as follows: 907320fd3aSMaxim Sobolev 917320fd3aSMaxim Sobolev open(2) -> ioctl(2) -> write(2) -> read(2) -> close(2). 927320fd3aSMaxim Sobolev 937320fd3aSMaxim Sobolev We will first open the device in the /dev/ directory; then 947320fd3aSMaxim Sobolev we will send an ioctl message to it using ioctl(2) call; 957320fd3aSMaxim Sobolev then write a small string via the write(2) call. This string 967320fd3aSMaxim Sobolev we write to the device will be stored in a static buffer, 977320fd3aSMaxim Sobolev and later will be accessible via the read(2) call. Finally, 987320fd3aSMaxim Sobolev we will close(2) our open()'d device so that we may no 997320fd3aSMaxim Sobolev longer make read or write calls on it. 100abbcaa0aSDoug Rabson 101abbcaa0aSDoug Rabson2.0 Directions 102abbcaa0aSDoug Rabson 103abbcaa0aSDoug Rabson To test the module, do the following: 104abbcaa0aSDoug Rabson 105abbcaa0aSDoug Rabson cd module 106abbcaa0aSDoug Rabson make load 107abbcaa0aSDoug Rabson 108abbcaa0aSDoug Rabson A load message (the copyright) will be printed on the console. 109abbcaa0aSDoug Rabson 110abbcaa0aSDoug Rabson cd ../test 111abbcaa0aSDoug Rabson make load 112abbcaa0aSDoug Rabson 113abbcaa0aSDoug Rabson The system call prints a message on the console when called. 114abbcaa0aSDoug Rabson This message will be printed when running "make load" in 115abbcaa0aSDoug Rabson the "test" subdirectory. 116abbcaa0aSDoug Rabson 117abbcaa0aSDoug Rabson 118abbcaa0aSDoug Rabson3.0 Recovering resources 119abbcaa0aSDoug Rabson 120abbcaa0aSDoug Rabson The module consumes memory when loaded; it can be freed up by 121abbcaa0aSDoug Rabson unloading it. To unload it, type the following from the directory 122abbcaa0aSDoug Rabson this file is in: 123abbcaa0aSDoug Rabson 124abbcaa0aSDoug Rabson cd module 125abbcaa0aSDoug Rabson make unload 126abbcaa0aSDoug Rabson 127abbcaa0aSDoug Rabson The miscellaneous module will be unloaded by name. 128abbcaa0aSDoug Rabson 129abbcaa0aSDoug Rabson 130abbcaa0aSDoug Rabson4.0 END OF DOCUMENT 131