freebsd-dev/share/examples/kld/cdev/README

# Copyright (c) 1998 Rajesh Vaidheeswarran
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
# 1. Redistributions of source code must retain the above copyright
#    notice, this list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the above copyright
#    notice, this list of conditions and the following disclaimer in the
#    documentation and/or other materials provided with the distribution.
# 3. All advertising materials mentioning features or use of this software
#    must display the following acknowledgement:
#      This product includes software developed by Rajesh Vaidheeswarran
# 4. The name Rajesh Vaidheeswarran may not be used to endorse or promote
#    products derived from this software without specific prior written
#    permission.
#
# THIS SOFTWARE IS PROVIDED BY RAJESH VAIDHEESWARRAN ``AS IS'' AND ANY
# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED.  IN NO EVENT SHALL THE RAJESH VAIDHEESWARRAN BE LIABLE
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
# SUCH DAMAGE.
#
# Copyright (c) 1993 Terrence R. Lambert.
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
# 1. Redistributions of source code must retain the above copyright
#    notice, this list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the above copyright
#    notice, this list of conditions and the following disclaimer in the
#    documentation and/or other materials provided with the distribution.
# 3. All advertising materials mentioning features or use of this software
#    must display the following acknowledgement:
#      This product includes software developed by Terrence R. Lambert.
# 4. The name Terrence R. Lambert may not be used to endorse or promote
#    products derived from this software without specific prior written
#    permission.
#
# THIS SOFTWARE IS PROVIDED BY TERRENCE R. LAMBERT ``AS IS'' AND ANY
# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED.  IN NO EVENT SHALL THE TERRENCE R. LAMBERT BE LIABLE
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
# SUCH DAMAGE.
#
# $FreeBSD$
#

1.0	Overview

	This is the README file for the sample kld module
	that mimics a character device driver.

	A kld module may be used to load any data or
	program into the kernel that can be made available by
	modifying a table, pointer, or other kernel data to inform
	the kernel that the module should be used instead of the
	previous code/data path.

	Generally, it is assumed that a loadable module is one of
	a set of similar modules (such as a file system or console
	terminal emulation), and that the reference is through a
	table (such as vfssw[]), and that a "special" value is
	assigned to the slots which are allowed to be replaced.
	This is not enforced, so you may use the kld module 
	any way you see fit.

	As with the loadable system calls, it may be desirable to
	allow the module loader to replace an *existing* entry to
	try out changes to kernel code without rebuilding and
	booting from the new kernel.

	The idea behind this example is to show some interaction
	with the device driver. Therefore the flow of the code that
	this driver is aimed at is as follows:

	    open(2) -> ioctl(2) -> write(2) -> read(2) -> close(2).

	We will first open the device in the /dev/ directory; then
	we will send an ioctl message to it using ioctl(2) call;
	then write a small string via the write(2) call. This string
	we write to the device will be stored in a static buffer,
	and later will be accessible via the read(2) call. Finally,
	we will close(2) our open()'d device so that we may no
	longer make read or write calls on it.

2.0	Directions

	To test the module, do the following:

		cd module
		make load

	A load message (the copyright) will be printed on the console.

		cd ../test
		make load

	The system call prints a message on the console when called.
	This message will be printed when running "make load" in
	the "test" subdirectory.


3.0	Recovering resources

	The module consumes memory when loaded; it can be freed up by
	unloading it.  To unload it, type the following from the directory
	this file is in:

		cd module
		make unload

	The miscellaneous module will be unloaded by name.


4.0	END OF DOCUMENT