xref: /freebsd/share/examples/kld/cdev/README (revision d0b2dbfa)
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#
62
631.0	Overview
64
65	This is the README file for the sample kld module
66	that mimics a character device driver.
67
68	A kld module may be used to load any data or
69	program into the kernel that can be made available by
70	modifying a table, pointer, or other kernel data to inform
71	the kernel that the module should be used instead of the
72	previous code/data path.
73
74	Generally, it is assumed that a loadable module is one of
75	a set of similar modules (such as a file system or console
76	terminal emulation), and that the reference is through a
77	table (such as vfssw[]), and that a "special" value is
78	assigned to the slots which are allowed to be replaced.
79	This is not enforced, so you may use the kld module
80	any way you see fit.
81
82	As with the loadable system calls, it may be desirable to
83	allow the module loader to replace an *existing* entry to
84	try out changes to kernel code without rebuilding and
85	booting from the new kernel.
86
87	The idea behind this example is to show some interaction
88	with the device driver. Therefore the flow of the code that
89	this driver is aimed at is as follows:
90
91	    open(2) -> ioctl(2) -> write(2) -> read(2) -> close(2).
92
93	We will first open the device in the /dev/ directory; then
94	we will send an ioctl message to it using ioctl(2) call;
95	then write a small string via the write(2) call. This string
96	we write to the device will be stored in a static buffer,
97	and later will be accessible via the read(2) call. Finally,
98	we will close(2) our open()'d device so that we may no
99	longer make read or write calls on it.
100
1012.0	Directions
102
103	To test the module, do the following:
104
105		cd module
106		make load
107
108	A load message (the copyright) will be printed on the console.
109
110		cd ../test
111		make load
112
113	The system call prints a message on the console when called.
114	This message will be printed when running "make load" in
115	the "test" subdirectory.
116
117
1183.0	Recovering resources
119
120	The module consumes memory when loaded; it can be freed up by
121	unloading it.  To unload it, type the following from the directory
122	this file is in:
123
124		cd module
125		make unload
126
127	The miscellaneous module will be unloaded by name.
128
129
1304.0	END OF DOCUMENT
131