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.\" $FreeBSD$ 30.\" 31.Dd November 14, 2011 32.Dt KOBJ 9 33.Os 34.Sh NAME 35.Nm kobj 36.Nd a kernel object system for FreeBSD 37.Sh SYNOPSIS 38.In sys/param.h 39.In sys/kobj.h 40.Ft void 41.Fn kobj_class_compile "kobj_class_t cls" 42.Ft void 43.Fn kobj_class_compile_static "kobj_class_t cls" "kobj_ops_t ops" 44.Ft void 45.Fn kobj_class_free "kobj_class_t cls" 46.Ft kobj_t 47.Fn kobj_create "kobj_class_t cls" "struct malloc_type *mtype" "int mflags" 48.Ft void 49.Fn kobj_init "kobj_t obj" "kobj_class_t cls" 50.Ft void 51.Fn kobj_init_static "kobj_t obj" "kobj_class_t cls" 52.Ft void 53.Fn kobj_delete "kobj_t obj" "struct malloc_type *mtype" 54.Fn DEFINE_CLASS name "kobj_method_t *methods" "size_t size" 55.Sh DESCRIPTION 56The kernel object system implements an object-oriented programming 57system in the 58.Fx 59kernel. 60The system is based around the concepts of interfaces, which are 61descriptions of sets of methods; classes, which are lists of functions 62implementing certain methods from those interfaces; and objects, 63which combine a class with a structure in memory. 64.Pp 65Methods are called using a dynamic method dispatching algorithm which 66is designed to allow new interfaces and classes to be introduced into 67the system at runtime. 68The method dispatch algorithm is designed to be both fast and robust 69and is only slightly more expensive than a direct function call, 70making kernel objects suitable for performance-critical algorithms. 71.Pp 72Suitable uses for kernel objects are any algorithms which need some 73kind of polymorphism (i.e., many different objects which can be treated 74in a uniform way). 75The common behaviour of the objects is described by a suitable 76interface and each different type of object is implemented by a 77suitable class. 78.Pp 79The simplest way to create a kernel object is to call 80.Fn kobj_create 81with a suitable class, malloc type and flags (see 82.Xr malloc 9 83for a description of the malloc type and flags). 84This will allocate memory for the object based on the object size 85specified by the class and initialise it by zeroing the memory and 86installing a pointer to the class' method dispatch table. 87Objects created in this way should be freed by calling 88.Fn kobj_delete . 89.Pp 90Clients which would like to manage the allocation of memory 91themselves should call 92.Fn kobj_init 93or 94.Fn kobj_init_static 95with a pointer to the memory for the object and the class which 96implements it. 97It is also possible to use 98.Fn kobj_init 99and 100.Fn kobj_init_static 101to change the class for an object. 102This should be done with care as the classes must agree on the layout 103of the object. 104The device framework uses this feature to associate drivers with 105devices. 106.Pp 107The functions 108.Fn kobj_class_compile , 109.Fn kobj_class_compile_static 110and 111.Fn kobj_class_free 112are used to process a class description to make method dispatching 113efficient. 114A client should not normally need to call these since a class 115will automatically be compiled the first time it is used. 116If a class is to be used before 117.Xr malloc 9 118and 119.Xr mutex 9 120are initialised, 121then 122.Fn kobj_class_compile_static 123should be called with the class and a pointer to a statically 124allocated 125.Vt kobj_ops 126structure before the class is used to initialise any objects. 127In that case, also 128.Fn kobj_init_static 129should be used instead of 130.Fn kobj_init . 131.Pp 132To define a class, first define a simple array of 133.Vt kobj_method_t . 134Each method which the class implements should be entered into the 135table using the macro 136.Fn KOBJMETHOD 137which takes the name of the method (including its interface) and a 138pointer to a function which implements it. 139The table should be terminated with two zeros. 140The macro 141.Fn DEFINE_CLASS 142can then be used to initialise a 143.Vt kobj_class_t 144structure. 145The size argument to 146.Fn DEFINE_CLASS 147specifies how much memory should be allocated for each object. 148.Sh HISTORY 149Some of the concepts for this interface appeared in the device 150framework used for the alpha port of 151.Fx 3.0 152and more widely in 153.Fx 4.0 . 154.Sh AUTHORS 155This manual page was written by 156.An Doug Rabson . 157