KOBJ(9)

💅 KOBJ(9) — a kernel object system for FreeBSD

okay bestie, this is the Kernel Developer's Manual page for kobj, and it's giving object-oriented kernel realness. Come sit, we're gonna get you fluent in interfaces, classes, and objects without the boring-manpage voice. 💖

---

✨ NAME ✨

kobj — a kernel object system for FreeBSD

🦋 SYNOPSIS 🦋

include these headers first, no cap:

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

then the function lineup is exactly this:

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_init_static(kobj_t obj, kobj_class_t cls);

void
kobj_delete(kobj_t obj, struct malloc_type *mtype);

DEFINE_CLASS(name, kobj_method_t *methods, size_t size);

🌸 DESCRIPTION 🌸

The kernel object system is literally the FreeBSD kernel's implementation of an object-oriented programming system. It's built around three iconic concepts:

• interfaces — descriptions of sets of methods. Think: the vibe/spec of what methods exist. ✨
• classes — lists of functions implementing certain methods from those interfaces. Think: the actual code girlies doing the work. 💪
• objects — a class combined with a structure in memory. Think: main character energy in the wild. 🌟

Methods get called through a dynamic method dispatching algorithm that's designed to let new interfaces and classes be introduced into the system at runtime. The dispatch algorithm is designed to be both fast and robust, and it's only slightly more expensive than a direct function call — which is why kernel objects are suitable for performance-critical algorithms. slay for low overhead. 🔥

Kernel objects are a good fit for any algorithm that needs some kind of polymorphism (i.e., many different objects which can be treated in a uniform way). The common behaviour of those objects is described by a suitable interface, and each different type of object is implemented by a suitable class. it's giving one interface, many class eras. 💅

---

🍼 the simplest way to create one

The simplest way to create a kernel object is to call kobj_create() with a suitable class, malloc type, and flags — see 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 by zeroing the memory and installing a pointer to the class' method dispatch table. Objects created this way should be freed by calling kobj_delete(). match the create with the delete, bestie. 🧚

🫶 if you're managing memory yourself

Clients who'd like to manage the allocation of memory themselves should call kobj_init() or kobj_init_static() with a pointer to the memory for the object and the class which implements it. It's also possible to use kobj_init() and kobj_init_static() to change the class for an object. Do that with care: the classes must agree on the layout of the object. The device framework uses this feature to associate drivers with devices. careful, now — layout agreement is not optional. 👀

⚙️ compiling and freeing classes

The functions kobj_class_compile(), kobj_class_compile_static(), and kobj_class_free() are used to process a class description to make method dispatching efficient. A client should not normally need to call these, since a class will automatically be compiled the first time it is used. automatic, iconic, no manual step needed. ✨

If a class is to be used before malloc(9) and mutex(9) are initialised, then kobj_class_compile_static() should be called with the class and a pointer to a statically allocated kobj_ops structure before the class is used to initialise any objects. In that case, also kobj_init_static() should be used instead of kobj_init(). important early-boot caveat — this is the static-allocation route, not the regular route. 🚨

🧵 defining a class

To define a class, first define a simple array of kobj_method_t. Each method which the class implements should be entered into the table using the macro 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. two zeros, periodt. 💀

The macro DEFINE_CLASS() can then be used to initialise a kobj_class_t structure. The size argument to DEFINE_CLASS() specifies how much memory should be allocated for each object. so that's the size of your object vibe. 🎀

🕰️ 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. lowkey legacy lore, but make it kernel history. 📜

👑 AUTHORS 👑

This manual page was written by Doug Rabson. ngl, respect the author, bestie. 🫶

---

💖 signed off from the Kernel Developer's Manual · Debian edition · November 14, 2011 · KOBJ(9) 💖