share/examples/kld/cdev/README

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