Add manpage for kernel object system.

svn path=/head/; revision=59092

share/man/man9/Makefile

@@ -36,7 +36,7 @@ MAN9+=	device.9 device_add_child.9 device_delete_child.9 device_enable.9 \
 	bus_generic_print_child.9 bus_generic_read_ivar.9 \
 	bus_generic_shutdown.9 \
 	VOP_ACLCHECK.9 VOP_GETACL.9 VOP_GETEXTATTR.9 VOP_SETACL.9 \
-	VOP_SETEXTATTR.9 acl.9 extattr.9
+	VOP_SETEXTATTR.9 acl.9 extattr.9 kobj.9
 
 MLINKS+=MD5.9 MD5Init.9 MD5.9 MD5Transform.9
 MLINKS+=VOP_ATTRIB.9 VOP_GETATTR.9
@@ -105,4 +105,11 @@ MLINKS+=microtime.9 getnanotime.9
 MLINKS+=microuptime.9 getmicrouptime.9 microuptime.9 nanouptime.9
 MLINKS+=microuptime.9 getnanouptime.9
 
+MLINKS+=kobj.9 kobj_class_compile.9
+MLINKS+=kobj.9 kobj_class_free.9
+MLINKS+=kobj.9 kobj_create.9
+MLINKS+=kobj.9 kobj_init.9
+MLINKS+=kobj.9 kobj_delete.9
+MLINKS+=kobj.9 DEFINE_CLASS.9
+
 .include <bsd.prog.mk>

share/man/man9/kobj.9

@@ -0,0 +1,129 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 2000 Doug Rabson
+.\"
+.\" All rights reserved.
+.\"
+.\" This program is free software.
+.\"
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``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 DEVELOPERS 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$
+.\"
+.Dd April 4, 2000
+.Dt KOBJ 9
+.Os FreeBSD
+.Sh NAME
+.Nm kobj
+.Nd a kernel object system for FreeBSD
+.Sh SYNOPSIS
+.Fd #include <sys/param.h>
+.Fd #include <sys/kobj.h>
+.Ft void
+.Fn kobj_class_compile "kobj_class_t cls"
+.Ft void
+.Fn kobj_class_free "kobj_class_t cls"
+.Ft kobj_t
+.Fn kobj_create "kobj_class_t cls" "struct malloc_type *mtype" "int mflags"
+.Ft void
+.Fn kobj_init "kobj_t obj" "kobj_class_t cls"
+.Ft void
+.Fn kobj_delete "kobj_t obj" "struct malloc_type *mtype"
+.Fn DEFINE_CLASS "name" "methods" "size"
+.Sh DESCRIPTION
+.Pp
+The kernel object system implements an object-oriented programming
+system in the FreeBSD kernel.
+The system is based around the concepts of interfaces, which are
+descriptions of sets of methods, classes which are lists of functions
+implementing certain methods from those interfaces and objects
+which combine a class with a structure in memory.
+.Pp
+Methods are called using a dynamic method dispatching algorithm which
+is designed to allow new interfaces and classes to be introduced into
+the system at runtime.
+The method dispatch algorithm is designed to be both fast and robust
+and is only slightly more expensive than a direct function call,
+making kernel objects suitable for performance-critical algorithms.
+.Pp
+Suitable uses for kernel objects are any algorithms which need some
+kind of polymorphism (i.e. many different objects which can be treated 
+in a uniform way).
+The common behaviour of the objects is described by a suitable
+interface and each different type of object is implemented by a
+suitable class.
+.Pp
+The simplest way to create a kernel object is to call
+.Fn kobj_create
+with a suitable class, malloc type and flags (see
+.Xr malloc 9
+for a description of the malloc type and flags).
+This will allocate memory for the object based on the object size
+specified by the class and initialise it be zeroing the memory and
+installing a pointer to the class' method dispatch table.
+Objects created in this way should be freed by calling
+.Fn kobj_free .
+.Pp
+Clients which would like to manage the allocation of memory
+themselves should call
+.Fn kobj_init
+with a pointer to the memory for the object and the class which
+implements it.
+It is also possible to use
+.Fn kobj_init
+to change the class for an object.
+This should be done with care as the classes must agree on the layout
+of the object.
+The device framework uses this feature to associate drivers with
+devices.
+.Pp
+The functions
+.Fn kobj_class_compile
+and
+.Fn kobj_class_free
+are used to process a class description to make method despatching
+efficient.
+A client should not normally need to call these since a class
+will automatically be compiled the first time it is used.
+.Pp
+To define a class, first define a simple array of
+.Dv kobj_method_t .
+Each method which the class implements should be entered into the
+table using the macro
+.Fn KOBJMETHOD
+which takes the name of the method (including its interface) and a
+pointer to a function which implements it.
+The table should be terminated with two zeros.
+The macro
+.Fn DEFINE_CLASS
+can then be used to initialise a
+.Dv kobj_class_t
+structure.
+The size argument to
+.Fn DEFINE_CLASS
+specifies how much memory should be allocated for each object.
+.Sh HISTORY
+Some of the concepts for this interface appeared in the device
+framework used for the alpha port of FreeBSD 3.0 and more widely in
+FreeBSD 4.0.
+.Sh AUTHORS
+This man page was written by
+.An Doug Rabson .