xref: /freebsd/share/man/man9/kobj.9 (revision 7fdf597e96a02165cfe22ff357b857d5fa15ed8a)
1.\" -*- nroff -*-
2.\"
3.\" Copyright (c) 2000 Doug Rabson
4.\"
5.\" All rights reserved.
6.\"
7.\" This program is free software.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28.\"
29.Dd November 14, 2011
30.Dt KOBJ 9
31.Os
32.Sh NAME
33.Nm kobj
34.Nd a kernel object system for FreeBSD
35.Sh SYNOPSIS
36.In sys/param.h
37.In sys/kobj.h
38.Ft void
39.Fn kobj_class_compile "kobj_class_t cls"
40.Ft void
41.Fn kobj_class_compile_static "kobj_class_t cls" "kobj_ops_t ops"
42.Ft void
43.Fn kobj_class_free "kobj_class_t cls"
44.Ft kobj_t
45.Fn kobj_create "kobj_class_t cls" "struct malloc_type *mtype" "int mflags"
46.Ft void
47.Fn kobj_init "kobj_t obj" "kobj_class_t cls"
48.Ft void
49.Fn kobj_init_static "kobj_t obj" "kobj_class_t cls"
50.Ft void
51.Fn kobj_delete "kobj_t obj" "struct malloc_type *mtype"
52.Fn DEFINE_CLASS name "kobj_method_t *methods" "size_t size"
53.Sh DESCRIPTION
54The kernel object system implements an object-oriented programming
55system in the
56.Fx
57kernel.
58The system is based around the concepts of interfaces, which are
59descriptions of sets of methods; classes, which are lists of functions
60implementing certain methods from those interfaces; and objects,
61which combine a class with a structure in memory.
62.Pp
63Methods are called using a dynamic method dispatching algorithm which
64is designed to allow new interfaces and classes to be introduced into
65the system at runtime.
66The method dispatch algorithm is designed to be both fast and robust
67and is only slightly more expensive than a direct function call,
68making kernel objects suitable for performance-critical algorithms.
69.Pp
70Suitable uses for kernel objects are any algorithms which need some
71kind of polymorphism (i.e., many different objects which can be treated
72in a uniform way).
73The common behaviour of the objects is described by a suitable
74interface and each different type of object is implemented by a
75suitable class.
76.Pp
77The simplest way to create a kernel object is to call
78.Fn kobj_create
79with a suitable class, malloc type and flags (see
80.Xr malloc 9
81for a description of the malloc type and flags).
82This will allocate memory for the object based on the object size
83specified by the class and initialise it by zeroing the memory and
84installing a pointer to the class' method dispatch table.
85Objects created in this way should be freed by calling
86.Fn kobj_delete .
87.Pp
88Clients which would like to manage the allocation of memory
89themselves should call
90.Fn kobj_init
91or
92.Fn kobj_init_static
93with a pointer to the memory for the object and the class which
94implements it.
95It is also possible to use
96.Fn kobj_init
97and
98.Fn kobj_init_static
99to change the class for an object.
100This should be done with care as the classes must agree on the layout
101of the object.
102The device framework uses this feature to associate drivers with
103devices.
104.Pp
105The functions
106.Fn kobj_class_compile ,
107.Fn kobj_class_compile_static
108and
109.Fn kobj_class_free
110are used to process a class description to make method dispatching
111efficient.
112A client should not normally need to call these since a class
113will automatically be compiled the first time it is used.
114If a class is to be used before
115.Xr malloc 9
116and
117.Xr mutex 9
118are initialised,
119then
120.Fn kobj_class_compile_static
121should be called with the class and a pointer to a statically
122allocated
123.Vt kobj_ops
124structure before the class is used to initialise any objects.
125In that case, also
126.Fn kobj_init_static
127should be used instead of
128.Fn kobj_init .
129.Pp
130To define a class, first define a simple array of
131.Vt kobj_method_t .
132Each method which the class implements should be entered into the
133table using the macro
134.Fn KOBJMETHOD
135which takes the name of the method (including its interface) and a
136pointer to a function which implements it.
137The table should be terminated with two zeros.
138The macro
139.Fn DEFINE_CLASS
140can then be used to initialise a
141.Vt kobj_class_t
142structure.
143The size argument to
144.Fn DEFINE_CLASS
145specifies how much memory should be allocated for each object.
146.Sh HISTORY
147Some of the concepts for this interface appeared in the device
148framework used for the alpha port of
149.Fx 3.0
150and more widely in
151.Fx 4.0 .
152.Sh AUTHORS
153This manual page was written by
154.An Doug Rabson .
155