Date: Mon, 26 Apr 2021 16:21:59 GMT From: Warner Losh <imp@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: bcf75b25de - main - kobj: Use one sentence per line Message-ID: <202104261621.13QGLx6t064441@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/doc/commit/?id=bcf75b25de3c6f53d166b2c766304e58e9f04c50 commit bcf75b25de3c6f53d166b2c766304e58e9f04c50 Author: Warner Losh <imp@FreeBSD.org> AuthorDate: 2021-04-19 02:16:47 +0000 Commit: Warner Losh <imp@FreeBSD.org> CommitDate: 2021-04-26 16:20:16 +0000 kobj: Use one sentence per line In advance of updating this chapter, go through and make it one sentence per line. No content changes. Sponsored by: Netflix --- .../en/books/arch-handbook/kobj/_index.adoc | 57 +++++++++++++++++----- 1 file changed, 44 insertions(+), 13 deletions(-) diff --git a/documentation/content/en/books/arch-handbook/kobj/_index.adoc b/documentation/content/en/books/arch-handbook/kobj/_index.adoc index 01321c5c62..bd11946acd 100644 --- a/documentation/content/en/books/arch-handbook/kobj/_index.adoc +++ b/documentation/content/en/books/arch-handbook/kobj/_index.adoc @@ -29,7 +29,9 @@ include::shared/en/urls.adoc[] toc::[] -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. +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. [[kernel-objects-term]] == Terminology @@ -49,9 +51,18 @@ A standard set of one or more methods. [[kernel-objects-operation]] == 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. +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. +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: @@ -102,7 +113,8 @@ KOBJMETHOD(NAME, FUNC) === 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 [.filename]#src/sys/kern/makeobjops.pl# can use to generate the header and code for the method declarations and method lookup functions. +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. Within this template the following keywords are used: `#include`, `INTERFACE`, `CODE`, `METHOD`, `STATICMETHOD`, and `DEFAULT`. @@ -115,7 +127,9 @@ 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];. +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: @@ -124,7 +138,8 @@ For example: INTERFACE foo; .... -The `CODE` keyword copies its arguments verbatim into the code file. Its syntax is `CODE { [whatever] };` +The `CODE` keyword copies its arguments verbatim into the code file. +Its syntax is `CODE { [whatever] };` For example: @@ -138,7 +153,8 @@ CODE { }; .... -The `METHOD` keyword describes a method. Its syntax is `METHOD [return type] [method name] { [object [, arguments]] };` +The `METHOD` keyword describes a method. +Its syntax is `METHOD [return type] [method name] { [object [, arguments]] };` For example: @@ -151,7 +167,9 @@ METHOD int 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];` +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: @@ -164,7 +182,9 @@ METHOD 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 `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. Other complete examples: @@ -176,7 +196,11 @@ src/sys/kern/device_if.m === 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()`. +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: @@ -191,11 +215,16 @@ kobj_method_t foomethods[] = { }; .... -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. +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. === 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. +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. @@ -212,7 +241,9 @@ struct foo_data { === 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. +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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202104261621.13QGLx6t064441>