# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2026-08-16 15:11-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: Title = #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:1 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:14 #, no-wrap msgid "Kernel Objects" msgstr "" #. type: Yaml Front Matter Hash Value: title #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:1 #, no-wrap msgid "Chapter 3. Kernel Objects" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:53 msgid "" "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." msgstr "" #. type: Title == #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:55 #, no-wrap msgid "Terminology" msgstr "" #. type: Labeled list #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:57 #, no-wrap msgid "Object" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:59 msgid "A set of data - data structure - data allocation." msgstr "" #. type: Labeled list #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:60 #, no-wrap msgid "Method" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:62 msgid "An operation - function." msgstr "" #. type: Labeled list #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:63 #, no-wrap msgid "Class" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:65 msgid "One or more methods." msgstr "" #. type: Labeled list #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:66 #, no-wrap msgid "Interface" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:68 msgid "A standard set of one or more methods." msgstr "" #. type: Title == #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:70 #, no-wrap msgid "Kobj Operation" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:75 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:84 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:86 msgid "These indirections can be visualized as the following:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:90 #, no-wrap msgid "object->cache<->class\n" msgstr "" #. type: Title == #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:93 #, no-wrap msgid "Using Kobj" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:95 #, no-wrap msgid "Structures" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:100 #, no-wrap msgid "struct kobj_method\n" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:102 #, no-wrap msgid "Functions" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:112 #, no-wrap msgid "" "void kobj_class_compile(kobj_class_t cls);\n" "void kobj_class_compile_static(kobj_class_t cls, kobj_ops_t ops);\n" "void kobj_class_free(kobj_class_t cls);\n" "kobj_t kobj_create(kobj_class_t cls, struct malloc_type *mtype, int mflags);\n" "void kobj_init(kobj_t obj, kobj_class_t cls);\n" "void kobj_delete(kobj_t obj, struct malloc_type *mtype);\n" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:114 #, no-wrap msgid "Macros" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:122 #, no-wrap msgid "" "KOBJ_CLASS_FIELDS\n" "KOBJ_FIELDS\n" "DEFINE_CLASS(name, methods, size)\n" "KOBJMETHOD(NAME, FUNC)\n" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:124 #, no-wrap msgid "Headers" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:130 #, no-wrap msgid "" "\n" "\n" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:132 #, no-wrap msgid "Creating an Interface Template" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:136 msgid "" "The first step in using Kobj is to create an Interface. Creating the " "interface involves creating a template that the script [.filename]#src/sys/" "kern/makeobjops.pl# can use to generate the header and code for the method " "declarations and method lookup functions." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:138 msgid "" "Within this template the following keywords are used: `#include`, " "`INTERFACE`, `CODE`, `EPILOG`, `HEADER`, `METHOD`, `PROLOG`, `STATICMETHOD`, " "and `DEFAULT`." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:140 msgid "" "The `#include` statement and what follows it is copied verbatim to the head " "of the generated code file." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:142 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:153 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:163 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:178 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:191 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:206 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:240 msgid "For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:146 #, no-wrap msgid "#include \n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:151 msgid "" "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];." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:157 #, no-wrap msgid "INTERFACE foo;\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:161 msgid "" "The `CODE` keyword copies its arguments verbatim into the code file. Its " "syntax is `CODE { [whatever] };`" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:172 #, no-wrap msgid "" "CODE {\n" "\tstruct foo * foo_alloc_null(struct bar *)\n" "\t{\n" "\t\treturn NULL;\n" "\t}\n" "};\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:176 msgid "" "The `HEADER` keyword copies its arguments verbatim into the header file. " "Its syntax is `HEADER { [whatever] };`" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:185 #, no-wrap msgid "" "HEADER {\n" " struct mumble;\n" " struct grumble;\n" "};\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:189 msgid "" "The `METHOD` keyword describes a method. Its syntax is `METHOD [return " "type] [method name] { [object [, arguments]] };`" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:199 #, no-wrap msgid "" "METHOD int bar {\n" "\tstruct object *;\n" "\tstruct foo *;\n" "\tstruct bar;\n" "};\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:204 msgid "" "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];`" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:214 #, no-wrap msgid "" "METHOD int bar {\n" "\tstruct object *;\n" "\tstruct foo *;\n" "\tint bar;\n" "} DEFAULT foo_hack;\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:219 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:222 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:224 msgid "Other complete examples:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:229 #, no-wrap msgid "" "src/sys/kern/bus_if.m\n" "src/sys/kern/device_if.m\n" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:231 #, no-wrap msgid "Creating a Class" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:238 msgid "" "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()`." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:244 #, no-wrap msgid "DEFINE_CLASS(fooclass, foomethods, sizeof(struct foodata));\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:250 #, no-wrap msgid "" "kobj_method_t foomethods[] = {\n" "\tKOBJMETHOD(bar_doo, foo_doo),\n" "\tKOBJMETHOD(bar_foo, foo_foo),\n" "\t{ NULL, NULL}\n" "};\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:255 msgid "" "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." msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:256 #, no-wrap msgid "Creating an Object" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:262 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:264 msgid "To integrate Kobj into the object you should use the macro KOBJ_FIELDS." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:266 msgid "For example" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:274 #, no-wrap msgid "" "struct foo_data {\n" "\tKOBJ_FIELDS;\n" "\tfoo_foo;\n" "\tfoo_bar;\n" "};\n" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:276 #, no-wrap msgid "Calling Methods" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:281 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:283 msgid "" "For example, if the interface name was foo and the method was bar then the " "call would be:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:287 #, no-wrap msgid "[return value = ] FOO_BAR(object [, other parameters]);\n" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:289 #, no-wrap msgid "Cleaning Up" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:291 msgid "" "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." msgstr ""