# 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 <LL@li.org>\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 ""