Chapter 3. Kernel Objects

Kernel Objects, or Kobj provides an object-oriented C programming system for the kernel. As such the data being operated on carries the description of how to operate on it. This allows operations to be added and removed from an interface at run time and without breaking binary compatibility.

3.1. Terminology

Object: A set of data - data structure - data allocation.
Method: An operation - function.
Class: One or more methods.
Interface: A standard set of one or more methods.

3.2. Kobj Operation

Kobj works by generating descriptions of methods. Each description holds a unique id as well as a default function. The description’s address is used to uniquely identify the method within a class' method table.

A class is built by creating a method table associating one or more functions with method descriptions. Before use the class is compiled. The compilation allocates a cache and associates it with the class. A unique id is assigned to each method description within the method table of the class if not already done so by another referencing class compilation. For every method to be used a function is generated by script to qualify arguments and automatically reference the method description for a lookup. The generated function looks up the method by using the unique id associated with the method description as a hash into the cache associated with the object’s class. If the method is not cached the generated function proceeds to use the class' table to find the method. If the method is found then the associated function within the class is used; otherwise, the default function associated with the method description is used.

These indirections can be visualized as the following:

object->cache<->class

3.3. Using Kobj

3.3.1. Structures

struct kobj_method

3.3.2. Functions

void kobj_class_compile(kobj_class_t cls);
void kobj_class_compile_static(kobj_class_t cls, kobj_ops_t ops);
void kobj_class_free(kobj_class_t cls);
kobj_t kobj_create(kobj_class_t cls, struct malloc_type *mtype, int mflags);
void kobj_init(kobj_t obj, kobj_class_t cls);
void kobj_delete(kobj_t obj, struct malloc_type *mtype);

3.3.3. Macros

KOBJ_CLASS_FIELDS
KOBJ_FIELDS
DEFINE_CLASS(name, methods, size)
KOBJMETHOD(NAME, FUNC)

3.3.4. Headers

<sys/param.h>
<sys/kobj.h>

3.3.5. Creating an Interface Template

The first step in using Kobj is to create an Interface. Creating the interface involves creating a template that the script src/sys/kern/makeobjops.pl can use to generate the header and code for the method declarations and method lookup functions.

Within this template the following keywords are used: #include , INTERFACE , CODE , EPILOG , HEADER , METHOD , PROLOG , STATICMETHOD , and DEFAULT .

The #include statement and what follows it is copied verbatim to the head of the generated code file.

For example:

#include <sys/foo.h>

The INTERFACE keyword is used to define the interface name. This name is concatenated with each method name as [interface name]_[method name]. Its syntax is INTERFACE [interface name];.

For example:

INTERFACE foo;

The CODE keyword copies its arguments verbatim into the code file. Its syntax is CODE { [whatever] };

For example:

CODE {
	struct foo * foo_alloc_null(struct bar *)
	{
		return NULL;
	}
};

The HEADER keyword copies its arguments verbatim into the header file. Its syntax is HEADER { [whatever] };

For example:

HEADER {
        struct mumble;
        struct grumble;
};

The METHOD keyword describes a method. Its syntax is METHOD [return type] [method name] { [object [, arguments]] };

For example:

METHOD int bar {
	struct object *;
	struct foo *;
	struct bar;
};

The DEFAULT keyword may follow the METHOD keyword. It extends the METHOD key word to include the default function for method. The extended syntax is METHOD [return type] [method name] { [object; [other arguments]] }DEFAULT [default function];

For example:

METHOD int bar {
	struct object *;
	struct foo *;
	int bar;
} DEFAULT foo_hack;

The STATICMETHOD keyword is used like the METHOD keyword except the kobj data is not at the head of the object structure so casting to kobj_t would be incorrect. Instead STATICMETHOD relies on the Kobj data being referenced as 'ops'. This is also useful for calling methods directly out of a class’s method table.

The PROLOG and EPILOG keywords sets inserts code immediately before or directly after the METHOD they are attached to. This feature is used primarily for profiling situations where it’s difficult to obtain the information in another way.

Other complete examples:

src/sys/kern/bus_if.m
src/sys/kern/device_if.m

3.3.6. Creating a Class

The second step in using Kobj is to create a class. A class consists of a name, a table of methods, and the size of objects if Kobj’s object handling facilities are used. To create the class use the macro DEFINE_CLASS() . To create the method table create an array of kobj_method_t terminated by a NULL entry. Each non-NULL entry may be created using the macro KOBJMETHOD() .

For example:

DEFINE_CLASS(fooclass, foomethods, sizeof(struct foodata));

kobj_method_t foomethods[] = {
	KOBJMETHOD(bar_doo, foo_doo),
	KOBJMETHOD(bar_foo, foo_foo),
	{ NULL, NULL}
};

The class must be "compiled". Depending on the state of the system at the time that the class is to be initialized a statically allocated cache, "ops table" have to be used. This can be accomplished by declaring a struct kobj_ops and using kobj_class_compile_static(); otherwise, kobj_class_compile() should be used.

3.3.7. Creating an Object

The third step in using Kobj involves how to define the object. Kobj object creation routines assume that Kobj data is at the head of an object. If this in not appropriate you will have to allocate the object yourself and then use kobj_init() on the Kobj portion of it; otherwise, you may use kobj_create() to allocate and initialize the Kobj portion of the object automatically. kobj_init() may also be used to change the class that an object uses.

To integrate Kobj into the object you should use the macro KOBJ_FIELDS.

For example

struct foo_data {
	KOBJ_FIELDS;
	foo_foo;
	foo_bar;
};

3.3.8. Calling Methods

The last step in using Kobj is to simply use the generated functions to use the desired method within the object’s class. This is as simple as using the interface name and the method name with a few modifications. The interface name should be concatenated with the method name using a '_' between them, all in upper case.

For example, if the interface name was foo and the method was bar then the call would be:

[return value = ] FOO_BAR(object [, other parameters]);

3.3.9. Cleaning Up

When an object allocated through kobj_create() is no longer needed kobj_delete() may be called on it, and when a class is no longer being used kobj_class_free() may be called on it.

Last modified on : February 18, 2025 by Fernando Apesteguía

Chapter 3. Kernel Objects

Table of Contents

3.1. Terminology

3.2. Kobj Operation

3.3. Using Kobj

3.3.1. Structures

3.3.2. Functions

3.3.3. Macros

3.3.4. Headers

3.3.5. Creating an Interface Template

3.3.6. Creating a Class

3.3.7. Creating an Object

3.3.8. Calling Methods

3.3.9. Cleaning Up