Path: blob/main/documentation/content/en/books/arch-handbook/kobj/_index.po
18098 views
# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2025-05-01 19:56-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[email protected]>\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: 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:54 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:56 #, no-wrap msgid "Terminology" msgstr "" #. type: Labeled list #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:58 #, no-wrap msgid "Object" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:60 msgid "A set of data - data structure - data allocation." msgstr "" #. type: Labeled list #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:61 #, no-wrap msgid "Method" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:63 msgid "An operation - function." msgstr "" #. type: Labeled list #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:64 #, no-wrap msgid "Class" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:66 msgid "One or more methods." msgstr "" #. type: Labeled list #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:67 #, no-wrap msgid "Interface" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:69 msgid "A standard set of one or more methods." msgstr "" #. type: Title == #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:71 #, no-wrap msgid "Kobj Operation" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:76 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:85 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:87 msgid "These indirections can be visualized as the following:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:91 #, no-wrap msgid "object->cache<->class\n" msgstr "" #. type: Title == #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:94 #, no-wrap msgid "Using Kobj" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:96 #, no-wrap msgid "Structures" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:101 #, no-wrap msgid "struct kobj_method\n" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:103 #, no-wrap msgid "Functions" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:113 #, 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:115 #, no-wrap msgid "Macros" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:123 #, 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:125 #, no-wrap msgid "Headers" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:131 #, no-wrap msgid "" "<sys/param.h>\n" "<sys/kobj.h>\n" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:133 #, no-wrap msgid "Creating an Interface Template" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:137 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:139 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:141 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:143 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:154 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:164 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:179 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:192 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:207 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:241 msgid "For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:147 #, no-wrap msgid "#include <sys/foo.h>\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:152 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:158 #, no-wrap msgid "INTERFACE foo;\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:162 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:173 #, 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:177 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:186 #, 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:190 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:200 #, 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:205 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:215 #, 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:220 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:223 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:225 msgid "Other complete examples:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:230 #, 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:232 #, no-wrap msgid "Creating a Class" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:239 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:245 #, 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:251 #, 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:256 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:257 #, no-wrap msgid "Creating an Object" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:263 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:265 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:267 msgid "For example" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:275 #, 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:277 #, no-wrap msgid "Calling Methods" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:282 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:284 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:288 #, no-wrap msgid "[return value = ] FOO_BAR(object [, other parameters]);\n" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:290 #, no-wrap msgid "Cleaning Up" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/kobj/_index.adoc:292 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 ""