diff --git a/en_US.ISO8859-1/books/arch-handbook/book.sgml b/en_US.ISO8859-1/books/arch-handbook/book.sgml index f906b3638b..c2d91f80a6 100644 --- a/en_US.ISO8859-1/books/arch-handbook/book.sgml +++ b/en_US.ISO8859-1/books/arch-handbook/book.sgml @@ -1,309 +1,310 @@ %bookinfo; %man; %chapters; %authors %mailing-lists; ]> FreeBSD Developers' Handbook The FreeBSD Documentation Project August 2000 2000 2001 The FreeBSD Documentation Project &bookinfo.legalnotice; Welcome to the Developers' Handbook. This manual is a work in progress and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the &a.doc;. The latest version of this document is always available from the FreeBSD World Wide Web server. It may also be downloaded in a variety of formats and compression options from the FreeBSD FTP server or one of the numerous mirror sites. Basics &chap.introduction; &chap.tools; &chap.secure; Interprocess Communication * Signals Signals, pipes, semaphores, message queues, shared memory, ports, sockets, doors &chap.sockets; &chap.ipv6; Kernel * History of the Unix Kernel Some history of the Unix/BSD kernel, system calls, how do processes work, blocking, scheduling, threads (kernel), context switching, signals, interrupts, modules, etc. &chap.locking; + &chap.kobj; &chap.vm; &chap.dma; &chap.kerneldebug; * UFS UFS, FFS, Ext2FS, JFS, inodes, buffer cache, labeling, locking, metadata, soft-updates, LFS, portalfs, procfs, vnodes, memory sharing, memory objects, TLBs, caching * AFS AFS, NFS, SANs etc] * Syscons Syscons, tty, PCVT, serial console, screen savers, etc * Compatibility Layers * Linux Linux, SVR4, etc Device Drivers &chap.driverbasics; &chap.isa; &chap.pci; &chap.scsi; &chap.usb; * NewBus This chapter will talk about the FreeBSD NewBus architecture. * Sound subsystem OSS, waveforms, etc Architectures &chap.x86; * Alpha Talk about the architectural specifics of FreeBSD/alpha. Explanation of allignment errors, how to fix, how to ignore. Example assembly language code for FreeBSD/alpha. * IA-64 Talk about the architectural specifics of FreeBSD/ia64. Appendices Dave A Patterson John L Hennessy 1998Morgan Kaufmann Publishers, Inc. 1-55860-428-6 Morgan Kaufmann Publishers, Inc. Computer Organization and Design The Hardware / Software Interface 1-2 W. Richard Stevens 1993Addison Wesley Longman, Inc. 0-201-56317-7 Addison Wesley Longman, Inc. Advanced Programming in the Unix Environment 1-2 Marshall Kirk McKusick Keith Bostic Michael J Karels John S Quarterman 1996Addison-Wesley Publishing Company, Inc. 0-201-54979-4 Addison-Wesley Publishing Company, Inc. The Design and Implementation of the 4.4 BSD Operating System 1-2 Aleph One Phrack 49; "Smashing the Stack for Fun and Profit" Chrispin Cowan Calton Pu Dave Maier StackGuard; Automatic Adaptive Detection and Prevention of Buffer-Overflow Attacks Todd Miller Theo de Raadt strlcpy and strlcat -- consistent, safe string copy and concatenation. &chap.index; diff --git a/en_US.ISO8859-1/books/arch-handbook/chapters.ent b/en_US.ISO8859-1/books/arch-handbook/chapters.ent index 186e943a7f..2430788825 100644 --- a/en_US.ISO8859-1/books/arch-handbook/chapters.ent +++ b/en_US.ISO8859-1/books/arch-handbook/chapters.ent @@ -1,63 +1,64 @@ + diff --git a/en_US.ISO8859-1/books/arch-handbook/kobj/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/kobj/chapter.sgml new file mode 100644 index 0000000000..a9ea688b9a --- /dev/null +++ b/en_US.ISO8859-1/books/arch-handbook/kobj/chapter.sgml @@ -0,0 +1,298 @@ + + + + Kernel Objects + + 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. + + + Terminology + + + + Object + A set of data - data structure - data + allocation. + + + + Method + + An operation - function. + + + + Class + + One or more methods. + + + + Interface + + A standard set of one or more methods. + + + + + + + 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. + + 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: + + object->cache<->class + + + + + Using Kobj + + + Structures + + struct kobj_method + + + + Functions + + 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_delete(kobj_t obj, struct malloc_type *mtype); + + + + Macros + + KOBJ_CLASS_FIELDS +KOBJ_FIELDS +DEFINE_CLASS(name, methods, size) +KOBJMETHOD(NAME, FUNC) + + + + Headers + + <sys/param.h> +<sys/kobj.h> + + + + 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 + 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. + + The #include statement and what follows + it is copied verbatim to the head of the generated code + file. + + 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]. It's syntax is + INTERFACE [interface name];. + + For example: + + INTERFACE foo; + + The CODE keyword copies its arguments + verbatim into the code file. It's syntax is + CODE { [whatever] }; + + For example: + + CODE { + struct foo * foo_alloc_null(struct bar *) + { + return NULL; +} +}; + + The METHOD keyword describes a method. It's syntax is + METHOD [return type] [method name] { [object [, + arguments]] }; + + For example: + + METHOD int bar { + struct object *; + struct foo *; + struct 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]; + + For example: + + METHOD int bar { + struct object *; + struct foo *; + int bar; +} DEFAULT foo_hack; + + The STATICMETHOD keyword is used like + the METHOD keyword except the kobj data isn't + 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: + + src/sys/kern/bus_if.m +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(). + + For example: + + DEFINE_CLASS(fooclass, foomethods, sizeof(struct foodata)); + +kobj_method_t foomethods[] = { + KOBJMETHOD(bar_doo, foo_doo), + KOBJMETHOD(bar_foo, foo_foo), + { NULL, NULL} +}; + + 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. + + To integrate Kobj into the object you should use the macro + KOBJ_FIELDS. + + For example + + struct foo_data { + KOBJ_FIELDS; + foo_foo; + foo_bar; +}; + + + + 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. + + For example, if the interface name was foo and the method + was bar then the call would be: + + [return value = ] FOO_BAR(object [, other parameters]); + + + + + Cleaning Up + + 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. + + + + + diff --git a/en_US.ISO8859-1/books/developers-handbook/book.sgml b/en_US.ISO8859-1/books/developers-handbook/book.sgml index f906b3638b..c2d91f80a6 100644 --- a/en_US.ISO8859-1/books/developers-handbook/book.sgml +++ b/en_US.ISO8859-1/books/developers-handbook/book.sgml @@ -1,309 +1,310 @@ %bookinfo; %man; %chapters; %authors %mailing-lists; ]> FreeBSD Developers' Handbook The FreeBSD Documentation Project August 2000 2000 2001 The FreeBSD Documentation Project &bookinfo.legalnotice; Welcome to the Developers' Handbook. This manual is a work in progress and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the &a.doc;. The latest version of this document is always available from the FreeBSD World Wide Web server. It may also be downloaded in a variety of formats and compression options from the FreeBSD FTP server or one of the numerous mirror sites. Basics &chap.introduction; &chap.tools; &chap.secure; Interprocess Communication * Signals Signals, pipes, semaphores, message queues, shared memory, ports, sockets, doors &chap.sockets; &chap.ipv6; Kernel * History of the Unix Kernel Some history of the Unix/BSD kernel, system calls, how do processes work, blocking, scheduling, threads (kernel), context switching, signals, interrupts, modules, etc. &chap.locking; + &chap.kobj; &chap.vm; &chap.dma; &chap.kerneldebug; * UFS UFS, FFS, Ext2FS, JFS, inodes, buffer cache, labeling, locking, metadata, soft-updates, LFS, portalfs, procfs, vnodes, memory sharing, memory objects, TLBs, caching * AFS AFS, NFS, SANs etc] * Syscons Syscons, tty, PCVT, serial console, screen savers, etc * Compatibility Layers * Linux Linux, SVR4, etc Device Drivers &chap.driverbasics; &chap.isa; &chap.pci; &chap.scsi; &chap.usb; * NewBus This chapter will talk about the FreeBSD NewBus architecture. * Sound subsystem OSS, waveforms, etc Architectures &chap.x86; * Alpha Talk about the architectural specifics of FreeBSD/alpha. Explanation of allignment errors, how to fix, how to ignore. Example assembly language code for FreeBSD/alpha. * IA-64 Talk about the architectural specifics of FreeBSD/ia64. Appendices Dave A Patterson John L Hennessy 1998Morgan Kaufmann Publishers, Inc. 1-55860-428-6 Morgan Kaufmann Publishers, Inc. Computer Organization and Design The Hardware / Software Interface 1-2 W. Richard Stevens 1993Addison Wesley Longman, Inc. 0-201-56317-7 Addison Wesley Longman, Inc. Advanced Programming in the Unix Environment 1-2 Marshall Kirk McKusick Keith Bostic Michael J Karels John S Quarterman 1996Addison-Wesley Publishing Company, Inc. 0-201-54979-4 Addison-Wesley Publishing Company, Inc. The Design and Implementation of the 4.4 BSD Operating System 1-2 Aleph One Phrack 49; "Smashing the Stack for Fun and Profit" Chrispin Cowan Calton Pu Dave Maier StackGuard; Automatic Adaptive Detection and Prevention of Buffer-Overflow Attacks Todd Miller Theo de Raadt strlcpy and strlcat -- consistent, safe string copy and concatenation. &chap.index; diff --git a/en_US.ISO8859-1/books/developers-handbook/chapters.ent b/en_US.ISO8859-1/books/developers-handbook/chapters.ent index 186e943a7f..2430788825 100644 --- a/en_US.ISO8859-1/books/developers-handbook/chapters.ent +++ b/en_US.ISO8859-1/books/developers-handbook/chapters.ent @@ -1,63 +1,64 @@ + diff --git a/en_US.ISO8859-1/books/developers-handbook/kobj/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/kobj/chapter.sgml new file mode 100644 index 0000000000..a9ea688b9a --- /dev/null +++ b/en_US.ISO8859-1/books/developers-handbook/kobj/chapter.sgml @@ -0,0 +1,298 @@ + + + + Kernel Objects + + 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. + + + Terminology + + + + Object + A set of data - data structure - data + allocation. + + + + Method + + An operation - function. + + + + Class + + One or more methods. + + + + Interface + + A standard set of one or more methods. + + + + + + + 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. + + 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: + + object->cache<->class + + + + + Using Kobj + + + Structures + + struct kobj_method + + + + Functions + + 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_delete(kobj_t obj, struct malloc_type *mtype); + + + + Macros + + KOBJ_CLASS_FIELDS +KOBJ_FIELDS +DEFINE_CLASS(name, methods, size) +KOBJMETHOD(NAME, FUNC) + + + + Headers + + <sys/param.h> +<sys/kobj.h> + + + + 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 + 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. + + The #include statement and what follows + it is copied verbatim to the head of the generated code + file. + + 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]. It's syntax is + INTERFACE [interface name];. + + For example: + + INTERFACE foo; + + The CODE keyword copies its arguments + verbatim into the code file. It's syntax is + CODE { [whatever] }; + + For example: + + CODE { + struct foo * foo_alloc_null(struct bar *) + { + return NULL; +} +}; + + The METHOD keyword describes a method. It's syntax is + METHOD [return type] [method name] { [object [, + arguments]] }; + + For example: + + METHOD int bar { + struct object *; + struct foo *; + struct 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]; + + For example: + + METHOD int bar { + struct object *; + struct foo *; + int bar; +} DEFAULT foo_hack; + + The STATICMETHOD keyword is used like + the METHOD keyword except the kobj data isn't + 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: + + src/sys/kern/bus_if.m +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(). + + For example: + + DEFINE_CLASS(fooclass, foomethods, sizeof(struct foodata)); + +kobj_method_t foomethods[] = { + KOBJMETHOD(bar_doo, foo_doo), + KOBJMETHOD(bar_foo, foo_foo), + { NULL, NULL} +}; + + 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. + + To integrate Kobj into the object you should use the macro + KOBJ_FIELDS. + + For example + + struct foo_data { + KOBJ_FIELDS; + foo_foo; + foo_bar; +}; + + + + 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. + + For example, if the interface name was foo and the method + was bar then the call would be: + + [return value = ] FOO_BAR(object [, other parameters]); + + + + + Cleaning Up + + 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. + + + + +