share/man/man9/kobj.9

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