diff options
Diffstat (limited to 'documentation/content/en/books/arch-handbook')
44 files changed, 25619 insertions, 1160 deletions
diff --git a/documentation/content/en/books/arch-handbook/_index.adoc b/documentation/content/en/books/arch-handbook/_index.adoc index bb01f09331..7124ef877e 100644 --- a/documentation/content/en/books/arch-handbook/_index.adoc +++ b/documentation/content/en/books/arch-handbook/_index.adoc @@ -2,7 +2,7 @@ title: FreeBSD Architecture Handbook authors: - author: The FreeBSD Documentation Project -copyright: Copyright © 2000-2006, 2012-2021 The FreeBSD Documentation Project +copyright: 2000-2006, 2012-2023 The FreeBSD Documentation Project description: For FreeBSD system developers. This book covers the architectural details of many important FreeBSD kernel subsystems trademarks: ["freebsd", "apple", "microsoft", "unix", "general"] tags: ["Arch Handbook", "FreeBSD"] @@ -10,7 +10,8 @@ next: books/arch-handbook/parti add_single_page_link: true showBookMenu: true weight: 0 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/" bookOrder: 50 --- diff --git a/documentation/content/en/books/arch-handbook/_index.po b/documentation/content/en/books/arch-handbook/_index.po new file mode 100644 index 0000000000..df557d6f7d --- /dev/null +++ b/documentation/content/en/books/arch-handbook/_index.po @@ -0,0 +1,59 @@ +# 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: YAML Front Matter: description +#: documentation/content/en/books/arch-handbook/_index.adoc:1 +#, no-wrap +msgid "For FreeBSD system developers. This book covers the architectural details of many important FreeBSD kernel subsystems" +msgstr "" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/_index.adoc:18 +#, no-wrap +msgid "FreeBSD Architecture Handbook" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/_index.adoc:51 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/_index.adoc:53 +msgid "" +"Welcome to the FreeBSD Architecture 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 {freebsd-doc}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/_index.adoc:55 +msgid "" +"The latest version of this document is always available from the " +"link:https://www.FreeBSD.org/[FreeBSD World Wide Web server]. It may also be " +"downloaded in a variety of formats and compression options from the https://" +"download.freebsd.org/doc/[FreeBSD download server] or one of the numerous " +"extref:{handbook}[mirror sites, mirrors]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/_index.adoc:56 +msgid "'''" +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/bibliography/_index.adoc b/documentation/content/en/books/arch-handbook/bibliography/_index.adoc index d49d1d7aed..c89d76022c 100644 --- a/documentation/content/en/books/arch-handbook/bibliography/_index.adoc +++ b/documentation/content/en/books/arch-handbook/bibliography/_index.adoc @@ -5,7 +5,8 @@ description: Bibliography of the FreeBSD Architecture Handbook tags: ["bibliography", "Arch Handbook", "FreeBSD"] showBookMenu: true weight: 20 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/bibliography/" --- [appendix] diff --git a/documentation/content/en/books/arch-handbook/bibliography/_index.po b/documentation/content/en/books/arch-handbook/bibliography/_index.po new file mode 100644 index 0000000000..45dc1c150e --- /dev/null +++ b/documentation/content/en/books/arch-handbook/bibliography/_index.po @@ -0,0 +1,39 @@ +# 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: YAML Front Matter: description +#: documentation/content/en/books/arch-handbook/bibliography/_index.adoc:1 +#, no-wrap +msgid "Bibliography of the FreeBSD Architecture Handbook" +msgstr "" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/bibliography/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/bibliography/_index.adoc:14 +#, no-wrap +msgid "Bibliography" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/bibliography/_index.adoc:51 +msgid "" +"[1] _Marshall Kirk McKusick, Keith Bostic, Michael J Karels, and John S " +"Quarterman._ Copyright © 1996 Addison-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." +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/book.adoc b/documentation/content/en/books/arch-handbook/book.adoc index 15b9bdede4..3273926895 100644 --- a/documentation/content/en/books/arch-handbook/book.adoc +++ b/documentation/content/en/books/arch-handbook/book.adoc @@ -2,7 +2,7 @@ title: FreeBSD Architecture Handbook authors: - author: The FreeBSD Documentation Project -copyright: Copyright © 2000-2006, 2012-2021 The FreeBSD Documentation Project +copyright: 2000-2006, 2012-2023 The FreeBSD Documentation Project description: For FreeBSD system developers. This book covers the architectural details of many important FreeBSD kernel subsystems trademarks: ["freebsd", "apple", "microsoft", "unix", "general"] tags: ["Arch Handbook", "FreeBSD"] diff --git a/documentation/content/en/books/arch-handbook/book.po b/documentation/content/en/books/arch-handbook/book.po new file mode 100644 index 0000000000..cb1347a865 --- /dev/null +++ b/documentation/content/en/books/arch-handbook/book.po @@ -0,0 +1,59 @@ +# 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: 2022-07-07 23:22-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: YAML Front Matter: description +#: documentation/content/en/books/arch-handbook/book.adoc:1 +#, no-wrap +msgid "For FreeBSD system developers. This book covers the architectural details of many important FreeBSD kernel subsystems" +msgstr "" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/book.adoc:1 +#: documentation/content/en/books/arch-handbook/book.adoc:12 +#, no-wrap +msgid "FreeBSD Architecture Handbook" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/book.adoc:49 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/book.adoc:51 +msgid "" +"Welcome to the FreeBSD Architecture 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 {freebsd-doc}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/book.adoc:53 +msgid "" +"The latest version of this document is always available from the link:" +"https://www.FreeBSD.org/[FreeBSD World Wide Web server]. It may also be " +"downloaded in a variety of formats and compression options from the https://" +"download.freebsd.org/doc/[FreeBSD download server] or one of the numerous " +"extref:{handbook}[mirror sites, mirrors]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/book.adoc:55 +msgid "'''" +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/boot/_index.adoc b/documentation/content/en/books/arch-handbook/boot/_index.adoc index cca516e445..9065a9a183 100644 --- a/documentation/content/en/books/arch-handbook/boot/_index.adoc +++ b/documentation/content/en/books/arch-handbook/boot/_index.adoc @@ -6,7 +6,8 @@ description: Bootstrapping and Kernel Initialization tags: ["boot", "BIOS", "kernel", "MBR", "FreeBSD"] showBookMenu: true weight: 2 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/boot/" --- [[boot]] @@ -189,7 +190,7 @@ The task of [.filename]#boot0# is quite simple: scan the partition table and let The Partition Table is a special, standard data structure embedded in the MBR (hence embedded in [.filename]#boot0#) describing the four standard PC "partitions". [.filename]#boot0# resides in the filesystem as [.filename]#/boot/boot0#. It is a small 512-byte file, and it is exactly what FreeBSD's installation procedure wrote to the hard disk's MBR if you chose the "bootmanager" option at installation time. -Indeed, [.filename]#boot0#_is_ the MBR. +Indeed, [.filename]#boot0# _is_ the MBR. As mentioned previously, we're calling the BIOS `INT 0x19` to load the MBR ([.filename]#boot0#) into memory at address `0x7c00`. The source file for [.filename]#boot0# can be found in [.filename]#stand/i386/boot0/boot0.S# - which is an awesome piece of code written by Robert Nordier. @@ -265,7 +266,7 @@ The next block is responsible for the relocation and subsequent jump to the relo [.programlisting] .... - movw %sp,%si # Source + movw %sp,%si # Source movw $start,%di # Destination movw $0x100,%cx # Word count rep # Relocate @@ -283,7 +284,8 @@ As [.filename]#boot0# is loaded by the BIOS to address `0x7C00`, it copies itsel The source address, `0x7c00`, is copied to register `%si`. The destination address, `0x600`, to register `%di`. The number of words to copy, `256` (the program's size = 512 bytes), is copied to register `%cx`. -Next, the `rep` instruction repeats the instruction that follows, that is, `movsw`, the number of times dictated by the `%cx` register.The `movsw` instruction copies the word pointed to by `%si` to the address pointed to by `%di`. +Next, the `rep` instruction repeats the instruction that follows, that is, `movsw`, the number of times dictated by the `%cx` register. +The `movsw` instruction copies the word pointed to by `%si` to the address pointed to by `%di`. This is repeated another 255 times. On each repetition, both the source and destination registers, `%si` and `%di`, are incremented by one. Thus, upon completion of the 256-word (512-byte) copy, `%di` has the value `0x600`+`512`= `0x800`, and `%si` has the value `0x7c00`+`512`= `0x7e00`; we have thus completed the code _relocation_. @@ -296,7 +298,8 @@ Now, `stosw` is executed 8 times. This instruction copies a `0` value to the address pointed to by the destination register (`%di`, which is `0x800`), and increments it. This is repeated another 7 times, so `%di` ends up with value `0x810`. Effectively, this clears the address range `0x800`-`0x80f`. -This range is used as a (fake) partition table for writing the MBR back to disk.Finally, the sector field for the CHS addressing of this fake partition is given the value 1 and a jump is made to the main function from the relocated code. +This range is used as a (fake) partition table for writing the MBR back to disk. +Finally, the sector field for the CHS addressing of this fake partition is given the value 1 and a jump is made to the main function from the relocated code. Note that until this jump to the relocated code, any reference to an absolute address was avoided. The following code block tests whether the drive number provided by the BIOS should be used, or the one stored in [.filename]#boot0#. @@ -1345,7 +1348,7 @@ sys/i386/i386/locore.s: === `init386()` -`init386()` is defined in [.filename]#sys/i386/i386/machdep.c# and performs low-level initialization specific to the i386 chip.The switch to protected mode was performed by the loader. +`init386()` is defined in [.filename]#sys/i386/i386/machdep.c# and performs low-level initialization specific to the i386 chip. The switch to protected mode was performed by the loader. The loader has created the very first task, in which the kernel continues to operate. Before looking at the code, consider the tasks the processor must complete to initialize protected mode execution: diff --git a/documentation/content/en/books/arch-handbook/boot/_index.po b/documentation/content/en/books/arch-handbook/boot/_index.po new file mode 100644 index 0000000000..a534129a8c --- /dev/null +++ b/documentation/content/en/books/arch-handbook/boot/_index.po @@ -0,0 +1,3006 @@ +# 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/boot/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:14 +#, no-wrap +msgid "Bootstrapping and Kernel Initialization" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1 +#, no-wrap +msgid "Chapter 1. Bootstrapping and Kernel Initialization" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:52 +#, no-wrap +msgid "Synopsis" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:57 +msgid "" +"This chapter is an overview of the boot and system initialization processes, " +"starting from the BIOS (firmware) POST, to the first user process creation. " +"Since the initial steps of system startup are very architecture dependent, " +"the IA-32 architecture is used as an example. But the AMD64 and ARM64 " +"architectures are much more important and compelling examples and should be " +"explained in the near future according to the topic of this document." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:61 +msgid "" +"The FreeBSD boot process can be surprisingly complex. After control is " +"passed from the BIOS, a considerable amount of low-level configuration must " +"be done before the kernel can be loaded and executed. This setup must be " +"done in a simple and flexible manner, allowing the user a great deal of " +"customization possibilities." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:63 +#, no-wrap +msgid "Overview" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:76 +msgid "" +"The boot process is an extremely machine-dependent activity. Not only must " +"code be written for every computer architecture, but there may also be " +"multiple types of booting on the same architecture. For example, a " +"directory listing of [.filename]#stand# reveals a great amount of " +"architecture-dependent code. There is a directory for each of the various " +"supported architectures. FreeBSD supports the CSM boot standard " +"(Compatibility Support Module). So CSM is supported (with both GPT and MBR " +"partitioning support) and UEFI booting (GPT is totally supported, MBR is " +"mostly supported). It also supports loading files from ext2fs, MSDOS, UFS " +"and ZFS. FreeBSD also supports the boot environment feature of ZFS which " +"allows the HOST OS to communicate details about what to boot that go beyond " +"a simple partition as was possible in the past. But UEFI is more relevant " +"than the CSM these days. The example that follows shows booting an x86 " +"computer from an MBR-partitioned hard drive with the FreeBSD " +"[.filename]#boot0# multi-boot loader stored in the very first sector. That " +"boot code starts the FreeBSD three-stage boot process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:82 +msgid "" +"The key to understanding this process is that it is a series of stages of " +"increasing complexity. These stages are [.filename]#boot1#, " +"[.filename]#boot2#, and [.filename]#loader# (see man:boot[8] for more " +"detail). The boot system executes each stage in sequence. The last stage, " +"[.filename]#loader#, is responsible for loading the FreeBSD kernel. Each " +"stage is examined in the following sections." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:85 +msgid "" +"Here is an example of the output generated by the different boot stages. " +"Actual output may differ from machine to machine:" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:91 +#, no-wrap +msgid "*FreeBSD Component*" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:93 +#, no-wrap +msgid "*Output (may vary)*" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:94 +#, no-wrap +msgid "`boot0`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:103 +#, no-wrap +msgid "" +"[source,bash]\n" +"....\n" +"F1 FreeBSD\n" +"F2 BSD\n" +"F5 Disk 2\n" +"...." +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:104 +#, no-wrap +msgid "`boot2` footnote:[This prompt will appear if the user presses a key just after selecting an OS to boot at the boot0 stage.]" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:113 +#, no-wrap +msgid "" +"[source,bash]\n" +"....\n" +">>FreeBSD/x86 BOOT\n" +"Default: 0:ad(0p4)/boot/loader\n" +"boot:\n" +"...." +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:114 +#, no-wrap +msgid "[.filename]#loader#" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:130 +#, no-wrap +msgid "" +"[source,bash]\n" +"....\n" +"BTX loader 1.00 BTX version is 1.02\n" +"Consoles: internal video/keyboard\n" +"BIOS drive C: is disk0\n" +"BIOS 639kB/2096064kB available memory\n" +"\n" +"FreeBSD/x86 bootstrap loader, Revision 1.1\n" +"Console internal video/keyboard\n" +"(root@releng1.nyi.freebsd.org, Fri Apr 9 04:04:45 UTC 2021)\n" +"Loading /boot/defaults/loader.conf\n" +"/boot/kernel/kernel text=0xed9008 data=0x117d28+0x176650 syms=[0x8+0x137988+0x8+0x1515f8]\n" +"...." +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:131 +#, no-wrap +msgid "kernel" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:144 +#, no-wrap +msgid "" +"[source,bash]\n" +"....\n" +"Copyright (c) 1992-2021 The FreeBSD Project.\n" +"Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994\n" +" The Regents of the University of California. All rights reserved.\n" +"FreeBSD is a registered trademark of The FreeBSD Foundation.\n" +"FreeBSD 13.0-RELEASE 0 releng/13.0-n244733-ea31abc261f: Fri Apr 9 04:04:45 UTC 2021\n" +" root@releng1.nyi.freebsd.org:/usr/obj/usr/src/i386.i386/sys/GENERIC i386\n" +"FreeBSD clang version 11.0.1 (git@github.com:llvm/llvm-project.git llvmorg-11.0.1-0-g43ff75f2c3fe)\n" +"...." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:147 +#, no-wrap +msgid "The BIOS" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:158 +msgid "" +"When the computer powers on, the processor's registers are set to some " +"predefined values. One of the registers is the _instruction pointer_ " +"register, and its value after a power on is well defined: it is a 32-bit " +"value of `0xfffffff0`. The instruction pointer register (also known as the " +"Program Counter) points to code to be executed by the processor. Another " +"important register is the `cr0` 32-bit control register, and its value just " +"after a reboot is `0`. One of ``cr0``'s bits, the PE (Protection Enabled) " +"bit, indicates whether the processor is running in 32-bit protected mode or " +"16-bit real mode. Since this bit is cleared at boot time, the processor " +"boots in 16-bit real mode. Real mode means, among other things, that linear " +"and physical addresses are identical. The reason for the processor not to " +"start immediately in 32-bit protected mode is backwards compatibility. In " +"particular, the boot process relies on the services provided by the BIOS, " +"and the BIOS itself works in legacy, 16-bit code." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:161 +msgid "" +"The value of `0xfffffff0` is slightly less than 4 GB, so unless the machine " +"has 4 GB of physical memory, it cannot point to a valid memory address. The " +"computer's hardware translates this address so that it points to a BIOS " +"memory block." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:166 +msgid "" +"The BIOS (Basic Input Output System) is a chip on the motherboard that has a " +"relatively small amount of read-only memory (ROM). This memory contains " +"various low-level routines that are specific to the hardware supplied with " +"the motherboard. The processor will first jump to the address 0xfffffff0, " +"which really resides in the BIOS's memory. Usually this address contains a " +"jump instruction to the BIOS's POST routines." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:170 +msgid "" +"The POST (Power On Self Test) is a set of routines including the memory " +"check, system bus check, and other low-level initialization so the CPU can " +"set up the computer properly. The important step of this stage is " +"determining the boot device. Modern BIOS implementations permit the " +"selection of a boot device, allowing booting from a floppy, CD-ROM, hard " +"disk, or other devices." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:179 +msgid "" +"The very last thing in the POST is the `INT 0x19` instruction. The `INT " +"0x19` handler reads 512 bytes from the first sector of boot device into the " +"memory at address `0x7c00`. The term _first sector_ originates from hard " +"drive architecture, where the magnetic plate is divided into a number of " +"cylindrical tracks. Tracks are numbered, and every track is divided into a " +"number (usually 64) of sectors. Track numbers start at 0, but sector " +"numbers start from 1. Track 0 is the outermost on the magnetic plate, and " +"sector 1, the first sector, has a special purpose. It is also called the " +"MBR, or Master Boot Record. The remaining sectors on the first track are " +"never used." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:183 +msgid "" +"This sector is our boot-sequence starting point. As we will see, this " +"sector contains a copy of our [.filename]#boot0# program. A jump is made by " +"the BIOS to address `0x7c00` so it starts executing." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:185 +#, no-wrap +msgid "The Master Boot Record (`boot0`)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:194 +msgid "" +"After control is received from the BIOS at memory address `0x7c00`, " +"[.filename]#boot0# starts executing. It is the first piece of code under " +"FreeBSD control. The task of [.filename]#boot0# is quite simple: scan the " +"partition table and let the user choose which partition to boot from. The " +"Partition Table is a special, standard data structure embedded in the MBR " +"(hence embedded in [.filename]#boot0#) describing the four standard PC " +"\"partitions\". [.filename]#boot0# resides in the filesystem as " +"[.filename]#/boot/boot0#. It is a small 512-byte file, and it is exactly " +"what FreeBSD's installation procedure wrote to the hard disk's MBR if you " +"chose the \"bootmanager\" option at installation time. Indeed, " +"[.filename]#boot0# _is_ the MBR." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:197 +msgid "" +"As mentioned previously, we're calling the BIOS `INT 0x19` to load the MBR " +"([.filename]#boot0#) into memory at address `0x7c00`. The source file for " +"[.filename]#boot0# can be found in [.filename]#stand/i386/boot0/boot0.S# - " +"which is an awesome piece of code written by Robert Nordier." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:202 +msgid "" +"A special structure starting from offset `0x1be` in the MBR is called the " +"_partition table_. It has four records of 16 bytes each, called _partition " +"records_, which represent how the hard disk is partitioned, or, in FreeBSD's " +"terminology, sliced. One byte of those 16 says whether a partition (slice) " +"is bootable or not. Exactly one record must have that flag set, otherwise " +"[.filename]#boot0#'s code will refuse to proceed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:204 +msgid "A partition record has the following fields:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:206 +msgid "the 1-byte filesystem type" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:207 +msgid "the 1-byte bootable flag" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:208 +msgid "the 6 byte descriptor in CHS format" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:209 +msgid "the 8 byte descriptor in LBA format" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:213 +msgid "" +"A partition record descriptor contains information about where exactly the " +"partition resides on the drive. Both descriptors, LBA and CHS, describe the " +"same information, but in different ways: LBA (Logical Block Addressing) has " +"the starting sector for the partition and the partition's length, while CHS " +"(Cylinder Head Sector) has coordinates for the first and last sectors of the " +"partition. The partition table ends with the special signature `0xaa55`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:218 +msgid "" +"The MBR must fit into 512 bytes, a single disk sector. This program uses " +"low-level \"tricks\" like taking advantage of the side effects of certain " +"instructions and reusing register values from previous operations to make " +"the most out of the fewest possible instructions. Care must also be taken " +"when handling the partition table, which is embedded in the MBR itself. For " +"these reasons, be very careful when modifying [.filename]#boot0.S#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:223 +msgid "" +"Note that the [.filename]#boot0.S# source file is assembled \"as is\": " +"instructions are translated one by one to binary, with no additional " +"information (no ELF file format, for example). This kind of low-level " +"control is achieved at link time through special control flags passed to the " +"linker. For example, the text section of the program is set to be located " +"at address `0x600`. In practice this means that [.filename]#boot0# must be " +"loaded to memory address `0x600` in order to function properly." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:230 +msgid "" +"It is worth looking at the [.filename]#Makefile# for [.filename]#boot0# " +"([.filename]#stand/i386/boot0/Makefile#), as it defines some of the run-time " +"behavior of [.filename]#boot0#. For instance, if a terminal connected to " +"the serial port (COM1) is used for I/O, the macro `SIO` must be defined (`-" +"DSIO`). `-DPXE` enables boot through PXE by pressing kbd:[F6]. " +"Additionally, the program defines a set of _flags_ that allow further " +"modification of its behavior. All of this is illustrated in the " +"[.filename]#Makefile#. For example, look at the linker directives which " +"command the linker to start the text section at address `0x600`, and to " +"build the output file \"as is\" (strip out any file formatting):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:235 +#, no-wrap +msgid "" +" BOOT_BOOT0_ORG?=0x600\n" +" ORG=${BOOT_BOOT0_ORG}\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:237 +#, no-wrap +msgid "[.filename]#stand/i386/boot0/Makefile# [[boot-boot0-makefile-as-is]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:239 +msgid "" +"Let us now start our study of the MBR, or [.filename]#boot0#, starting where " +"execution begins." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:245 +msgid "" +"Some modifications have been made to some instructions in favor of better " +"exposition. For example, some macros are expanded, and some macro tests are " +"omitted when the result of the test is known. This applies to all of the " +"code examples shown." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:256 +#, no-wrap +msgid "" +"start:\n" +" cld\t\t\t# String ops inc\n" +" xorw %ax,%ax\t\t# Zero\n" +" movw %ax,%es\t\t# Address\n" +" movw %ax,%ds\t\t# data\n" +" movw %ax,%ss\t\t# Set up\n" +" movw $LOAD,%sp\t\t# stack\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:258 +#, no-wrap +msgid "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-entrypoint]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:264 +msgid "" +"This first block of code is the entry point of the program. It is where the " +"BIOS transfers control. First, it makes sure that the string operations " +"autoincrement its pointer operands (the `cld` instruction) footnote:[When in " +"doubt, we refer the reader to the official Intel manuals, which describe the " +"exact semantics for each instruction: .]. Then, as it makes no assumption " +"about the state of the segment registers, it initializes them. Finally, it " +"sets the stack pointer register (`%sp`) to ($LOAD = address `0x7c00`), so we " +"have a working stack." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:266 +msgid "" +"The next block is responsible for the relocation and subsequent jump to the " +"relocated code." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:280 +#, no-wrap +msgid "" +" movw %sp,%si # Source\n" +" movw $start,%di\t\t# Destination\n" +" movw $0x100,%cx\t\t# Word count\n" +" rep\t\t\t# Relocate\n" +" movsw\t\t\t# code\n" +" movw %di,%bp\t\t# Address variables\n" +" movb $0x8,%cl\t\t# Words to clear\n" +" rep\t\t\t# Zero\n" +" stosw\t\t\t# them\n" +" incb -0xe(%di)\t\t# Set the S field to 1\n" +" jmp main-LOAD+ORIGIN\t# Jump to relocated code\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:282 +#, no-wrap +msgid "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-relocation]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:293 +msgid "" +"As [.filename]#boot0# is loaded by the BIOS to address `0x7C00`, it copies " +"itself to address `0x600` and then transfers control there (recall that it " +"was linked to execute at address `0x600`). The source address, `0x7c00`, is " +"copied to register `%si`. The destination address, `0x600`, to register " +"`%di`. The number of words to copy, `256` (the program's size = 512 bytes), " +"is copied to register `%cx`. Next, the `rep` instruction repeats the " +"instruction that follows, that is, `movsw`, the number of times dictated by " +"the `%cx` register. The `movsw` instruction copies the word pointed to by " +"`%si` to the address pointed to by `%di`. This is repeated another 255 " +"times. On each repetition, both the source and destination registers, `%si` " +"and `%di`, are incremented by one. Thus, upon completion of the 256-word " +"(512-byte) copy, `%di` has the value `0x600`+`512`= `0x800`, and `%si` has " +"the value `0x7c00`+`512`= `0x7e00`; we have thus completed the code " +"_relocation_. Since the last update of this document, the copy instructions " +"have changed in the code, so instead of the movsb and stosb, movsw and stosw " +"have been introduced, which copy 2 bytes(1 word) in one iteration." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:304 +msgid "" +"Next, the destination register `%di` is copied to `%bp`. `%bp` gets the " +"value `0x800`. The value `8` is copied to `%cl` in preparation for a new " +"string operation (like our previous `movsw`). Now, `stosw` is executed 8 " +"times. This instruction copies a `0` value to the address pointed to by the " +"destination register (`%di`, which is `0x800`), and increments it. This is " +"repeated another 7 times, so `%di` ends up with value `0x810`. Effectively, " +"this clears the address range `0x800`-`0x80f`. This range is used as a " +"(fake) partition table for writing the MBR back to disk. Finally, the " +"sector field for the CHS addressing of this fake partition is given the " +"value 1 and a jump is made to the main function from the relocated code. " +"Note that until this jump to the relocated code, any reference to an " +"absolute address was avoided." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:306 +msgid "" +"The following code block tests whether the drive number provided by the BIOS " +"should be used, or the one stored in [.filename]#boot0#." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:318 +#, no-wrap +msgid "" +"main:\n" +" testb $SETDRV,_FLAGS(%bp)\t# Set drive number?\n" +"#ifndef CHECK_DRIVE\t/* disable drive checks */\n" +" jz save_curdrive\t\t# no, use the default\n" +"#else\n" +" jnz disable_update\t# Yes\n" +" testb %dl,%dl\t\t# Drive number valid?\n" +" js save_curdrive\t\t# Possibly (0x80 set)\n" +"#endif\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:320 +#, no-wrap +msgid "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-drivenumber]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:327 +msgid "" +"This code tests the `SETDRV` bit (`0x20`) in the _flags_ variable. Recall " +"that register `%bp` points to address location `0x800`, so the test is done " +"to the _flags_ variable at address `0x800`-`69`= `0x7bb`. This is an " +"example of the type of modifications that can be done to " +"[.filename]#boot0#. The `SETDRV` flag is not set by default, but it can be " +"set in the [.filename]#Makefile#. When set, the drive number stored in the " +"MBR is used instead of the one provided by the BIOS. We assume the " +"defaults, and that the BIOS provided a valid drive number, so we jump to " +"`save_curdrive`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:329 +msgid "" +"The next block saves the drive number provided by the BIOS, and calls `putn` " +"to print a new line on the screen." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:341 +#, no-wrap +msgid "" +"save_curdrive:\n" +" movb %dl, (%bp)\t\t# Save drive number\n" +" pushw %dx\t\t\t# Also in the stack\n" +"#ifdef\tTEST\t/* test code, print internal bios drive */\n" +" rolb $1, %dl\n" +" movw $drive, %si\n" +" call putkey\n" +"#endif\n" +" callw putn\t\t# Print a newline\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:343 +#, no-wrap +msgid "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-savedrivenumber]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:345 +msgid "" +"Note that we assume `TEST` is not defined, so the conditional code in it is " +"not assembled and will not appear in our executable [.filename]#boot0#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:351 +msgid "" +"Our next block implements the actual scanning of the partition table. It " +"prints to the screen the partition type for each of the four entries in the " +"partition table. It compares each type with a list of well-known operating " +"system file systems. Examples of recognized partition types are NTFS " +"(Windows(R), ID 0x7), `ext2fs` (Linux(R), ID 0x83), and, of course, `ffs`/" +"`ufs2` (FreeBSD, ID 0xa5). The implementation is fairly simple." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:356 +#, no-wrap +msgid "" +" movw $(partbl+0x4),%bx\t# Partition table (+4)\n" +" xorw %dx,%dx\t\t# Item number\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:372 +#, no-wrap +msgid "" +"read_entry:\n" +" movb %ch,-0x4(%bx)\t# Zero active flag (ch == 0)\n" +" btw %dx,_FLAGS(%bp)\t# Entry enabled?\n" +" jnc next_entry\t\t# No\n" +" movb (%bx),%al\t\t# Load type\n" +" test %al, %al\t\t# skip empty partition\n" +" jz next_entry\n" +" movw $bootable_ids,%di\t# Lookup tables\n" +" movb $(TLEN+1),%cl\t# Number of entries\n" +" repne\t\t\t# Locate\n" +" scasb\t\t\t# type\n" +" addw $(TLEN-1), %di\t# Adjust\n" +" movb (%di),%cl\t\t# Partition\n" +" addw %cx,%di\t\t# description\n" +" callw putx\t\t# Display it\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:377 +#, no-wrap +msgid "" +"next_entry:\n" +" incw %dx\t\t\t# Next item\n" +" addb $0x10,%bl\t\t# Next entry\n" +" jnc read_entry\t\t# Till done\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:379 +#, no-wrap +msgid "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-partition-scan]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:383 +msgid "" +"It is important to note that the active flag for each entry is cleared, so " +"after the scanning, _no_ partition entry is active in our memory copy of " +"[.filename]#boot0#. Later, the active flag will be set for the selected " +"partition. This ensures that only one active partition exists if the user " +"chooses to write the changes back to disk." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:388 +msgid "" +"The next block tests for other drives. At startup, the BIOS writes the " +"number of drives present in the computer to address `0x475`. If there are " +"any other drives present, [.filename]#boot0# prints the current drive to " +"screen. The user may command [.filename]#boot0# to scan partitions on " +"another drive later." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:397 +#, no-wrap +msgid "" +" popw %ax\t\t\t# Drive number\n" +" subb $0x80-0x1,%al\t\t# Does next\n" +" cmpb NHRDRV,%al\t\t# drive exist? (from BIOS?)\n" +" jb print_drive\t\t# Yes\n" +" decw %ax\t\t\t# Already drive 0?\n" +" jz print_prompt\t\t# Yes\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:399 +#, no-wrap +msgid "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-test-drives]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:402 +msgid "" +"We make the assumption that a single drive is present, so the jump to " +"`print_drive` is not performed. We also assume nothing strange happened, so " +"we jump to `print_prompt`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:404 +msgid "" +"This next block just prints out a prompt followed by the default option:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:414 +#, no-wrap +msgid "" +"print_prompt:\n" +" movw $prompt,%si\t\t# Display\n" +" callw putstr\t\t# prompt\n" +" movb _OPT(%bp),%dl\t# Display\n" +" decw %si\t\t\t# default\n" +" callw putkey\t\t# key\n" +" jmp start_input\t\t# Skip beep\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:416 +#, no-wrap +msgid "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-prompt]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:418 +msgid "" +"Finally, a jump is performed to `start_input`, where the BIOS services are " +"used to start a timer and for reading user input from the keyboard; if the " +"timer expires, the default option will be selected:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:434 +#, no-wrap +msgid "" +"start_input:\n" +" xorb %ah,%ah\t\t# BIOS: Get\n" +" int $0x1a\t\t\t# system time\n" +" movw %dx,%di\t\t# Ticks when\n" +" addw _TICKS(%bp),%di\t# timeout\n" +"read_key:\n" +" movb $0x1,%ah\t\t# BIOS: Check\n" +" int $0x16\t\t\t# for keypress\n" +" jnz got_key\t\t# Have input\n" +" xorb %ah,%ah\t\t# BIOS: int 0x1a, 00\n" +" int $0x1a\t\t\t# get system time\n" +" cmpw %di,%dx\t\t# Timeout?\n" +" jb read_key\t\t# No\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:436 +#, no-wrap +msgid "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-start-input]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:449 +msgid "" +"An interrupt is requested with number `0x1a` and argument `0` in register " +"`%ah`. The BIOS has a predefined set of services, requested by applications " +"as software-generated interrupts through the `int` instruction and receiving " +"arguments in registers (in this case, `%ah`). Here, particularly, we are " +"requesting the number of clock ticks since last midnight; this value is " +"computed by the BIOS through the RTC (Real Time Clock). This clock can be " +"programmed to work at frequencies ranging from 2 Hz to 8192 Hz. The BIOS " +"sets it to 18.2 Hz at startup. When the request is satisfied, a 32-bit " +"result is returned by the BIOS in registers `%cx` and `%dx` (lower bytes in " +"`%dx`). This result (the `%dx` part) is copied to register `%di`, and the " +"value of the `TICKS` variable is added to `%di`. This variable resides in " +"[.filename]#boot0# at offset `_TICKS` (a negative value) from register `%bp` " +"(which, recall, points to `0x800`). The default value of this variable is " +"`0xb6` (182 in decimal). Now, the idea is that [.filename]#boot0# " +"constantly requests the time from the BIOS, and when the value returned in " +"register `%dx` is greater than the value stored in `%di`, the time is up and " +"the default selection will be made. Since the RTC ticks 18.2 times per " +"second, this condition will be met after 10 seconds (this default behavior " +"can be changed in the [.filename]#Makefile#). Until this time has passed, " +"[.filename]#boot0# continually asks the BIOS for any user input; this is " +"done through `int 0x16`, argument `1` in `%ah`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:457 +msgid "" +"Whether a key was pressed or the time expired, subsequent code validates the " +"selection. Based on the selection, the register `%si` is set to point to " +"the appropriate partition entry in the partition table. This new selection " +"overrides the previous default one. Indeed, it becomes the new default. " +"Finally, the ACTIVE flag of the selected partition is set. If it was " +"enabled at compile time, the in-memory version of [.filename]#boot0# with " +"these modified values is written back to the MBR on disk. We leave the " +"details of this implementation to the reader." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:459 +msgid "" +"We now end our study with the last code block from the [.filename]#boot0# " +"program:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:472 +#, no-wrap +msgid "" +" movw $LOAD,%bx\t\t# Address for read\n" +" movb $0x2,%ah\t\t# Read sector\n" +" callw intx13\t\t# from disk\n" +" jc beep\t\t\t# If error\n" +" cmpw $MAGIC,0x1fe(%bx)\t# Bootable?\n" +" jne beep\t\t\t# No\n" +" pushw %si\t\t\t# Save ptr to selected part.\n" +" callw putn\t\t# Leave some space\n" +" popw %si\t\t\t# Restore, next stage uses it\n" +" jmp *%bx\t\t\t# Invoke bootstrap\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:474 +#, no-wrap +msgid "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-check-bootable]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:478 +msgid "" +"Recall that `%si` points to the selected partition entry. This entry tells " +"us where the partition begins on disk. We assume, of course, that the " +"partition selected is actually a FreeBSD slice." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:482 +msgid "" +"From now on, we will favor the use of the technically more accurate term " +"\"slice\" rather than \"partition\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:488 +msgid "" +"The transfer buffer is set to `0x7c00` (register `%bx`), and a read for the " +"first sector of the FreeBSD slice is requested by calling `intx13`. We " +"assume that everything went okay, so a jump to `beep` is not performed. In " +"particular, the new sector read must end with the magic sequence `0xaa55`. " +"Finally, the value at `%si` (the pointer to the selected partition table) is " +"preserved for use by the next stage, and a jump is performed to address " +"`0x7c00`, where execution of our next stage (the just-read block) is started." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:490 +#, no-wrap +msgid "`boot1` Stage" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:493 +msgid "So far we have gone through the following sequence:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:497 +msgid "" +"The BIOS did some early hardware initialization, including the POST. The " +"MBR ([.filename]#boot0#) was loaded from absolute disk sector one to address " +"`0x7c00`. Execution control was passed to that location." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:500 +msgid "" +"[.filename]#boot0# relocated itself to the location it was linked to execute " +"(`0x600`), followed by a jump to continue execution at the appropriate " +"place. Finally, [.filename]#boot0# loaded the first disk sector from the " +"FreeBSD slice to address `0x7c00`. Execution control was passed to that " +"location." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:513 +msgid "" +"[.filename]#boot1# is the next step in the boot-loading sequence. It is the " +"first of three boot stages. Note that we have been dealing exclusively with " +"disk sectors. Indeed, the BIOS loads the absolute first sector, while " +"[.filename]#boot0# loads the first sector of the FreeBSD slice. Both loads " +"are to address `0x7c00`. We can conceptually think of these disk sectors as " +"containing the files [.filename]#boot0# and [.filename]#boot1#, " +"respectively, but in reality this is not entirely true for " +"[.filename]#boot1#. Strictly speaking, unlike [.filename]#boot0#, " +"[.filename]#boot1# is not part of the boot blocks footnote:[There is a file /" +"boot/boot1, but it is not the written to the beginning of the FreeBSD " +"slice. Instead, it is concatenated with boot2 to form boot, which is " +"written to the beginning of the FreeBSD slice and read at boot time.]. " +"Instead, a single, full-blown file, [.filename]#boot# ([.filename]#/boot/" +"boot#), is what ultimately is written to disk. This file is a combination " +"of [.filename]#boot1#, [.filename]#boot2# and the `Boot Extender` (or BTX). " +"This single file is greater in size than a single sector (greater than 512 " +"bytes). Fortunately, [.filename]#boot1# occupies _exactly_ the first 512 " +"bytes of this single file, so when [.filename]#boot0# loads the first sector " +"of the FreeBSD slice (512 bytes), it is actually loading [.filename]#boot1# " +"and transferring control to it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:518 +msgid "" +"The main task of [.filename]#boot1# is to load the next boot stage. This " +"next stage is somewhat more complex. It is composed of a server called the " +"\"Boot Extender\", or BTX, and a client, called [.filename]#boot2#. As we " +"will see, the last boot stage, [.filename]#loader#, is also a client of the " +"BTX server." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:520 +msgid "" +"Let us now look in detail at what exactly is done by [.filename]#boot1#, " +"starting like we did for [.filename]#boot0#, at its entry point:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:525 +#, no-wrap +msgid "" +"start:\n" +"\tjmp main\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:527 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-entry]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:529 +msgid "" +"The entry point at `start` simply jumps past a special data area to the " +"label `main`, which in turn looks like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:544 +#, no-wrap +msgid "" +"main:\n" +" cld\t\t\t# String ops inc\n" +" xor %cx,%cx\t\t# Zero\n" +" mov %cx,%es\t\t# Address\n" +" mov %cx,%ds\t\t# data\n" +" mov %cx,%ss\t\t# Set up\n" +" mov $start,%sp\t\t# stack\n" +" mov %sp,%si\t\t# Source\n" +" mov $MEM_REL,%di\t\t# Destination\n" +" incb %ch\t\t\t# Word count\n" +" rep\t\t\t# Copy\n" +" movsw\t\t\t# code\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:546 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-main]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:551 +msgid "" +"Just like [.filename]#boot0#, this code relocates [.filename]#boot1#, this " +"time to memory address `0x700`. However, unlike [.filename]#boot0#, it does " +"not jump there. [.filename]#boot1# is linked to execute at address " +"`0x7c00`, effectively where it was loaded in the first place. The reason " +"for this relocation will be discussed shortly." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:556 +msgid "" +"Next comes a loop that looks for the FreeBSD slice. Although " +"[.filename]#boot0# loaded [.filename]#boot1# from the FreeBSD slice, no " +"information was passed to it about this footnote:[Actually we did pass a " +"pointer to the slice entry in register %si. However, boot1 does not assume " +"that it was loaded by boot0 (perhaps some other MBR loaded it, and did not " +"pass this information), so it assumes nothing.], so [.filename]#boot1# must " +"rescan the partition table to find where the FreeBSD slice starts. " +"Therefore it rereads the MBR:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:564 +#, no-wrap +msgid "" +" mov $part4,%si\t\t# Partition\n" +" cmpb $0x80,%dl\t\t# Hard drive?\n" +" jb main.4\t\t\t# No\n" +" movb $0x1,%dh\t\t# Block count\n" +" callw nread\t\t# Read MBR\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:566 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-find-freebsd]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:574 +msgid "" +"In the code above, register `%dl` maintains information about the boot " +"device. This is passed on by the BIOS and preserved by the MBR. Numbers " +"`0x80` and greater tells us that we are dealing with a hard drive, so a call " +"is made to `nread`, where the MBR is read. Arguments to `nread` are passed " +"through `%si` and `%dh`. The memory address at label `part4` is copied to " +"`%si`. This memory address holds a \"fake partition\" to be used by " +"`nread`. The following is the data in the fake partition:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:582 +#, no-wrap +msgid "" +" part4:\n" +"\t.byte 0x80, 0x00, 0x01, 0x00\n" +"\t.byte 0xa5, 0xfe, 0xff, 0xff\n" +"\t.byte 0x00, 0x00, 0x00, 0x00\n" +"\t.byte 0x50, 0xc3, 0x00, 0x00\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:584 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot2-make-fake-partition]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:589 +msgid "" +"In particular, the LBA for this fake partition is hardcoded to zero. This " +"is used as an argument to the BIOS for reading absolute sector one from the " +"hard drive. Alternatively, CHS addressing could be used. In this case, the " +"fake partition holds cylinder 0, head 0 and sector 1, which is equivalent to " +"absolute sector one." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:591 +msgid "Let us now proceed to take a look at `nread`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:601 +#, no-wrap +msgid "" +"nread:\n" +" mov $MEM_BUF,%bx\t\t# Transfer buffer\n" +" mov 0x8(%si),%ax\t\t# Get\n" +" mov 0xa(%si),%cx\t\t# LBA\n" +" push %cs\t\t\t# Read from\n" +" callw xread.1\t\t# disk\n" +" jnc return\t\t# If success, return\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:603 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-nread]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:612 +msgid "" +"Recall that `%si` points to the fake partition. The word footnote:[In the " +"context of 16-bit real mode, a word is 2 bytes.] at offset `0x8` is copied " +"to register `%ax` and word at offset `0xa` to `%cx`. They are interpreted " +"by the BIOS as the lower 4-byte value denoting the LBA to be read (the upper " +"four bytes are assumed to be zero). Register `%bx` holds the memory address " +"where the MBR will be loaded. The instruction pushing `%cs` onto the stack " +"is very interesting. In this context, it accomplishes nothing. However, as " +"we will see shortly, [.filename]#boot2#, in conjunction with the BTX server, " +"also uses `xread.1`. This mechanism will be discussed in the next section." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:614 +msgid "" +"The code at `xread.1` further calls the `read` function, which actually " +"calls the BIOS asking for the disk sector:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:631 +#, no-wrap +msgid "" +"xread.1:\n" +"\tpushl $0x0\t\t# absolute\n" +"\tpush %cx\t\t# block\n" +"\tpush %ax\t\t# number\n" +"\tpush %es\t\t# Address of\n" +"\tpush %bx\t\t# transfer buffer\n" +"\txor %ax,%ax\t\t# Number of\n" +"\tmovb %dh,%al\t\t# blocks to\n" +"\tpush %ax\t\t# transfer\n" +"\tpush $0x10\t\t# Size of packet\n" +"\tmov %sp,%bp\t\t# Packet pointer\n" +"\tcallw read\t\t# Read from disk\n" +"\tlea 0x10(%bp),%sp\t# Clear stack\n" +"\tlret\t\t\t# To far caller\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:633 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-xread1]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:637 +msgid "" +"Note the long return instruction at the end of this block. This instruction " +"pops out the `%cs` register pushed by `nread`, and returns. Finally, " +"`nread` also returns." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:639 +msgid "" +"With the MBR loaded to memory, the actual loop for searching the FreeBSD " +"slice begins:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:659 +#, no-wrap +msgid "" +"\tmov $0x1,%cx\t\t # Two passes\n" +"main.1:\n" +"\tmov $MEM_BUF+PRT_OFF,%si # Partition table\n" +"\tmovb $0x1,%dh\t\t # Partition\n" +"main.2:\n" +"\tcmpb $PRT_BSD,0x4(%si)\t # Our partition type?\n" +"\tjne main.3\t\t # No\n" +"\tjcxz main.5\t\t # If second pass\n" +"\ttestb $0x80,(%si)\t # Active?\n" +"\tjnz main.5\t\t # Yes\n" +"main.3:\n" +"\tadd $0x10,%si\t\t # Next entry\n" +"\tincb %dh\t\t # Partition\n" +"\tcmpb $0x1+PRT_NUM,%dh\t\t # In table?\n" +"\tjb main.2\t\t # Yes\n" +"\tdec %cx\t\t\t # Do two\n" +"\tjcxz main.1\t\t # passes\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:661 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-find-part]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:665 +msgid "" +"If a FreeBSD slice is identified, execution continues at `main.5`. Note " +"that when a FreeBSD slice is found `%si` points to the appropriate entry in " +"the partition table, and `%dh` holds the partition number. We assume that a " +"FreeBSD slice is found, so we continue execution at `main.5`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:680 +#, no-wrap +msgid "" +"main.5:\n" +"\tmov %dx,MEM_ARG\t\t\t # Save args\n" +"\tmovb $NSECT,%dh\t\t\t # Sector count\n" +"\tcallw nread\t\t\t # Read disk\n" +"\tmov $MEM_BTX,%bx\t\t\t # BTX\n" +"\tmov 0xa(%bx),%si\t\t # Get BTX length and set\n" +"\tadd %bx,%si\t\t\t # %si to start of boot2.bin\n" +"\tmov $MEM_USR+SIZ_PAG*2,%di\t\t\t # Client page 2\n" +"\tmov $MEM_BTX+(NSECT-1)*SIZ_SEC,%cx\t\t\t # Byte\n" +"\tsub %si,%cx\t\t\t # count\n" +"\trep\t\t\t\t # Relocate\n" +"\tmovsb\t\t\t\t # client\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:682 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-main5]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:688 +msgid "" +"Recall that at this point, register `%si` points to the FreeBSD slice entry " +"in the MBR partition table, so a call to `nread` will effectively read " +"sectors at the beginning of this partition. The argument passed on register " +"`%dh` tells `nread` to read 16 disk sectors. Recall that the first 512 " +"bytes, or the first sector of the FreeBSD slice, coincides with the " +"[.filename]#boot1# program. Also recall that the file written to the " +"beginning of the FreeBSD slice is not [.filename]#/boot/boot1#, but " +"[.filename]#/boot/boot#. Let us look at the size of these files in the " +"filesystem:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:695 +#, no-wrap +msgid "" +"-r--r--r-- 1 root wheel 512B Jan 8 00:15 /boot/boot0\n" +"-r--r--r-- 1 root wheel 512B Jan 8 00:15 /boot/boot1\n" +"-r--r--r-- 1 root wheel 7.5K Jan 8 00:15 /boot/boot2\n" +"-r--r--r-- 1 root wheel 8.0K Jan 8 00:15 /boot/boot\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:703 +msgid "" +"Both [.filename]#boot0# and [.filename]#boot1# are 512 bytes each, so they " +"fit _exactly_ in one disk sector. [.filename]#boot2# is much bigger, " +"holding both the BTX server and the [.filename]#boot2# client. Finally, a " +"file called simply [.filename]#boot# is 512 bytes larger than " +"[.filename]#boot2#. This file is a concatenation of [.filename]#boot1# and " +"[.filename]#boot2#. As already noted, [.filename]#boot0# is the file " +"written to the absolute first disk sector (the MBR), and [.filename]#boot# " +"is the file written to the first sector of the FreeBSD slice; " +"[.filename]#boot1# and [.filename]#boot2# are _not_ written to disk. The " +"command used to concatenate [.filename]#boot1# and [.filename]#boot2# into a " +"single [.filename]#boot# is merely `cat boot1 boot2 > boot`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:707 +msgid "" +"So [.filename]#boot1# occupies exactly the first 512 bytes of " +"[.filename]#boot# and, because [.filename]#boot# is written to the first " +"sector of the FreeBSD slice, [.filename]#boot1# fits exactly in this first " +"sector. When `nread` reads the first 16 sectors of the FreeBSD slice, it " +"effectively reads the entire [.filename]#boot# file footnote:[512*16=8192 " +"bytes, exactly the size of boot]. We will see more details about how " +"[.filename]#boot# is formed from [.filename]#boot1# and [.filename]#boot2# " +"in the next section." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:713 +msgid "" +"Recall that `nread` uses memory address `0x8c00` as the transfer buffer to " +"hold the sectors read. This address is conveniently chosen. Indeed, " +"because [.filename]#boot1# belongs to the first 512 bytes, it ends up in the " +"address range `0x8c00`-`0x8dff`. The 512 bytes that follows (range `0x8e00`-" +"`0x8fff`) is used to store the _bsdlabel_ footnote:[Historically known as " +"disklabel. If you ever wondered where FreeBSD stored this information, it " +"is in this region - see man:bsdlabel[8]]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:721 +msgid "" +"Starting at address `0x9000` is the beginning of the BTX server, and " +"immediately following is the [.filename]#boot2# client. The BTX server acts " +"as a kernel, and executes in protected mode in the most privileged level. " +"In contrast, the BTX clients ([.filename]#boot2#, for example), execute in " +"user mode. We will see how this is accomplished in the next section. The " +"code after the call to `nread` locates the beginning of [.filename]#boot2# " +"in the memory buffer, and copies it to memory address `0xc000`. This is " +"because the BTX server arranges [.filename]#boot2# to execute in a segment " +"starting at `0xa000`. We explore this in detail in the following section." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:724 +msgid "" +"The last code block of [.filename]#boot1# enables access to memory above 1MB " +"footnote:[This is necessary for legacy reasons. Interested readers should " +"see .] and concludes with a jump to the starting point of the BTX server:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:732 +#, no-wrap +msgid "" +"seta20:\n" +"\tcli\t\t\t# Disable interrupts\n" +"seta20.1:\n" +"\tdec %cx\t\t\t# Timeout?\n" +"\tjz seta20.3\t\t# Yes\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:747 +#, no-wrap +msgid "" +"\tinb $0x64,%al\t\t# Get status\n" +"\ttestb $0x2,%al\t\t# Busy?\n" +"\tjnz seta20.1\t\t# Yes\n" +"\tmovb $0xd1,%al\t\t# Command: Write\n" +"\toutb %al,$0x64\t\t# output port\n" +"seta20.2:\n" +"\tinb $0x64,%al\t\t# Get status\n" +"\ttestb $0x2,%al\t\t# Busy?\n" +"\tjnz seta20.2\t\t# Yes\n" +"\tmovb $0xdf,%al\t\t# Enable\n" +"\toutb %al,$0x60\t\t# A20\n" +"seta20.3:\n" +"\tsti\t\t\t# Enable interrupts\n" +"\tjmp 0x9010\t\t# Start BTX\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:749 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-seta20]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:751 +msgid "Note that right before the jump, interrupts are enabled." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:753 +#, no-wrap +msgid "The BTX Server" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:757 +msgid "" +"Next in our boot sequence is the BTX Server. Let us quickly remember how we " +"got here:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:759 +msgid "" +"The BIOS loads the absolute sector one (the MBR, or [.filename]#boot0#), to " +"address `0x7c00` and jumps there." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:761 +msgid "" +"[.filename]#boot0# relocates itself to `0x600`, the address it was linked to " +"execute, and jumps over there. It then reads the first sector of the " +"FreeBSD slice (which consists of [.filename]#boot1#) into address `0x7c00` " +"and jumps over there." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:766 +msgid "" +"[.filename]#boot1# loads the first 16 sectors of the FreeBSD slice into " +"address `0x8c00`. This 16 sectors, or 8192 bytes, is the whole file " +"[.filename]#boot#. The file is a concatenation of [.filename]#boot1# and " +"[.filename]#boot2#. [.filename]#boot2#, in turn, contains the BTX server " +"and the [.filename]#boot2# client. Finally, a jump is made to address " +"`0x9010`, the entry point of the BTX server." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:770 +msgid "" +"Before studying the BTX Server in detail, let us further review how the " +"single, all-in-one [.filename]#boot# file is created. The way " +"[.filename]#boot# is built is defined in its [.filename]#Makefile# " +"([.filename]#stand/i386/boot2/Makefile#). Let us look at the rule that " +"creates the [.filename]#boot# file:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:775 +#, no-wrap +msgid "" +" boot: boot1 boot2\n" +"\tcat boot1 boot2 > boot\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:777 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/Makefile# [[boot-boot1-make-boot]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:780 +msgid "" +"This tells us that [.filename]#boot1# and [.filename]#boot2# are needed, and " +"the rule simply concatenates them to produce a single file called " +"[.filename]#boot#. The rules for creating [.filename]#boot1# are also quite " +"simple:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:785 +#, no-wrap +msgid "" +" boot1: boot1.out\n" +"\t${OBJCOPY} -S -O binary boot1.out ${.TARGET}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:788 +#, no-wrap +msgid "" +" boot1.out: boot1.o\n" +"\t${LD} ${LD_FLAGS} -e start --defsym ORG=${ORG1} -T ${LDSCRIPT} -o ${.TARGET} boot1.o\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:790 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/Makefile# [[boot-boot1-make-boot1]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:799 +msgid "" +"To apply the rule for creating [.filename]#boot1#, [.filename]#boot1.out# " +"must be resolved. This, in turn, depends on the existence of " +"[.filename]#boot1.o#. This last file is simply the result of assembling our " +"familiar [.filename]#boot1.S#, without linking. Now, the rule for creating " +"[.filename]#boot1.out# is applied. This tells us that [.filename]#boot1.o# " +"should be linked with `start` as its entry point, and starting at address " +"`0x7c00`. Finally, [.filename]#boot1# is created from " +"[.filename]#boot1.out# applying the appropriate rule. This rule is the " +"[.filename]#objcopy# command applied to [.filename]#boot1.out#. Note the " +"flags passed to [.filename]#objcopy#: `-S` tells it to strip all relocation " +"and symbolic information; `-O binary` indicates the output format, that is, " +"a simple, unformatted binary file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:801 +msgid "" +"Having [.filename]#boot1#, let us take a look at how [.filename]#boot2# is " +"constructed:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:808 +#, no-wrap +msgid "" +" boot2: boot2.ld\n" +"\t@set -- `ls -l ${.ALLSRC}`; x=$$((${BOOT2SIZE}-$$5)); \\\n" +"\t echo \"$$x bytes available\"; test $$x -ge 0\n" +"\t${DD} if=${.ALLSRC} of=${.TARGET} bs=${BOOT2SIZE} conv=sync\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:812 +#, no-wrap +msgid "" +" boot2.ld: boot2.ldr boot2.bin ${BTXKERN}\n" +"\tbtxld -v -E ${ORG2} -f bin -b ${BTXKERN} -l boot2.ldr \\\n" +"\t -o ${.TARGET} -P 1 boot2.bin\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:815 +#, no-wrap +msgid "" +" boot2.ldr:\n" +"\t${DD} if=/dev/zero of=${.TARGET} bs=512 count=1\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:818 +#, no-wrap +msgid "" +" boot2.bin: boot2.out\n" +"\t${OBJCOPY} -S -O binary boot2.out ${.TARGET}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:821 +#, no-wrap +msgid "" +" boot2.out: ${BTXCRT} boot2.o sio.o ashldi3.o\n" +"\t${LD} ${LD_FLAGS} --defsym ORG=${ORG2} -T ${LDSCRIPT} -o ${.TARGET} ${.ALLSRC}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:828 +#, no-wrap +msgid "" +" boot2.h: boot1.out\n" +"\t${NM} -t d ${.ALLSRC} | awk '/([0-9])+ T xread/ \\\n" +"\t { x = $$1 - ORG1; \\\n" +"\t printf(\"#define XREADORG %#x\\n\", REL1 + x) }' \\\n" +"\t ORG1=`printf \"%d\" ${ORG1}` \\\n" +"\t REL1=`printf \"%d\" ${REL1}` > ${.TARGET}\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:830 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/Makefile# [[boot-boot1-make-boot2]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:834 +msgid "" +"The mechanism for building [.filename]#boot2# is far more elaborate. Let us " +"point out the most relevant facts. The dependency list is as follows:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:842 +#, no-wrap +msgid "" +" boot2: boot2.ld\n" +" boot2.ld: boot2.ldr boot2.bin ${BTXDIR}\n" +" boot2.bin: boot2.out\n" +" boot2.out: ${BTXDIR} boot2.o sio.o ashldi3.o\n" +" boot2.h: boot1.out\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:844 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/Makefile# [[boot-boot1-make-boot2-more]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:847 +msgid "" +"Note that initially there is no header file [.filename]#boot2.h#, but its " +"creation depends on [.filename]#boot1.out#, which we already have. The rule " +"for its creation is a bit terse, but the important thing is that the output, " +"[.filename]#boot2.h#, is something like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:851 +#, no-wrap +msgid "#define XREADORG 0x725\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:853 +#, no-wrap +msgid "[.filename]#stand/i386/boot2/boot2.h# [[boot-boot1-make-boot2h]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:859 +msgid "" +"Recall that [.filename]#boot1# was relocated (i.e., copied from `0x7c00` to " +"`0x700`). This relocation will now make sense, because as we will see, the " +"BTX server reclaims some memory, including the space where " +"[.filename]#boot1# was originally loaded. However, the BTX server needs " +"access to [.filename]#boot1#'s `xread` function; this function, according to " +"the output of [.filename]#boot2.h#, is at location `0x725`. Indeed, the BTX " +"server uses the `xread` function from [.filename]#boot1#'s relocated code. " +"This function is now accessible from within the [.filename]#boot2# client." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:868 +msgid "" +"The next rule directs the linker to link various files " +"([.filename]#ashldi3.o#, [.filename]#boot2.o# and [.filename]#sio.o#). Note " +"that the output file, [.filename]#boot2.out#, is linked to execute at " +"address `0x2000` (${ORG2}). Recall that [.filename]#boot2# will be executed " +"in user mode, within a special user segment set up by the BTX server. This " +"segment starts at `0xa000`. Also, remember that the [.filename]#boot2# " +"portion of [.filename]#boot# was copied to address `0xc000`, that is, offset " +"`0x2000` from the start of the user segment, so [.filename]#boot2# will work " +"properly when we transfer control to it. Next, [.filename]#boot2.bin# is " +"created from [.filename]#boot2.out# by stripping its symbols and format " +"information; boot2.bin is a _raw_ binary. Now, note that a file " +"[.filename]#boot2.ldr# is created as a 512-byte file full of zeros. This " +"space is reserved for the bsdlabel." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:873 +msgid "" +"Now that we have files [.filename]#boot1#, [.filename]#boot2.bin# and " +"[.filename]#boot2.ldr#, only the BTX server is missing before creating the " +"all-in-one [.filename]#boot# file. The BTX server is located in " +"[.filename]#stand/i386/btx/btx#; it has its own [.filename]#Makefile# with " +"its own set of rules for building. The important thing to notice is that it " +"is also compiled as a _raw_ binary, and that it is linked to execute at " +"address `0x9000`. The details can be found in [.filename]#stand/i386/btx/" +"btx/Makefile#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:880 +msgid "" +"Having the files that comprise the [.filename]#boot# program, the final step " +"is to _merge_ them. This is done by a special program called " +"[.filename]#btxld# (source located in [.filename]#/usr/src/usr.sbin/" +"btxld#). Some arguments to this program include the name of the output file " +"([.filename]#boot#), its entry point (`0x2000`) and its file format (raw " +"binary). The various files are finally merged by this utility into the file " +"[.filename]#boot#, which consists of [.filename]#boot1#, [.filename]#boot2#, " +"the `bsdlabel` and the BTX server. This file, which takes exactly 16 " +"sectors, or 8192 bytes, is what is actually written to the beginning of the " +"FreeBSD slice during installation. Let us now proceed to study the BTX " +"server program." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:883 +msgid "" +"The BTX server prepares a simple environment and switches from 16-bit real " +"mode to 32-bit protected mode, right before passing control to the client. " +"This includes initializing and updating the following data structures:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:886 +msgid "" +"Modifies the `Interrupt Vector Table (IVT)`. The IVT provides exception and " +"interrupt handlers for Real-Mode code." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:889 +msgid "" +"The `Interrupt Descriptor Table (IDT)` is created. Entries are provided for " +"processor exceptions, hardware interrupts, two system calls and V86 " +"interface. The IDT provides exception and interrupt handlers for Protected-" +"Mode code." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:891 +msgid "" +"A `Task-State Segment (TSS)` is created. This is necessary because the " +"processor works in the _least_ privileged level when executing the client " +"([.filename]#boot2#), but in the _most_ privileged level when executing the " +"BTX server." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:894 +msgid "" +"The GDT (Global Descriptor Table) is set up. Entries (descriptors) are " +"provided for supervisor code and data, user code and data, and real-mode " +"code and data. footnote:[Real-mode code and data are necessary when " +"switching back to real mode from protected mode, as suggested by the Intel " +"manuals.]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:899 +msgid "" +"Let us now start studying the actual implementation. Recall that " +"[.filename]#boot1# made a jump to address `0x9010`, the BTX server's entry " +"point. Before studying program execution there, note that the BTX server " +"has a special header at address range `0x9000-0x900f`, right before its " +"entry point. This header is defined as follows:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:915 +#, no-wrap +msgid "" +"start:\t\t\t\t\t\t# Start of code\n" +"/*\n" +" * BTX header.\n" +" */\n" +"btx_hdr:\t.byte 0xeb\t\t\t# Machine ID\n" +"\t\t.byte 0xe\t\t\t# Header size\n" +"\t\t.ascii \"BTX\"\t\t\t# Magic\n" +"\t\t.byte 0x1\t\t\t# Major version\n" +"\t\t.byte 0x2\t\t\t# Minor version\n" +"\t\t.byte BTX_FLAGS\t\t\t# Flags\n" +"\t\t.word PAG_CNT-MEM_ORG>>0xc\t# Paging control\n" +"\t\t.word break-start\t\t# Text size\n" +"\t\t.long 0x0\t\t\t# Entry address\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:917 +#, no-wrap +msgid "[.filename]#stand/i386/btx/btx/btx.S# [[btx-header]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:922 +msgid "" +"Note the first two bytes are `0xeb` and `0xe`. In the IA-32 architecture, " +"these two bytes are interpreted as a relative jump past the header into the " +"entry point, so in theory, [.filename]#boot1# could jump here (address " +"`0x9000`) instead of address `0x9010`. Note that the last field in the BTX " +"header is a pointer to the client's ([.filename]#boot2#) entry pointb2. " +"This field is patched at link time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:924 +msgid "Immediately following the header is the BTX server's entry point:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:938 +#, no-wrap +msgid "" +"/*\n" +" * Initialization routine.\n" +" */\n" +"init:\t\tcli\t\t\t\t# Disable interrupts\n" +"\t\txor %ax,%ax\t\t\t# Zero/segment\n" +"\t\tmov %ax,%ss\t\t\t# Set up\n" +"\t\tmov $MEM_ESP0,%sp\t\t# stack\n" +"\t\tmov %ax,%es\t\t\t# Address\n" +"\t\tmov %ax,%ds\t\t\t# data\n" +"\t\tpushl $0x2\t\t\t# Clear\n" +"\t\tpopfl\t\t\t\t# flags\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:940 +#, no-wrap +msgid "[.filename]#stand/i386/btx/btx/btx.S# [[btx-init]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:944 +msgid "" +"This code disables interrupts, sets up a working stack (starting at address " +"`0x1800`) and clears the flags in the EFLAGS register. Note that the " +"`popfl` instruction pops out a doubleword (4 bytes) from the stack and " +"places it in the EFLAGS register. As the value actually popped is `2`, the " +"EFLAGS register is effectively cleared (IA-32 requires that bit 2 of the " +"EFLAGS register always be 1)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:947 +msgid "" +"Our next code block clears (sets to `0`) the memory range `0x5e00-0x8fff`. " +"This range is where the various data structures will be created:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:957 +#, no-wrap +msgid "" +"/*\n" +" * Initialize memory.\n" +" */\n" +"\t\tmov $MEM_IDT,%di\t\t# Memory to initialize\n" +"\t\tmov $(MEM_ORG-MEM_IDT)/2,%cx\t# Words to zero\n" +"\t\trep\t\t\t\t# Zero-fill\n" +"\t\tstosw\t\t\t\t# memory\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:959 +#, no-wrap +msgid "[.filename]#stand/i386/btx/btx/btx.S# [[btx-clear-mem]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:962 +msgid "" +"Recall that [.filename]#boot1# was originally loaded to address `0x7c00`, " +"so, with this memory initialization, that copy effectively disappeared. " +"However, also recall that [.filename]#boot1# was relocated to `0x700`, so " +"_that_ copy is still in memory, and the BTX server will make use of it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:970 +msgid "" +"Next, the real-mode IVT (Interrupt Vector Table is updated. The IVT is an " +"array of segment/offset pairs for exception and interrupt handlers. The " +"BIOS normally maps hardware interrupts to interrupt vectors `0x8` to `0xf` " +"and `0x70` to `0x77` but, as will be seen, the 8259A Programmable Interrupt " +"Controller, the chip controlling the actual mapping of hardware interrupts " +"to interrupt vectors, is programmed to remap these interrupt vectors from " +"`0x8-0xf` to `0x20-0x27` and from `0x70-0x77` to `0x28-0x2f`. Thus, " +"interrupt handlers are provided for interrupt vectors `0x20-0x2f`. The " +"reason the BIOS-provided handlers are not used directly is because they work " +"in 16-bit real mode, but not 32-bit protected mode. Processor mode will be " +"switched to 32-bit protected mode shortly. However, the BTX server sets up " +"a mechanism to effectively use the handlers provided by the BIOS:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:985 +#, no-wrap +msgid "" +"/*\n" +" * Update real mode IDT for reflecting hardware interrupts.\n" +" */\n" +"\t\tmov $intr20,%bx\t\t\t# Address first handler\n" +"\t\tmov $0x10,%cx\t\t\t# Number of handlers\n" +"\t\tmov $0x20*4,%di\t\t\t# First real mode IDT entry\n" +"init.0:\t\tmov %bx,(%di)\t\t\t# Store IP\n" +"\t\tinc %di\t\t\t\t# Address next\n" +"\t\tinc %di\t\t\t\t# entry\n" +"\t\tstosw\t\t\t\t# Store CS\n" +"\t\tadd $4,%bx\t\t\t# Next handler\n" +"\t\tloop init.0\t\t\t# Next IRQ\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:987 +#, no-wrap +msgid "[.filename]#stand/i386/btx/btx/btx.S# [[btx-ivt]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:992 +msgid "" +"The next block creates the IDT (Interrupt Descriptor Table). The IDT is " +"analogous, in protected mode, to the IVT in real mode. That is, the IDT " +"describes the various exception and interrupt handlers used when the " +"processor is executing in protected mode. In essence, it also consists of " +"an array of segment/offset pairs, although the structure is somewhat more " +"complex, because segments in protected mode are different than in real mode, " +"and various protection mechanisms apply:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1019 +#, no-wrap +msgid "" +"/*\n" +" * Create IDT.\n" +" */\n" +"\t\tmov $MEM_IDT,%di\t\t# IDT's address\n" +"\t\tmov $idtctl,%si\t\t\t# Control string\n" +"init.1:\t\tlodsb\t\t\t\t# Get entry\n" +"\t\tcbw\t\t\t\t# count\n" +"\t\txchg %ax,%cx\t\t\t# as word\n" +"\t\tjcxz init.4\t\t\t# If done\n" +"\t\tlodsb\t\t\t\t# Get segment\n" +"\t\txchg %ax,%dx\t\t\t# P:DPL:type\n" +"\t\tlodsw\t\t\t\t# Get control\n" +"\t\txchg %ax,%bx\t\t\t# set\n" +"\t\tlodsw\t\t\t\t# Get handler offset\n" +"\t\tmov $SEL_SCODE,%dh\t\t# Segment selector\n" +"init.2:\t\tshr %bx\t\t\t\t# Handle this int?\n" +"\t\tjnc init.3\t\t\t# No\n" +"\t\tmov %ax,(%di)\t\t\t# Set handler offset\n" +"\t\tmov %dh,0x2(%di)\t\t# and selector\n" +"\t\tmov %dl,0x5(%di)\t\t# Set P:DPL:type\n" +"\t\tadd $0x4,%ax\t\t\t# Next handler\n" +"init.3:\t\tlea 0x8(%di),%di\t\t# Next entry\n" +"\t\tloop init.2\t\t\t# Till set done\n" +"\t\tjmp init.1\t\t\t# Continue\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1021 +#, no-wrap +msgid "[.filename]#stand/i386/btx/btx/btx.S# [[btx-idt]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1029 +msgid "" +"Each entry in the `IDT` is 8 bytes long. Besides the segment/offset " +"information, they also describe the segment type, privilege level, and " +"whether the segment is present in memory or not. The construction is such " +"that interrupt vectors from `0` to `0xf` (exceptions) are handled by " +"function `intx00`; vector `0x10` (also an exception) is handled by `intx10`; " +"hardware interrupts, which are later configured to start at interrupt vector " +"`0x20` all the way to interrupt vector `0x2f`, are handled by function " +"`intx20`. Lastly, interrupt vector `0x30`, which is used for system calls, " +"is handled by `intx30`, and vectors `0x31` and `0x32` are handled by " +"`intx31`. It must be noted that only descriptors for interrupt vectors " +"`0x30`, `0x31` and `0x32` are given privilege level 3, the same privilege " +"level as the [.filename]#boot2# client, which means the client can execute a " +"software-generated interrupt to this vectors through the `int` instruction " +"without failing (this is the way [.filename]#boot2# use the services " +"provided by the BTX server). Also, note that _only_ software-generated " +"interrupts are protected from code executing in lesser privilege levels. " +"Hardware-generated interrupts and processor-generated exceptions are " +"_always_ handled adequately, regardless of the actual privileges involved." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1034 +msgid "" +"The next step is to initialize the TSS (Task-State Segment). The TSS is a " +"hardware feature that helps the operating system or executive software " +"implement multitasking functionality through process abstraction. The IA-32 " +"architecture demands the creation and use of _at least_ one TSS if " +"multitasking facilities are used or different privilege levels are defined. " +"Since the [.filename]#boot2# client is executed in privilege level 3, but " +"the BTX server runs in privilege level 0, a TSS must be defined:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1043 +#, no-wrap +msgid "" +"/*\n" +" * Initialize TSS.\n" +" */\n" +"init.4:\t\tmovb $_ESP0H,TSS_ESP0+1(%di)\t# Set ESP0\n" +"\t\tmovb $SEL_SDATA,TSS_SS0(%di)\t# Set SS0\n" +"\t\tmovb $_TSSIO,TSS_MAP(%di)\t# Set I/O bit map base\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1045 +#, no-wrap +msgid "[.filename]#stand/i386/btx/btx/btx.S# [[btx-tss]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1049 +msgid "" +"Note that a value is given for the Privilege Level 0 stack pointer and stack " +"segment in the TSS. This is needed because, if an interrupt or exception is " +"received while executing [.filename]#boot2# in Privilege Level 3, a change " +"to Privilege Level 0 is automatically performed by the processor, so a new " +"working stack is needed. Finally, the I/O Map Base Address field of the TSS " +"is given a value, which is a 16-bit offset from the beginning of the TSS to " +"the I/O Permission Bitmap and the Interrupt Redirection Bitmap." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1052 +msgid "" +"After the IDT and TSS are created, the processor is ready to switch to " +"protected mode. This is done in the next block:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1070 +#, no-wrap +msgid "" +"/*\n" +" * Bring up the system.\n" +" */\n" +"\t\tmov $0x2820,%bx\t\t\t# Set protected mode\n" +"\t\tcallw setpic\t\t\t# IRQ offsets\n" +"\t\tlidt idtdesc\t\t\t# Set IDT\n" +"\t\tlgdt gdtdesc\t\t\t# Set GDT\n" +"\t\tmov %cr0,%eax\t\t\t# Switch to protected\n" +"\t\tinc %ax\t\t\t\t# mode\n" +"\t\tmov %eax,%cr0\t\t\t#\n" +"\t\tljmp $SEL_SCODE,$init.8\t\t# To 32-bit code\n" +"\t\t.code32\n" +"init.8:\t\txorl %ecx,%ecx\t\t\t# Zero\n" +"\t\tmovb $SEL_SDATA,%cl\t\t# To 32-bit\n" +"\t\tmovw %cx,%ss\t\t\t# stack\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1072 +#, no-wrap +msgid "[.filename]#stand/i386/btx/btx/btx.S# [[btx-prot]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1085 +msgid "" +"First, a call is made to `setpic` to program the 8259A PIC (Programmable " +"Interrupt Controller). This chip is connected to multiple hardware " +"interrupt sources. Upon receiving an interrupt from a device, it signals " +"the processor with the appropriate interrupt vector. This can be customized " +"so that specific interrupts are associated with specific interrupt vectors, " +"as explained before. Next, the IDTR (Interrupt Descriptor Table Register) " +"and GDTR (Global Descriptor Table Register) are loaded with the instructions " +"`lidt` and `lgdt`, respectively. These registers are loaded with the base " +"address and limit address for the IDT and GDT. The following three " +"instructions set the Protection Enable (PE) bit of the `%cr0` register. " +"This effectively switches the processor to 32-bit protected mode. Next, a " +"long jump is made to `init.8` using segment selector SEL_SCODE, which " +"selects the Supervisor Code Segment. The processor is effectively executing " +"in CPL 0, the most privileged level, after this jump. Finally, the " +"Supervisor Data Segment is selected for the stack by assigning the segment " +"selector SEL_SDATA to the `%ss` register. This data segment also has a " +"privilege level of `0`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1087 +msgid "" +"Our last code block is responsible for loading the TR (Task Register) with " +"the segment selector for the TSS we created earlier, and setting the User " +"Mode environment before passing execution control to the [.filename]#boot2# " +"client." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1123 +#, no-wrap +msgid "" +"/*\n" +" * Launch user task.\n" +" */\n" +"\t\tmovb $SEL_TSS,%cl\t\t# Set task\n" +"\t\tltr %cx\t\t\t\t# register\n" +"\t\tmovl $MEM_USR,%edx\t\t# User base address\n" +"\t\tmovzwl %ss:BDA_MEM,%eax\t\t# Get free memory\n" +"\t\tshll $0xa,%eax\t\t\t# To bytes\n" +"\t\tsubl $ARGSPACE,%eax\t\t# Less arg space\n" +"\t\tsubl %edx,%eax\t\t\t# Less base\n" +"\t\tmovb $SEL_UDATA,%cl\t\t# User data selector\n" +"\t\tpushl %ecx\t\t\t# Set SS\n" +"\t\tpushl %eax\t\t\t# Set ESP\n" +"\t\tpush $0x202\t\t\t# Set flags (IF set)\n" +"\t\tpush $SEL_UCODE\t\t\t# Set CS\n" +"\t\tpushl btx_hdr+0xc\t\t# Set EIP\n" +"\t\tpushl %ecx\t\t\t# Set GS\n" +"\t\tpushl %ecx\t\t\t# Set FS\n" +"\t\tpushl %ecx\t\t\t# Set DS\n" +"\t\tpushl %ecx\t\t\t# Set ES\n" +"\t\tpushl %edx\t\t\t# Set EAX\n" +"\t\tmovb $0x7,%cl\t\t\t# Set remaining\n" +"init.9:\t\tpush $0x0\t\t\t# general\n" +"\t\tloop init.9\t\t\t# registers\n" +"#ifdef BTX_SERIAL\n" +"\t\tcall sio_init\t\t\t# setup the serial console\n" +"#endif\n" +"\t\tpopa\t\t\t\t# and initialize\n" +"\t\tpopl %es\t\t\t# Initialize\n" +"\t\tpopl %ds\t\t\t# user\n" +"\t\tpopl %fs\t\t\t# segment\n" +"\t\tpopl %gs\t\t\t# registers\n" +"\t\tiret\t\t\t\t# To user mode\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1125 +#, no-wrap +msgid "[.filename]#stand/i386/btx/btx/btx.S# [[btx-end]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1149 +msgid "" +"Note that the client's environment include a stack segment selector and " +"stack pointer (registers `%ss` and `%esp`). Indeed, once the TR is loaded " +"with the appropriate stack segment selector (instruction `ltr`), the stack " +"pointer is calculated and pushed onto the stack along with the stack's " +"segment selector. Next, the value `0x202` is pushed onto the stack; it is " +"the value that the EFLAGS will get when control is passed to the client. " +"Also, the User Mode code segment selector and the client's entry point are " +"pushed. Recall that this entry point is patched in the BTX header at link " +"time. Finally, segment selectors (stored in register `%ecx`) for the " +"segment registers `%gs, %fs, %ds and %es` are pushed onto the stack, along " +"with the value at `%edx` (`0xa000`). Keep in mind the various values that " +"have been pushed onto the stack (they will be popped out shortly). Next, " +"values for the remaining general purpose registers are also pushed onto the " +"stack (note the `loop` that pushes the value `0` seven times). Now, values " +"will be started to be popped out of the stack. First, the `popa` " +"instruction pops out of the stack the latest seven values pushed. They are " +"stored in the general purpose registers in order `%edi, %esi, %ebp, %ebx, " +"%edx, %ecx, %eax`. Then, the various segment selectors pushed are popped " +"into the various segment registers. Five values still remain on the stack. " +"They are popped when the `iret` instruction is executed. This instruction " +"first pops the value that was pushed from the BTX header. This value is a " +"pointer to [.filename]#boot2#'s entry point. It is placed in the register " +"`%eip`, the instruction pointer register. Next, the segment selector for " +"the User Code Segment is popped and copied to register `%cs`. Remember that " +"this segment's privilege level is 3, the least privileged level. This means " +"that we must provide values for the stack of this privilege level. This is " +"why the processor, besides further popping the value for the EFLAGS " +"register, does two more pops out of the stack. These values go to the stack " +"pointer (`%esp`) and the stack segment (`%ss`). Now, execution continues at " +"``boot0``'s entry point." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1153 +msgid "" +"It is important to note how the User Code Segment is defined. This " +"segment's _base address_ is set to `0xa000`. This means that code memory " +"addresses are _relative_ to address 0xa000; if code being executed is " +"fetched from address `0x2000`, the _actual_ memory addressed is " +"`0xa000+0x2000=0xc000`." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1155 +#, no-wrap +msgid "boot2 Stage" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1162 +msgid "" +"`boot2` defines an important structure, `struct bootinfo`. This structure " +"is initialized by `boot2` and passed to the loader, and then further to the " +"kernel. Some nodes of this structures are set by `boot2`, the rest by the " +"loader. This structure, among other information, contains the kernel " +"filename, BIOS harddisk geometry, BIOS drive number for boot device, " +"physical memory available, `envp` pointer etc. The definition for it is:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1187 +#, no-wrap +msgid "" +"/usr/include/machine/bootinfo.h:\n" +"struct bootinfo {\n" +"\tu_int32_t\tbi_version;\n" +"\tu_int32_t\tbi_kernelname;\t\t/* represents a char * */\n" +"\tu_int32_t\tbi_nfs_diskless;\t/* struct nfs_diskless * */\n" +"\t\t\t\t/* End of fields that are always present. */\n" +"#define\tbi_endcommon\tbi_n_bios_used\n" +"\tu_int32_t\tbi_n_bios_used;\n" +"\tu_int32_t\tbi_bios_geom[N_BIOS_GEOM];\n" +"\tu_int32_t\tbi_size;\n" +"\tu_int8_t\tbi_memsizes_valid;\n" +"\tu_int8_t\tbi_bios_dev;\t\t/* bootdev BIOS unit number */\n" +"\tu_int8_t\tbi_pad[2];\n" +"\tu_int32_t\tbi_basemem;\n" +"\tu_int32_t\tbi_extmem;\n" +"\tu_int32_t\tbi_symtab;\t\t/* struct symtab * */\n" +"\tu_int32_t\tbi_esymtab;\t\t/* struct symtab * */\n" +"\t\t\t\t/* Items below only from advanced bootloader */\n" +"\tu_int32_t\tbi_kernend;\t\t/* end of kernel space */\n" +"\tu_int32_t\tbi_envp;\t\t/* environment */\n" +"\tu_int32_t\tbi_modulep;\t\t/* preloaded modules */\n" +"};\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1194 +msgid "" +"`boot2` enters into an infinite loop waiting for user input, then calls " +"`load()`. If the user does not press anything, the loop breaks by a " +"timeout, so `load()` will load the default file ([.filename]#/boot/" +"loader#). Functions `ino_t lookup(char *filename)` and `int xfsread(ino_t " +"inode, void *buf, size_t nbyte)` are used to read the content of a file into " +"memory. [.filename]#/boot/loader# is an ELF binary, but where the ELF " +"header is prepended with [.filename]#a.out#'s `struct exec` structure. " +"`load()` scans the loader's ELF header, loading the content of [.filename]#/" +"boot/loader# into memory, and passing the execution to the loader's entry:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1201 +#, no-wrap +msgid "" +"stand/i386/boot2/boot2.c:\n" +" __exec((caddr_t)addr, RB_BOOTINFO | (opts & RBX_MASK),\n" +"\t MAKEBOOTDEV(dev_maj[dsk.type], dsk.slice, dsk.unit, dsk.part),\n" +"\t 0, 0, 0, VTOP(&bootinfo));\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1204 +#, no-wrap +msgid "loader Stage" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1209 +msgid "" +"loader is a BTX client as well. I will not describe it here in detail, " +"there is a comprehensive man page written by Mike Smith, man:loader[8]. The " +"underlying mechanisms and BTX were discussed above." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1212 +msgid "" +"The main task for the loader is to boot the kernel. When the kernel is " +"loaded into memory, it is being called by the loader:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1218 +#, no-wrap +msgid "" +"stand/common/boot.c:\n" +" /* Call the exec handler from the loader matching the kernel */\n" +" file_formats[fp->f_loader]->l_exec(fp);\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1221 +#, no-wrap +msgid "Kernel Initialization" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1228 +msgid "" +"Let us take a look at the command that links the kernel. This will help " +"identify the exact location where the loader passes execution to the " +"kernel. This location is the kernel's actual entry point. This command is " +"now excluded from [.filename]#sys/conf/Makefile.i386#. The content that " +"interests us can be found in [.filename]#/usr/obj/usr/src/i386.i386/sys/" +"GENERIC/#." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1235 +#, no-wrap +msgid "" +"/usr/obj/usr/src/i386.i386/sys/GENERIC/kernel.meta:\n" +"ld -m elf_i386_fbsd -Bdynamic -T /usr/src/sys/conf/ldscript.i386 --build-id=sha1 --no-warn-mismatch \\\n" +"--warn-common --export-dynamic --dynamic-linker /red/herring -X -o kernel locore.o\n" +"<lots of kernel .o files>\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1241 +msgid "" +"A few interesting things can be seen here. First, the kernel is an ELF " +"dynamically linked binary, but the dynamic linker for kernel is [.filename]#/" +"red/herring#, which is definitely a bogus file. Second, taking a look at " +"the file [.filename]#sys/conf/ldscript.i386# gives an idea about what ld " +"options are used when compiling a kernel. Reading through the first few " +"lines, the string" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1246 +#, no-wrap +msgid "" +"sys/conf/ldscript.i386:\n" +"ENTRY(btext)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1250 +msgid "" +"says that a kernel's entry point is the symbol `btext`. This symbol is " +"defined in [.filename]#locore.s#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1261 +#, no-wrap +msgid "" +"sys/i386/i386/locore.s:\n" +"\t.text\n" +"/**********************************************************************\n" +" *\n" +" * This is where the bootblocks start us, set the ball rolling...\n" +" *\n" +" */\n" +"NON_GPROF_ENTRY(btext)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1265 +msgid "" +"First, the register EFLAGS is set to a predefined value of 0x00000002. Then " +"all the segment registers are initialized:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1272 +#, no-wrap +msgid "" +"sys/i386/i386/locore.s:\n" +"/* Don't trust what the BIOS gives for eflags. */\n" +"\tpushl\t$PSL_KERNEL\n" +"\tpopfl\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1280 +#, no-wrap +msgid "" +"/*\n" +" * Don't trust what the BIOS gives for %fs and %gs. Trust the bootstrap\n" +" * to set %cs, %ds, %es and %ss.\n" +" */\n" +"\tmov\t%ds, %ax\n" +"\tmov\t%ax, %fs\n" +"\tmov\t%ax, %gs\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1284 +msgid "" +"btext calls the routines `recover_bootinfo()`, `identify_cpu()`, which are " +"also defined in [.filename]#locore.s#. Here is a description of what they " +"do:" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1290 +#, no-wrap +msgid "`recover_bootinfo`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1294 +#, no-wrap +msgid "" +"This routine parses the parameters to the kernel passed from the bootstrap.\n" +"The kernel may have been booted in 3 ways: by the loader, described above, by the old disk boot blocks, or by the old diskless boot procedure.\n" +"This function determines the booting method, and stores the `struct bootinfo` structure into the kernel memory." +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1295 +#, no-wrap +msgid "`identify_cpu`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1296 +#, no-wrap +msgid "This function tries to find out what CPU it is running on, storing the value found in a variable `_cpu`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1299 +msgid "The next steps are enabling VME, if the CPU supports it:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1307 +#, no-wrap +msgid "" +"sys/i386/i386/mpboot.s:\n" +"\ttestl\t$CPUID_VME,%edx\n" +"\tjz\t3f\n" +"\torl\t$CR4_VME,%eax\n" +"3:\tmovl\t%eax,%cr4\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1310 +msgid "Then, enabling paging:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1320 +#, no-wrap +msgid "" +"sys/i386/i386/mpboot.s:\n" +"/* Now enable paging */\n" +"\tmovl\tIdlePTD_nopae, %eax\n" +"\tmovl\t%eax,%cr3\t\t\t/* load ptd addr into mmu */\n" +"\tmovl\t%cr0,%eax\t\t\t/* get control word */\n" +"\torl\t$CR0_PE|CR0_PG,%eax\t\t/* enable paging */\n" +"\tmovl\t%eax,%cr0\t\t\t/* and let's page NOW! */\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1323 +msgid "" +"The next three lines of code are because the paging was set, so the jump is " +"needed to continue the execution in virtualized address space:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1329 +#, no-wrap +msgid "" +"sys/i386/i386/mpboot.s:\n" +"\tpushl\t$mp_begin\t\t\t\t/* jump to high mem */\n" +"\tret\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1332 +#, no-wrap +msgid "" +"/* now running relocated at KERNBASE where the system is linked to run */\n" +"mp_begin:\t/* now running relocated at KERNBASE */\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1337 +msgid "" +"The function `init386()` is called with a pointer to the first free physical " +"page, after that `mi_startup()`. `init386` is an architecture dependent " +"initialization function, and `mi_startup()` is an architecture independent " +"one (the 'mi_' prefix stands for Machine Independent). The kernel never " +"returns from `mi_startup()`, and by calling it, the kernel finishes booting:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1347 +#, no-wrap +msgid "" +"sys/i386/i386/locore.s:\n" +"\tpushl\tphysfree\t\t\t/* value of first for init386(first) */\n" +"\tcall\tinit386\t\t\t\t/* wire 386 chip for unix operation */\n" +"\taddl\t$4,%esp\n" +"\tmovl\t%eax,%esp\t\t\t/* Switch to true top of stack. */\n" +"\tcall\tmi_startup\t\t\t/* autoconfiguration, mountroot etc */\n" +"\t/* NOTREACHED */\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1349 +#, no-wrap +msgid "`init386()`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1354 +msgid "" +"`init386()` is defined in [.filename]#sys/i386/i386/machdep.c# and performs " +"low-level initialization specific to the i386 chip. The switch to protected " +"mode was performed by the loader. The loader has created the very first " +"task, in which the kernel continues to operate. Before looking at the code, " +"consider the tasks the processor must complete to initialize protected mode " +"execution:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1356 +msgid "" +"Initialize the kernel tunable parameters, passed from the bootstrapping " +"program." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1357 +msgid "Prepare the GDT." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1358 +msgid "Prepare the IDT." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1359 +msgid "Initialize the system console." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1360 +msgid "Initialize the DDB, if it is compiled into kernel." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1361 +msgid "Initialize the TSS." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1362 +msgid "Prepare the LDT." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1363 +msgid "Set up thread0's pcb." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1366 +msgid "" +"`init386()` initializes the tunable parameters passed from bootstrap by " +"setting the environment pointer (envp) and calling `init_param1()`. The " +"envp pointer has been passed from loader in the `bootinfo` structure:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1372 +#, no-wrap +msgid "" +"sys/i386/i386/machdep.c:\n" +"\t/* Init basic tunables, hz etc */\n" +"\tinit_param1();\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1376 +msgid "" +"`init_param1()` is defined in [.filename]#sys/kern/subr_param.c#. That file " +"has a number of sysctls, and two functions, `init_param1()` and " +"`init_param2()`, that are called from `init386()`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1384 +#, no-wrap +msgid "" +"sys/kern/subr_param.c:\n" +"\thz = -1;\n" +"\tTUNABLE_INT_FETCH(\"kern.hz\", &hz);\n" +"\tif (hz == -1)\n" +"\t\thz = vm_guest > VM_GUEST_NO ? HZ_VM : HZ;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1387 +msgid "" +"TUNABLE_<typename>_FETCH is used to fetch the value from the environment:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1392 +#, no-wrap +msgid "" +"/usr/src/sys/sys/kernel.h:\n" +"#define\tTUNABLE_INT_FETCH(path, var)\tgetenv_int((path), (var))\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1396 +msgid "" +"Sysctl `kern.hz` is the system clock tick. Additionally, these sysctls are " +"set by `init_param1()`: `kern.maxswzone, kern.maxbcache, kern.maxtsiz, " +"kern.dfldsiz, kern.maxdsiz, kern.dflssiz, kern.maxssiz, kern.sgrowsiz`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1404 +msgid "" +"Then `init386()` prepares the Global Descriptors Table (GDT). Every task on " +"an x86 is running in its own virtual address space, and this space is " +"addressed by a segment:offset pair. Say, for instance, the current " +"instruction to be executed by the processor lies at CS:EIP, then the linear " +"virtual address for that instruction would be \"the virtual address of code " +"segment CS\" + EIP. For convenience, segments begin at virtual address 0 " +"and end at a 4GB boundary. Therefore, the instruction's linear virtual " +"address for this example would just be the value of EIP. Segment registers " +"such as CS, DS etc are the selectors, i.e., indexes, into GDT (to be more " +"precise, an index is not a selector itself, but the INDEX field of a " +"selector). FreeBSD's GDT holds descriptors for 15 selectors per CPU:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1410 +#, no-wrap +msgid "" +"sys/i386/i386/machdep.c:\n" +"union descriptor gdt0[NGDT];\t/* initial global descriptor table */\n" +"union descriptor *gdt = gdt0;\t/* global descriptor table */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1435 +#, no-wrap +msgid "" +"sys/x86/include/segments.h:\n" +"/*\n" +" * Entries in the Global Descriptor Table (GDT)\n" +" */\n" +"#define\tGNULL_SEL\t0\t/* Null Descriptor */\n" +"#define\tGPRIV_SEL\t1\t/* SMP Per-Processor Private Data */\n" +"#define\tGUFS_SEL\t2\t/* User %fs Descriptor (order critical: 1) */\n" +"#define\tGUGS_SEL\t3\t/* User %gs Descriptor (order critical: 2) */\n" +"#define\tGCODE_SEL\t4\t/* Kernel Code Descriptor (order critical: 1) */\n" +"#define\tGDATA_SEL\t5\t/* Kernel Data Descriptor (order critical: 2) */\n" +"#define\tGUCODE_SEL\t6\t/* User Code Descriptor (order critical: 3) */\n" +"#define\tGUDATA_SEL\t7\t/* User Data Descriptor (order critical: 4) */\n" +"#define\tGBIOSLOWMEM_SEL\t8\t/* BIOS low memory access (must be entry 8) */\n" +"#define\tGPROC0_SEL\t9\t/* Task state process slot zero and up */\n" +"#define\tGLDT_SEL\t10\t/* Default User LDT */\n" +"#define\tGUSERLDT_SEL\t11\t/* User LDT */\n" +"#define\tGPANIC_SEL\t12\t/* Task state to consider panic from */\n" +"#define\tGBIOSCODE32_SEL\t13\t/* BIOS interface (32bit Code) */\n" +"#define\tGBIOSCODE16_SEL\t14\t/* BIOS interface (16bit Code) */\n" +"#define\tGBIOSDATA_SEL\t15\t/* BIOS interface (Data) */\n" +"#define\tGBIOSUTIL_SEL\t16\t/* BIOS interface (Utility) */\n" +"#define\tGBIOSARGS_SEL\t17\t/* BIOS interface (Arguments) */\n" +"#define\tGNDIS_SEL\t18\t/* For the NDIS layer */\n" +"#define\tNGDT\t\t19\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1439 +msgid "" +"Note that those #defines are not selectors themselves, but just a field " +"INDEX of a selector, so they are exactly the indices of the GDT. for " +"example, an actual selector for the kernel code (GCODE_SEL) has the value " +"0x20." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1447 +msgid "" +"The next step is to initialize the Interrupt Descriptor Table (IDT). This " +"table is referenced by the processor when a software or hardware interrupt " +"occurs. For example, to make a system call, user application issues the " +"`INT 0x80` instruction. This is a software interrupt, so the processor's " +"hardware looks up a record with index 0x80 in the IDT. This record points " +"to the routine that handles this interrupt, in this particular case, this " +"will be the kernel's syscall gate. The IDT may have a maximum of 256 " +"(0x100) records. The kernel allocates NIDT records for the IDT, where NIDT " +"is the maximum (256):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1453 +#, no-wrap +msgid "" +"sys/i386/i386/machdep.c:\n" +"static struct gate_descriptor idt0[NIDT];\n" +"struct gate_descriptor *idt = &idt0[0];\t/* interrupt descriptor table */\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1457 +msgid "" +"For each interrupt, an appropriate handler is set. The syscall gate for " +"`INT 0x80` is set as well:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1463 +#, no-wrap +msgid "" +"sys/i386/i386/machdep.c:\n" +"\tsetidt(IDT_SYSCALL, &IDTVEC(int0x80_syscall),\n" +"\t\t\tSDT_SYS386IGT, SEL_UPL, GSEL(GCODE_SEL, SEL_KPL));\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1466 +msgid "" +"So when a userland application issues the `INT 0x80` instruction, control " +"will transfer to the function `_Xint0x80_syscall`, which is in the kernel " +"code segment and will be executed with supervisor privileges." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1468 +msgid "Console and DDB are then initialized:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1479 +#, no-wrap +msgid "" +"sys/i386/i386/machdep.c:\n" +"\tcninit();\n" +"/* skipped */\n" +" kdb_init();\n" +"#ifdef KDB\n" +"\tif (boothowto & RB_KDB)\n" +"\t\tkdb_enter(KDB_WHY_BOOTFLAGS, \"Boot flags requested debugger\");\n" +"#endif\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1482 +msgid "" +"The Task State Segment is another x86 protected mode structure, the TSS is " +"used by the hardware to store task information when a task switch occurs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1485 +msgid "" +"The Local Descriptors Table is used to reference userland code and data. " +"Several selectors are defined to point to the LDT, they are the system call " +"gates and the user code and data selectors:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1494 +#, no-wrap +msgid "" +"sys/x86/include/segments.h:\n" +"#define\tLSYS5CALLS_SEL\t0\t/* forced by intel BCS */\n" +"#define\tLSYS5SIGR_SEL\t1\n" +"#define\tLUCODE_SEL\t3\n" +"#define\tLUDATA_SEL\t5\n" +"#define\tNLDT\t\t(LUDATA_SEL + 1)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1499 +msgid "" +"Next, proc0's Process Control Block (`struct pcb`) structure is " +"initialized. proc0 is a `struct proc` structure that describes a kernel " +"process. It is always present while the kernel is running, therefore it is " +"linked with thread0:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1507 +#, no-wrap +msgid "" +"sys/i386/i386/machdep.c:\n" +"register_t\n" +"init386(int first)\n" +"{\n" +" /* ... skipped ... */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1511 +#, no-wrap +msgid "" +" proc_linkup0(&proc0, &thread0);\n" +" /* ... skipped ... */\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1515 +msgid "" +"The structure `struct pcb` is a part of a proc structure. It is defined in " +"[.filename]#/usr/include/machine/pcb.h# and has a process's information " +"specific to the i386 architecture, such as registers values." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1516 +#, no-wrap +msgid "`mi_startup()`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1519 +msgid "" +"This function performs a bubble sort of all the system initialization " +"objects and then calls the entry of each object one by one:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1524 +#, no-wrap +msgid "" +"sys/kern/init_main.c:\n" +"\tfor (sipp = sysinit; sipp < sysinit_end; sipp++) {\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1526 +#, no-wrap +msgid "\t\t/* ... skipped ... */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1531 +#, no-wrap +msgid "" +"\t\t/* Call function */\n" +"\t\t(*((*sipp)->func))((*sipp)->udata);\n" +"\t\t/* ... skipped ... */\n" +"\t}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1534 +msgid "" +"Although the sysinit framework is described in the link:/books/developers-" +"handbook[Developers' Handbook], I will discuss the internals of it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1538 +msgid "" +"Every system initialization object (sysinit object) is created by calling a " +"SYSINIT() macro. Let us take as example an `announce` sysinit object. This " +"object prints the copyright message:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1549 +#, no-wrap +msgid "" +"sys/kern/init_main.c:\n" +"static void\n" +"print_caddr_t(void *data __unused)\n" +"{\n" +"\tprintf(\"%s\", (char *)data);\n" +"}\n" +"/* ... skipped ... */\n" +"SYSINIT(announce, SI_SUB_COPYRIGHT, SI_ORDER_FIRST, print_caddr_t, copyright);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1553 +msgid "" +"The subsystem ID for this object is SI_SUB_COPYRIGHT (0x0800001). So, the " +"copyright message will be printed out first, just after the console " +"initialization." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1557 +msgid "" +"Let us take a look at what exactly the macro `SYSINIT()` does. It expands " +"to a `C_SYSINIT()` macro. The `C_SYSINIT()` macro then expands to a static " +"`struct sysinit` structure declaration with another `DATA_SET` macro call:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1565 +#, no-wrap +msgid "" +"/usr/include/sys/kernel.h:\n" +" #define C_SYSINIT(uniquifier, subsystem, order, func, ident) \\\n" +" static struct sysinit uniquifier ## _sys_init = { \\ subsystem, \\\n" +" order, \\ func, \\ (ident) \\ }; \\ DATA_WSET(sysinit_set,uniquifier ##\n" +" _sys_init);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1569 +#, no-wrap +msgid "" +"#define\tSYSINIT(uniquifier, subsystem, order, func, ident)\t\\\n" +"\tC_SYSINIT(uniquifier, subsystem, order,\t\t\t\\\n" +"\t(sysinit_cfunc_t)(sysinit_nfunc_t)func, (void *)(ident))\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1572 +msgid "" +"The `DATA_SET()` macro expands to a `_MAKE_SET()`, and that macro is the " +"point where all the sysinit magic is hidden:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1578 +#, no-wrap +msgid "" +"/usr/include/linker_set.h:\n" +"#define TEXT_SET(set, sym) _MAKE_SET(set, sym)\n" +"#define DATA_SET(set, sym) _MAKE_SET(set, sym)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1582 +msgid "" +"After executing these macros, various sections were made in the kernel, " +"including`set.sysinit_set`. Running objdump on a kernel binary, you may " +"notice the presence of such small sections:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1594 +#, no-wrap +msgid "" +"% llvm-objdump -h /kernel\n" +"Sections:\n" +"Idx Name Size VMA Type\n" +" 10 set_sysctl_set 000021d4 01827078 DATA\n" +" 16 set_kbddriver_set 00000010 0182a4d0 DATA\n" +" 20 set_scterm_set 0000000c 0182c75c DATA\n" +" 21 set_cons_set 00000014 0182c768 DATA\n" +" 33 set_scrndr_set 00000024 0182c828 DATA\n" +" 41 set_sysinit_set 000014d8 018fabb0 DATA\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1598 +msgid "" +"This screen dump shows that the size of set.sysinit_set section is 0x14d8 " +"bytes, so `0x14d8/sizeof(void *)` sysinit objects are compiled into the " +"kernel. The other sections such as `set.sysctl_set` represent other linker " +"sets." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1600 +msgid "" +"By defining a variable of type `struct sysinit` the content of " +"`set.sysinit_set` section will be \"collected\" into that variable:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1605 +#, no-wrap +msgid "" +"sys/kern/init_main.c:\n" +" SET_DECLARE(sysinit_set, struct sysinit);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1608 +msgid "The `struct sysinit` is defined as follows:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1618 +#, no-wrap +msgid "" +"sys/sys/kernel.h:\n" +" struct sysinit {\n" +"\tenum sysinit_sub_id\tsubsystem;\t/* subsystem identifier*/\n" +"\tenum sysinit_elem_order\torder;\t\t/* init order within subsystem*/\n" +"\tsysinit_cfunc_t func;\t\t\t/* function\t\t*/\n" +"\tconst void\t*udata;\t\t\t/* multiplexer/argument */\n" +"};\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1623 +msgid "" +"Returning to the `mi_startup()` discussion, it is must be clear now, how the " +"sysinit objects are being organized. The `mi_startup()` function sorts them " +"and calls each. The very last object is the system scheduler:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1635 +#, no-wrap +msgid "" +"/usr/include/sys/kernel.h:\n" +"enum sysinit_sub_id {\n" +"\tSI_SUB_DUMMY\t\t= 0x0000000,\t/* not executed; for linker*/\n" +"\tSI_SUB_DONE\t\t= 0x0000001,\t/* processed*/\n" +"\tSI_SUB_TUNABLES\t\t= 0x0700000,\t/* establish tunable values */\n" +"\tSI_SUB_COPYRIGHT\t= 0x0800001,\t/* first use of console*/\n" +"...\n" +"\tSI_SUB_LAST\t\t= 0xfffffff\t/* final initialization */\n" +"};\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1640 +msgid "" +"The system scheduler sysinit object is defined in the file [.filename]#sys/" +"vm/vm_glue.c#, and the entry point for that object is `scheduler()`. That " +"function is actually an infinite loop, and it represents a process with PID " +"0, the swapper process. The thread0 structure, mentioned before, is used to " +"describe it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1642 +msgid "" +"The first user process, called _init_, is created by the sysinit object " +"`init`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1653 +#, no-wrap +msgid "" +"sys/kern/init_main.c:\n" +"static void\n" +"create_init(const void *udata __unused)\n" +"{\n" +"\tstruct fork_req fr;\n" +"\tstruct ucred *newcred, *oldcred;\n" +"\tstruct thread *td;\n" +"\tint error;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1686 +#, no-wrap +msgid "" +"\tbzero(&fr, sizeof(fr));\n" +"\tfr.fr_flags = RFFDG | RFPROC | RFSTOPPED;\n" +"\tfr.fr_procp = &initproc;\n" +"\terror = fork1(&thread0, &fr);\n" +"\tif (error)\n" +"\t\tpanic(\"cannot fork init: %d\\n\", error);\n" +"\tKASSERT(initproc->p_pid == 1, (\"create_init: initproc->p_pid != 1\"));\n" +"\t/* divorce init's credentials from the kernel's */\n" +"\tnewcred = crget();\n" +"\tsx_xlock(&proctree_lock);\n" +"\tPROC_LOCK(initproc);\n" +"\tinitproc->p_flag |= P_SYSTEM | P_INMEM;\n" +"\tinitproc->p_treeflag |= P_TREE_REAPER;\n" +"\toldcred = initproc->p_ucred;\n" +"\tcrcopy(newcred, oldcred);\n" +"#ifdef MAC\n" +"\tmac_cred_create_init(newcred);\n" +"#endif\n" +"#ifdef AUDIT\n" +"\taudit_cred_proc1(newcred);\n" +"#endif\n" +"\tproc_set_cred(initproc, newcred);\n" +"\ttd = FIRST_THREAD_IN_PROC(initproc);\n" +"\tcrcowfree(td);\n" +"\ttd->td_realucred = crcowget(initproc->p_ucred);\n" +"\ttd->td_ucred = td->td_realucred;\n" +"\tPROC_UNLOCK(initproc);\n" +"\tsx_xunlock(&proctree_lock);\n" +"\tcrfree(oldcred);\n" +"\tcpu_fork_kthread_handler(FIRST_THREAD_IN_PROC(initproc), start_init, NULL);\n" +"}\n" +"SYSINIT(init, SI_SUB_CREATE_INIT, SI_ORDER_FIRST, create_init, NULL);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1692 +msgid "" +"The function `create_init()` allocates a new process by calling `fork1()`, " +"but does not mark it runnable. When this new process is scheduled for " +"execution by the scheduler, the `start_init()` will be called. That " +"function is defined in [.filename]#init_main.c#. It tries to load and exec " +"the [.filename]#init# binary, probing [.filename]#/sbin/init# first, then " +"[.filename]#/sbin/oinit#, [.filename]#/sbin/init.bak#, and finally " +"[.filename]#/rescue/init#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1702 +#, no-wrap +msgid "" +"sys/kern/init_main.c:\n" +"static char init_path[MAXPATHLEN] =\n" +"#ifdef\tINIT_PATH\n" +" __XSTRING(INIT_PATH);\n" +"#else\n" +" \"/sbin/init:/sbin/oinit:/sbin/init.bak:/rescue/init\";\n" +"#endif\n" +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/driverbasics/_index.adoc b/documentation/content/en/books/arch-handbook/driverbasics/_index.adoc index acaca6502e..b55be854c3 100644 --- a/documentation/content/en/books/arch-handbook/driverbasics/_index.adoc +++ b/documentation/content/en/books/arch-handbook/driverbasics/_index.adoc @@ -6,7 +6,8 @@ description: Writing FreeBSD Device Drivers tags: ["writing", "device drivers", "KLD", "FreeBSD"] showBookMenu: true weight: 11 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/driverbasics/" --- [[driverbasics]] @@ -90,28 +91,28 @@ Skeleton Layout of a kernel module static int skel_loader(struct module *m, int what, void *arg) { - int err = 0; - - switch (what) { - case MOD_LOAD: /* kldload */ - uprintf("Skeleton KLD loaded.\n"); - break; - case MOD_UNLOAD: - uprintf("Skeleton KLD unloaded.\n"); - break; - default: - err = EOPNOTSUPP; - break; - } - return(err); + int err = 0; + + switch (what) { + case MOD_LOAD: /* kldload */ + uprintf("Skeleton KLD loaded.\n"); + break; + case MOD_UNLOAD: + uprintf("Skeleton KLD unloaded.\n"); + break; + default: + err = EOPNOTSUPP; + break; + } + return(err); } /* Declare this module to the rest of the kernel */ static moduledata_t skel_mod = { - "skel", - skel_loader, - NULL + "skel", + skel_loader, + NULL }; DECLARE_MODULE(skeleton, skel_mod, SI_SUB_KLD, SI_ORDER_ANY); @@ -343,4 +344,4 @@ For this reason, no serious applications rely on block devices, and in fact, alm Drivers for network devices do not use device nodes in order to be accessed. Their selection is based on other decisions made inside the kernel and instead of calling open(), use of a network device is generally introduced by using the system call socket(2). -For more information see ifnet(9), the source of the loopback device, and Bill Paul's network drivers. +For more information see ifnet(9), the source of the loopback device. diff --git a/documentation/content/en/books/arch-handbook/driverbasics/_index.po b/documentation/content/en/books/arch-handbook/driverbasics/_index.po new file mode 100644 index 0000000000..d4b715c1a0 --- /dev/null +++ b/documentation/content/en/books/arch-handbook/driverbasics/_index.po @@ -0,0 +1,632 @@ +# 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/driverbasics/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:14 +#, no-wrap +msgid "Writing FreeBSD Device Drivers" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:1 +#, no-wrap +msgid "Chapter 9. Writing FreeBSD Device Drivers" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:52 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:55 +msgid "" +"This chapter provides a brief introduction to writing device drivers for " +"FreeBSD. A device in this context is a term used mostly for hardware-related " +"stuff that belongs to the system, like disks, printers, or a graphics " +"display with its keyboard. A device driver is the software component of the " +"operating system that controls a specific device. There are also so-called " +"pseudo-devices where a device driver emulates the behavior of a device in " +"software without any particular underlying hardware. Device drivers can be " +"compiled into the system statically or loaded on demand through the dynamic " +"kernel linker facility `kld'." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:57 +msgid "" +"Most devices in a UNIX(R)-like operating system are accessed through device-" +"nodes, sometimes also called special files. These files are usually located " +"under the directory [.filename]#/dev# in the filesystem hierarchy." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:59 +msgid "" +"Device drivers can roughly be broken down into two categories; character and " +"network device drivers." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:61 +#, no-wrap +msgid "Dynamic Kernel Linker Facility - KLD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:64 +msgid "" +"The kld interface allows system administrators to dynamically add and remove " +"functionality from a running system. This allows device driver writers to " +"load their new changes into a running kernel without constantly rebooting to " +"test changes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:66 +msgid "The kld interface is used through:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:68 +msgid "`kldload` - loads a new kernel module" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:69 +msgid "`kldunload` - unloads a kernel module" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:70 +msgid "`kldstat` - lists loaded modules" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:72 +msgid "Skeleton Layout of a kernel module" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:79 +#, no-wrap +msgid "" +"/*\n" +" * KLD Skeleton\n" +" * Inspired by Andrew Reiter's Daemonnews article\n" +" */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:86 +#, no-wrap +msgid "" +"#include <sys/types.h>\n" +"#include <sys/systm.h> /* uprintf */\n" +"#include <sys/errno.h>\n" +"#include <sys/param.h> /* defines used in kernel.h */\n" +"#include <sys/module.h>\n" +"#include <sys/kernel.h> /* types used in module initialization */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:90 +#, no-wrap +msgid "" +"/*\n" +" * Load handler that deals with the loading and unloading of a KLD.\n" +" */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:95 +#, no-wrap +msgid "" +"static int\n" +"skel_loader(struct module *m, int what, void *arg)\n" +"{\n" +"\tint err = 0;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:109 +#, no-wrap +msgid "" +"\tswitch (what) {\n" +"\tcase MOD_LOAD: /* kldload */\n" +"\t\tuprintf(\"Skeleton KLD loaded.\\n\");\n" +"\t\tbreak;\n" +"\tcase MOD_UNLOAD:\n" +"\t\tuprintf(\"Skeleton KLD unloaded.\\n\");\n" +"\t\tbreak;\n" +"\tdefault:\n" +"\t\terr = EOPNOTSUPP;\n" +"\t\tbreak;\n" +"\t}\n" +"\treturn(err);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:111 +#, no-wrap +msgid "/* Declare this module to the rest of the kernel */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:117 +#, no-wrap +msgid "" +"static moduledata_t skel_mod = {\n" +"\t\"skel\",\n" +"\tskel_loader,\n" +"\tNULL\n" +"};\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:119 +#, no-wrap +msgid "DECLARE_MODULE(skeleton, skel_mod, SI_SUB_KLD, SI_ORDER_ANY);\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:121 +#, no-wrap +msgid "Makefile" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:124 +msgid "" +"FreeBSD provides a system makefile to simplify compiling a kernel module." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:129 +#, no-wrap +msgid "" +"SRCS=skeleton.c\n" +"KMOD=skeleton\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:131 +#, no-wrap +msgid ".include <bsd.kmod.mk>\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:134 +msgid "" +"Running `make` with this makefile will create a file " +"[.filename]#skeleton.ko# that can be loaded into the kernel by typing:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:138 +#, no-wrap +msgid "# kldload -v ./skeleton.ko\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:141 +#, no-wrap +msgid "Character Devices" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:144 +msgid "" +"A character device driver is one that transfers data directly to and from a " +"user process. This is the most common type of device driver and there are " +"plenty of simple examples in the source tree." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:146 +msgid "" +"This simple example pseudo-device remembers whatever values are written to " +"it and can then echo them back when read." +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:147 +#, no-wrap +msgid "Example of a Sample Echo Pseudo-Device Driver for FreeBSD 10.X - 12.X" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:159 +#, no-wrap +msgid "" +"/*\n" +" * Simple Echo pseudo-device KLD\n" +" *\n" +" * Murray Stokely\n" +" * Søren (Xride) Straarup\n" +" * Eitan Adler\n" +" */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:168 +#, no-wrap +msgid "" +"#include <sys/types.h>\n" +"#include <sys/systm.h> /* uprintf */\n" +"#include <sys/param.h> /* defines used in kernel.h */\n" +"#include <sys/module.h>\n" +"#include <sys/kernel.h> /* types used in module initialization */\n" +"#include <sys/conf.h> /* cdevsw struct */\n" +"#include <sys/uio.h> /* uio struct */\n" +"#include <sys/malloc.h>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:170 +#, no-wrap +msgid "#define BUFFERSIZE 255\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:176 +#, no-wrap +msgid "" +"/* Function prototypes */\n" +"static d_open_t echo_open;\n" +"static d_close_t echo_close;\n" +"static d_read_t echo_read;\n" +"static d_write_t echo_write;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:186 +#, no-wrap +msgid "" +"/* Character device entry points */\n" +"static struct cdevsw echo_cdevsw = {\n" +"\t.d_version = D_VERSION,\n" +"\t.d_open = echo_open,\n" +"\t.d_close = echo_close,\n" +"\t.d_read = echo_read,\n" +"\t.d_write = echo_write,\n" +"\t.d_name = \"echo\",\n" +"};\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:191 +#, no-wrap +msgid "" +"struct s_echo {\n" +"\tchar msg[BUFFERSIZE + 1];\n" +"\tint len;\n" +"};\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:195 +#, no-wrap +msgid "" +"/* vars */\n" +"static struct cdev *echo_dev;\n" +"static struct s_echo *echomsg;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:198 +#, no-wrap +msgid "" +"MALLOC_DECLARE(M_ECHOBUF);\n" +"MALLOC_DEFINE(M_ECHOBUF, \"echobuffer\", \"buffer for echo module\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:207 +#, no-wrap +msgid "" +"/*\n" +" * This function is called by the kld[un]load(2) system calls to\n" +" * determine what actions to take when a module is loaded or unloaded.\n" +" */\n" +"static int\n" +"echo_loader(struct module *m __unused, int what, void *arg __unused)\n" +"{\n" +"\tint error = 0;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:220 +#, no-wrap +msgid "" +"\tswitch (what) {\n" +"\tcase MOD_LOAD: /* kldload */\n" +"\t\terror = make_dev_p(MAKEDEV_CHECKNAME | MAKEDEV_WAITOK,\n" +"\t\t &echo_dev,\n" +"\t\t &echo_cdevsw,\n" +"\t\t 0,\n" +"\t\t UID_ROOT,\n" +"\t\t GID_WHEEL,\n" +"\t\t 0600,\n" +"\t\t \"echo\");\n" +"\t\tif (error != 0)\n" +"\t\t\tbreak;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:236 +#, no-wrap +msgid "" +"\t\techomsg = malloc(sizeof(*echomsg), M_ECHOBUF, M_WAITOK |\n" +"\t\t M_ZERO);\n" +"\t\tprintf(\"Echo device loaded.\\n\");\n" +"\t\tbreak;\n" +"\tcase MOD_UNLOAD:\n" +"\t\tdestroy_dev(echo_dev);\n" +"\t\tfree(echomsg, M_ECHOBUF);\n" +"\t\tprintf(\"Echo device unloaded.\\n\");\n" +"\t\tbreak;\n" +"\tdefault:\n" +"\t\terror = EOPNOTSUPP;\n" +"\t\tbreak;\n" +"\t}\n" +"\treturn (error);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:242 +#, no-wrap +msgid "" +"static int\n" +"echo_open(struct cdev *dev __unused, int oflags __unused, int devtype __unused,\n" +" struct thread *td __unused)\n" +"{\n" +"\tint error = 0;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:246 +#, no-wrap +msgid "" +"\tuprintf(\"Opened device \\\"echo\\\" successfully.\\n\");\n" +"\treturn (error);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:251 +#, no-wrap +msgid "" +"static int\n" +"echo_close(struct cdev *dev __unused, int fflag __unused, int devtype __unused,\n" +" struct thread *td __unused)\n" +"{\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:255 +#, no-wrap +msgid "" +"\tuprintf(\"Closing device \\\"echo\\\".\\n\");\n" +"\treturn (0);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:266 +#, no-wrap +msgid "" +"/*\n" +" * The read function just takes the buf that was saved via\n" +" * echo_write() and returns it to userland for accessing.\n" +" * uio(9)\n" +" */\n" +"static int\n" +"echo_read(struct cdev *dev __unused, struct uio *uio, int ioflag __unused)\n" +"{\n" +"\tsize_t amt;\n" +"\tint error;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:274 +#, no-wrap +msgid "" +"\t/*\n" +"\t * How big is this read operation? Either as big as the user wants,\n" +"\t * or as big as the remaining data. Note that the 'len' does not\n" +"\t * include the trailing null character.\n" +"\t */\n" +"\tamt = MIN(uio->uio_resid, uio->uio_offset >= echomsg->len + 1 ? 0 :\n" +"\t echomsg->len + 1 - uio->uio_offset);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:277 +#, no-wrap +msgid "" +"\tif ((error = uiomove(echomsg->msg, amt, uio)) != 0)\n" +"\t\tuprintf(\"uiomove failed!\\n\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:280 +#, no-wrap +msgid "" +"\treturn (error);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:290 +#, no-wrap +msgid "" +"/*\n" +" * echo_write takes in a character string and saves it\n" +" * to buf for later accessing.\n" +" */\n" +"static int\n" +"echo_write(struct cdev *dev __unused, struct uio *uio, int ioflag __unused)\n" +"{\n" +"\tsize_t amt;\n" +"\tint error;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:297 +#, no-wrap +msgid "" +"\t/*\n" +"\t * We either write from the beginning or are appending -- do\n" +"\t * not allow random access.\n" +"\t */\n" +"\tif (uio->uio_offset != 0 && (uio->uio_offset != echomsg->len))\n" +"\t\treturn (EINVAL);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:301 +#, no-wrap +msgid "" +"\t/* This is a new message, reset length */\n" +"\tif (uio->uio_offset == 0)\n" +"\t\techomsg->len = 0;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:304 +#, no-wrap +msgid "" +"\t/* Copy the string in from user memory to kernel memory */\n" +"\tamt = MIN(uio->uio_resid, (BUFFERSIZE - echomsg->len));\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:306 +#, no-wrap +msgid "\terror = uiomove(echomsg->msg + uio->uio_offset, amt, uio);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:310 +#, no-wrap +msgid "" +"\t/* Now we need to null terminate and record the length */\n" +"\techomsg->len = uio->uio_offset;\n" +"\techomsg->msg[echomsg->len] = 0;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:315 +#, no-wrap +msgid "" +"\tif (error != 0)\n" +"\t\tuprintf(\"Write failed: bad address!\\n\");\n" +"\treturn (error);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:317 +#, no-wrap +msgid "DEV_MODULE(echo, echo_loader, NULL);\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:321 +msgid "With this driver loaded try:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:329 +#, no-wrap +msgid "" +"# echo -n \"Test Data\" > /dev/echo\n" +"# cat /dev/echo\n" +"Opened device \"echo\" successfully.\n" +"Test Data\n" +"Closing device \"echo\".\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:332 +msgid "Real hardware devices are described in the next chapter." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:334 +#, no-wrap +msgid "Block Devices (Are Gone)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:337 +msgid "" +"Other UNIX(R) systems may support a second type of disk device known as " +"block devices. Block devices are disk devices for which the kernel provides " +"caching. This caching makes block-devices almost unusable, or at least " +"dangerously unreliable. The caching will reorder the sequence of write " +"operations, depriving the application of the ability to know the exact disk " +"contents at any one instant in time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:339 +msgid "" +"This makes predictable and reliable crash recovery of on-disk data " +"structures (filesystems, databases, etc.) impossible. Since writes may be " +"delayed, there is no way the kernel can report to the application which " +"particular write operation encountered a write error, this further compounds " +"the consistency problem." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:341 +msgid "" +"For this reason, no serious applications rely on block devices, and in fact, " +"almost all applications which access disks directly take great pains to " +"specify that character (or \"raw\") devices should always be used. As the " +"implementation of the aliasing of each disk (partition) to two devices with " +"different semantics significantly complicated the relevant kernel code, " +"FreeBSD dropped support for cached disk devices as part of the modernization " +"of the disk I/O infrastructure." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:343 +#, no-wrap +msgid "Network Drivers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:346 +msgid "" +"Drivers for network devices do not use device nodes in order to be accessed. " +"Their selection is based on other decisions made inside the kernel and " +"instead of calling open(), use of a network device is generally introduced " +"by using the system call socket(2)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:347 +msgid "For more information see ifnet(9), the source of the loopback device." +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/isa/_index.adoc b/documentation/content/en/books/arch-handbook/isa/_index.adoc index b2913774ef..b4586a0864 100644 --- a/documentation/content/en/books/arch-handbook/isa/_index.adoc +++ b/documentation/content/en/books/arch-handbook/isa/_index.adoc @@ -6,7 +6,8 @@ description: ISA Device Drivers tags: ["ISA", "device drivers", "FreeBSD"] showBookMenu: true weight: 12 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/isa/" --- [[isa-driver]] @@ -364,10 +365,9 @@ highaddr = BUS_SPACE_MAXADDR ** _maxsize_ - the maximal size of memory (in bytes) that may be allocated through this tag. In case it is difficult to estimate or could be arbitrarily big, the value for ISA devices would be `BUS_SPACE_MAXSIZE_24BIT`. ** _nsegments_ - maximal number of scatter-gather segments supported by the device. If unrestricted then the value `BUS_SPACE_UNRESTRICTED` should be used. This value is recommended for the parent tags, the actual restrictions would then be specified for the descendant tags. Tags with nsegments equal to `BUS_SPACE_UNRESTRICTED` may not be used to actually load maps, they may be used only as parent tags. The practical limit for nsegments seems to be about 250-300, higher values will cause kernel stack overflow (the hardware can not normally support that many scatter-gather buffers anyway). ** _maxsegsz_ - maximal size of a scatter-gather segment supported by the device. The maximal value for ISA device would be `BUS_SPACE_MAXSIZE_24BIT`. -** _flags_ - a bitmap of flags. The only interesting flags are: +** _flags_ - a bitmap of flags. The only interesting flag is: *** _BUS_DMA_ALLOCNOW_ - requests to allocate all the potentially needed bounce pages when creating the tag. -*** _BUS_DMA_ISA_ - mysterious flag used only on Alpha machines. It is not defined for the i386 machines. Probably it should be used by all the ISA drivers for Alpha machines but it looks like there are no such drivers yet. ** _dmat_ - pointer to the storage for the new tag to be returned. diff --git a/documentation/content/en/books/arch-handbook/isa/_index.po b/documentation/content/en/books/arch-handbook/isa/_index.po new file mode 100644 index 0000000000..d92ec3736e --- /dev/null +++ b/documentation/content/en/books/arch-handbook/isa/_index.po @@ -0,0 +1,3063 @@ +# 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/isa/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:14 +#, no-wrap +msgid "ISA Device Drivers" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1 +#, no-wrap +msgid "Chapter 10. ISA Device Drivers" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:52 +#, no-wrap +msgid "Synopsis" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:55 +msgid "" +"This chapter introduces the issues relevant to writing a driver for an ISA " +"device. The pseudo-code presented here is rather detailed and reminiscent of " +"the real code but is still only pseudo-code. It avoids the details " +"irrelevant to the subject of the discussion. The real-life examples can be " +"found in the source code of real drivers. In particular the drivers `ep` and " +"`aha` are good sources of information." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:57 +#, no-wrap +msgid "Basic Information" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:60 +msgid "A typical ISA driver would need the following include files:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:68 +#, no-wrap +msgid "" +"#include <sys/module.h>\n" +"#include <sys/bus.h>\n" +"#include <machine/bus.h>\n" +"#include <machine/resource.h>\n" +"#include <sys/rman.h>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:71 +#, no-wrap +msgid "" +"#include <isa/isavar.h>\n" +"#include <isa/pnpvar.h>\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:74 +msgid "They describe the things specific to the ISA and generic bus subsystem." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:76 +msgid "" +"The bus subsystem is implemented in an object-oriented fashion, its main " +"structures are accessed by associated method functions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:78 +msgid "" +"The list of bus methods implemented by an ISA driver is like one for any " +"other bus. For a hypothetical driver named \"xxx\" they would be:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:80 +msgid "" +"`static void xxx_isa_identify (driver_t *, device_t);` Normally used for bus " +"drivers, not device drivers. But for ISA devices this method may have " +"special use: if the device provides some device-specific (non-PnP) way to " +"auto-detect devices this routine may implement it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:81 +msgid "" +"`static int xxx_isa_probe (device_t dev);` Probe for a device at a known (or " +"PnP) location. This routine can also accommodate device-specific auto-" +"detection of parameters for partially configured devices." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:82 +msgid "" +"`static int xxx_isa_attach (device_t dev);` Attach and initialize device." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:83 +msgid "" +"`static int xxx_isa_detach (device_t dev);` Detach device before unloading " +"the driver module." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:84 +msgid "" +"`static int xxx_isa_shutdown (device_t dev);` Execute shutdown of the device " +"before system shutdown." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:85 +msgid "" +"`static int xxx_isa_suspend (device_t dev);` Suspend the device before the " +"system goes to the power-save state. May also abort transition to the power-" +"save state." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:86 +msgid "" +"`static int xxx_isa_resume (device_t dev);` Resume the device activity after " +"return from power-save state." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:88 +msgid "" +"`xxx_isa_probe()` and `xxx_isa_attach()` are mandatory, the rest of the " +"routines are optional, depending on the device's needs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:90 +msgid "" +"The driver is linked to the system with the following set of descriptions." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:104 +#, no-wrap +msgid "" +" /* table of supported bus methods */\n" +" static device_method_t xxx_isa_methods[] = {\n" +" /* list all the bus method functions supported by the driver */\n" +" /* omit the unsupported methods */\n" +" DEVMETHOD(device_identify, xxx_isa_identify),\n" +" DEVMETHOD(device_probe, xxx_isa_probe),\n" +" DEVMETHOD(device_attach, xxx_isa_attach),\n" +" DEVMETHOD(device_detach, xxx_isa_detach),\n" +" DEVMETHOD(device_shutdown, xxx_isa_shutdown),\n" +" DEVMETHOD(device_suspend, xxx_isa_suspend),\n" +" DEVMETHOD(device_resume, xxx_isa_resume),\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:107 +#, no-wrap +msgid "" +"\tDEVMETHOD_END\n" +" };\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:113 +#, no-wrap +msgid "" +" static driver_t xxx_isa_driver = {\n" +" \"xxx\",\n" +" xxx_isa_methods,\n" +" sizeof(struct xxx_softc),\n" +" };\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:115 +#, no-wrap +msgid " static devclass_t xxx_devclass;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:118 +#, no-wrap +msgid "" +" DRIVER_MODULE(xxx, isa, xxx_isa_driver, xxx_devclass,\n" +" load_function, load_argument);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:121 +msgid "" +"Here struct `xxx_softc` is a device-specific structure that contains private " +"driver data and descriptors for the driver's resources. The bus code " +"automatically allocates one softc descriptor per device as needed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:123 +msgid "" +"If the driver is implemented as a loadable module then `load_function()` is " +"called to do driver-specific initialization or clean-up when the driver is " +"loaded or unloaded and load_argument is passed as one of its arguments. If " +"the driver does not support dynamic loading (in other words it must always " +"be linked into the kernel) then these values should be set to 0 and the last " +"definition would look like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:128 +#, no-wrap +msgid "" +" DRIVER_MODULE(xxx, isa, xxx_isa_driver,\n" +" xxx_devclass, 0, 0);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:131 +msgid "" +"If the driver is for a device which supports PnP then a table of supported " +"PnP IDs must be defined. The table consists of a list of PnP IDs supported " +"by this driver and human-readable descriptions of the hardware types and " +"models having these IDs. It looks like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:140 +#, no-wrap +msgid "" +" static struct isa_pnp_id xxx_pnp_ids[] = {\n" +" /* a line for each supported PnP ID */\n" +" { 0x12345678, \"Our device model 1234A\" },\n" +" { 0x12345679, \"Our device model 1234B\" },\n" +" { 0, NULL }, /* end of table */\n" +" };\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:143 +msgid "" +"If the driver does not support PnP devices it still needs an empty PnP ID " +"table, like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:149 +#, no-wrap +msgid "" +" static struct isa_pnp_id xxx_pnp_ids[] = {\n" +" { 0, NULL }, /* end of table */\n" +" };\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:152 +#, no-wrap +msgid "`device_t` Pointer" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:155 +msgid "" +"`device_t` is the pointer type for the device structure. Here we consider " +"only the methods interesting from the device driver writer's standpoint. The " +"methods to manipulate values in the device structure are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:157 +msgid "`device_t device_get_parent(dev)` Get the parent bus of a device." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:158 +msgid "`driver_t device_get_driver(dev)` Get pointer to its driver structure." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:159 +msgid "" +"`char *device_get_name(dev)` Get the driver name, such as `\"xxx\"` for our " +"example." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:160 +msgid "" +"`int device_get_unit(dev)` Get the unit number (units are numbered from 0 " +"for the devices associated with each driver)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:161 +msgid "" +"`char *device_get_nameunit(dev)` Get the device name including the unit " +"number, such as \"xxx0\", \"xxx1\" and so on." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:162 +msgid "" +"`char *device_get_desc(dev)` Get the device description. Normally it " +"describes the exact model of device in human-readable form." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:163 +msgid "" +"`device_set_desc(dev, desc)` Set the description. This makes the device " +"description point to the string desc which may not be deallocated or changed " +"after that." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:164 +msgid "" +"`device_set_desc_copy(dev, desc)` Set the description. The description is " +"copied into an internal dynamically allocated buffer, so the string desc may " +"be changed afterwards without adverse effects." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:165 +msgid "" +"`void *device_get_softc(dev)` Get pointer to the device descriptor (struct " +"`xxx_softc`) associated with this device." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:166 +msgid "" +"`u_int32_t device_get_flags(dev)` Get the flags specified for the device in " +"the configuration file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:168 +msgid "" +"A convenience function `device_printf(dev, fmt, ...)` may be used to print " +"the messages from the device driver. It automatically prepends the unitname " +"and colon to the message." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:170 +msgid "" +"The device_t methods are implemented in the file [.filename]#kern/" +"bus_subr.c#." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:172 +#, no-wrap +msgid "Configuration File and the Order of Identifying and Probing During Auto-Configuration" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:175 +msgid "The ISA devices are described in the kernel configuration file like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:180 +#, no-wrap +msgid "" +"device xxx0 at isa? port 0x300 irq 10 drq 5\n" +" iomem 0xd0000 flags 0x1 sensitive\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:183 +msgid "" +"The values of port, IRQ and so on are converted to the resource values " +"associated with the device. They are optional, depending on the device's " +"needs and abilities for auto-configuration. For example, some devices do not " +"need DRQ at all and some allow the driver to read the IRQ setting from the " +"device configuration ports. If a machine has multiple ISA buses the exact " +"bus may be specified in the configuration line, like `isa0` or `isa1`, " +"otherwise the device would be searched for on all the ISA buses." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:185 +msgid "" +"`sensitive` is a resource requesting that this device must be probed before " +"all non-sensitive devices. It is supported but does not seem to be used in " +"any current driver." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:187 +msgid "" +"For legacy ISA devices in many cases the drivers are still able to detect " +"the configuration parameters. But each device to be configured in the system " +"must have a config line. If two devices of some type are installed in the " +"system but there is only one configuration line for the corresponding " +"driver, ie:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:190 +#, no-wrap +msgid "device xxx0 at isa?\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:192 +#, no-wrap +msgid " then only one device will be configured.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:194 +msgid "" +"But for the devices supporting automatic identification by the means of Plug-" +"n-Play or some proprietary protocol one configuration line is enough to " +"configure all the devices in the system, like the one above or just simply:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:198 +#, no-wrap +msgid "device xxx at isa?\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:201 +msgid "" +"If a driver supports both auto-identified and legacy devices and both kinds " +"are installed at once in one machine then it is enough to describe in the " +"config file the legacy devices only. The auto-identified devices will be " +"added automatically." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:203 +msgid "When an ISA bus is auto-configured the events happen as follows:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:205 +msgid "" +"All the drivers' identify routines (including the PnP identify routine which " +"identifies all the PnP devices) are called in random order. As they identify " +"the devices they add them to the list on the ISA bus. Normally the drivers' " +"identify routines associate their drivers with the new devices. The PnP " +"identify routine does not know about the other drivers yet so it does not " +"associate any with the new devices it adds." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:207 +msgid "" +"The PnP devices are put to sleep using the PnP protocol to prevent them from " +"being probed as legacy devices." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:209 +msgid "" +"The probe routines of non-PnP devices marked as `sensitive` are called. If " +"probe for a device went successfully, the attach routine is called for it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:211 +msgid "" +"The probe and attach routines of all non-PNP devices are called likewise." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:213 +msgid "" +"The PnP devices are brought back from the sleep state and assigned the " +"resources they request: I/O and memory address ranges, IRQs and DRQs, all of " +"them not conflicting with the attached legacy devices." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:215 +msgid "" +"Then for each PnP device the probe routines of all the present ISA drivers " +"are called. The first one that claims the device gets attached. It is " +"possible that multiple drivers would claim the device with different " +"priority; in this case, the highest-priority driver wins. The probe routines " +"must call `ISA_PNP_PROBE()` to compare the actual PnP ID with the list of " +"the IDs supported by the driver and if the ID is not in the table return " +"failure. That means that absolutely every driver, even the ones not " +"supporting any PnP devices must call `ISA_PNP_PROBE()`, at least with an " +"empty PnP ID table to return failure on unknown PnP devices." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:217 +msgid "" +"The probe routine returns a positive value (the error code) on error, zero " +"or negative value on success." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:219 +msgid "" +"The negative return values are used when a PnP device supports multiple " +"interfaces. For example, an older compatibility interface and a newer " +"advanced interface which are supported by different drivers. Then both " +"drivers would detect the device. The driver which returns a higher value in " +"the probe routine takes precedence (in other words, the driver returning 0 " +"has highest precedence, returning -1 is next, returning -2 is after it and " +"so on). In result the devices which support only the old interface will be " +"handled by the old driver (which should return -1 from the probe routine) " +"while the devices supporting the new interface as well will be handled by " +"the new driver (which should return 0 from the probe routine). If multiple " +"drivers return the same value then the one called first wins. So if a driver " +"returns value 0 it may be sure that it won the priority arbitration." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:221 +msgid "" +"The device-specific identify routines can also assign not a driver but a " +"class of drivers to the device. Then all the drivers in the class are probed " +"for this device, like the case with PnP. This feature is not implemented in " +"any existing driver and is not considered further in this document." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:223 +msgid "" +"As the PnP devices are disabled when probing the legacy devices they will " +"not be attached twice (once as legacy and once as PnP). But in case of " +"device-dependent identify routines it is the responsibility of the driver to " +"make sure that the same device will not be attached by the driver twice: " +"once as legacy user-configured and once as auto-identified." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:225 +msgid "" +"Another practical consequence for the auto-identified devices (both PnP and " +"device-specific) is that the flags can not be passed to them from the kernel " +"configuration file. So they must either not use the flags at all or use the " +"flags from the device unit 0 for all the auto-identified devices or use the " +"sysctl interface instead of flags." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:227 +msgid "" +"Other unusual configurations may be accommodated by accessing the " +"configuration resources directly with functions of families " +"`resource_query_*()` and `resource_*_value()`. Their implementations are " +"located in [.filename]#kern/subr_bus.c#. The old IDE disk driver " +"[.filename]#i386/isa/wd.c# contains examples of such use. But the standard " +"means of configuration must always be preferred. Leave parsing the " +"configuration resources to the bus configuration code." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:229 +#, no-wrap +msgid "Resources" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:232 +msgid "" +"The information that a user enters into the kernel configuration file is " +"processed and passed to the kernel as configuration resources. This " +"information is parsed by the bus configuration code and transformed into a " +"value of structure device_t and the bus resources associated with it. The " +"drivers may access the configuration resources directly using functions " +"`resource_*` for more complex cases of configuration. However, generally " +"this is neither needed nor recommended, so this issue is not discussed " +"further here." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:234 +msgid "" +"The bus resources are associated with each device. They are identified by " +"type and number within the type. For the ISA bus the following types are " +"defined:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:236 +msgid "_SYS_RES_IRQ_ - interrupt number" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:237 +msgid "_SYS_RES_DRQ_ - ISA DMA channel number" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:238 +msgid "" +"_SYS_RES_MEMORY_ - range of device memory mapped into the system memory space" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:239 +msgid "_SYS_RES_IOPORT_ - range of device I/O registers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:241 +msgid "" +"The enumeration within types starts from 0, so if a device has two memory " +"regions it would have resources of type `SYS_RES_MEMORY` numbered 0 and 1. " +"The resource type has nothing to do with the C language type, all the " +"resource values have the C language type `unsigned long` and must be cast as " +"necessary. The resource numbers do not have to be contiguous, although for " +"ISA they normally would be. The permitted resource numbers for ISA devices " +"are:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:248 +#, no-wrap +msgid "" +" IRQ: 0-1\n" +" DRQ: 0-1\n" +" MEMORY: 0-3\n" +" IOPORT: 0-7\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:251 +msgid "" +"All the resources are represented as ranges, with a start value and count. " +"For IRQ and DRQ resources the count would normally be equal to 1. The values " +"for memory refer to the physical addresses." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:253 +msgid "Three types of activities can be performed on resources:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:255 +msgid "set/get" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:256 +msgid "allocate/release" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:257 +msgid "activate/deactivate" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:259 +msgid "" +"Setting sets the range used by the resource. Allocation reserves the " +"requested range that no other driver would be able to reserve it (and " +"checking that no other driver reserved this range already). Activation makes " +"the resource accessible to the driver by doing whatever is necessary for " +"that (for example, for memory it would be mapping into the kernel virtual " +"address space)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:261 +msgid "The functions to manipulate resources are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:263 +msgid "" +"`int bus_set_resource(device_t dev, int type, int rid, u_long start, u_long " +"count)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:265 +msgid "" +"Set a range for a resource. Returns 0 if successful, error code otherwise. " +"Normally, this function will return an error only if one of `type`, `rid`, " +"`start` or `count` has a value that falls out of the permitted range." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:267 +msgid "dev - driver's device" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:268 +msgid "type - type of resource, SYS_RES_*" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:269 +msgid "rid - resource number (ID) within type" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:270 +msgid "start, count - resource range" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:272 +msgid "" +"`int bus_get_resource(device_t dev, int type, int rid, u_long *startp, " +"u_long *countp)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:274 +msgid "" +"Get the range of resource. Returns 0 if successful, error code if the " +"resource is not defined yet." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:275 +msgid "" +"`u_long bus_get_resource_start(device_t dev, int type, int rid) u_long " +"bus_get_resource_count (device_t dev, int type, int rid)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:277 +msgid "" +"Convenience functions to get only the start or count. Return 0 in case of " +"error, so if the resource start has 0 among the legitimate values it would " +"be impossible to tell if the value is 0 or an error occurred. Luckily, no " +"ISA resources for add-on drivers may have a start value equal to 0." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:278 +msgid "`void bus_delete_resource(device_t dev, int type, int rid)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:280 +msgid "Delete a resource, make it undefined." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:281 +msgid "" +"`struct resource * bus_alloc_resource(device_t dev, int type, int *rid, " +"u_long start, u_long end, u_long count, u_int flags)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:283 +msgid "" +"Allocate a resource as a range of count values not allocated by anyone else, " +"somewhere between start and end. Alas, alignment is not supported. If the " +"resource was not set yet it is automatically created. The special values of " +"start 0 and end ~0 (all ones) means that the fixed values previously set by " +"`bus_set_resource()` must be used instead: start and count as themselves and " +"end=(start+count), in this case if the resource was not defined before then " +"an error is returned. Although rid is passed by reference it is not set " +"anywhere by the resource allocation code of the ISA bus. (The other buses " +"may use a different approach and modify it)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:285 +msgid "Flags are a bitmap, the flags interesting for the caller are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:287 +msgid "" +"_RF_ACTIVE_ - causes the resource to be automatically activated after " +"allocation." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:288 +msgid "" +"_RF_SHAREABLE_ - resource may be shared at the same time by multiple drivers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:289 +msgid "" +"_RF_TIMESHARE_ - resource may be time-shared by multiple drivers, i.e., " +"allocated at the same time by many but activated only by one at any given " +"moment of time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:290 +msgid "" +"Returns 0 on error. The allocated values may be obtained from the returned " +"handle using methods `rhand_*()`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:291 +msgid "" +"`int bus_release_resource(device_t dev, int type, int rid, struct resource " +"*r)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:292 +msgid "" +"Release the resource, r is the handle returned by `bus_alloc_resource()`. " +"Returns 0 on success, error code otherwise." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:293 +msgid "" +"`int bus_activate_resource(device_t dev, int type, int rid, struct resource " +"*r) int bus_deactivate_resource(device_t dev, int type, int rid, struct " +"resource *r)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:294 +msgid "" +"Activate or deactivate resource. Return 0 on success, error code otherwise. " +"If the resource is time-shared and currently activated by another driver " +"then `EBUSY` is returned." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:295 +msgid "" +"`int bus_setup_intr(device_t dev, struct resource *r, int flags, " +"driver_intr_t *handler, void *arg, void **cookiep) int " +"bus_teardown_intr(device_t dev, struct resource *r, void *cookie)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:296 +msgid "" +"Associate or de-associate the interrupt handler with a device. Return 0 on " +"success, error code otherwise." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:297 +msgid "r - the activated resource handler describing the IRQ" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:299 +msgid "flags - the interrupt priority level, one of:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:301 +msgid "" +"`INTR_TYPE_TTY` - terminals and other likewise character-type devices. To " +"mask them use `spltty()`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:302 +msgid "" +"`(INTR_TYPE_TTY | INTR_TYPE_FAST)` - terminal type devices with small input " +"buffer, critical to the data loss on input (such as the old-fashioned serial " +"ports). To mask them use `spltty()`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:303 +msgid "" +"`INTR_TYPE_BIO` - block-type devices, except those on the CAM controllers. " +"To mask them use `splbio()`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:304 +msgid "" +"`INTR_TYPE_CAM` - CAM (Common Access Method) bus controllers. To mask them " +"use `splcam()`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:305 +msgid "" +"`INTR_TYPE_NET` - network interface controllers. To mask them use `splimp()`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:306 +msgid "" +"`INTR_TYPE_MISC` - miscellaneous devices. There is no other way to mask them " +"than by `splhigh()` which masks all interrupts." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:308 +msgid "" +"When an interrupt handler executes all the other interrupts matching its " +"priority level will be masked. The only exception is the MISC level for " +"which no other interrupts are masked and which is not masked by any other " +"interrupt." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:310 +msgid "" +"_handler_ - pointer to the handler function, the type driver_intr_t is " +"defined as `void driver_intr_t(void *)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:311 +msgid "" +"_arg_ - the argument passed to the handler to identify this particular " +"device. It is cast from void* to any real type by the handler. The old " +"convention for the ISA interrupt handlers was to use the unit number as " +"argument, the new (recommended) convention is using a pointer to the device " +"softc structure." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:312 +msgid "" +"_cookie[p]_ - the value received from `setup()` is used to identify the " +"handler when passed to `teardown()`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:314 +msgid "" +"A number of methods are defined to operate on the resource handlers (struct " +"resource *). Those of interest to the device driver writers are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:316 +msgid "" +"`u_long rman_get_start(r) u_long rman_get_end(r)` Get the start and end of " +"allocated resource range." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:317 +msgid "" +"`void *rman_get_virtual(r)` Get the virtual address of activated memory " +"resource." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:319 +#, no-wrap +msgid "Bus Memory Mapping" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:322 +msgid "" +"In many cases data is exchanged between the driver and the device through " +"the memory. Two variants are possible:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:324 +msgid "(a) memory is located on the device card" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:326 +msgid "(b) memory is the main memory of the computer" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:328 +msgid "" +"In case (a) the driver always copies the data back and forth between the on-" +"card memory and the main memory as necessary. To map the on-card memory into " +"the kernel virtual address space the physical address and length of the on-" +"card memory must be defined as a `SYS_RES_MEMORY` resource. That resource " +"can then be allocated and activated, and its virtual address obtained using " +"`rman_get_virtual()`. The older drivers used the function `pmap_mapdev()` " +"for this purpose, which should not be used directly any more. Now it is one " +"of the internal steps of resource activation." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:330 +msgid "" +"Most of the ISA cards will have their memory configured for physical " +"location somewhere in range 640KB-1MB. Some of the ISA cards require larger " +"memory ranges which should be placed somewhere under 16MB (because of the 24-" +"bit address limitation on the ISA bus). In that case if the machine has more " +"memory than the start address of the device memory (in other words, they " +"overlap) a memory hole must be configured at the address range used by " +"devices. Many BIOSes allow configuration of a memory hole of 1MB starting at " +"14MB or 15MB. FreeBSD can handle the memory holes properly if the BIOS " +"reports them properly (this feature may be broken on old BIOSes)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:332 +msgid "" +"In case (b) just the address of the data is sent to the device, and the " +"device uses DMA to actually access the data in the main memory. Two " +"limitations are present: First, ISA cards can only access memory below 16MB. " +"Second, the contiguous pages in virtual address space may not be contiguous " +"in physical address space, so the device may have to do scatter/gather " +"operations. The bus subsystem provides ready solutions for some of these " +"problems, the rest has to be done by the drivers themselves." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:334 +msgid "" +"Two structures are used for DMA memory allocation, `bus_dma_tag_t` and " +"`bus_dmamap_t`. Tag describes the properties required for the DMA memory. " +"Map represents a memory block allocated according to these properties. " +"Multiple maps may be associated with the same tag." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:336 +msgid "" +"Tags are organized into a tree-like hierarchy with inheritance of the " +"properties. A child tag inherits all the requirements of its parent tag, and " +"may make them more strict but never more loose." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:338 +msgid "" +"Normally one top-level tag (with no parent) is created for each device unit. " +"If multiple memory areas with different requirements are needed for each " +"device then a tag for each of them may be created as a child of the parent " +"tag." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:340 +msgid "The tags can be used to create a map in two ways." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:342 +msgid "" +"First, a chunk of contiguous memory conformant with the tag requirements may " +"be allocated (and later may be freed). This is normally used to allocate " +"relatively long-living areas of memory for communication with the device. " +"Loading of such memory into a map is trivial: it is always considered as one " +"chunk in the appropriate physical memory range." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:344 +msgid "" +"Second, an arbitrary area of virtual memory may be loaded into a map. Each " +"page of this memory will be checked for conformance to the map requirement. " +"If it conforms then it is left at its original location. If it is not then a " +"fresh conformant \"bounce page\" is allocated and used as intermediate " +"storage. When writing the data from the non-conformant original pages they " +"will be copied to their bounce pages first and then transferred from the " +"bounce pages to the device. When reading the data would go from the device " +"to the bounce pages and then copied to their non-conformant original pages. " +"The process of copying between the original and bounce pages is called " +"synchronization. This is normally used on a per-transfer basis: buffer for " +"each transfer would be loaded, transfer done and buffer unloaded." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:346 +msgid "The functions working on the DMA memory are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:348 +msgid "" +"`int bus_dma_tag_create(bus_dma_tag_t parent, bus_size_t alignment, " +"bus_size_t boundary, bus_addr_t lowaddr, bus_addr_t highaddr, " +"bus_dma_filter_t *filter, void *filterarg, bus_size_t maxsize, int " +"nsegments, bus_size_t maxsegsz, int flags, bus_dma_tag_t *dmat)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:350 +msgid "Create a new tag. Returns 0 on success, the error code otherwise." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:352 +msgid "_parent_ - parent tag, or NULL to create a top-level tag." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:353 +msgid "" +"_alignment_ - required physical alignment of the memory area to be allocated " +"for this tag. Use value 1 for \"no specific alignment\". Applies only to the " +"future `bus_dmamem_alloc()` but not `bus_dmamap_create()` calls." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:354 +msgid "" +"_boundary_ - physical address boundary that must not be crossed when " +"allocating the memory. Use value 0 for \"no boundary\". Applies only to the " +"future `bus_dmamem_alloc()` but not `bus_dmamap_create()` calls. Must be " +"power of 2. If the memory is planned to be used in non-cascaded DMA mode " +"(i.e., the DMA addresses will be supplied not by the device itself but by " +"the ISA DMA controller) then the boundary must be no larger than 64KB " +"(64*1024) due to the limitations of the DMA hardware." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:355 +msgid "" +"_lowaddr, highaddr_ - the names are slightly misleading; these values are " +"used to limit the permitted range of physical addresses used to allocate the " +"memory. The exact meaning varies depending on the planned future use:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:357 +msgid "" +"For `bus_dmamem_alloc()` all the addresses from 0 to lowaddr-1 are " +"considered permitted, the higher ones are forbidden." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:358 +msgid "" +"For `bus_dmamap_create()` all the addresses outside the inclusive range " +"[lowaddr; highaddr] are considered accessible. The addresses of pages inside " +"the range are passed to the filter function which decides if they are " +"accessible. If no filter function is supplied then all the range is " +"considered unaccessible." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:359 +msgid "For the ISA devices the normal values (with no filter function) are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:361 +msgid "lowaddr = BUS_SPACE_MAXADDR_24BIT" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:363 +msgid "highaddr = BUS_SPACE_MAXADDR" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:365 +msgid "" +"_filter, filterarg_ - the filter function and its argument. If NULL is " +"passed for filter then the whole range [lowaddr, highaddr] is considered " +"unaccessible when doing `bus_dmamap_create()`. Otherwise the physical " +"address of each attempted page in range [lowaddr; highaddr] is passed to the " +"filter function which decides if it is accessible. The prototype of the " +"filter function is: `int filterfunc(void *arg, bus_addr_t paddr)`. It must " +"return 0 if the page is accessible, non-zero otherwise." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:366 +msgid "" +"_maxsize_ - the maximal size of memory (in bytes) that may be allocated " +"through this tag. In case it is difficult to estimate or could be " +"arbitrarily big, the value for ISA devices would be " +"`BUS_SPACE_MAXSIZE_24BIT`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:367 +msgid "" +"_nsegments_ - maximal number of scatter-gather segments supported by the " +"device. If unrestricted then the value `BUS_SPACE_UNRESTRICTED` should be " +"used. This value is recommended for the parent tags, the actual restrictions " +"would then be specified for the descendant tags. Tags with nsegments equal " +"to `BUS_SPACE_UNRESTRICTED` may not be used to actually load maps, they may " +"be used only as parent tags. The practical limit for nsegments seems to be " +"about 250-300, higher values will cause kernel stack overflow (the hardware " +"can not normally support that many scatter-gather buffers anyway)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:368 +msgid "" +"_maxsegsz_ - maximal size of a scatter-gather segment supported by the " +"device. The maximal value for ISA device would be `BUS_SPACE_MAXSIZE_24BIT`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:369 +msgid "_flags_ - a bitmap of flags. The only interesting flag is:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:371 +msgid "" +"_BUS_DMA_ALLOCNOW_ - requests to allocate all the potentially needed bounce " +"pages when creating the tag." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:373 +msgid "_dmat_ - pointer to the storage for the new tag to be returned." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:375 +msgid "`int bus_dma_tag_destroy(bus_dma_tag_t dmat)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:377 +msgid "Destroy a tag. Returns 0 on success, the error code otherwise." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:379 +msgid "dmat - the tag to be destroyed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:380 +msgid "" +"`int bus_dmamem_alloc(bus_dma_tag_t dmat, void** vaddr, int flags, " +"bus_dmamap_t *mapp)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:382 +msgid "" +"Allocate an area of contiguous memory described by the tag. The size of " +"memory to be allocated is tag's maxsize. Returns 0 on success, the error " +"code otherwise. The result still has to be loaded by `bus_dmamap_load()` " +"before being used to get the physical address of the memory." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:384 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:396 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:404 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:419 +msgid "_dmat_ - the tag" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:385 +msgid "" +"_vaddr_ - pointer to the storage for the kernel virtual address of the " +"allocated area to be returned." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:386 +msgid "flags - a bitmap of flags. The only interesting flag is:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:388 +msgid "" +"_BUS_DMA_NOWAIT_ - if the memory is not immediately available return the " +"error. If this flag is not set then the routine is allowed to sleep until " +"the memory becomes available." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:390 +msgid "_mapp_ - pointer to the storage for the new map to be returned." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:392 +msgid "" +"`void bus_dmamem_free(bus_dma_tag_t dmat, void *vaddr, bus_dmamap_t map)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:394 +msgid "" +"Free the memory allocated by `bus_dmamem_alloc()`. At present, freeing of " +"the memory allocated with ISA restrictions is not implemented. Due to this " +"the recommended model of use is to keep and re-use the allocated areas for " +"as long as possible. Do not lightly free some area and then shortly allocate " +"it again. That does not mean that `bus_dmamem_free()` should not be used at " +"all: hopefully it will be properly implemented soon." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:397 +msgid "_vaddr_ - the kernel virtual address of the memory" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:398 +msgid "_map_ - the map of the memory (as returned from `bus_dmamem_alloc()`)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:400 +msgid "" +"`int bus_dmamap_create(bus_dma_tag_t dmat, int flags, bus_dmamap_t *mapp)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:402 +msgid "" +"Create a map for the tag, to be used in `bus_dmamap_load()` later. Returns 0 " +"on success, the error code otherwise." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:405 +msgid "" +"_flags_ - theoretically, a bit map of flags. But no flags are defined yet, " +"so at present it will be always 0." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:406 +msgid "_mapp_ - pointer to the storage for the new map to be returned" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:408 +msgid "`int bus_dmamap_destroy(bus_dma_tag_t dmat, bus_dmamap_t map)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:410 +msgid "Destroy a map. Returns 0 on success, the error code otherwise." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:412 +msgid "dmat - the tag to which the map is associated" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:413 +msgid "map - the map to be destroyed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:415 +msgid "" +"`int bus_dmamap_load(bus_dma_tag_t dmat, bus_dmamap_t map, void *buf, " +"bus_size_t buflen, bus_dmamap_callback_t *callback, void *callback_arg, int " +"flags)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:417 +msgid "" +"Load a buffer into the map (the map must be previously created by " +"`bus_dmamap_create()` or `bus_dmamem_alloc()`). All the pages of the buffer " +"are checked for conformance to the tag requirements and for those not " +"conformant the bounce pages are allocated. An array of physical segment " +"descriptors is built and passed to the callback routine. This callback " +"routine is then expected to handle it in some way. The number of bounce " +"buffers in the system is limited, so if the bounce buffers are needed but " +"not immediately available the request will be queued and the callback will " +"be called when the bounce buffers will become available. Returns 0 if the " +"callback was executed immediately or `EINPROGRESS` if the request was queued " +"for future execution. In the latter case the synchronization with queued " +"callback routine is the responsibility of the driver." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:420 +msgid "_map_ - the map" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:421 +msgid "_buf_ - kernel virtual address of the buffer" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:422 +msgid "_buflen_ - length of the buffer" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:423 +msgid "_callback_, `callback_arg` - the callback function and its argument" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:425 +msgid "" +"The prototype of callback function is: `void callback(void *arg, " +"bus_dma_segment_t *seg, int nseg, int error)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:427 +msgid "_arg_ - the same as callback_arg passed to `bus_dmamap_load()`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:428 +msgid "_seg_ - array of the segment descriptors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:429 +msgid "_nseg_ - number of descriptors in array" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:430 +msgid "" +"_error_ - indication of the segment number overflow: if it is set to `EFBIG` " +"then the buffer did not fit into the maximal number of segments permitted by " +"the tag. In this case only the permitted number of descriptors will be in " +"the array. Handling of this situation is up to the driver: depending on the " +"desired semantics it can either consider this an error or split the buffer " +"in two and handle the second part separately" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:432 +msgid "Each entry in the segments array contains the fields:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:434 +msgid "_ds_addr_ - physical bus address of the segment" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:435 +msgid "_ds_len_ - length of the segment" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:437 +msgid "`void bus_dmamap_unload(bus_dma_tag_t dmat, bus_dmamap_t map)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:439 +msgid "unload the map." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:441 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:448 +msgid "_dmat_ - tag" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:442 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:449 +msgid "_map_ - loaded map" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:444 +msgid "" +"`void bus_dmamap_sync (bus_dma_tag_t dmat, bus_dmamap_t map, " +"bus_dmasync_op_t op)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:446 +msgid "" +"Synchronise a loaded buffer with its bounce pages before and after physical " +"transfer to or from device. This is the function that does all the necessary " +"copying of data between the original buffer and its mapped version. The " +"buffers must be synchronized both before and after doing the transfer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:450 +msgid "_op_ - type of synchronization operation to perform:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:452 +msgid "`BUS_DMASYNC_PREREAD` - before reading from device into buffer" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:453 +msgid "`BUS_DMASYNC_POSTREAD` - after reading from device into buffer" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:454 +msgid "`BUS_DMASYNC_PREWRITE` - before writing the buffer to device" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:455 +msgid "`BUS_DMASYNC_POSTWRITE` - after writing the buffer to device" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:457 +msgid "" +"As of now PREREAD and POSTWRITE are null operations but that may change in " +"the future, so they must not be ignored in the driver. Synchronization is " +"not needed for the memory obtained from `bus_dmamem_alloc()`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:459 +msgid "" +"Before calling the callback function from `bus_dmamap_load()` the segment " +"array is stored in the stack. And it gets pre-allocated for the maximal " +"number of segments allowed by the tag. As a result of this the practical " +"limit for the number of segments on i386 architecture is about 250-300 (the " +"kernel stack is 4KB minus the size of the user structure, size of a segment " +"array entry is 8 bytes, and some space must be left). Since the array is " +"allocated based on the maximal number this value must not be set higher than " +"really needed. Fortunately, for most of hardware the maximal supported " +"number of segments is much lower. But if the driver wants to handle buffers " +"with a very large number of scatter-gather segments it should do that in " +"portions: load part of the buffer, transfer it to the device, load next part " +"of the buffer, and so on." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:461 +msgid "" +"Another practical consequence is that the number of segments may limit the " +"size of the buffer. If all the pages in the buffer happen to be physically " +"non-contiguous then the maximal supported buffer size for that fragmented " +"case would be (nsegments * page_size). For example, if a maximal number of " +"10 segments is supported then on i386 maximal guaranteed supported buffer " +"size would be 40K. If a higher size is desired then special tricks should be " +"used in the driver." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:463 +msgid "" +"If the hardware does not support scatter-gather at all or the driver wants " +"to support some buffer size even if it is heavily fragmented then the " +"solution is to allocate a contiguous buffer in the driver and use it as " +"intermediate storage if the original buffer does not fit." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:465 +msgid "" +"Below are the typical call sequences when using a map depend on the use of " +"the map. The characters -> are used to show the flow of time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:467 +msgid "" +"For a buffer which stays practically fixed during all the time between " +"attachment and detachment of a device:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:469 +msgid "" +"bus_dmamem_alloc -> bus_dmamap_load -> ...use buffer... -> -> " +"bus_dmamap_unload -> bus_dmamem_free" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:471 +msgid "" +"For a buffer that changes frequently and is passed from outside the driver:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:480 +#, no-wrap +msgid "" +" bus_dmamap_create ->\n" +" -> bus_dmamap_load -> bus_dmamap_sync(PRE...) -> do transfer ->\n" +" -> bus_dmamap_sync(POST...) -> bus_dmamap_unload ->\n" +" ...\n" +" -> bus_dmamap_load -> bus_dmamap_sync(PRE...) -> do transfer ->\n" +" -> bus_dmamap_sync(POST...) -> bus_dmamap_unload ->\n" +" -> bus_dmamap_destroy\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:483 +msgid "" +"When loading a map created by `bus_dmamem_alloc()` the passed address and " +"size of the buffer must be the same as used in `bus_dmamem_alloc()`. In this " +"case it is guaranteed that the whole buffer will be mapped as one segment " +"(so the callback may be based on this assumption) and the request will be " +"executed immediately (EINPROGRESS will never be returned). All the callback " +"needs to do in this case is to save the physical address." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:485 +msgid "A typical example would be:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:493 +#, no-wrap +msgid "" +" static void\n" +" alloc_callback(void *arg, bus_dma_segment_t *seg, int nseg, int error)\n" +" {\n" +" *(bus_addr_t *)arg = seg[0].ds_addr;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:504 +#, no-wrap +msgid "" +" ...\n" +" int error;\n" +" struct somedata {\n" +" ....\n" +" };\n" +" struct somedata *vsomedata; /* virtual address */\n" +" bus_addr_t psomedata; /* physical bus-relative address */\n" +" bus_dma_tag_t tag_somedata;\n" +" bus_dmamap_t map_somedata;\n" +" ...\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:512 +#, no-wrap +msgid "" +" error=bus_dma_tag_create(parent_tag, alignment,\n" +" boundary, lowaddr, highaddr, /*filter*/ NULL, /*filterarg*/ NULL,\n" +" /*maxsize*/ sizeof(struct somedata), /*nsegments*/ 1,\n" +" /*maxsegsz*/ sizeof(struct somedata), /*flags*/ 0,\n" +" &tag_somedata);\n" +" if(error)\n" +" return error;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:517 +#, no-wrap +msgid "" +" error = bus_dmamem_alloc(tag_somedata, &vsomedata, /* flags*/ 0,\n" +" &map_somedata);\n" +" if(error)\n" +" return error;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:521 +#, no-wrap +msgid "" +" bus_dmamap_load(tag_somedata, map_somedata, (void *)vsomedata,\n" +" sizeof (struct somedata), alloc_callback,\n" +" (void *) &psomedata, /*flags*/0);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:524 +msgid "" +"Looks a bit long and complicated but that is the way to do it. The practical " +"consequence is: if multiple memory areas are allocated always together it " +"would be a really good idea to combine them all into one structure and " +"allocate as one (if the alignment and boundary limitations permit)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:526 +msgid "" +"When loading an arbitrary buffer into the map created by " +"`bus_dmamap_create()` special measures must be taken to synchronize with the " +"callback in case it would be delayed. The code would look like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:532 +#, no-wrap +msgid "" +" {\n" +" int s;\n" +" int error;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:551 +#, no-wrap +msgid "" +" s = splsoftvm();\n" +" error = bus_dmamap_load(\n" +" dmat,\n" +" dmamap,\n" +" buffer_ptr,\n" +" buffer_len,\n" +" callback,\n" +" /*callback_arg*/ buffer_descriptor,\n" +" /*flags*/0);\n" +" if (error == EINPROGRESS) {\n" +" /*\n" +" * Do whatever is needed to ensure synchronization\n" +" * with callback. Callback is guaranteed not to be started\n" +" * until we do splx() or tsleep().\n" +" */\n" +" }\n" +" splx(s);\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:554 +msgid "Two possible approaches for the processing of requests are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:556 +msgid "" +"If requests are completed by marking them explicitly as done (such as the " +"CAM requests) then it would be simpler to put all the further processing " +"into the callback driver which would mark the request when it is done. Then " +"not much extra synchronization is needed. For the flow control reasons it " +"may be a good idea to freeze the request queue until this request gets " +"completed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:558 +msgid "" +"If requests are completed when the function returns (such as classic read or " +"write requests on character devices) then a synchronization flag should be " +"set in the buffer descriptor and `tsleep()` called. Later when the callback " +"gets called it will do its processing and check this synchronization flag. " +"If it is set then the callback should issue a wakeup. In this approach the " +"callback function could either do all the needed processing (just like the " +"previous case) or simply save the segments array in the buffer descriptor. " +"Then after callback completes the calling function could use this saved " +"segments array and do all the processing." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:560 +#, no-wrap +msgid "DMA" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:563 +msgid "" +"The Direct Memory Access (DMA) is implemented in the ISA bus through the DMA " +"controller (actually, two of them but that is an irrelevant detail). To make " +"the early ISA devices simple and cheap the logic of the bus control and " +"address generation was concentrated in the DMA controller. Fortunately, " +"FreeBSD provides a set of functions that mostly hide the annoying details of " +"the DMA controller from the device drivers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:565 +msgid "" +"The simplest case is for the fairly intelligent devices. Like the bus master " +"devices on PCI they can generate the bus cycles and memory addresses all by " +"themselves. The only thing they really need from the DMA controller is bus " +"arbitration. So for this purpose they pretend to be cascaded slave DMA " +"controllers. And the only thing needed from the system DMA controller is to " +"enable the cascaded mode on a DMA channel by calling the following function " +"when attaching the driver:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:567 +msgid "`void isa_dmacascade(int channel_number)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:569 +msgid "" +"All the further activity is done by programming the device. When detaching " +"the driver no DMA-related functions need to be called." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:571 +msgid "" +"For the simpler devices things get more complicated. The functions used are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:573 +msgid "`int isa_dma_acquire(int chanel_number)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:575 +msgid "" +"Reserve a DMA channel. Returns 0 on success or EBUSY if the channel was " +"already reserved by this or a different driver. Most of the ISA devices are " +"not able to share DMA channels anyway, so normally this function is called " +"when attaching a device. This reservation was made redundant by the modern " +"interface of bus resources but still must be used in addition to the latter. " +"If not used then later, other DMA routines will panic." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:576 +msgid "`int isa_dma_release(int chanel_number)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:578 +msgid "" +"Release a previously reserved DMA channel. No transfers must be in progress " +"when the channel is released (in addition the device must not try to " +"initiate transfer after the channel is released)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:579 +msgid "`void isa_dmainit(int chan, u_int bouncebufsize)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:581 +msgid "" +"Allocate a bounce buffer for use with the specified channel. The requested " +"size of the buffer can not exceed 64KB. This bounce buffer will be " +"automatically used later if a transfer buffer happens to be not physically " +"contiguous or outside of the memory accessible by the ISA bus or crossing " +"the 64KB boundary. If the transfers will be always done from buffers which " +"conform to these conditions (such as those allocated by `bus_dmamem_alloc()` " +"with proper limitations) then `isa_dmainit()` does not have to be called. " +"But it is quite convenient to transfer arbitrary data using the DMA " +"controller. The bounce buffer will automatically care of the scatter-gather " +"issues." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:583 +msgid "_chan_ - channel number" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:584 +msgid "_bouncebufsize_ - size of the bounce buffer in bytes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:586 +msgid "`void isa_dmastart(int flags, caddr_t addr, u_int nbytes, int chan)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:588 +msgid "" +"Prepare to start a DMA transfer. This function must be called to set up the " +"DMA controller before actually starting transfer on the device. It checks " +"that the buffer is contiguous and falls into the ISA memory range, if not " +"then the bounce buffer is automatically used. If bounce buffer is required " +"but not set up by `isa_dmainit()` or too small for the requested transfer " +"size then the system will panic. In case of a write request with bounce " +"buffer the data will be automatically copied to the bounce buffer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:589 +msgid "" +"flags - a bitmask determining the type of operation to be done. The " +"direction bits B_READ and B_WRITE are mutually exclusive." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:591 +msgid "B_READ - read from the ISA bus into memory" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:592 +msgid "B_WRITE - write from the memory to the ISA bus" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:593 +msgid "" +"B_RAW - if set then the DMA controller will remember the buffer and after " +"the end of transfer will automatically re-initialize itself to repeat " +"transfer of the same buffer again (of course, the driver may change the data " +"in the buffer before initiating another transfer in the device). If not set " +"then the parameters will work only for one transfer, and `isa_dmastart()` " +"will have to be called again before initiating the next transfer. Using " +"B_RAW makes sense only if the bounce buffer is not used." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:595 +msgid "addr - virtual address of the buffer" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:596 +msgid "" +"nbytes - length of the buffer. Must be less or equal to 64KB. Length of 0 is " +"not allowed: the DMA controller will understand it as 64KB while the kernel " +"code will understand it as 0 and that would cause unpredictable effects. For " +"channels number 4 and higher the length must be even because these channels " +"transfer 2 bytes at a time. In case of an odd length the last byte will not " +"be transferred." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:597 +msgid "chan - channel number" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:598 +msgid "`void isa_dmadone(int flags, caddr_t addr, int nbytes, int chan)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:600 +msgid "" +"Synchronize the memory after device reports that transfer is done. If that " +"was a read operation with a bounce buffer then the data will be copied from " +"the bounce buffer to the original buffer. Arguments are the same as for " +"`isa_dmastart()`. Flag B_RAW is permitted but it does not affect " +"`isa_dmadone()` in any way." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:601 +msgid "`int isa_dmastatus(int channel_number)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:603 +msgid "" +"Returns the number of bytes left in the current transfer to be transferred. " +"In case the flag B_READ was set in `isa_dmastart()` the number returned will " +"never be equal to zero. At the end of transfer it will be automatically " +"reset back to the length of buffer. The normal use is to check the number of " +"bytes left after the device signals that the transfer is completed. If the " +"number of bytes is not 0 then something probably went wrong with that " +"transfer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:604 +msgid "`int isa_dmastop(int channel_number)`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:606 +msgid "" +"Aborts the current transfer and returns the number of bytes left " +"untransferred." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:608 +#, no-wrap +msgid "xxx_isa_probe" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:611 +msgid "" +"This function probes if a device is present. If the driver supports auto-" +"detection of some part of device configuration (such as interrupt vector or " +"memory address) this auto-detection must be done in this routine." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:613 +msgid "" +"As for any other bus, if the device cannot be detected or is detected but " +"failed the self-test or some other problem happened then it returns a " +"positive value of error. The value `ENXIO` must be returned if the device is " +"not present. Other error values may mean other conditions. Zero or negative " +"values mean success. Most of the drivers return zero as success." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:615 +msgid "" +"The negative return values are used when a PnP device supports multiple " +"interfaces. For example, an older compatibility interface and a newer " +"advanced interface which are supported by different drivers. Then both " +"drivers would detect the device. The driver which returns a higher value in " +"the probe routine takes precedence (in other words, the driver returning 0 " +"has highest precedence, one returning -1 is next, one returning -2 is after " +"it and so on). In result the devices which support only the old interface " +"will be handled by the old driver (which should return -1 from the probe " +"routine) while the devices supporting the new interface as well will be " +"handled by the new driver (which should return 0 from the probe routine)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:617 +msgid "" +"The device descriptor struct xxx_softc is allocated by the system before " +"calling the probe routine. If the probe routine returns an error the " +"descriptor will be automatically deallocated by the system. So if a probing " +"error occurs the driver must make sure that all the resources it used during " +"probe are deallocated and that nothing keeps the descriptor from being " +"safely deallocated. If the probe completes successfully the descriptor will " +"be preserved by the system and later passed to the routine " +"`xxx_isa_attach()`. If a driver returns a negative value it can not be sure " +"that it will have the highest priority and its attach routine will be " +"called. So in this case it also must release all the resources before " +"returning and if necessary allocate them again in the attach routine. When " +"`xxx_isa_probe()` returns 0 releasing the resources before returning is also " +"a good idea and a well-behaved driver should do so. But in cases where there " +"is some problem with releasing the resources the driver is allowed to keep " +"resources between returning 0 from the probe routine and execution of the " +"attach routine." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:619 +msgid "" +"A typical probe routine starts with getting the device descriptor and unit:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:626 +#, no-wrap +msgid "" +" struct xxx_softc *sc = device_get_softc(dev);\n" +" int unit = device_get_unit(dev);\n" +" int pnperror;\n" +" int error = 0;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:629 +#, no-wrap +msgid "" +" sc->dev = dev; /* link it back */\n" +" sc->unit = unit;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:632 +msgid "" +"Then check for the PnP devices. The check is carried out by a table " +"containing the list of PnP IDs supported by this driver and human-readable " +"descriptions of the device models corresponding to these IDs." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:638 +#, no-wrap +msgid "" +" pnperror=ISA_PNP_PROBE(device_get_parent(dev), dev,\n" +" xxx_pnp_ids); if(pnperror == ENXIO) return ENXIO;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:641 +msgid "" +"The logic of ISA_PNP_PROBE is the following: If this card (device unit) was " +"not detected as PnP then ENOENT will be returned. If it was detected as PnP " +"but its detected ID does not match any of the IDs in the table then ENXIO is " +"returned. Finally, if it has PnP support and it matches on of the IDs in the " +"table, 0 is returned and the appropriate description from the table is set " +"by `device_set_desc()`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:643 +msgid "" +"If a driver supports only PnP devices then the condition would look like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:648 +#, no-wrap +msgid "" +" if(pnperror != 0)\n" +" return pnperror;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:651 +msgid "" +"No special treatment is required for the drivers which do not support PnP " +"because they pass an empty PnP ID table and will always get ENXIO if called " +"on a PnP card." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:653 +msgid "" +"The probe routine normally needs at least some minimal set of resources, " +"such as I/O port number to find the card and probe it. Depending on the " +"hardware the driver may be able to discover the other necessary resources " +"automatically. The PnP devices have all the resources pre-set by the PnP " +"subsystem, so the driver does not need to discover them by itself." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:655 +msgid "" +"Typically the minimal information required to get access to the device is " +"the I/O port number. Then some devices allow to get the rest of information " +"from the device configuration registers (though not all devices do that). So " +"first we try to get the port start value:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:660 +#, no-wrap +msgid "" +" sc->port0 = bus_get_resource_start(dev,\n" +" SYS_RES_IOPORT, 0 /*rid*/); if(sc->port0 == 0) return ENXIO;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:663 +msgid "" +"The base port address is saved in the structure softc for future use. If it " +"will be used very often then calling the resource function each time would " +"be prohibitively slow. If we do not get a port we just return an error. Some " +"device drivers can instead be clever and try to probe all the possible " +"ports, like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:677 +#, no-wrap +msgid "" +" /* table of all possible base I/O port addresses for this device */\n" +" static struct xxx_allports {\n" +" u_short port; /* port address */\n" +" short used; /* flag: if this port is already used by some unit */\n" +" } xxx_allports = {\n" +" { 0x300, 0 },\n" +" { 0x320, 0 },\n" +" { 0x340, 0 },\n" +" { 0, 0 } /* end of table */\n" +" };\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:681 +#, no-wrap +msgid "" +" ...\n" +" int port, i;\n" +" ...\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:687 +#, no-wrap +msgid "" +" port = bus_get_resource_start(dev, SYS_RES_IOPORT, 0 /*rid*/);\n" +" if(port !=0 ) {\n" +" for(i=0; xxx_allports[i].port!=0; i++) {\n" +" if(xxx_allports[i].used || xxx_allports[i].port != port)\n" +" continue;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:695 +#, no-wrap +msgid "" +" /* found it */\n" +" xxx_allports[i].used = 1;\n" +" /* do probe on a known port */\n" +" return xxx_really_probe(dev, port);\n" +" }\n" +" return ENXIO; /* port is unknown or already used */\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:700 +#, no-wrap +msgid "" +" /* we get here only if we need to guess the port */\n" +" for(i=0; xxx_allports[i].port!=0; i++) {\n" +" if(xxx_allports[i].used)\n" +" continue;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:705 +#, no-wrap +msgid "" +" /* mark as used - even if we find nothing at this port\n" +" * at least we won't probe it in future\n" +" */\n" +" xxx_allports[i].used = 1;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:712 +#, no-wrap +msgid "" +" error = xxx_really_probe(dev, xxx_allports[i].port);\n" +" if(error == 0) /* found a device at that port */\n" +" return 0;\n" +" }\n" +" /* probed all possible addresses, none worked */\n" +" return ENXIO;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:715 +msgid "" +"Of course, normally the driver's `identify()` routine should be used for " +"such things. But there may be one valid reason why it may be better to be " +"done in `probe()`: if this probe would drive some other sensitive device " +"crazy. The probe routines are ordered with consideration of the `sensitive` " +"flag: the sensitive devices get probed first and the rest of the devices " +"later. But the `identify()` routines are called before any probes, so they " +"show no respect to the sensitive devices and may upset them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:717 +msgid "" +"Now, after we got the starting port we need to set the port count (except " +"for PnP devices) because the kernel does not have this information in the " +"configuration file." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:725 +#, no-wrap +msgid "" +" if(pnperror /* only for non-PnP devices */\n" +" && bus_set_resource(dev, SYS_RES_IOPORT, 0, sc->port0,\n" +" XXX_PORT_COUNT)<0)\n" +" return ENXIO;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:728 +msgid "" +"Finally allocate and activate a piece of port address space (special values " +"of start and end mean \"use those we set by ``bus_set_resource()``\"):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:736 +#, no-wrap +msgid "" +" sc->port0_rid = 0;\n" +" sc->port0_r = bus_alloc_resource(dev, SYS_RES_IOPORT,\n" +" &sc->port0_rid,\n" +" /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:739 +#, no-wrap +msgid "" +" if(sc->port0_r == NULL)\n" +" return ENXIO;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:742 +msgid "" +"Now having access to the port-mapped registers we can poke the device in " +"some way and check if it reacts like it is expected to. If it does not then " +"there is probably some other device or no device at all at this address." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:744 +msgid "" +"Normally drivers do not set up the interrupt handlers until the attach " +"routine. Instead they do probes in the polling mode using the `DELAY()` " +"function for timeout. The probe routine must never hang forever, all the " +"waits for the device must be done with timeouts. If the device does not " +"respond within the time it is probably broken or misconfigured and the " +"driver must return error. When determining the timeout interval give the " +"device some extra time to be on the safe side: although `DELAY()` is " +"supposed to delay for the same amount of time on any machine it has some " +"margin of error, depending on the exact CPU." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:746 +msgid "" +"If the probe routine really wants to check that the interrupts really work " +"it may configure and probe the interrupts too. But that is not recommended." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:753 +#, no-wrap +msgid "" +" /* implemented in some very device-specific way */\n" +" if(error = xxx_probe_ports(sc))\n" +" goto bad; /* will deallocate the resources before returning */\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:756 +msgid "" +"The function `xxx_probe_ports()` may also set the device description " +"depending on the exact model of device it discovers. But if there is only " +"one supported device model this can be as well done in a hardcoded way. Of " +"course, for the PnP devices the PnP support sets the description from the " +"table automatically." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:761 +#, no-wrap +msgid "" +" if(pnperror)\n" +" device_set_desc(dev, \"Our device model 1234\");\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:764 +msgid "" +"Then the probe routine should either discover the ranges of all the " +"resources by reading the device configuration registers or make sure that " +"they were set explicitly by the user. We will consider it with an example of " +"on-board memory. The probe routine should be as non-intrusive as possible, " +"so allocation and check of functionality of the rest of resources (besides " +"the ports) would be better left to the attach routine." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:766 +msgid "" +"The memory address may be specified in the kernel configuration file or on " +"some devices it may be pre-configured in non-volatile configuration " +"registers. If both sources are available and different, which one should be " +"used? Probably if the user bothered to set the address explicitly in the " +"kernel configuration file they know what they are doing and this one should " +"take precedence. An example of implementation could be:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:774 +#, no-wrap +msgid "" +" /* try to find out the config address first */\n" +" sc->mem0_p = bus_get_resource_start(dev, SYS_RES_MEMORY, 0 /*rid*/);\n" +" if(sc->mem0_p == 0) { /* nope, not specified by user */\n" +" sc->mem0_p = xxx_read_mem0_from_device_config(sc);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:782 +#, no-wrap +msgid "" +" if(sc->mem0_p == 0)\n" +" /* can't get it from device config registers either */\n" +" goto bad;\n" +" } else {\n" +" if(xxx_set_mem0_address_on_device(sc) < 0)\n" +" goto bad; /* device does not support that address */\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:794 +#, no-wrap +msgid "" +" /* just like the port, set the memory size,\n" +" * for some devices the memory size would not be constant\n" +" * but should be read from the device configuration registers instead\n" +" * to accommodate different models of devices. Another option would\n" +" * be to let the user set the memory size as \"msize\" configuration\n" +" * resource which will be automatically handled by the ISA bus.\n" +" */\n" +" if(pnperror) { /* only for non-PnP devices */\n" +" sc->mem0_size = bus_get_resource_count(dev, SYS_RES_MEMORY, 0 /*rid*/);\n" +" if(sc->mem0_size == 0) /* not specified by user */\n" +" sc->mem0_size = xxx_read_mem0_size_from_device_config(sc);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:803 +#, no-wrap +msgid "" +" if(sc->mem0_size == 0) {\n" +" /* suppose this is a very old model of device without\n" +" * auto-configuration features and the user gave no preference,\n" +" * so assume the minimalistic case\n" +" * (of course, the real value will vary with the driver)\n" +" */\n" +" sc->mem0_size = 8*1024;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:806 +#, no-wrap +msgid "" +" if(xxx_set_mem0_size_on_device(sc) < 0)\n" +" goto bad; /* device does not support that size */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:813 +#, no-wrap +msgid "" +" if(bus_set_resource(dev, SYS_RES_MEMORY, /*rid*/0,\n" +" sc->mem0_p, sc->mem0_size)<0)\n" +" goto bad;\n" +" } else {\n" +" sc->mem0_size = bus_get_resource_count(dev, SYS_RES_MEMORY, 0 /*rid*/);\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:816 +msgid "Resources for IRQ and DRQ are easy to check by analogy." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:818 +msgid "If all went well then release all the resources and return success." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:823 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1086 +#, no-wrap +msgid "" +" xxx_free_resources(sc);\n" +" return 0;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:826 +msgid "" +"Finally, handle the troublesome situations. All the resources should be " +"deallocated before returning. We make use of the fact that before the " +"structure softc is passed to us it gets zeroed out, so we can find out if " +"some resource was allocated: then its descriptor is non-zero." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:830 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1047 +#, no-wrap +msgid " bad:\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:836 +#, no-wrap +msgid "" +" xxx_free_resources(sc);\n" +" if(error)\n" +" return error;\n" +" else /* exact error is unknown */\n" +" return ENXIO;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:839 +msgid "" +"That would be all for the probe routine. Freeing of resources is done from " +"multiple places, so it is moved to a function which may look like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:847 +#, no-wrap +msgid "" +"static void\n" +" xxx_free_resources(sc)\n" +" struct xxx_softc *sc;\n" +" {\n" +" /* check every resource and free if not zero */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:855 +#, no-wrap +msgid "" +" /* interrupt handler */\n" +" if(sc->intr_r) {\n" +" bus_teardown_intr(sc->dev, sc->intr_r, sc->intr_cookie);\n" +" bus_release_resource(sc->dev, SYS_RES_IRQ, sc->intr_rid,\n" +" sc->intr_r);\n" +" sc->intr_r = 0;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:870 +#, no-wrap +msgid "" +" /* all kinds of memory maps we could have allocated */\n" +" if(sc->data_p) {\n" +" bus_dmamap_unload(sc->data_tag, sc->data_map);\n" +" sc->data_p = 0;\n" +" }\n" +" if(sc->data) { /* sc->data_map may be legitimately equal to 0 */\n" +" /* the map will also be freed */\n" +" bus_dmamem_free(sc->data_tag, sc->data, sc->data_map);\n" +" sc->data = 0;\n" +" }\n" +" if(sc->data_tag) {\n" +" bus_dma_tag_destroy(sc->data_tag);\n" +" sc->data_tag = 0;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:872 +#, no-wrap +msgid " ... free other maps and tags if we have them ...\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:877 +#, no-wrap +msgid "" +" if(sc->parent_tag) {\n" +" bus_dma_tag_destroy(sc->parent_tag);\n" +" sc->parent_tag = 0;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:891 +#, no-wrap +msgid "" +" /* release all the bus resources */\n" +" if(sc->mem0_r) {\n" +" bus_release_resource(sc->dev, SYS_RES_MEMORY, sc->mem0_rid,\n" +" sc->mem0_r);\n" +" sc->mem0_r = 0;\n" +" }\n" +" ...\n" +" if(sc->port0_r) {\n" +" bus_release_resource(sc->dev, SYS_RES_IOPORT, sc->port0_rid,\n" +" sc->port0_r);\n" +" sc->port0_r = 0;\n" +" }\n" +" }\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:894 +#, no-wrap +msgid "xxx_isa_attach" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:897 +msgid "" +"The attach routine actually connects the driver to the system if the probe " +"routine returned success and the system had chosen to attach that driver. If " +"the probe routine returned 0 then the attach routine may expect to receive " +"the device structure softc intact, as it was set by the probe routine. Also " +"if the probe routine returns 0 it may expect that the attach routine for " +"this device shall be called at some point in the future. If the probe " +"routine returns a negative value then the driver may make none of these " +"assumptions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:899 +msgid "" +"The attach routine returns 0 if it completed successfully or error code " +"otherwise." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:901 +msgid "" +"The attach routine starts just like the probe routine, with getting some " +"frequently used data into more accessible variables." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:907 +#, no-wrap +msgid "" +" struct xxx_softc *sc = device_get_softc(dev);\n" +" int unit = device_get_unit(dev);\n" +" int error = 0;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:910 +msgid "" +"Then allocate and activate all the necessary resources. As normally the port " +"range will be released before returning from probe, it has to be allocated " +"again. We expect that the probe routine had properly set all the resource " +"ranges, as well as saved them in the structure softc. If the probe routine " +"had left some resource allocated then it does not need to be allocated again " +"(which would be considered an error)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:916 +#, no-wrap +msgid "" +" sc->port0_rid = 0;\n" +" sc->port0_r = bus_alloc_resource(dev, SYS_RES_IOPORT, &sc->port0_rid,\n" +" /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:919 +#, no-wrap +msgid "" +" if(sc->port0_r == NULL)\n" +" return ENXIO;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:924 +#, no-wrap +msgid "" +" /* on-board memory */\n" +" sc->mem0_rid = 0;\n" +" sc->mem0_r = bus_alloc_resource(dev, SYS_RES_MEMORY, &sc->mem0_rid,\n" +" /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:927 +#, no-wrap +msgid "" +" if(sc->mem0_r == NULL)\n" +" goto bad;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:930 +#, no-wrap +msgid "" +" /* get its virtual address */\n" +" sc->mem0_v = rman_get_virtual(sc->mem0_r);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:933 +msgid "" +"The DMA request channel (DRQ) is allocated likewise. To initialize it use " +"functions of the `isa_dma*()` family. For example:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:935 +msgid "`isa_dmacascade(sc->drq0);`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:937 +msgid "" +"The interrupt request line (IRQ) is a bit special. Besides allocation the " +"driver's interrupt handler should be associated with it. Historically in the " +"old ISA drivers the argument passed by the system to the interrupt handler " +"was the device unit number. But in modern drivers the convention suggests " +"passing the pointer to structure softc. The important reason is that when " +"the structures softc are allocated dynamically then getting the unit number " +"from softc is easy while getting softc from the unit number is difficult. " +"Also this convention makes the drivers for different buses look more uniform " +"and allows them to share the code: each bus gets its own probe, attach, " +"detach and other bus-specific routines while the bulk of the driver code may " +"be shared among them." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:944 +#, no-wrap +msgid "" +" sc->intr_rid = 0;\n" +" sc->intr_r = bus_alloc_resource(dev, SYS_RES_MEMORY, &sc->intr_rid,\n" +" /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:947 +#, no-wrap +msgid "" +" if(sc->intr_r == NULL)\n" +" goto bad;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:956 +#, no-wrap +msgid "" +" /*\n" +" * XXX_INTR_TYPE is supposed to be defined depending on the type of\n" +" * the driver, for example as INTR_TYPE_CAM for a CAM driver\n" +" */\n" +" error = bus_setup_intr(dev, sc->intr_r, XXX_INTR_TYPE,\n" +" (driver_intr_t *) xxx_intr, (void *) sc, &sc->intr_cookie);\n" +" if(error)\n" +" goto bad;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:959 +msgid "" +"If the device needs to make DMA to the main memory then this memory should " +"be allocated like described before:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:971 +#, no-wrap +msgid "" +" error=bus_dma_tag_create(NULL, /*alignment*/ 4,\n" +" /*boundary*/ 0, /*lowaddr*/ BUS_SPACE_MAXADDR_24BIT,\n" +" /*highaddr*/ BUS_SPACE_MAXADDR, /*filter*/ NULL, /*filterarg*/ NULL,\n" +" /*maxsize*/ BUS_SPACE_MAXSIZE_24BIT,\n" +" /*nsegments*/ BUS_SPACE_UNRESTRICTED,\n" +" /*maxsegsz*/ BUS_SPACE_MAXSIZE_24BIT, /*flags*/ 0,\n" +" &sc->parent_tag);\n" +" if(error)\n" +" goto bad;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:988 +#, no-wrap +msgid "" +" /* many things get inherited from the parent tag\n" +" * sc->data is supposed to point to the structure with the shared data,\n" +" * for example for a ring buffer it could be:\n" +" * struct {\n" +" * u_short rd_pos;\n" +" * u_short wr_pos;\n" +" * char bf[XXX_RING_BUFFER_SIZE]\n" +" * } *data;\n" +" */\n" +" error=bus_dma_tag_create(sc->parent_tag, 1,\n" +" 0, BUS_SPACE_MAXADDR, 0, /*filter*/ NULL, /*filterarg*/ NULL,\n" +" /*maxsize*/ sizeof(* sc->data), /*nsegments*/ 1,\n" +" /*maxsegsz*/ sizeof(* sc->data), /*flags*/ 0,\n" +" &sc->data_tag);\n" +" if(error)\n" +" goto bad;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:993 +#, no-wrap +msgid "" +" error = bus_dmamem_alloc(sc->data_tag, &sc->data, /* flags*/ 0,\n" +" &sc->data_map);\n" +" if(error)\n" +" goto bad;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1009 +#, no-wrap +msgid "" +" /* xxx_alloc_callback() just saves the physical address at\n" +" * the pointer passed as its argument, in this case &sc->data_p.\n" +" * See details in the section on bus memory mapping.\n" +" * It can be implemented like:\n" +" *\n" +" * static void\n" +" * xxx_alloc_callback(void *arg, bus_dma_segment_t *seg,\n" +" * int nseg, int error)\n" +" * {\n" +" * *(bus_addr_t *)arg = seg[0].ds_addr;\n" +" * }\n" +" */\n" +" bus_dmamap_load(sc->data_tag, sc->data_map, (void *)sc->data,\n" +" sizeof (* sc->data), xxx_alloc_callback, (void *) &sc->data_p,\n" +" /*flags*/0);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1012 +msgid "" +"After all the necessary resources are allocated the device should be " +"initialized. The initialization may include testing that all the expected " +"features are functional." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1017 +#, no-wrap +msgid "" +" if(xxx_initialize(sc) < 0)\n" +" goto bad;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1020 +msgid "" +"The bus subsystem will automatically print on the console the device " +"description set by probe. But if the driver wants to print some extra " +"information about the device it may do so, for example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1025 +#, no-wrap +msgid " device_printf(dev, \"has on-card FIFO buffer of %d bytes\\n\", sc->fifosize);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1028 +msgid "" +"If the initialization routine experiences any problems then printing " +"messages about them before returning error is also recommended." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1030 +msgid "" +"The final step of the attach routine is attaching the device to its " +"functional subsystem in the kernel. The exact way to do it depends on the " +"type of the driver: a character device, a block device, a network device, a " +"CAM SCSI bus device and so on." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1032 +msgid "If all went well then return success." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1038 +#, no-wrap +msgid "" +" error = xxx_attach_subsystem(sc);\n" +" if(error)\n" +" goto bad;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1040 +#, no-wrap +msgid " return 0;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1043 +msgid "" +"Finally, handle the troublesome situations. All the resources should be " +"deallocated before returning an error. We make use of the fact that before " +"the structure softc is passed to us it gets zeroed out, so we can find out " +"if some resource was allocated: then its descriptor is non-zero." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1053 +#, no-wrap +msgid "" +" xxx_free_resources(sc);\n" +" if(error)\n" +" return error;\n" +" else /* exact error is unknown */\n" +" return ENXIO;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1056 +msgid "That would be all for the attach routine." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1058 +#, no-wrap +msgid "xxx_isa_detach" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1061 +msgid "" +"If this function is present in the driver and the driver is compiled as a " +"loadable module then the driver gets the ability to be unloaded. This is an " +"important feature if the hardware supports hot plug. But the ISA bus does " +"not support hot plug, so this feature is not particularly important for the " +"ISA devices. The ability to unload a driver may be useful when debugging it, " +"but in many cases installation of the new version of the driver would be " +"required only after the old version somehow wedges the system and a reboot " +"will be needed anyway, so the efforts spent on writing the detach routine " +"may not be worth it. Another argument that unloading would allow upgrading " +"the drivers on a production machine seems to be mostly theoretical. " +"Installing a new version of a driver is a dangerous operation which should " +"never be performed on a production machine (and which is not permitted when " +"the system is running in secure mode). Still, the detach routine may be " +"provided for the sake of completeness." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1063 +msgid "" +"The detach routine returns 0 if the driver was successfully detached or the " +"error code otherwise." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1065 +msgid "" +"The logic of detach is a mirror of the attach. The first thing to do is to " +"detach the driver from its kernel subsystem. If the device is currently open " +"then the driver has two choices: refuse to be detached or forcibly close and " +"proceed with detach. The choice used depends on the ability of the " +"particular kernel subsystem to do a forced close and on the preferences of " +"the driver's author. Generally the forced close seems to be the preferred " +"alternative." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1070 +#, no-wrap +msgid "" +" struct xxx_softc *sc = device_get_softc(dev);\n" +" int error;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1074 +#, no-wrap +msgid "" +" error = xxx_detach_subsystem(sc);\n" +" if(error)\n" +" return error;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1077 +msgid "" +"Next the driver may want to reset the hardware to some consistent state. " +"That includes stopping any ongoing transfers, disabling the DMA channels and " +"interrupts to avoid memory corruption by the device. For most of the drivers " +"this is exactly what the shutdown routine does, so if it is included in the " +"driver we can just call it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1079 +msgid "`xxx_isa_shutdown(dev);`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1081 +msgid "And finally release all the resources and return success." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1089 +#, no-wrap +msgid "xxx_isa_shutdown" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1092 +msgid "" +"This routine is called when the system is about to be shut down. It is " +"expected to bring the hardware to some consistent state. For most of the ISA " +"devices no special action is required, so the function is not really " +"necessary because the device will be re-initialized on reboot anyway. But " +"some devices have to be shut down with a special procedure, to make sure " +"that they will be properly detected after soft reboot (this is especially " +"true for many devices with proprietary identification protocols). In any " +"case disabling DMA and interrupts in the device registers and stopping any " +"ongoing transfers is a good idea. The exact action depends on the hardware, " +"so we do not consider it here in any detail." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1094 +#, no-wrap +msgid "xxx_intr" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1097 +msgid "" +"The interrupt handler is called when an interrupt is received which may be " +"from this particular device. The ISA bus does not support interrupt sharing " +"(except in some special cases) so in practice if the interrupt handler is " +"called then the interrupt almost for sure came from its device. Still, the " +"interrupt handler must poll the device registers and make sure that the " +"interrupt was generated by its device. If not it should just return." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1099 +msgid "" +"The old convention for the ISA drivers was getting the device unit number as " +"an argument. This is obsolete, and the new drivers receive whatever argument " +"was specified for them in the attach routine when calling " +"`bus_setup_intr()`. By the new convention it should be the pointer to the " +"structure softc. So the interrupt handler commonly starts as:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1106 +#, no-wrap +msgid "" +" static void\n" +" xxx_intr(struct xxx_softc *sc)\n" +" {\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1109 +msgid "" +"It runs at the interrupt priority level specified by the interrupt type " +"parameter of `bus_setup_intr()`. That means that all the other interrupts of " +"the same type as well as all the software interrupts are disabled." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1111 +msgid "To avoid races it is commonly written as a loop:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1119 +#, no-wrap +msgid "" +" while(xxx_interrupt_pending(sc)) {\n" +" xxx_process_interrupt(sc);\n" +" xxx_acknowledge_interrupt(sc);\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1121 +msgid "" +"The interrupt handler has to acknowledge interrupt to the device only but " +"not to the interrupt controller, the system takes care of the latter." +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/jail/_index.adoc b/documentation/content/en/books/arch-handbook/jail/_index.adoc index 48cc3c1a0c..a77ce2ae10 100644 --- a/documentation/content/en/books/arch-handbook/jail/_index.adoc +++ b/documentation/content/en/books/arch-handbook/jail/_index.adoc @@ -6,7 +6,8 @@ description: The Jail Subsystem tags: ["jail", "architecture", "networking", "kernel"] showBookMenu: true weight: 5 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/jail/" --- [[jail]] diff --git a/documentation/content/en/books/arch-handbook/jail/_index.po b/documentation/content/en/books/arch-handbook/jail/_index.po new file mode 100644 index 0000000000..11a5c7c097 --- /dev/null +++ b/documentation/content/en/books/arch-handbook/jail/_index.po @@ -0,0 +1,981 @@ +# 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/jail/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:14 +#, no-wrap +msgid "The Jail Subsystem" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:1 +#, no-wrap +msgid "Chapter 4. The Jail Subsystem" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:52 +msgid "" +"On most UNIX(R) systems, `root` has omnipotent power. This promotes " +"insecurity. If an attacker gained `root` on a system, he would have every " +"function at his fingertips. In FreeBSD there are sysctls which dilute the " +"power of `root`, in order to minimize the damage caused by an attacker. " +"Specifically, one of these functions is called `secure levels`. Similarly, " +"another function which is present from FreeBSD 4.0 and onward, is a utility " +"called man:jail[8]. Jail chroots an environment and sets certain " +"restrictions on processes which are forked within the jail. For example, a " +"jailed process cannot affect processes outside the jail, utilize certain " +"system calls, or inflict any damage on the host environment." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:54 +msgid "" +"Jail is becoming the new security model. People are running potentially " +"vulnerable servers such as Apache, BIND, and sendmail within jails, so that " +"if an attacker gains `root` within the jail, it is only an annoyance, and " +"not a devastation. This article mainly focuses on the internals (source " +"code) of jail. For information on how to set up a jail see the extref:" +"{handbook}[handbook entry on jails, jails]." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:56 +#, no-wrap +msgid "Architecture" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:59 +msgid "" +"Jail consists of two realms: the userland program, man:jail[8], and the code " +"implemented within the kernel: the man:jail[2] system call and associated " +"restrictions. I will be discussing the userland program and then how jail is " +"implemented within the kernel." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:60 +#, no-wrap +msgid "Userland Code" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:63 +msgid "" +"The source for the userland jail is located in [.filename]#/usr/src/usr.sbin/" +"jail#, consisting of one file, [.filename]#jail.c#. The program takes these " +"arguments: the path of the jail, hostname, IP address, and the command to be " +"executed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:64 +#, no-wrap +msgid "Data Structures" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:67 +msgid "" +"In [.filename]#jail.c#, the first thing I would note is the declaration of " +"an important structure `struct jail j;` which was included from [.filename]#/" +"usr/include/sys/jail.h#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:69 +msgid "The definition of the `jail` structure is:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:73 +#, no-wrap +msgid "/usr/include/sys/jail.h:\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:80 +#, no-wrap +msgid "" +"struct jail {\n" +" u_int32_t version;\n" +" char *path;\n" +" char *hostname;\n" +" u_int32_t ip_number;\n" +"};\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:83 +msgid "" +"As you can see, there is an entry for each of the arguments passed to the " +"man:jail[8] program, and indeed, they are set during its execution." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:97 +#, no-wrap +msgid "" +"/usr/src/usr.sbin/jail/jail.c\n" +"char path[PATH_MAX];\n" +"...\n" +"if (realpath(argv[0], path) == NULL)\n" +" err(1, \"realpath: %s\", argv[0]);\n" +"if (chdir(path) != 0)\n" +" err(1, \"chdir: %s\", path);\n" +"memset(&j, 0, sizeof(j));\n" +"j.version = 0;\n" +"j.path = path;\n" +"j.hostname = argv[1];\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:99 +#, no-wrap +msgid "Networking" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:102 +msgid "" +"One of the arguments passed to the man:jail[8] program is an IP address with " +"which the jail can be accessed over the network. man:jail[8] translates the " +"IP address given into host byte order and then stores it in `j` (the `jail` " +"structure)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:111 +#, no-wrap +msgid "" +"/usr/src/usr.sbin/jail/jail.c:\n" +"struct in_addr in;\n" +"...\n" +"if (inet_aton(argv[2], &in) == 0)\n" +" errx(1, \"Could not make sense of ip-number: %s\", argv[2]);\n" +"j.ip_number = ntohl(in.s_addr);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:114 +msgid "" +"The man:inet_aton[3] function \"interprets the specified character string as " +"an Internet address, placing the address into the structure provided.\" The " +"`ip_number` member in the `jail` structure is set only when the IP address " +"placed onto the `in` structure by man:inet_aton[3] is translated into host " +"byte order by man:ntohl[3]." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:115 +#, no-wrap +msgid "Jailing the Process" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:118 +msgid "" +"Finally, the userland program jails the process. Jail now becomes an " +"imprisoned process itself and then executes the command given using " +"man:execv[3]." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:126 +#, no-wrap +msgid "" +"/usr/src/usr.sbin/jail/jail.c\n" +"i = jail(&j);\n" +"...\n" +"if (execv(argv[3], argv + 3) != 0)\n" +" err(1, \"execv: %s\", argv[3]);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:129 +msgid "" +"As you can see, the `jail()` function is called, and its argument is the " +"`jail` structure which has been filled with the arguments given to the " +"program. Finally, the program you specify is executed. I will now discuss " +"how jail is implemented within the kernel." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:130 +#, no-wrap +msgid "Kernel Space" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:133 +msgid "" +"We will now be looking at the file [.filename]#/usr/src/sys/kern/" +"kern_jail.c#. This is the file where the man:jail[2] system call, " +"appropriate sysctls, and networking functions are defined." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:134 +#, no-wrap +msgid "Sysctls" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:137 +msgid "In [.filename]#kern_jail.c#, the following sysctls are defined:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:145 +#, no-wrap +msgid "" +"/usr/src/sys/kern/kern_jail.c:\n" +"int jail_set_hostname_allowed = 1;\n" +"SYSCTL_INT(_security_jail, OID_AUTO, set_hostname_allowed, CTLFLAG_RW,\n" +" &jail_set_hostname_allowed, 0,\n" +" \"Processes in jail can set their hostnames\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:150 +#, no-wrap +msgid "" +"int jail_socket_unixiproute_only = 1;\n" +"SYSCTL_INT(_security_jail, OID_AUTO, socket_unixiproute_only, CTLFLAG_RW,\n" +" &jail_socket_unixiproute_only, 0,\n" +" \"Processes in jail are limited to creating UNIX/IPv4/route sockets only\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:155 +#, no-wrap +msgid "" +"int jail_sysvipc_allowed = 0;\n" +"SYSCTL_INT(_security_jail, OID_AUTO, sysvipc_allowed, CTLFLAG_RW,\n" +" &jail_sysvipc_allowed, 0,\n" +" \"Processes in jail can use System V IPC primitives\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:160 +#, no-wrap +msgid "" +"static int jail_enforce_statfs = 2;\n" +"SYSCTL_INT(_security_jail, OID_AUTO, enforce_statfs, CTLFLAG_RW,\n" +" &jail_enforce_statfs, 0,\n" +" \"Processes in jail cannot see all mounted file systems\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:165 +#, no-wrap +msgid "" +"int jail_allow_raw_sockets = 0;\n" +"SYSCTL_INT(_security_jail, OID_AUTO, allow_raw_sockets, CTLFLAG_RW,\n" +" &jail_allow_raw_sockets, 0,\n" +" \"Prison root can create raw sockets\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:170 +#, no-wrap +msgid "" +"int jail_chflags_allowed = 0;\n" +"SYSCTL_INT(_security_jail, OID_AUTO, chflags_allowed, CTLFLAG_RW,\n" +" &jail_chflags_allowed, 0,\n" +" \"Processes in jail can alter system file flags\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:175 +#, no-wrap +msgid "" +"int jail_mount_allowed = 0;\n" +"SYSCTL_INT(_security_jail, OID_AUTO, mount_allowed, CTLFLAG_RW,\n" +" &jail_mount_allowed, 0,\n" +" \"Processes in jail can mount/unmount jail-friendly file systems\");\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:178 +msgid "" +"Each of these sysctls can be accessed by the user through the man:sysctl[8] " +"program. Throughout the kernel, these specific sysctls are recognized by " +"their name. For example, the name of the first sysctl is " +"`security.jail.set_hostname_allowed`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:179 +#, no-wrap +msgid "man:jail[2] System Call" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:182 +msgid "" +"Like all system calls, the man:jail[2] system call takes two arguments, " +"`struct thread *td` and `struct jail_args *uap`. `td` is a pointer to the " +"`thread` structure which describes the calling thread. In this context, " +"`uap` is a pointer to the structure in which a pointer to the `jail` " +"structure passed by the userland [.filename]#jail.c# is contained. When I " +"described the userland program before, you saw that the man:jail[2] system " +"call was given a `jail` structure as its own argument." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:193 +#, no-wrap +msgid "" +"/usr/src/sys/kern/kern_jail.c:\n" +"/*\n" +" * struct jail_args {\n" +" * struct jail *jail;\n" +" * };\n" +" */\n" +"int\n" +"jail(struct thread *td, struct jail_args *uap)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:196 +msgid "" +"Therefore, `uap->jail` can be used to access the `jail` structure which was " +"passed to the system call. Next, the system call copies the `jail` structure " +"into kernel space using the man:copyin[9] function. man:copyin[9] takes " +"three arguments: the address of the data which is to be copied into kernel " +"space, `uap->jail`, where to store it, `j` and the size of the storage. The " +"`jail` structure pointed by `uap->jail` is copied into kernel space and is " +"stored in another `jail` structure, `j`." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:201 +#, no-wrap +msgid "" +"/usr/src/sys/kern/kern_jail.c:\n" +"error = copyin(uap->jail, &j, sizeof(j));\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:204 +msgid "" +"There is another important structure defined in [.filename]#jail.h#. It is " +"the `prison` structure. The `prison` structure is used exclusively within " +"kernel space. Here is the definition of the `prison` structure." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:222 +#, no-wrap +msgid "" +"/usr/include/sys/jail.h:\n" +"struct prison {\n" +" LIST_ENTRY(prison) pr_list; /* (a) all prisons */\n" +" int pr_id; /* (c) prison id */\n" +" int pr_ref; /* (p) refcount */\n" +" char pr_path[MAXPATHLEN]; /* (c) chroot path */\n" +" struct vnode *pr_root; /* (c) vnode to rdir */\n" +" char pr_host[MAXHOSTNAMELEN]; /* (p) jail hostname */\n" +" u_int32_t pr_ip; /* (c) ip addr host */\n" +" void *pr_linux; /* (p) linux abi */\n" +" int pr_securelevel; /* (p) securelevel */\n" +" struct task pr_task; /* (d) destroy task */\n" +" struct mtx pr_mtx;\n" +" void **pr_slots; /* (p) additional data */\n" +"};\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:225 +msgid "" +"The man:jail[2] system call then allocates memory for a `prison` structure " +"and copies data between the `jail` and `prison` structure." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:239 +#, no-wrap +msgid "" +"/usr/src/sys/kern/kern_jail.c:\n" +"MALLOC(pr, struct prison *, sizeof(*pr), M_PRISON, M_WAITOK | M_ZERO);\n" +"...\n" +"error = copyinstr(j.path, &pr->pr_path, sizeof(pr->pr_path), 0);\n" +"if (error)\n" +" goto e_killmtx;\n" +"...\n" +"error = copyinstr(j.hostname, &pr->pr_host, sizeof(pr->pr_host), 0);\n" +"if (error)\n" +" goto e_dropvnref;\n" +"pr->pr_ip = j.ip_number;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:242 +msgid "" +"Next, we will discuss another important system call man:jail_attach[2], " +"which implements the function to put a process into the jail." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:253 +#, no-wrap +msgid "" +"/usr/src/sys/kern/kern_jail.c:\n" +"/*\n" +" * struct jail_attach_args {\n" +" * int jid;\n" +" * };\n" +" */\n" +"int\n" +"jail_attach(struct thread *td, struct jail_attach_args *uap)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:256 +msgid "" +"This system call makes the changes that can distinguish a jailed process " +"from those unjailed ones. To understand what man:jail_attach[2] does for us, " +"certain background information is needed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:258 +msgid "" +"On FreeBSD, each kernel visible thread is identified by its `thread` " +"structure, while the processes are described by their `proc` structures. You " +"can find the definitions of the `thread` and `proc` structure in " +"[.filename]#/usr/include/sys/proc.h#. For example, the `td` argument in any " +"system call is actually a pointer to the calling thread's `thread` " +"structure, as stated before. The `td_proc` member in the `thread` structure " +"pointed by `td` is a pointer to the `proc` structure which represents the " +"process that contains the thread represented by `td`. The `proc` structure " +"contains members which can describe the owner's identity(`p_ucred`), the " +"process resource limits(`p_limit`), and so on. In the `ucred` structure " +"pointed by `p_ucred` member in the `proc` structure, there is a pointer to " +"the `prison` structure(`cr_prison`)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:278 +#, no-wrap +msgid "" +"/usr/include/sys/proc.h:\n" +"struct thread {\n" +" ...\n" +" struct proc *td_proc;\n" +" ...\n" +"};\n" +"struct proc {\n" +" ...\n" +" struct ucred *p_ucred;\n" +" ...\n" +"};\n" +"/usr/include/sys/ucred.h\n" +"struct ucred {\n" +" ...\n" +" struct prison *cr_prison;\n" +" ...\n" +"};\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:281 +msgid "" +"In [.filename]#kern_jail.c#, the function `jail()` then calls function " +"`jail_attach()` with a given `jid`. And `jail_attach()` calls function " +"`change_root()` to change the root directory of the calling process. The " +"`jail_attach()` then creates a new `ucred` structure, and attaches the newly " +"created `ucred` structure to the calling process after it has successfully " +"attached the `prison` structure to the `ucred` structure. From then on, the " +"calling process is recognized as jailed. When the kernel routine `jailed()` " +"is called in the kernel with the newly created `ucred` structure as its " +"argument, it returns 1 to tell that the credential is connected with a jail. " +"The public ancestor process of all the process forked within the jail, is " +"the process which runs man:jail[8], as it calls the man:jail[2] system call. " +"When a program is executed through man:execve[2], it inherits the jailed " +"property of its parent's `ucred` structure, therefore it has a jailed " +"`ucred` structure." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:296 +#, no-wrap +msgid "" +"/usr/src/sys/kern/kern_jail.c\n" +"int\n" +"jail(struct thread *td, struct jail_args *uap)\n" +"{\n" +"...\n" +" struct jail_attach_args jaa;\n" +"...\n" +" error = jail_attach(td, &jaa);\n" +" if (error)\n" +" goto e_dropprref;\n" +"...\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:314 +#, no-wrap +msgid "" +"int\n" +"jail_attach(struct thread *td, struct jail_attach_args *uap)\n" +"{\n" +" struct proc *p;\n" +" struct ucred *newcred, *oldcred;\n" +" struct prison *pr;\n" +"...\n" +" p = td->td_proc;\n" +"...\n" +" pr = prison_find(uap->jid);\n" +"...\n" +" change_root(pr->pr_root, td);\n" +"...\n" +" newcred->cr_prison = pr;\n" +" p->p_ucred = newcred;\n" +"...\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:317 +msgid "" +"When a process is forked from its parent process, the man:fork[2] system " +"call uses `crhold()` to maintain the credential for the newly forked " +"process. It inherently keep the newly forked child's credential consistent " +"with its parent, so the child process is also jailed." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:324 +#, no-wrap +msgid "" +"/usr/src/sys/kern/kern_fork.c:\n" +"p2->p_ucred = crhold(td->td_ucred);\n" +"...\n" +"td2->td_ucred = crhold(p2->p_ucred);\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:327 +#, no-wrap +msgid "Restrictions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:330 +msgid "" +"Throughout the kernel there are access restrictions relating to jailed " +"processes. Usually, these restrictions only check whether the process is " +"jailed, and if so, returns an error. For example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:335 +#, no-wrap +msgid "" +"if (jailed(td->td_ucred))\n" +" return (EPERM);\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:337 +#, no-wrap +msgid "SysV IPC" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:340 +msgid "" +"System V IPC is based on messages. Processes can send each other these " +"messages which tell them how to act. The functions which deal with messages " +"are: man:msgctl[3], man:msgget[3], man:msgsnd[3] and man:msgrcv[3]. Earlier, " +"I mentioned that there were certain sysctls you could turn on or off in " +"order to affect the behavior of jail. One of these sysctls was " +"`security.jail.sysvipc_allowed`. By default, this sysctl is set to 0. If it " +"were set to 1, it would defeat the whole purpose of having a jail; " +"privileged users from the jail would be able to affect processes outside the " +"jailed environment. The difference between a message and a signal is that " +"the message only consists of the signal number." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:342 +msgid "[.filename]#/usr/src/sys/kern/sysv_msg.c#:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:344 +msgid "" +"`msgget(key, msgflg)`: `msgget` returns (and possibly creates) a message " +"descriptor that designates a message queue for use in other functions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:345 +msgid "" +"`msgctl(msgid, cmd, buf)`: Using this function, a process can query the " +"status of a message descriptor." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:346 +msgid "" +"`msgsnd(msgid, msgp, msgsz, msgflg)`: `msgsnd` sends a message to a process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:347 +msgid "" +"`msgrcv(msgid, msgp, msgsz, msgtyp, msgflg)`: a process receives messages " +"using this function" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:349 +msgid "" +"In each of the system calls corresponding to these functions, there is this " +"conditional:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:355 +#, no-wrap +msgid "" +"/usr/src/sys/kern/sysv_msg.c:\n" +"if (!jail_sysvipc_allowed && jailed(td->td_ucred))\n" +" return (ENOSYS);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:358 +msgid "" +"Semaphore system calls allow processes to synchronize execution by doing a " +"set of operations atomically on a set of semaphores. Basically semaphores " +"provide another way for processes lock resources. However, process waiting " +"on a semaphore, that is being used, will sleep until the resources are " +"relinquished. The following semaphore system calls are blocked inside a " +"jail: man:semget[2], man:semctl[2] and man:semop[2]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:360 +msgid "[.filename]#/usr/src/sys/kern/sysv_sem.c#:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:362 +msgid "" +"`semctl(semid, semnum, cmd, ...)`: `semctl` does the specified `cmd` on the " +"semaphore queue indicated by `semid`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:363 +msgid "" +"`semget(key, nsems, flag)`: `semget` creates an array of semaphores, " +"corresponding to `key`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:365 +msgid "`key and flag take on the same meaning as they do in msgget.`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:366 +msgid "" +"`semop(semid, array, nops)`: `semop` performs a group of operations " +"indicated by `array`, to the set of semaphores identified by `semid`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:368 +msgid "" +"System V IPC allows for processes to share memory. Processes can communicate " +"directly with each other by sharing parts of their virtual address space and " +"then reading and writing data stored in the shared memory. These system " +"calls are blocked within a jailed environment: man:shmdt[2], man:shmat[2], " +"man:shmctl[2] and man:shmget[2]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:370 +msgid "[.filename]#/usr/src/sys/kern/sysv_shm.c#:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:372 +msgid "" +"`shmctl(shmid, cmd, buf)`: `shmctl` does various control operations on the " +"shared memory region identified by `shmid`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:373 +msgid "" +"`shmget(key, size, flag)`: `shmget` accesses or creates a shared memory " +"region of `size` bytes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:374 +msgid "" +"`shmat(shmid, addr, flag)`: `shmat` attaches a shared memory region " +"identified by `shmid` to the address space of a process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:375 +msgid "" +"`shmdt(addr)`: `shmdt` detaches the shared memory region previously attached " +"at `addr`." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:376 +#, no-wrap +msgid "Sockets" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:379 +msgid "" +"Jail treats the man:socket[2] system call and related lower-level socket " +"functions in a special manner. In order to determine whether a certain " +"socket is allowed to be created, it first checks to see if the sysctl " +"`security.jail.socket_unixiproute_only` is set. If set, sockets are only " +"allowed to be created if the family specified is either `PF_LOCAL`, " +"`PF_INET` or `PF_ROUTE`. Otherwise, it returns an error." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:397 +#, no-wrap +msgid "" +"/usr/src/sys/kern/uipc_socket.c:\n" +"int\n" +"socreate(int dom, struct socket **aso, int type, int proto,\n" +" struct ucred *cred, struct thread *td)\n" +"{\n" +" struct protosw *prp;\n" +"...\n" +" if (jailed(cred) && jail_socket_unixiproute_only &&\n" +" prp->pr_domain->dom_family != PF_LOCAL &&\n" +" prp->pr_domain->dom_family != PF_INET &&\n" +" prp->pr_domain->dom_family != PF_ROUTE) {\n" +" return (EPROTONOSUPPORT);\n" +" }\n" +"...\n" +"}\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:399 +#, no-wrap +msgid "Berkeley Packet Filter" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:402 +msgid "" +"The Berkeley Packet Filter provides a raw interface to data link layers in a " +"protocol independent fashion. BPF is now controlled by the man:devfs[8] " +"whether it can be used in a jailed environment." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:403 +#, no-wrap +msgid "Protocols" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:406 +msgid "" +"There are certain protocols which are very common, such as TCP, UDP, IP and " +"ICMP. IP and ICMP are on the same level: the network layer 2. There are " +"certain precautions which are taken in order to prevent a jailed process " +"from binding a protocol to a certain address only if the `nam` parameter is " +"set. `nam` is a pointer to a `sockaddr` structure, which describes the " +"address on which to bind the service. A more exact definition is that " +"`sockaddr` \"may be used as a template for referring to the identifying tag " +"and length of each address\". In the function `in_pcbbind_setup()`, `sin` is " +"a pointer to a `sockaddr_in` structure, which contains the port, address, " +"length and domain family of the socket which is to be bound. Basically, this " +"disallows any processes from jail to be able to specify the address that " +"does not belong to the jail in which the calling process exists." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:443 +#, no-wrap +msgid "" +"/usr/src/sys/netinet/in_pcb.c:\n" +"int\n" +"in_pcbbind_setup(struct inpcb *inp, struct sockaddr *nam, in_addr_t *laddrp,\n" +" u_short *lportp, struct ucred *cred)\n" +"{\n" +" ...\n" +" struct sockaddr_in *sin;\n" +" ...\n" +" if (nam) {\n" +" sin = (struct sockaddr_in *)nam;\n" +" ...\n" +" if (sin->sin_addr.s_addr != INADDR_ANY)\n" +" if (prison_ip(cred, 0, &sin->sin_addr.s_addr))\n" +" return(EINVAL);\n" +" ...\n" +" if (lport) {\n" +" ...\n" +" if (prison && prison_ip(cred, 0, &sin->sin_addr.s_addr))\n" +" return (EADDRNOTAVAIL);\n" +" ...\n" +" }\n" +" }\n" +" if (lport == 0) {\n" +" ...\n" +" if (laddr.s_addr != INADDR_ANY)\n" +" if (prison_ip(cred, 0, &laddr.s_addr))\n" +" return (EINVAL);\n" +" ...\n" +" }\n" +"...\n" +" if (prison_ip(cred, 0, &laddr.s_addr))\n" +" return (EINVAL);\n" +"...\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:446 +msgid "" +"You might be wondering what function `prison_ip()` does. `prison_ip()` is " +"given three arguments, a pointer to the credential(represented by `cred`), " +"any flags, and an IP address. It returns 1 if the IP address does NOT belong " +"to the jail or 0 otherwise. As you can see from the code, if it is indeed an " +"IP address not belonging to the jail, the protocol is not allowed to bind to " +"that address." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:454 +#, no-wrap +msgid "" +"/usr/src/sys/kern/kern_jail.c:\n" +"int\n" +"prison_ip(struct ucred *cred, int flag, u_int32_t *ip)\n" +"{\n" +" u_int32_t tmp;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:479 +#, no-wrap +msgid "" +" if (!jailed(cred))\n" +" return (0);\n" +" if (flag)\n" +" tmp = *ip;\n" +" else\n" +" tmp = ntohl(*ip);\n" +" if (tmp == INADDR_ANY) {\n" +" if (flag)\n" +" *ip = cred->cr_prison->pr_ip;\n" +" else\n" +" *ip = htonl(cred->cr_prison->pr_ip);\n" +" return (0);\n" +" }\n" +" if (tmp == INADDR_LOOPBACK) {\n" +" if (flag)\n" +" *ip = cred->cr_prison->pr_ip;\n" +" else\n" +" *ip = htonl(cred->cr_prison->pr_ip);\n" +" return (0);\n" +" }\n" +" if (cred->cr_prison->pr_ip != tmp)\n" +" return (1);\n" +" return (0);\n" +"}\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:481 +#, no-wrap +msgid "Filesystem" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:484 +msgid "" +"Even `root` users within the jail are not allowed to unset or modify any " +"file flags, such as immutable, append-only, and undeleteable flags, if the " +"securelevel is greater than 0." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:529 +#, no-wrap +msgid "" +"/usr/src/sys/ufs/ufs/ufs_vnops.c:\n" +"static int\n" +"ufs_setattr(ap)\n" +" ...\n" +"{\n" +" ...\n" +" if (!priv_check_cred(cred, PRIV_VFS_SYSFLAGS, 0)) {\n" +" if (ip->i_flags\n" +" & (SF_NOUNLINK | SF_IMMUTABLE | SF_APPEND)) {\n" +" error = securelevel_gt(cred, 0);\n" +" if (error)\n" +" return (error);\n" +" }\n" +" ...\n" +" }\n" +"}\n" +"/usr/src/sys/kern/kern_priv.c\n" +"int\n" +"priv_check_cred(struct ucred *cred, int priv, int flags)\n" +"{\n" +" ...\n" +" error = prison_priv_check(cred, priv);\n" +" if (error)\n" +" return (error);\n" +" ...\n" +"}\n" +"/usr/src/sys/kern/kern_jail.c\n" +"int\n" +"prison_priv_check(struct ucred *cred, int priv)\n" +"{\n" +" ...\n" +" switch (priv) {\n" +" ...\n" +" case PRIV_VFS_SYSFLAGS:\n" +" if (jail_chflags_allowed)\n" +" return (0);\n" +" else\n" +" return (EPERM);\n" +" ...\n" +" }\n" +" ...\n" +"}\n" +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/kobj/_index.adoc b/documentation/content/en/books/arch-handbook/kobj/_index.adoc index 50b33bbc37..a52300e4c0 100644 --- a/documentation/content/en/books/arch-handbook/kobj/_index.adoc +++ b/documentation/content/en/books/arch-handbook/kobj/_index.adoc @@ -6,7 +6,8 @@ description: Kernel Objects tags: ["kernel objects", "kobj", "guide", "FreeBSD"] showBookMenu: true weight: 4 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/kobj/" --- [[kernel-objects]] diff --git a/documentation/content/en/books/arch-handbook/kobj/_index.po b/documentation/content/en/books/arch-handbook/kobj/_index.po new file mode 100644 index 0000000000..f89b3099a7 --- /dev/null +++ b/documentation/content/en/books/arch-handbook/kobj/_index.po @@ -0,0 +1,491 @@ +# 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 "" diff --git a/documentation/content/en/books/arch-handbook/locking/_index.adoc b/documentation/content/en/books/arch-handbook/locking/_index.adoc index b4fa6b8a68..61df2f9fac 100644 --- a/documentation/content/en/books/arch-handbook/locking/_index.adoc +++ b/documentation/content/en/books/arch-handbook/locking/_index.adoc @@ -6,7 +6,8 @@ description: Locking Notes tags: ["locking", "notes", "SMP", "Mutexes"] showBookMenu: true weight: 3 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/locking/" --- [[locking]] diff --git a/documentation/content/en/books/arch-handbook/locking/_index.po b/documentation/content/en/books/arch-handbook/locking/_index.po new file mode 100644 index 0000000000..fc802ac0d4 --- /dev/null +++ b/documentation/content/en/books/arch-handbook/locking/_index.po @@ -0,0 +1,354 @@ +# 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/locking/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:14 +#, no-wrap +msgid "Locking Notes" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:1 +#, no-wrap +msgid "Chapter 2. Locking Notes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:52 +msgid "" +"_This chapter is maintained by the FreeBSD SMP Next Generation Project._" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:54 +msgid "" +"This document outlines the locking used in the FreeBSD kernel to permit " +"effective multi-processing within the kernel. Locking can be achieved via " +"several means. Data structures can be protected by mutexes or man:lockmgr[9] " +"locks. A few variables are protected simply by always using atomic " +"operations to access them." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:56 +#, no-wrap +msgid "Mutexes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:59 +msgid "" +"A mutex is simply a lock used to guarantee mutual exclusion. Specifically, a " +"mutex may only be owned by one entity at a time. If another entity wishes to " +"obtain a mutex that is already owned, it must wait until the mutex is " +"released. In the FreeBSD kernel, mutexes are owned by processes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:61 +msgid "" +"Mutexes may be recursively acquired, but they are intended to be held for a " +"short period of time. Specifically, one may not sleep while holding a mutex. " +"If you need to hold a lock across a sleep, use a man:lockmgr[9] lock." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:63 +msgid "Each mutex has several properties of interest:" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:64 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:92 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:131 +#, no-wrap +msgid "Variable Name" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:66 +msgid "The name of the struct mtx variable in the kernel source." +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:67 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:93 +#, no-wrap +msgid "Logical Name" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:69 +msgid "" +"The name of the mutex assigned to it by `mtx_init`. This name is displayed " +"in KTR trace messages and witness errors and warnings and is used to " +"distinguish mutexes in the witness code." +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:70 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:94 +#, no-wrap +msgid "Type" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:72 +msgid "" +"The type of the mutex in terms of the `MTX_*` flags. The meaning for each " +"flag is related to its meaning as documented in man:mutex[9]." +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:73 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:106 +#, no-wrap +msgid "`MTX_DEF`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:75 +msgid "A sleep mutex" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:76 +#, no-wrap +msgid "`MTX_SPIN`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:78 +msgid "A spin mutex" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:79 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:100 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:112 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:118 +#, no-wrap +msgid "`MTX_RECURSE`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:81 +msgid "This mutex is allowed to recurse." +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:82 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:95 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:133 +#, no-wrap +msgid "Protectees" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:84 +msgid "" +"A list of data structures or data structure members that this entry " +"protects. For data structure members, the name will be in the form of " +"`structure name`.`member name`." +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:85 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:97 +#, no-wrap +msgid "Dependent Functions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:87 +msgid "Functions that can only be called if this mutex is held." +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:88 +#, no-wrap +msgid "Mutex List" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:98 +#, no-wrap +msgid "sched_lock" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:99 +#, no-wrap +msgid "\"sched lock\"" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:99 +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:117 +#, no-wrap +msgid "`MTX_SPIN` \\" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:101 +#, no-wrap +msgid "`_gmonparam`, `cnt.v_swtch`, `cp_time`, `curpriority`, `mtx`.`mtx_blocked`, `mtx`.`mtx_contested`, `proc`.`p_procq`, `proc`.`p_slpq`, `proc`.`p_sflag`, `proc`.`p_stat`, `proc`.`p_estcpu`, `proc`.`p_cpticks` `proc`.`p_pctcpu`, `proc`.`p_wchan`, `proc`.`p_wmesg`, `proc`.`p_swtime`, `proc`.`p_slptime`, `proc`.`p_runtime`, `proc`.`p_uu`, `proc`.`p_su`, `proc`.`p_iu`, `proc`.`p_uticks`, `proc`.`p_sticks`, `proc`.`p_iticks`, `proc`.`p_oncpu`, `proc`.`p_lastcpu`, `proc`.`p_rqindex`, `proc`.`p_heldmtx`, `proc`.`p_blocked`, `proc`.`p_mtxname`, `proc`.`p_contested`, `proc`.`p_priority`, `proc`.`p_usrpri`, `proc`.`p_nativepri`, `proc`.`p_nice`, `proc`.`p_rtprio`, `pscnt`, `slpque`, `itqueuebits`, `itqueues`, `rtqueuebits`, `rtqueues`, `queuebits`, `queues`, `idqueuebits`, `idqueues`, `switchtime`, `switchticks`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:103 +#, no-wrap +msgid "`setrunqueue`, `remrunqueue`, `mi_switch`, `chooseproc`, `schedclock`, `resetpriority`, `updatepri`, `maybe_resched`, `cpu_switch`, `cpu_throw`, `need_resched`, `resched_wanted`, `clear_resched`, `aston`, `astoff`, `astpending`, `calcru`, `proc_compare`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:104 +#, no-wrap +msgid "vm86pcb_lock" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:105 +#, no-wrap +msgid "\"vm86pcb lock\"" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:107 +#, no-wrap +msgid "`vm86pcb`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:109 +#, no-wrap +msgid "`vm86_bioscall`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:110 +#, no-wrap +msgid "Giant" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:111 +#, no-wrap +msgid "\"Giant\"" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:111 +#, no-wrap +msgid "`MTX_DEF` \\" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:113 +#, no-wrap +msgid "nearly everything" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:115 +#, no-wrap +msgid "lots" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:116 +#, no-wrap +msgid "callout_lock" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:117 +#, no-wrap +msgid "\"callout lock\"" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:119 +#, no-wrap +msgid "`callfree`, `callwheel`, `nextsoftcheck`, `proc`.`p_itcallout`, `proc`.`p_slpcallout`, `softticks`, `ticks`" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:123 +#, no-wrap +msgid "Shared Exclusive Locks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:126 +msgid "" +"These locks provide basic reader-writer type functionality and may be held " +"by a sleeping process. Currently they are backed by man:lockmgr[9]." +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:127 +#, no-wrap +msgid "Shared Exclusive Lock List" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:134 +#, no-wrap +msgid "`allproc_lock`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:136 +#, no-wrap +msgid "`allproc` `zombproc` `pidhashtbl` `proc`.`p_list` `proc`.`p_hash` `nextpid`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:137 +#, no-wrap +msgid "`proctree_lock`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:138 +#, no-wrap +msgid "`proc`.`p_children` `proc`.`p_sibling`" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:141 +#, no-wrap +msgid "Atomically Protected Variables" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:144 +msgid "" +"An atomically protected variable is a special variable that is not protected " +"by an explicit lock. Instead, all data accesses to the variables use special " +"atomic operations as described in man:atomic[9]. Very few variables are " +"treated this way, although other synchronization primitives such as mutexes " +"are implemented with atomically protected variables." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:145 +msgid "`mtx`.`mtx_lock`" +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/mac/_index.adoc b/documentation/content/en/books/arch-handbook/mac/_index.adoc index a1ee13c101..fa3f393c29 100644 --- a/documentation/content/en/books/arch-handbook/mac/_index.adoc +++ b/documentation/content/en/books/arch-handbook/mac/_index.adoc @@ -1,6 +1,6 @@ --- title: Chapter 6. The TrustedBSD MAC Framework -authors: +authors: - author: Chris Costello email: chris@FreeBSD.org - author: Robert Watson @@ -11,7 +11,8 @@ description: The TrustedBSD MAC Framework tags: ["TrustedBSD", "MAC"] showBookMenu: true weight: 7 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/mac/" --- [[mac]] @@ -64,34 +65,46 @@ Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML [IMPORTANT] ==== -THIS DOCUMENTATION IS PROVIDED BY THE NETWORKS ASSOCIATES TECHNOLOGY, INC "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NETWORKS ASSOCIATES TECHNOLOGY, INC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +THIS DOCUMENTATION IS PROVIDED BY THE NETWORKS ASSOCIATES TECHNOLOGY, INC "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL NETWORKS ASSOCIATES TECHNOLOGY, INC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ==== [[mac-synopsis]] == Synopsis -FreeBSD includes experimental support for several mandatory access control policies, as well as a framework for kernel security extensibility, the TrustedBSD MAC Framework. The MAC Framework is a pluggable access control framework, permitting new security policies to be easily linked into the kernel, loaded at boot, or loaded dynamically at run-time. The framework provides a variety of features to make it easier to implement new security policies, including the ability to easily tag security labels (such as confidentiality information) onto system objects. +FreeBSD includes experimental support for several mandatory access control policies, as well as a framework for kernel security extensibility, the TrustedBSD MAC Framework. +The MAC Framework is a pluggable access control framework, permitting new security policies to be easily linked into the kernel, loaded at boot, or loaded dynamically at run-time. +The framework provides a variety of features to make it easier to implement new security policies, including the ability to easily tag security labels (such as confidentiality information) onto system objects. This chapter introduces the MAC policy framework and provides documentation for a sample MAC policy module. [[mac-introduction]] == Introduction -The TrustedBSD MAC framework provides a mechanism to allow the compile-time or run-time extension of the kernel access control model. New system policies may be implemented as kernel modules and linked to the kernel; if multiple policy modules are present, their results will be composed. The MAC Framework provides a variety of access control infrastructure services to assist policy writers, including support for transient and persistent policy-agnostic object security labels. This support is currently considered experimental. +The TrustedBSD MAC framework provides a mechanism to allow the compile-time or run-time extension of the kernel access control model. +New system policies may be implemented as kernel modules and linked to the kernel; if multiple policy modules are present, their results will be composed. +The MAC Framework provides a variety of access control infrastructure services to assist policy writers, including support for transient and persistent policy-agnostic object security labels. +This support is currently considered experimental. This chapter provides information appropriate for developers of policy modules, as well as potential consumers of MAC-enabled environments, to learn about how the MAC Framework supports access control extension of the kernel. [[mac-background]] == Policy Background -Mandatory Access Control (MAC), refers to a set of access control policies that are mandatorily enforced on users by the operating system. MAC policies may be contrasted with Discretionary Access Control (DAC) protections, by which non-administrative users may (at their discretion) protect objects. In traditional UNIX systems, DAC protections include file permissions and access control lists; MAC protections include process controls preventing inter-user debugging and firewalls. A variety of MAC policies have been formulated by operating system designers and security researches, including the Multi-Level Security (MLS) confidentiality policy, the Biba integrity policy, Role-Based Access Control (RBAC), Domain and Type Enforcement (DTE), and Type Enforcement (TE). Each model bases decisions on a variety of factors, including user identity, role, and security clearance, as well as security labels on objects representing concepts such as data sensitivity and integrity. +Mandatory Access Control (MAC), refers to a set of access control policies that are mandatorily enforced on users by the operating system. +MAC policies may be contrasted with Discretionary Access Control (DAC) protections, by which non-administrative users may (at their discretion) protect objects. +In traditional UNIX systems, DAC protections include file permissions and access control lists; MAC protections include process controls preventing inter-user debugging and firewalls. +A variety of MAC policies have been formulated by operating system designers and security researches, including the Multi-Level Security (MLS) confidentiality policy, the Biba integrity policy, Role-Based Access Control (RBAC), Domain and Type Enforcement (DTE), and Type Enforcement (TE). +Each model bases decisions on a variety of factors, including user identity, role, and security clearance, as well as security labels on objects representing concepts such as data sensitivity and integrity. -The TrustedBSD MAC Framework is capable of supporting policy modules that implement all of these policies, as well as a broad class of system hardening policies, which may use existing security attributes, such as user and group IDs, as well as extended attributes on files, and other system properties. In addition, despite the name, the MAC Framework can also be used to implement purely discretionary policies, as policy modules are given substantial flexibility in how they authorize protections. +The TrustedBSD MAC Framework is capable of supporting policy modules that implement all of these policies, as well as a broad class of system hardening policies, which may use existing security attributes, such as user and group IDs, as well as extended attributes on files, and other system properties. +In addition, despite the name, the MAC Framework can also be used to implement purely discretionary policies, as policy modules are given substantial flexibility in how they authorize protections. [[mac-framework-kernel-arch]] == MAC Framework Kernel Architecture -The TrustedBSD MAC Framework permits kernel modules to extend the operating system security policy, as well as providing infrastructure functionality required by many access control modules. If multiple policies are simultaneously loaded, the MAC Framework will usefully (for some definition of useful) compose the results of the policies. +The TrustedBSD MAC Framework permits kernel modules to extend the operating system security policy, as well as providing infrastructure functionality required by many access control modules. +If multiple policies are simultaneously loaded, the MAC Framework will usefully (for some definition of useful) compose the results of the policies. [[mac-framework-kernel-arch-elements]] === Kernel Elements @@ -116,56 +129,103 @@ The MAC Framework contains a number of kernel elements: The TrustedBSD MAC Framework may be directly managed using sysctl's, loader tunables, and system calls. -In most cases, sysctl's and loader tunables of the same name modify the same parameters, and control behavior such as enforcement of protections relating to various kernel subsystems. In addition, if MAC debugging support is compiled into the kernel, several counters will be maintained tracking label allocation. It is generally advisable that per-subsystem enforcement controls not be used to control policy behavior in production environments, as they broadly impact the operation of all active policies. Instead, per-policy controls should be preferred, as they provide greater granularity and greater operational consistency for policy modules. +In most cases, sysctl's and loader tunables of the same name modify the same parameters, and control behavior such as enforcement of protections relating to various kernel subsystems. +In addition, if MAC debugging support is compiled into the kernel, several counters will be maintained tracking label allocation. +It is generally advisable that per-subsystem enforcement controls not be used to control policy behavior in production environments, as they broadly impact the operation of all active policies. +Instead, per-policy controls should be preferred, as they provide greater granularity and greater operational consistency for policy modules. Loading and unloading of policy modules is performed using the system module management system calls and other system interfaces, including boot loader variables; policy modules will have the opportunity to influence load and unload events, including preventing undesired unloading of the policy. [[mac-framework-kernel-arch-synchronization]] === Policy List Concurrency and Synchronization -As the set of active policies may change at run-time, and the invocation of entry points is non-atomic, synchronization is required to prevent loading or unloading of policies while an entry point invocation is in progress, freezing the set of active policies for the duration. This is accomplished by means of a framework busy count: whenever an entry point is entered, the busy count is incremented; whenever it is exited, the busy count is decremented. While the busy count is elevated, policy list changes are not permitted, and threads attempting to modify the policy list will sleep until the list is not busy. The busy count is protected by a mutex, and a condition variable is used to wake up sleepers waiting on policy list modifications. One side effect of this synchronization model is that recursion into the MAC Framework from within a policy module is permitted, although not generally used. +As the set of active policies may change at run-time, and the invocation of entry points is non-atomic, synchronization is required to prevent loading or unloading of policies while an entry point invocation is in progress, freezing the set of active policies for the duration. +This is accomplished by means of a framework busy count: whenever an entry point is entered, the busy count is incremented; whenever it is exited, the busy count is decremented. +While the busy count is elevated, policy list changes are not permitted, and threads attempting to modify the policy list will sleep until the list is not busy. +The busy count is protected by a mutex, and a condition variable is used to wake up sleepers waiting on policy list modifications. +One side effect of this synchronization model is that recursion into the MAC Framework from within a policy module is permitted, although not generally used. -Various optimizations are used to reduce the overhead of the busy count, including avoiding the full cost of incrementing and decrementing if the list is empty or contains only static entries (policies that are loaded before the system starts, and cannot be unloaded). A compile-time option is also provided which prevents any change in the set of loaded policies at run-time, which eliminates the mutex locking costs associated with supporting dynamically loaded and unloaded policies as synchronization is no longer required. +Various optimizations are used to reduce the overhead of the busy count, including avoiding the full cost of incrementing and decrementing if the list is empty or contains only static entries (policies that are loaded before the system starts, and cannot be unloaded). +A compile-time option is also provided which prevents any change in the set of loaded policies at run-time, which eliminates the mutex locking costs associated with supporting dynamically loaded and unloaded policies as synchronization is no longer required. As the MAC Framework is not permitted to block in some entry points, a normal sleep lock cannot be used; as a result, it is possible for the load or unload attempt to block for a substantial period of time waiting for the framework to become idle. [[mac-framework-kernel-arch-label-synchronization]] === Label Synchronization -As kernel objects of interest may generally be accessed from more than one thread at a time, and simultaneous entry of more than one thread into the MAC Framework is permitted, security attribute storage maintained by the MAC Framework is carefully synchronized. In general, existing kernel synchronization on kernel object data is used to protect MAC Framework security labels on the object: for example, MAC labels on sockets are protected using the existing socket mutex. Likewise, semantics for concurrent access are generally identical to those of the container objects: for credentials, copy-on-write semantics are maintained for label contents as with the remainder of the credential structure. The MAC Framework asserts necessary locks on objects when invoked with an object reference. Policy authors must be aware of these synchronization semantics, as they will sometimes limit the types of accesses permitted on labels: for example, when a read-only reference to a credential is passed to a policy via an entry point, only read operations are permitted on the label state attached to the credential. +As kernel objects of interest may generally be accessed from more than one thread at a time, and simultaneous entry of more than one thread into the MAC Framework is permitted, security attribute storage maintained by the MAC Framework is carefully synchronized. +In general, existing kernel synchronization on kernel object data is used to protect MAC Framework security labels on the object: for example, MAC labels on sockets are protected using the existing socket mutex. +Likewise, semantics for concurrent access are generally identical to those of the container objects: for credentials, copy-on-write semantics are maintained for label contents as with the remainder of the credential structure. +The MAC Framework asserts necessary locks on objects when invoked with an object reference. +Policy authors must be aware of these synchronization semantics, as they will sometimes limit the types of accesses permitted on labels: for example, when a read-only reference to a credential is passed to a policy via an entry point, only read operations are permitted on the label state attached to the credential. [[mac-framework-kernel-arch-policy-synchronization]] === Policy Synchronization and Concurrency -Policy modules must be written to assume that many kernel threads may simultaneously enter one more policy entry points due to the parallel and preemptive nature of the FreeBSD kernel. If the policy module makes use of mutable state, this may require the use of synchronization primitives within the policy to prevent inconsistent views on that state resulting in incorrect operation of the policy. Policies will generally be able to make use of existing FreeBSD synchronization primitives for this purpose, including mutexes, sleep locks, condition variables, and counting semaphores. However, policies should be written to employ these primitives carefully, respecting existing kernel lock orders, and recognizing that some entry points are not permitted to sleep, limiting the use of primitives in those entry points to mutexes and wakeup operations. +Policy modules must be written to assume that many kernel threads may simultaneously enter one more policy entry points due to the parallel and preemptive nature of the FreeBSD kernel. +If the policy module makes use of mutable state, this may require the use of synchronization primitives within the policy to prevent inconsistent views on that state resulting in incorrect operation of the policy. +Policies will generally be able to make use of existing FreeBSD synchronization primitives for this purpose, including mutexes, sleep locks, condition variables, and counting semaphores. +However, policies should be written to employ these primitives carefully, respecting existing kernel lock orders, and recognizing that some entry points are not permitted to sleep, limiting the use of primitives in those entry points to mutexes and wakeup operations. -When policy modules call out to other kernel subsystems, they will generally need to release any in-policy locks in order to avoid violating the kernel lock order or risking lock recursion. This will maintain policy locks as leaf locks in the global lock order, helping to avoid deadlock. +When policy modules call out to other kernel subsystems, they will generally need to release any in-policy locks in order to avoid violating the kernel lock order or risking lock recursion. +This will maintain policy locks as leaf locks in the global lock order, helping to avoid deadlock. [[mac-framework-kernel-arch-registration]] === Policy Registration -The MAC Framework maintains two lists of active policies: a static list, and a dynamic list. The lists differ only with regards to their locking semantics: an elevated reference count is not required to make use of the static list. When kernel modules containing MAC Framework policies are loaded, the policy module will use `SYSINIT` to invoke a registration function; when a policy module is unloaded, `SYSINIT` will likewise invoke a de-registration function. Registration may fail if a policy module is loaded more than once, if insufficient resources are available for the registration (for example, the policy might require labeling and insufficient labeling state might be available), or other policy prerequisites might not be met (some policies may only be loaded prior to boot). Likewise, de-registration may fail if a policy is flagged as not unloadable. +The MAC Framework maintains two lists of active policies: a static list, and a dynamic list. +The lists differ only with regards to their locking semantics: an elevated reference count is not required to make use of the static list. +When kernel modules containing MAC Framework policies are loaded, the policy module will use `SYSINIT` to invoke a registration function; when a policy module is unloaded, `SYSINIT` will likewise invoke a de-registration function. +Registration may fail if a policy module is loaded more than once, if insufficient resources are available for the registration (for example, the policy might require labeling and insufficient labeling state might be available), or other policy prerequisites might not be met (some policies may only be loaded prior to boot). +Likewise, de-registration may fail if a policy is flagged as not unloadable. [[mac-framework-kernel-arch-entrypoints]] === Entry Points -Kernel services interact with the MAC Framework in two ways: they invoke a series of APIs to notify the framework of relevant events, and they provide a policy-agnostic label structure pointer in security-relevant objects. The label pointer is maintained by the MAC Framework via label management entry points, and permits the Framework to offer a labeling service to policy modules through relatively non-invasive changes to the kernel subsystem maintaining the object. For example, label pointers have been added to processes, process credentials, sockets, pipes, vnodes, Mbufs, network interfaces, IP reassembly queues, and a variety of other security-relevant structures. Kernel services also invoke the MAC Framework when they perform important security decisions, permitting policy modules to augment those decisions based on their own criteria (possibly including data stored in security labels). Most of these security critical decisions will be explicit access control checks; however, some affect more general decision functions such as packet matching for sockets and label transition at program execution. +Kernel services interact with the MAC Framework in two ways: they invoke a series of APIs to notify the framework of relevant events, and they provide a policy-agnostic label structure pointer in security-relevant objects. +The label pointer is maintained by the MAC Framework via label management entry points, and permits the Framework to offer a labeling service to policy modules through relatively non-invasive changes to the kernel subsystem maintaining the object. +For example, label pointers have been added to processes, process credentials, sockets, pipes, vnodes, Mbufs, network interfaces, IP reassembly queues, and a variety of other security-relevant structures. +Kernel services also invoke the MAC Framework when they perform important security decisions, permitting policy modules to augment those decisions based on their own criteria (possibly including data stored in security labels). +Most of these security critical decisions will be explicit access control checks; however, some affect more general decision functions such as packet matching for sockets and label transition at program execution. [[mac-framework-kernel-arch-composition]] === Policy Composition -When more than one policy module is loaded into the kernel at a time, the results of the policy modules will be composed by the framework using a composition operator. This operator is currently hard-coded, and requires that all active policies must approve a request for it to return success. As policies may return a variety of error conditions (success, access denied, object does not exist, ...), a precedence operator selects the resulting error from the set of errors returned by policies. In general, errors indicating that an object does not exist will be preferred to errors indicating that access to an object is denied. While it is not guaranteed that the resulting composition will be useful or secure, we have found that it is for many useful selections of policies. For example, traditional trusted systems often ship with two or more policies using a similar composition. +When more than one policy module is loaded into the kernel at a time, the results of the policy modules will be composed by the framework using a composition operator. +This operator is currently hard-coded, and requires that all active policies must approve a request for it to return success. +As policies may return a variety of error conditions (success, access denied, object does not exist, ...), a precedence operator selects the resulting error from the set of errors returned by policies. +In general, errors indicating that an object does not exist will be preferred to errors indicating that access to an object is denied. +While it is not guaranteed that the resulting composition will be useful or secure, we have found that it is for many useful selections of policies. +For example, traditional trusted systems often ship with two or more policies using a similar composition. [[mac-framework-kernel-arch-labels]] === Labeling Support -As many interesting access control extensions rely on security labels on objects, the MAC Framework provides a set of policy-agnostic label management system calls covering a variety of user-exposed objects. Common label types include partition identifiers, sensitivity labels, integrity labels, compartments, domains, roles, and types. By policy agnostic, we mean that policy modules are able to completely define the semantics of meta-data associated with an object. Policy modules participate in the internalization and externalization of string-based labels provides by user applications, and can expose multiple label elements to applications if desired. - -In-memory labels are stored in slab-allocated `struct label`, which consists of a fixed-length array of unions, each holding a `void *` pointer and a `long`. Policies registering for label storage will be assigned a "slot" identifier, which may be used to dereference the label storage. The semantics of the storage are left entirely up to the policy module: modules are provided with a variety of entry points associated with the kernel object life cycle, including initialization, association/creation, and destruction. Using these interfaces, it is possible to implement reference counting and other storage models. Direct access to the object structure is generally not required by policy modules to retrieve a label, as the MAC Framework generally passes both a pointer to the object and a direct pointer to the object's label into entry points. The primary exception to this rule is the process credential, which must be manually dereferenced to access the credential label. This may change in future revisions of the MAC Framework. - -Initialization entry points frequently include a sleeping disposition flag indicating whether or not an initialization is permitted to sleep; if sleeping is not permitted, a failure may be returned to cancel allocation of the label (and hence object). This may occur, for example, in the network stack during interrupt handling, where sleeping is not permitted, or while the caller holds a mutex. Due to the performance cost of maintaining labels on in-flight network packets (Mbufs), policies must specifically declare a requirement that Mbuf labels be allocated. Dynamically loaded policies making use of labels must be able to handle the case where their init function has not been called on an object, as objects may already exist when the policy is loaded. The MAC Framework guarantees that uninitialized label slots will hold a 0 or NULL value, which policies may use to detect uninitialized values. However, as allocation of Mbuf labels is conditional, policies must also be able to handle a NULL label pointer for Mbufs if they have been loaded dynamically. - -In the case of file system labels, special support is provided for the persistent storage of security labels in extended attributes. Where available, extended attribute transactions are used to permit consistent compound updates of security labels on vnodes--currently this support is present only in the UFS2 file system. Policy authors may choose to implement multilabel file system object labels using one (or more) extended attributes. For efficiency reasons, the vnode label (`v_label`) is a cache of any on-disk label; policies are able to load values into the cache when the vnode is instantiated, and update the cache as needed. As a result, the extended attribute need not be directly accessed with every access control check. +As many interesting access control extensions rely on security labels on objects, the MAC Framework provides a set of policy-agnostic label management system calls covering a variety of user-exposed objects. +Common label types include partition identifiers, sensitivity labels, integrity labels, compartments, domains, roles, and types. +By policy agnostic, we mean that policy modules are able to completely define the semantics of meta-data associated with an object. +Policy modules participate in the internalization and externalization of string-based labels provides by user applications, and can expose multiple label elements to applications if desired. + +In-memory labels are stored in slab-allocated `struct label`, which consists of a fixed-length array of unions, each holding a `void *` pointer and a `long`. +Policies registering for label storage will be assigned a "slot" identifier, which may be used to dereference the label storage. +The semantics of the storage are left entirely up to the policy module: modules are provided with a variety of entry points associated with the kernel object life cycle, including initialization, association/creation, and destruction. +Using these interfaces, it is possible to implement reference counting and other storage models. +Direct access to the object structure is generally not required by policy modules to retrieve a label, as the MAC Framework generally passes both a pointer to the object and a direct pointer to the object's label into entry points. +The primary exception to this rule is the process credential, which must be manually dereferenced to access the credential label. +This may change in future revisions of the MAC Framework. + +Initialization entry points frequently include a sleeping disposition flag indicating whether or not an initialization is permitted to sleep; if sleeping is not permitted, a failure may be returned to cancel allocation of the label (and hence object). +This may occur, for example, in the network stack during interrupt handling, where sleeping is not permitted, or while the caller holds a mutex. +Due to the performance cost of maintaining labels on in-flight network packets (Mbufs), policies must specifically declare a requirement that Mbuf labels be allocated. +Dynamically loaded policies making use of labels must be able to handle the case where their init function has not been called on an object, as objects may already exist when the policy is loaded. +The MAC Framework guarantees that uninitialized label slots will hold a 0 or NULL value, which policies may use to detect uninitialized values. +However, as allocation of Mbuf labels is conditional, policies must also be able to handle a NULL label pointer for Mbufs if they have been loaded dynamically. + +In the case of file system labels, special support is provided for the persistent storage of security labels in extended attributes. +Where available, extended attribute transactions are used to permit consistent compound updates of security labels on vnodes--currently this support is present only in the UFS2 file system. +Policy authors may choose to implement multilabel file system object labels using one (or more) extended attributes. +For efficiency reasons, the vnode label (`v_label`) is a cache of any on-disk label; policies are able to load values into the cache when the vnode is instantiated, and update the cache as needed. +As a result, the extended attribute need not be directly accessed with every access control check. [NOTE] ==== @@ -177,7 +237,11 @@ Currently, if a labeled policy permits dynamic unloading, its state slot cannot The MAC Framework implements a number of system calls: most of these calls support the policy-agnostic label retrieval and manipulation APIs exposed to user applications. -The label management calls accept a label description structure, `struct mac`, which contains a series of MAC label elements. Each element contains a character string name, and character string value. Each policy will be given the chance to claim a particular element name, permitting policies to expose multiple independent elements if desired. Policy modules perform the internalization and externalization between kernel labels and user-provided labels via entry points, permitting a variety of semantics. Label management system calls are generally wrapped by user library functions to perform memory allocation and error handling, simplifying user applications that must manage labels. +The label management calls accept a label description structure, `struct mac`, which contains a series of MAC label elements. +Each element contains a character string name, and character string value. +Each policy will be given the chance to claim a particular element name, permitting policies to expose multiple independent elements if desired. +Policy modules perform the internalization and externalization between kernel labels and user-provided labels via entry points, permitting a variety of semantics. +Label management system calls are generally wrapped by user library functions to perform memory allocation and error handling, simplifying user applications that must manage labels. The following MAC-related system calls are present in the FreeBSD kernel: @@ -191,7 +255,8 @@ The following MAC-related system calls are present in the FreeBSD kernel: * `mac_get_pid()` may be used to request the label of another process by process id. * `mac_get_link()` is identical to `mac_get_file()`, only it will not follow a symbolic link if it is the final entry in the path, so may be used to retrieve the label on a symlink. * `mac_set_link()` is identical to `mac_set_file()`, only it will not follow a symbolic link if it is the final entry in a path, so may be used to manipulate the label on a symlink. -* `mac_execve()` is identical to the `execve()` system call, only it also accepts a requested label to set the process label to when beginning execution of a new program. This change in label on execution is referred to as a "transition". +* `mac_execve()` is identical to the `execve()` system call, only it also accepts a requested label to set the process label to when beginning execution of a new program. +This change in label on execution is referred to as a "transition". * `mac_get_peer()`, actually implemented via a socket option, retrieves the label of a remote peer on a socket, if available. In addition to these system calls, the `SIOCSIGMAC` and `SIOCSIFMAC` network interface ioctls permit the labels on network interfaces to be retrieved and set. @@ -199,7 +264,9 @@ In addition to these system calls, the `SIOCSIGMAC` and `SIOCSIFMAC` network int [[mac-policy-architecture]] == MAC Policy Architecture -Security policies are either linked directly into the kernel, or compiled into loadable kernel modules that may be loaded at boot, or dynamically using the module loading system calls at runtime. Policy modules interact with the system through a set of declared entry points, providing access to a stream of system events and permitting the policy to influence access control decisions. Each policy contains a number of elements: +Security policies are either linked directly into the kernel, or compiled into loadable kernel modules that may be loaded at boot, or dynamically using the module loading system calls at runtime. +Policy modules interact with the system through a set of declared entry points, providing access to a stream of system events and permitting the policy to influence access control decisions. +Each policy contains a number of elements: * Optional configuration parameters for policy. * Centralized implementation of the policy logic and parameters. @@ -229,37 +296,61 @@ static struct mac_policy_ops mac_policy_ops = }; .... -The MAC policy entry point vector, `mac__policy__ops` in this example, associates functions defined in the module with specific entry points. A complete listing of available entry points and their prototypes may be found in the MAC entry point reference section. Of specific interest during module registration are the .mpo_destroy and .mpo_init entry points. .mpo_init will be invoked once a policy is successfully registered with the module framework but prior to any other entry points becoming active. This permits the policy to perform any policy-specific allocation and initialization, such as initialization of any data or locks. .mpo_destroy will be invoked when a policy module is unloaded to permit releasing of any allocated memory and destruction of locks. Currently, these two entry points are invoked with the MAC policy list mutex held to prevent any other entry points from being invoked: this will be changed, but in the mean time, policies should be careful about what kernel primitives they invoke so as to avoid lock ordering or sleeping problems. +The MAC policy entry point vector, `mac__policy__ops` in this example, associates functions defined in the module with specific entry points. +A complete listing of available entry points and their prototypes may be found in the MAC entry point reference section. +Of specific interest during module registration are the .mpo_destroy and .mpo_init entry points. +.mpo_init will be invoked once a policy is successfully registered with the module framework but prior to any other entry points becoming active. +This permits the policy to perform any policy-specific allocation and initialization, such as initialization of any data or locks. +.mpo_destroy will be invoked when a policy module is unloaded to permit releasing of any allocated memory and destruction of locks. +Currently, these two entry points are invoked with the MAC policy list mutex held to prevent any other entry points from being invoked: this will be changed, but in the mean time, policies should be careful about what kernel primitives they invoke so as to avoid lock ordering or sleeping problems. -The policy declaration's module name field exists so that the module may be uniquely identified for the purposes of module dependencies. An appropriate string should be selected. The full string name of the policy is displayed to the user via the kernel log during load and unload events, and also exported when providing status information to userland processes. +The policy declaration's module name field exists so that the module may be uniquely identified for the purposes of module dependencies. +An appropriate string should be selected. +The full string name of the policy is displayed to the user via the kernel log during load and unload events, and also exported when providing status information to userland processes. [[mac-policy-flags]] === Policy Flags -The policy declaration flags field permits the module to provide the framework with information about its capabilities at the time the module is loaded. Currently, three flags are defined: +The policy declaration flags field permits the module to provide the framework with information about its capabilities at the time the module is loaded. +Currently, three flags are defined: MPC_LOADTIME_FLAG_UNLOADOK:: -This flag indicates that the policy module may be unloaded. If this flag is not provided, then the policy framework will reject requests to unload the module. This flag might be used by modules that allocate label state and are unable to free that state at runtime. +This flag indicates that the policy module may be unloaded. +If this flag is not provided, then the policy framework will reject requests to unload the module. +This flag might be used by modules that allocate label state and are unable to free that state at runtime. MPC_LOADTIME_FLAG_NOTLATE:: -This flag indicates that the policy module must be loaded and initialized early in the boot process. If the flag is specified, attempts to register the module following boot will be rejected. The flag may be used by policies that require pervasive labeling of all system objects, and cannot handle objects that have not been properly initialized by the policy. +This flag indicates that the policy module must be loaded and initialized early in the boot process. +If the flag is specified, attempts to register the module following boot will be rejected. +The flag may be used by policies that require pervasive labeling of all system objects, and cannot handle objects that have not been properly initialized by the policy. MPC_LOADTIME_FLAG_LABELMBUFS:: -This flag indicates that the policy module requires labeling of Mbufs, and that memory should always be allocated for the storage of Mbuf labels. By default, the MAC Framework will not allocate label storage for Mbufs unless at least one loaded policy has this flag set. This measurably improves network performance when policies do not require Mbuf labeling. A kernel option, `MAC_ALWAYS_LABEL_MBUF`, exists to force the MAC Framework to allocate Mbuf label storage regardless of the setting of this flag, and may be useful in some environments. +This flag indicates that the policy module requires labeling of Mbufs, and that memory should always be allocated for the storage of Mbuf labels. +By default, the MAC Framework will not allocate label storage for Mbufs unless at least one loaded policy has this flag set. +This measurably improves network performance when policies do not require Mbuf labeling. +A kernel option, `MAC_ALWAYS_LABEL_MBUF`, exists to force the MAC Framework to allocate Mbuf label storage regardless of the setting of this flag, and may be useful in some environments. [NOTE] ==== -Policies using the `MPC_LOADTIME_FLAG_LABELMBUFS` without the `MPC_LOADTIME_FLAG_NOTLATE` flag set must be able to correctly handle `NULL` Mbuf label pointers passed into entry points. This is necessary as in-flight Mbufs without label storage may persist after a policy enabling Mbuf labeling has been loaded. If a policy is loaded before the network subsystem is active (i.e., the policy is not being loaded late), then all Mbufs are guaranteed to have label storage. +Policies using the `MPC_LOADTIME_FLAG_LABELMBUFS` without the `MPC_LOADTIME_FLAG_NOTLATE` flag set must be able to correctly handle `NULL` Mbuf label pointers passed into entry points. +This is necessary as in-flight Mbufs without label storage may persist after a policy enabling Mbuf labeling has been loaded. +If a policy is loaded before the network subsystem is active (i.e., the policy is not being loaded late), then all Mbufs are guaranteed to have label storage. ==== [[mac-policy-entry-points]] === Policy Entry Points -Four classes of entry points are offered to policies registered with the framework: entry points associated with the registration and management of policies, entry points denoting initialization, creation, destruction, and other life cycle events for kernel objects, events associated with access control decisions that the policy module may influence, and calls associated with the management of labels on objects. In addition, a `mac_syscall()` entry point is provided so that policies may extend the kernel interface without registering new system calls. +Four classes of entry points are offered to policies registered with the framework: entry points associated with the registration and management of policies, entry points denoting initialization, creation, destruction, and other life cycle events for kernel objects, events associated with access control decisions that the policy module may influence, and calls associated with the management of labels on objects. +In addition, a `mac_syscall()` entry point is provided so that policies may extend the kernel interface without registering new system calls. -Policy module writers should be aware of the kernel locking strategy, as well as what object locks are available during which entry points. Writers should attempt to avoid deadlock scenarios by avoiding grabbing non-leaf locks inside of entry points, and also follow the locking protocol for object access and modification. In particular, writers should be aware that while necessary locks to access objects and their labels are generally held, sufficient locks to modify an object or its label may not be present for all entry points. Locking information for arguments is documented in the MAC framework entry point document. +Policy module writers should be aware of the kernel locking strategy, as well as what object locks are available during which entry points. +Writers should attempt to avoid deadlock scenarios by avoiding grabbing non-leaf locks inside of entry points, and also follow the locking protocol for object access and modification. +In particular, writers should be aware that while necessary locks to access objects and their labels are generally held, sufficient locks to modify an object or its label may not be present for all entry points. +Locking information for arguments is documented in the MAC framework entry point document. -Policy entry points will pass a reference to the object label along with the object itself. This permits labeled policies to be unaware of the internals of the object yet still make decisions based on the label. The exception to this is the process credential, which is assumed to be understood by policies as a first class security object in the kernel. +Policy entry points will pass a reference to the object label along with the object itself. +This permits labeled policies to be unaware of the internals of the object yet still make decisions based on the label. +The exception to this is the process credential, which is assumed to be understood by policies as a first class security object in the kernel. [[mac-entry-point-reference]] == MAC Policy Entry Point Reference @@ -272,8 +363,7 @@ Policy entry points will pass a reference to the object label along with the obj [source,c] ---- -void mpo_init( conf); -struct mac_policy_conf *conf; +void mpo_init(struct mac_policy_conf *conf); ---- [.informaltable] @@ -288,15 +378,16 @@ struct mac_policy_conf *conf; | |=== -Policy load event. The policy list mutex is held, so sleep operations cannot be performed, and calls out to other kernel subsystems must be made with caution. If potentially sleeping memory allocations are required during policy initialization, they should be made using a separate module SYSINIT(). +Policy load event. +The policy list mutex is held, so sleep operations cannot be performed, and calls out to other kernel subsystems must be made with caution. +If potentially sleeping memory allocations are required during policy initialization, they should be made using a separate module SYSINIT(). [[mpo-destroy]] ==== `mpo_destroy` [source,c] ---- -void mpo_destroy( conf); -struct mac_policy_conf *conf; +void mpo_destroy(struct mac_policy_conf *conf); ---- [.informaltable] @@ -311,19 +402,15 @@ struct mac_policy_conf *conf; | |=== -Policy load event. The policy list mutex is held, so caution should be applied. +Policy load event. +The policy list mutex is held, so caution should be applied. [[mac-mpo-syscall]] ==== `mpo_syscall` [source,c] ---- -int mpo_syscall( td, - call, - arg); -struct thread *td; -int call; -void *arg; +int mpo_syscall(struct thread *td, int call, void *arg); ---- [.informaltable] @@ -346,7 +433,10 @@ void *arg; | |=== -This entry point provides a policy-multiplexed system call so that policies may provide additional services to user processes without registering specific system calls. The policy name provided during registration is used to demux calls from userland, and the arguments will be forwarded to this entry point. When implementing new services, security modules should be sure to invoke appropriate access control checks from the MAC framework as needed. For example, if a policy implements an augmented signal functionality, it should call the necessary signal access control checks to invoke the MAC framework and other registered policies. +This entry point provides a policy-multiplexed system call so that policies may provide additional services to user processes without registering specific system calls. +The policy name provided during registration is used to demultiplexer calls from userland, and the arguments will be forwarded to this entry point. +When implementing new services, security modules should be sure to invoke appropriate access control checks from the MAC framework as needed. +For example, if a policy implements an augmented signal functionality, it should call the necessary signal access control checks to invoke the MAC framework and other registered policies. [NOTE] ==== @@ -358,8 +448,7 @@ Modules must currently perform the `copyin()` of the syscall data on their own. [source,c] ---- -void mpo_thread_userret( td); -struct thread *td; +void mpo_thread_userret(struct thread *td); ---- [.informaltable] @@ -374,7 +463,11 @@ struct thread *td; | |=== -This entry point permits policy modules to perform MAC-related events when a thread returns to user space, via a system call return, trap return, or otherwise. This is required for policies that have floating process labels, as it is not always possible to acquire the process lock at arbitrary points in the stack during system call processing; process labels might represent traditional authentication data, process history information, or other data. To employ this mechanism, intended changes to the process credential label may be stored in the `p_label` protected by a per-policy spin lock, and then set the per-thread `TDF_ASTPENDING` flag and per-process `PS_MACPENDM` flag to schedule a call to the userret entry point. From this entry point, the policy may create a replacement credential with less concern about the locking context. Policy writers are cautioned that event ordering relating to scheduling an AST and the AST being performed may be complex and interlaced in multithreaded applications. +This entry point permits policy modules to perform MAC-related events when a thread returns to user space, via a system call return, trap return, or otherwise. +This is required for policies that have floating process labels, as it is not always possible to acquire the process lock at arbitrary points in the stack during system call processing; process labels might represent traditional authentication data, process history information, or other data. +To employ this mechanism, intended changes to the process credential label may be stored in the `p_label` protected by a per-policy spin lock, and then set the per-thread `TDF_ASTPENDING` flag and per-process `PS_MACPENDM` flag to schedule a call to the `userret` entry point. +From this entry point, the policy may create a replacement credential with less concern about the locking context. +Policy writers are cautioned that event ordering relating to scheduling an AST and the AST being performed may be complex and interlaced in multithreaded applications. [[mac-label-ops]] === Label Operations @@ -384,8 +477,7 @@ This entry point permits policy modules to perform MAC-related events when a thr [source,c] ---- -void mpo_init_bpfdesc_label( label); -struct label *label; +void mpo_init_bpfdesc_label(struct label *label); ---- [.informaltable] @@ -400,15 +492,15 @@ struct label *label; | |=== -Initialize the label on a newly instantiated bpfdesc (BPF descriptor). Sleeping is permitted. +Initialize the label on a newly instantiated bpfdesc (BPF descriptor). +Sleeping is permitted. [[mac-mpo-init-cred-label]] ==== `mpo_init_cred_label` [source,c] ---- -void mpo_init_cred_label( label); -struct label *label; +void mpo_init_cred_label(struct label *label); ---- [.informaltable] @@ -423,15 +515,15 @@ struct label *label; | |=== -Initialize the label for a newly instantiated user credential. Sleeping is permitted. +Initialize the label for a newly instantiated user credential. +Sleeping is permitted. [[mac-mpo-init-devfsdirent]] ==== `mpo_init_devfsdirent_label` [source,c] ---- -void mpo_init_devfsdirent_label( label); -struct label *label; +void mpo_init_devfsdirent_label(struct label *label); ---- [.informaltable] @@ -446,15 +538,15 @@ struct label *label; | |=== -Initialize the label on a newly instantiated devfs entry. Sleeping is permitted. +Initialize the label on a newly instantiated devfs entry. +Sleeping is permitted. [[mac-mpo-init-ifnet]] ==== `mpo_init_ifnet_label` [source,c] ---- -void mpo_init_ifnet_label( label); -struct label *label; +void mpo_init_ifnet_label(struct label *label); ---- [.informaltable] @@ -469,17 +561,15 @@ struct label *label; | |=== -Initialize the label on a newly instantiated network interface. Sleeping is permitted. +Initialize the label on a newly instantiated network interface. +Sleeping is permitted. [[mac-mpo-init-ipq]] ==== `mpo_init_ipq_label` [source,c] ---- -void mpo_init_ipq_label( label, - flag); -struct label *label; -int flag; +void mpo_init_ipq_label(struct label *label, int flag); ---- [.informaltable] @@ -498,17 +588,17 @@ int flag; | |=== -Initialize the label on a newly instantiated IP fragment reassembly queue. The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a sleeping man:malloc[9] during this initialization call. IP fragment reassembly queue allocation frequently occurs in performance sensitive environments, and the implementation should be careful to avoid sleeping or long-lived operations. This entry point is permitted to fail resulting in the failure to allocate the IP fragment reassembly queue. +Initialize the label on a newly instantiated IP fragment reassembly queue. +The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a sleeping man:malloc[9] during this initialization call. +IP fragment reassembly queue allocation frequently occurs in performance sensitive environments, and the implementation should be careful to avoid sleeping or long-lived operations. +This entry point is permitted to fail resulting in the failure to allocate the IP fragment reassembly queue. [[mac-mpo-init-mbuf]] ==== `mpo_init_mbuf_label` [source,c] ---- -void mpo_init_mbuf_label( flag, - label); -int flag; -struct label *label; +void mpo_init_mbuf_label(int flag, struct label *label); ---- [.informaltable] @@ -527,17 +617,17 @@ struct label *label; | |=== -Initialize the label on a newly instantiated mbuf packet header (`mbuf`). The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a sleeping man:malloc[9] during this initialization call. Mbuf allocation frequently occurs in performance sensitive environments, and the implementation should be careful to avoid sleeping or long-lived operations. This entry point is permitted to fail resulting in the failure to allocate the mbuf header. +Initialize the label on a newly instantiated mbuf packet header (`mbuf`). +The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a sleeping man:malloc[9] during this initialization call. +Mbuf allocation frequently occurs in performance sensitive environments, and the implementation should be careful to avoid sleeping or long-lived operations. +This entry point is permitted to fail resulting in the failure to allocate the mbuf header. [[mac-mpo-init-mount]] ==== `mpo_init_mount_label` [source,c] ---- -void mpo_init_mount_label( mntlabel, - fslabel); -struct label *mntlabel; -struct label *fslabel; +void mpo_init_mount_label(struct label *mntlabel, struct label *fslabel); ---- [.informaltable] @@ -556,15 +646,15 @@ struct label *fslabel; | |=== -Initialize the labels on a newly instantiated mount point. Sleeping is permitted. +Initialize the labels on a newly instantiated mount point. +Sleeping is permitted. [[mac-mpo-init-mount-fs-label]] ==== `mpo_init_mount_fs_label` [source,c] ---- -void mpo_init_mount_fs_label( label); -struct label *label; +void mpo_init_mount_fs_label(struct label *label); ---- [.informaltable] @@ -579,15 +669,15 @@ struct label *label; | |=== -Initialize the label on a newly mounted file system. Sleeping is permitted +Initialize the label on a newly mounted file system. +Sleeping is permitted [[mac-mpo-init-pipe-label]] ==== `mpo_init_pipe_label` [source,c] ---- -void mpo_init_pipe_label( label); -struct label*label; +void mpo_init_pipe_label(struct label *label); ---- [.informaltable] @@ -602,17 +692,15 @@ struct label*label; | |=== -Initialize a label for a newly instantiated pipe. Sleeping is permitted. +Initialize a label for a newly instantiated pipe. +Sleeping is permitted. [[mac-mpo-init-socket]] ==== `mpo_init_socket_label` [source,c] ---- -void mpo_init_socket_label( label, - flag); -struct label *label; -int flag; +void mpo_init_socket_label(struct label *label, int flag); ---- [.informaltable] @@ -631,17 +719,15 @@ int flag; | |=== -Initialize a label for a newly instantiated socket. The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a sleeping man:malloc[9] during this initialization call. +Initialize a label for a newly instantiated socket. +The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a sleeping man:malloc[9] during this initialization call. [[mac-mpo-init-socket-peer-label]] ==== `mpo_init_socket_peer_label` [source,c] ---- -void mpo_init_socket_peer_label( label, - flag); -struct label *label; -int flag; +void mpo_init_socket_peer_label(struct label *label, int flag); ---- [.informaltable] @@ -660,15 +746,15 @@ int flag; | |=== -Initialize the peer label for a newly instantiated socket. The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a sleeping man:malloc[9] during this initialization call. +Initialize the peer label for a newly instantiated socket. +The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a sleeping man:malloc[9] during this initialization call. [[mac-mpo-init-proc-label]] ==== `mpo_init_proc_label` [source,c] ---- -void mpo_init_proc_label( label); -struct label *label; +void mpo_init_proc_label(struct label *label); ---- [.informaltable] @@ -683,15 +769,15 @@ struct label *label; | |=== -Initialize the label for a newly instantiated process. Sleeping is permitted. +Initialize the label for a newly instantiated process. +Sleeping is permitted. [[mac-mpo-init-vnode]] ==== `mpo_init_vnode_label` [source,c] ---- -void mpo_init_vnode_label( label); -struct label *label; +void mpo_init_vnode_label(struct label *label); ---- [.informaltable] @@ -706,15 +792,15 @@ struct label *label; | |=== -Initialize the label on a newly instantiated vnode. Sleeping is permitted. +Initialize the label on a newly instantiated vnode. +Sleeping is permitted. [[mac-mpo-destroy-bpfdesc]] ==== `mpo_destroy_bpfdesc_label` [source,c] ---- -void mpo_destroy_bpfdesc_label( label); -struct label *label; +void mpo_destroy_bpfdesc_label(struct label *label); ---- [.informaltable] @@ -729,15 +815,15 @@ struct label *label; | |=== -Destroy the label on a BPF descriptor. In this entry point a policy should free any internal storage associated with `label` so that it may be destroyed. +Destroy the label on a BPF descriptor. +In this entry point a policy should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-cred]] ==== `mpo_destroy_cred_label` [source,c] ---- -void mpo_destroy_cred_label( label); -struct label *label; +void mpo_destroy_cred_label(struct label *label); ---- [.informaltable] @@ -752,15 +838,15 @@ struct label *label; | |=== -Destroy the label on a credential. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. +Destroy the label on a credential. +In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-devfsdirent]] ==== `mpo_destroy_devfsdirent_label` [source,c] ---- -void mpo_destroy_devfsdirent_label( label); -struct label *label; +void mpo_destroy_devfsdirent_label(struct label *label); ---- [.informaltable] @@ -775,15 +861,15 @@ struct label *label; | |=== -Destroy the label on a devfs entry. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. +Destroy the label on a devfs entry. +In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-ifnet-label]] ==== `mpo_destroy_ifnet_label` [source,c] ---- -void mpo_destroy_ifnet_label( label); -struct label *label; +void mpo_destroy_ifnet_label(struct label *label); ---- [.informaltable] @@ -798,15 +884,15 @@ struct label *label; | |=== -Destroy the label on a removed interface. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. +Destroy the label on a removed interface. +In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-ipq-label]] ==== `mpo_destroy_ipq_label` [source,c] ---- -void mpo_destroy_ipq_label( label); -struct label *label; +void mpo_destroy_ipq_label(struct label *label); ---- [.informaltable] @@ -821,15 +907,15 @@ struct label *label; | |=== -Destroy the label on an IP fragment queue. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. +Destroy the label on an IP fragment queue. +In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-mbuf-label]] ==== `mpo_destroy_mbuf_label` [source,c] ---- -void mpo_destroy_mbuf_label( label); -struct label *label; +void mpo_destroy_mbuf_label(struct label *label); ---- [.informaltable] @@ -844,15 +930,15 @@ struct label *label; | |=== -Destroy the label on an mbuf header. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. +Destroy the label on an mbuf header. +In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-mount-label]] ==== `mpo_destroy_mount_label` [source,c] ---- -void mpo_destroy_mount_label( label); -struct label *label; +void mpo_destroy_mount_label(struct label *label); ---- [.informaltable] @@ -867,17 +953,15 @@ struct label *label; | |=== -Destroy the labels on a mount point. In this entry point, a policy module should free the internal storage associated with `mntlabel` so that they may be destroyed. +Destroy the labels on a mount point. +In this entry point, a policy module should free the internal storage associated with `mntlabel` so that they may be destroyed. [[mac-mpo-destroy-mount]] ==== `mpo_destroy_mount_label` [source,c] ---- -void mpo_destroy_mount_label( mntlabel, - fslabel); -struct label *mntlabel; -struct label *fslabel; +void mpo_destroy_mount_label(struct label *mntlabel, struct label *fslabel); ---- [.informaltable] @@ -896,15 +980,15 @@ struct label *fslabel; | |=== -Destroy the labels on a mount point. In this entry point, a policy module should free the internal storage associated with `mntlabel` and `fslabel` so that they may be destroyed. +Destroy the labels on a mount point. +In this entry point, a policy module should free the internal storage associated with `mntlabel` and `fslabel` so that they may be destroyed. [[mac-mpo-destroy-socket]] ==== `mpo_destroy_socket_label` [source,c] ---- -void mpo_destroy_socket_label( label); -struct label *label; +void mpo_destroy_socket_label(struct label *label); ---- [.informaltable] @@ -919,15 +1003,15 @@ struct label *label; | |=== -Destroy the label on a socket. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. +Destroy the label on a socket. +In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-socket-peer-label]] ==== `mpo_destroy_socket_peer_label` [source,c] ---- -void mpo_destroy_socket_peer_label( peerlabel); -struct label *peerlabel; +void mpo_destroy_socket_peer_label(struct label *peerlabel); ---- [.informaltable] @@ -942,15 +1026,15 @@ struct label *peerlabel; | |=== -Destroy the peer label on a socket. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. +Destroy the peer label on a socket. +In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-pipe-label]] ==== `mpo_destroy_pipe_label` [source,c] ---- -void mpo_destroy_pipe_label( label); -struct label *label; +void mpo_destroy_pipe_label(struct label *label); ---- [.informaltable] @@ -965,15 +1049,15 @@ struct label *label; | |=== -Destroy the label on a pipe. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. +Destroy the label on a pipe. +In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-proc-label]] ==== `mpo_destroy_proc_label` [source,c] ---- -void mpo_destroy_proc_label( label); -struct label *label; +void mpo_destroy_proc_label(struct label *label); ---- [.informaltable] @@ -988,15 +1072,15 @@ struct label *label; | |=== -Destroy the label on a process. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. +Destroy the label on a process. +In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-vnode-label]] ==== `mpo_destroy_vnode_label` [source,c] ---- -void mpo_destroy_vnode_label( label); -struct label *label; +void mpo_destroy_vnode_label(struct label *label); ---- [.informaltable] @@ -1011,17 +1095,15 @@ struct label *label; | |=== -Destroy the label on a vnode. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. +Destroy the label on a vnode. +In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-copy-mbuf-label]] ==== `mpo_copy_mbuf_label` [source,c] ---- -void mpo_copy_mbuf_label( src, - dest); -struct label *src; -struct label *dest; +void mpo_copy_mbuf_label(struct label *src, struct label *dest); ---- [.informaltable] @@ -1047,10 +1129,7 @@ Copy the label information in `src` into `dest`. [source,c] ---- -void mpo_copy_pipe_label( src, - dest); -struct label *src; -struct label *dest; +void mpo_copy_pipe_label(struct label *src, struct label *dest); ---- [.informaltable] @@ -1076,10 +1155,7 @@ Copy the label information in `src` into `dest`. [source,c] ---- -void mpo_copy_vnode_label( src, - dest); -struct label *src; -struct label *dest; +void mpo_copy_vnode_label(struct label *src, struct label *dest); ---- [.informaltable] @@ -1105,14 +1181,8 @@ Copy the label information in `src` into `dest`. [source,c] ---- -int mpo_externalize_cred_label( label, - element_name, - sb, - *claimed); -struct label *label; -char *element_name; -struct sbuf *sb; -int *claimed; +int mpo_externalize_cred_label(struct label *label, char *element_name, + struct sbuf *sb, int *claimed); ---- [.informaltable] @@ -1139,21 +1209,20 @@ int *claimed; | |=== -Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. If `element_name` does not match the name of your policy, simply return 0. Only return nonzero if an error occurs while externalizing the label data. Once the policy fills in `element_data`, `*claimed` should be incremented. +Produce an externalized label based on the label structure passed. +An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. +Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. +If `element_name` does not match the name of your policy, simply return 0. +Only return nonzero if an error occurs while externalizing the label data. +Once the policy fills in `element_data`, `*claimed` should be incremented. [[mac-mpo-externalize-ifnet-label]] ==== `mpo_externalize_ifnet_label` [source,c] ---- -int mpo_externalize_ifnet_label( label, - element_name, - sb, - *claimed); -struct label *label; -char *element_name; -struct sbuf *sb; -int *claimed; +int mpo_externalize_ifnet_label(struct label *label, char *element_name, + struct sbuf *sb, int *claimed); ---- [.informaltable] @@ -1180,21 +1249,20 @@ int *claimed; | |=== -Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. If `element_name` does not match the name of your policy, simply return 0. Only return nonzero if an error occurs while externalizing the label data. Once the policy fills in `element_data`, `*claimed` should be incremented. +Produce an externalized label based on the label structure passed. +An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. +Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. +If `element_name` does not match the name of your policy, simply return 0. +Only return nonzero if an error occurs while externalizing the label data. +Once the policy fills in `element_data`, `*claimed` should be incremented. [[mac-mpo-externalize-pipe-label]] ==== `mpo_externalize_pipe_label` [source,c] ---- -int mpo_externalize_pipe_label( label, - element_name, - sb, - *claimed); -struct label *label; -char *element_name; -struct sbuf *sb; -int *claimed; +int mpo_externalize_pipe_label(struct label *label, char *element_name, + struct sbuf *sb, int *claimed); ---- [.informaltable] @@ -1221,21 +1289,20 @@ int *claimed; | |=== -Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. If `element_name` does not match the name of your policy, simply return 0. Only return nonzero if an error occurs while externalizing the label data. Once the policy fills in `element_data`, `*claimed` should be incremented. +Produce an externalized label based on the label structure passed. +An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. +Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. +If `element_name` does not match the name of your policy, simply return 0. +Only return nonzero if an error occurs while externalizing the label data. +Once the policy fills in `element_data`, `*claimed` should be incremented. [[mac-mpo-externalize-socket-label]] ==== `mpo_externalize_socket_label` [source,c] ---- -int mpo_externalize_socket_label( label, - element_name, - sb, - *claimed); -struct label *label; -char *element_name; -struct sbuf *sb; -int *claimed; +int mpo_externalize_socket_label(struct label *label, char *element_name, + struct sbuf *sb, int *claimed); ---- [.informaltable] @@ -1262,21 +1329,20 @@ int *claimed; | |=== -Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. If `element_name` does not match the name of your policy, simply return 0. Only return nonzero if an error occurs while externalizing the label data. Once the policy fills in `element_data`, `*claimed` should be incremented. +Produce an externalized label based on the label structure passed. +An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. +Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. +If `element_name` does not match the name of your policy, simply return 0. +Only return nonzero if an error occurs while externalizing the label data. +Once the policy fills in `element_data`, `*claimed` should be incremented. [[mac-mpo-externalize-socket-peer-label]] ==== `mpo_externalize_socket_peer_label` [source,c] ---- -int mpo_externalize_socket_peer_label( label, - element_name, - sb, - *claimed); -struct label *label; -char *element_name; -struct sbuf *sb; -int *claimed; +int mpo_externalize_socket_peer_label(struct label *label, char *element_name, + struct sbuf *sb, int *claimed); ---- [.informaltable] @@ -1303,21 +1369,20 @@ int *claimed; | |=== -Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. If `element_name` does not match the name of your policy, simply return 0. Only return nonzero if an error occurs while externalizing the label data. Once the policy fills in `element_data`, `*claimed` should be incremented. +Produce an externalized label based on the label structure passed. +An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. +Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. +If `element_name` does not match the name of your policy, simply return 0. +Only return nonzero if an error occurs while externalizing the label data. +Once the policy fills in `element_data`, `*claimed` should be incremented. [[mac-mpo-externalize-vnode-label]] ==== `mpo_externalize_vnode_label` [source,c] ---- -int mpo_externalize_vnode_label( label, - element_name, - sb, - *claimed); -struct label *label; -char *element_name; -struct sbuf *sb; -int *claimed; +int mpo_externalize_vnode_label(struct label *label, char *element_name, + struct sbuf *sb, int *claimed); ---- [.informaltable] @@ -1344,21 +1409,20 @@ int *claimed; | |=== -Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. If `element_name` does not match the name of your policy, simply return 0. Only return nonzero if an error occurs while externalizing the label data. Once the policy fills in `element_data`, `*claimed` should be incremented. +Produce an externalized label based on the label structure passed. +An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. +Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. +If `element_name` does not match the name of your policy, simply return 0. +Only return nonzero if an error occurs while externalizing the label data. +Once the policy fills in `element_data`, `*claimed` should be incremented. [[mac-mpo-internalize-cred-label]] ==== `mpo_internalize_cred_label` [source,c] ---- -int mpo_internalize_cred_label( label, - element_name, - element_data, - claimed); -struct label *label; -char *element_name; -char *element_data; -int *claimed; +int mpo_internalize_cred_label(struct label *label, char *element_name, + char *element_data, int *claimed); ---- [.informaltable] @@ -1385,21 +1449,17 @@ int *claimed; | |=== -Produce an internal label structure based on externalized label data in text format. Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. +Produce an internal label structure based on externalized label data in text format. +Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. +Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. [[mac-mpo-internalize-ifnet-label]] ==== `mpo_internalize_ifnet_label` [source,c] ---- -int mpo_internalize_ifnet_label( label, - element_name, - element_data, - claimed); -struct label *label; -char *element_name; -char *element_data; -int *claimed; +int mpo_internalize_ifnet_label(struct label *label, char *element_name, + char *element_data, int *claimed); ---- [.informaltable] @@ -1426,21 +1486,17 @@ int *claimed; | |=== -Produce an internal label structure based on externalized label data in text format. Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. +Produce an internal label structure based on externalized label data in text format. +Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. +Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. [[mac-mpo-internalize-pipe-label]] ==== `mpo_internalize_pipe_label` [source,c] ---- -int mpo_internalize_pipe_label( label, - element_name, - element_data, - claimed); -struct label *label; -char *element_name; -char *element_data; -int *claimed; +int mpo_internalize_pipe_label(struct label *label, char *element_name, + char *element_data, int *claimed); ---- [.informaltable] @@ -1467,21 +1523,17 @@ int *claimed; | |=== -Produce an internal label structure based on externalized label data in text format. Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. +Produce an internal label structure based on externalized label data in text format. +Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. +Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. [[mac-mpo-internalize-socket-label]] ==== `mpo_internalize_socket_label` [source,c] ---- -int mpo_internalize_socket_label( label, - element_name, - element_data, - claimed); -struct label *label; -char *element_name; -char *element_data; -int *claimed; +int mpo_internalize_socket_label(struct label *label, char *element_name, + char *element_data, int *claimed); ---- [.informaltable] @@ -1508,21 +1560,17 @@ int *claimed; | |=== -Produce an internal label structure based on externalized label data in text format. Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. +Produce an internal label structure based on externalized label data in text format. +Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. +Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. [[mac-mpo-internalize-vnode-label]] ==== `mpo_internalize_vnode_label` [source,c] ---- -int mpo_internalize_vnode_label( label, - element_name, - element_data, - claimed); -struct label *label; -char *element_name; -char *element_data; -int *claimed; +int mpo_internalize_vnode_label(struct label *label, char *element_name, + char *element_data, int *claimed); ---- [.informaltable] @@ -1549,12 +1597,19 @@ int *claimed; | |=== -Produce an internal label structure based on externalized label data in text format. Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. +Produce an internal label structure based on externalized label data in text format. +Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. +Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. [[mac-label-events]] === Label Events -This class of entry points is used by the MAC framework to permit policies to maintain label information on kernel objects. For each labeled kernel object of interest to a MAC policy, entry points may be registered for relevant life cycle events. All objects implement initialization, creation, and destruction hooks. Some objects will also implement relabeling, allowing user processes to change the labels on objects. Some objects will also implement object-specific events, such as label events associated with IP reassembly. A typical labeled object will have the following life cycle of entry points: +This class of entry points is used by the MAC framework to permit policies to maintain label information on kernel objects. +For each labeled kernel object of interest to a MAC policy, entry points may be registered for relevant life cycle events. +All objects implement initialization, creation, and destruction hooks. +Some objects will also implement relabeling, allowing user processes to change the labels on objects. +Some objects will also implement object-specific events, such as label events associated with IP reassembly. +A typical labeled object will have the following life cycle of entry points: [.programlisting] .... @@ -1569,17 +1624,26 @@ Access control events ~-->--o Label destruction o .... -Label initialization permits policies to allocate memory and set initial values for labels without context for the use of the object. The label slot allocated to a policy will be zeroed by default, so some policies may not need to perform initialization. +Label initialization permits policies to allocate memory and set initial values for labels without context for the use of the object. +The label slot allocated to a policy will be zeroed by default, so some policies may not need to perform initialization. -Label creation occurs when the kernel structure is associated with an actual kernel object. For example, Mbufs may be allocated and remain unused in a pool until they are required. mbuf allocation causes label initialization on the mbuf to take place, but mbuf creation occurs when the mbuf is associated with a datagram. Typically, context will be provided for a creation event, including the circumstances of the creation, and labels of other relevant objects in the creation process. For example, when an mbuf is created from a socket, the socket and its label will be presented to registered policies in addition to the new mbuf and its label. Memory allocation in creation events is discouraged, as it may occur in performance sensitive ports of the kernel; in addition, creation calls are not permitted to fail so a failure to allocate memory cannot be reported. +Label creation occurs when the kernel structure is associated with an actual kernel object. +For example, Mbufs may be allocated and remain unused in a pool until they are required. +mbuf allocation causes label initialization on the mbuf to take place, but mbuf creation occurs when the mbuf is associated with a datagram. +Typically, context will be provided for a creation event, including the circumstances of the creation, and labels of other relevant objects in the creation process. +For example, when an mbuf is created from a socket, the socket and its label will be presented to registered policies in addition to the new mbuf and its label. +Memory allocation in creation events is discouraged, as it may occur in performance sensitive ports of the kernel; in addition, creation calls are not permitted to fail so a failure to allocate memory cannot be reported. -Object specific events do not generally fall into the other broad classes of label events, but will generally provide an opportunity to modify or update the label on an object based on additional context. For example, the label on an IP fragment reassembly queue may be updated during the MAC_UPDATE_IPQ entry point as a result of the acceptance of an additional mbuf to that queue. +Object specific events do not generally fall into the other broad classes of label events, but will generally provide an opportunity to modify or update the label on an object based on additional context. +For example, the label on an IP fragment reassembly queue may be updated during the MAC_UPDATE_IPQ entry point as a result of the acceptance of an additional mbuf to that queue. Access control events are discussed in detail in the following section. Label destruction permits policies to release storage or state associated with a label during its association with an object so that the kernel data structures supporting the object may be reused or released. -In addition to labels associated with specific kernel objects, an additional class of labels exists: temporary labels. These labels are used to store update information submitted by user processes. These labels are initialized and destroyed as with other label types, but the creation event is MAC_INTERNALIZE, which accepts a user label to be converted to an in-kernel representation. +In addition to labels associated with specific kernel objects, an additional class of labels exists: temporary labels. +These labels are used to store update information submitted by user processes. +These labels are initialized and destroyed as with other label types, but the creation event is MAC_INTERNALIZE, which accepts a user label to be converted to an in-kernel representation. [[mac-fs-label-event-ops]] ==== File System Object Labeling Event Operations @@ -1589,18 +1653,9 @@ In addition to labels associated with specific kernel objects, an additional cla [source,c] ---- -void mpo_associate_vnode_devfs( mp, - fslabel, - de, - delabel, - vp, - vlabel); -struct mount *mp; -struct label *fslabel; -struct devfs_dirent *de; -struct label *delabel; -struct vnode *vp; -struct label *vlabel; +void mpo_associate_vnode_devfs(struct mount *mp, struct label *fslabel, + struct devfs_dirent *de, struct label *delabel, struct vnode *vp, + struct label *vlabel); ---- [.informaltable] @@ -1642,14 +1697,8 @@ Fill in the label (`vlabel`) for a newly created devfs vnode based on the devfs [source,c] ---- -int mpo_associate_vnode_extattr( mp, - fslabel, - vp, - vlabel); -struct mount *mp; -struct label *fslabel; -struct vnode *vp; -struct label *vlabel; +int mpo_associate_vnode_extattr(struct mount *mp, struct label *fslabel, + struct vnode *vp, struct label *vlabel); ---- [.informaltable] @@ -1676,21 +1725,18 @@ struct label *vlabel; | |=== -Attempt to retrieve the label for `vp` from the file system extended attributes. Upon success, the value `0` is returned. Should extended attribute retrieval not be supported, an accepted fallback is to copy `fslabel` into `vlabel`. In the event of an error, an appropriate value for `errno` should be returned. +Attempt to retrieve the label for `vp` from the file system extended attributes. +Upon success, the value `0` is returned. +Should extended attribute retrieval not be supported, an accepted fallback is to copy `fslabel` into `vlabel`. +In the event of an error, an appropriate value for `errno` should be returned. [[mac-mpo-associate-vnode-singlelabel]] ===== `mpo_associate_vnode_singlelabel` [source,c] ---- -void mpo_associate_vnode_singlelabel( mp, - fslabel, - vp, - vlabel); -struct mount *mp; -struct label *fslabel; -struct vnode *vp; -struct label *vlabel; +void mpo_associate_vnode_singlelabel(struct mount *mp, struct label *fslabel, + struct vnode *vp, struct label *vlabel); ---- [.informaltable] @@ -1724,12 +1770,8 @@ On non-multilabel file systems, this entry point is called to set the policy lab [source,c] ---- -void mpo_create_devfs_device( dev, - devfs_dirent, - label); -dev_t dev; -struct devfs_dirent *devfs_dirent; -struct label *label; +void mpo_create_devfs_device(dev_t dev, struct devfs_dirent *devfs_dirent, + struct label *label); ---- [.informaltable] @@ -1752,21 +1794,16 @@ struct label *label; | |=== -Fill out the label on a devfs_dirent being created for the passed device. This call will be made when the device file system is mounted, regenerated, or a new device is made available. +Fill out the label on a devfs_dirent being created for the passed device. +This call will be made when the device file system is mounted, regenerated, or a new device is made available. [[mac-mpo-create-devfs-directory]] ===== `mpo_create_devfs_directory` [source,c] ---- -void mpo_create_devfs_directory( dirname, - dirnamelen, - devfs_dirent, - label); -char *dirname; -int dirnamelen; -struct devfs_dirent *devfs_dirent; -struct label *label; +void mpo_create_devfs_directory(char *dirname, int dirnamelen, + struct devfs_dirent *devfs_dirent, struct label *label); ---- [.informaltable] @@ -1789,25 +1826,17 @@ struct label *label; | |=== -Fill out the label on a devfs_dirent being created for the passed directory. This call will be made when the device file system is mounted, regenerated, or a new device requiring a specific directory hierarchy is made available. +Fill out the label on a devfs_dirent being created for the passed directory. +This call will be made when the device file system is mounted, regenerated, or a new device requiring a specific directory hierarchy is made available. [[mac-mpo-create-devfs-symlink]] ===== `mpo_create_devfs_symlink` [source,c] ---- -void mpo_create_devfs_symlink( cred, - mp, - dd, - ddlabel, - de, - delabel); -struct ucred *cred; -struct mount *mp; -struct devfs_dirent *dd; -struct label *ddlabel; -struct devfs_dirent *de; -struct label *delabel; +void mpo_create_devfs_symlink(struct ucred *cred, struct mount *mp, + struct devfs_dirent *dd, struct label *ddlabel, struct devfs_dirent *de, + struct label *delabel); ---- [.informaltable] @@ -1849,22 +1878,9 @@ Fill in the label (`delabel`) for a newly created man:devfs[5] symbolic link ent [source,c] ---- -int mpo_create_vnode_extattr( cred, - mp, - fslabel, - dvp, - dlabel, - vp, - vlabel, - cnp); -struct ucred *cred; -struct mount *mp; -struct label *fslabel; -struct vnode *dvp; -struct label *dlabel; -struct vnode *vp; -struct label *vlabel; -struct componentname *cnp; +int mpo_create_vnode_extattr(struct ucred *cred, struct mount *mp, + struct label *fslabel, struct vnode *dvp, struct label *dlabel, + struct vnode *vp, struct label *vlabel, struct componentname *cnp); ---- [.informaltable] @@ -1907,21 +1923,17 @@ struct componentname *cnp; | |=== -Write out the label for `vp` to the appropriate extended attribute. If the write succeeds, fill in `vlabel` with the label, and return 0. Otherwise, return an appropriate error. +Write out the label for `vp` to the appropriate extended attribute. +If the write succeeds, fill in `vlabel` with the label, and return 0. +Otherwise, return an appropriate error. [[mac-mpo-create-mount]] ===== `mpo_create_mount` [source,c] ---- -void mpo_create_mount( cred, - mp, - mnt, - fslabel); -struct ucred *cred; -struct mount *mp; -struct label *mnt; -struct label *fslabel; +void mpo_create_mount(struct ucred *cred, struct mount *mp, struct label *mnt, + struct label *fslabel); ---- [.informaltable] @@ -1948,21 +1960,16 @@ struct label *fslabel; | |=== -Fill out the labels on the mount point being created by the passed subject credential. This call will be made when a new file system is mounted. +Fill out the labels on the mount point being created by the passed subject credential. +This call will be made when a new file system is mounted. [[mac-mpo-create-root-mount]] ===== `mpo_create_root_mount` [source,c] ---- -void mpo_create_root_mount( cred, - mp, - mntlabel, - fslabel); -struct ucred *cred; -struct mount *mp; -struct label *mntlabel; -struct label *fslabel; +void mpo_create_root_mount(struct ucred *cred, struct mount *mp, + struct label *mntlabel, struct label *fslabel); ---- [.informaltable] @@ -1972,24 +1979,19 @@ struct label *fslabel; | Description | Locking -3+|See <<mac-mpo-create-mount>>. +3+|See crossref:mac[mac-mpo-create-mount, `mpo_create_mount`]. |=== -Fill out the labels on the mount point being created by the passed subject credential. This call will be made when the root file system is mounted, after mpo_create_mount;. +Fill out the labels on the mount point being created by the passed subject credential. +This call will be made when the root file system is mounted, after `mpo_create_mount;`. [[mac-mpo-relabel-vnode]] ===== `mpo_relabel_vnode` [source,c] ---- -void mpo_relabel_vnode( cred, - vp, - vnodelabel, - newlabel); -struct ucred *cred; -struct vnode *vp; -struct label *vnodelabel; -struct label *newlabel; +void mpo_relabel_vnode(struct ucred *cred, struct vnode *vp, + struct label *vnodelabel, struct label *newlabel); ---- [.informaltable] @@ -2023,14 +2025,8 @@ Update the label on the passed vnode given the passed update vnode label and the [source,c] ---- -int mpo_setlabel_vnode_extattr( cred, - vp, - vlabel, - intlabel); -struct ucred *cred; -struct vnode *vp; -struct label *vlabel; -struct label *intlabel; +int mpo_setlabel_vnode_extattr(struct ucred *cred, struct vnode *vp, + struct label *vlabel, struct label *intlabel); ---- [.informaltable] @@ -2057,21 +2053,16 @@ struct label *intlabel; | |=== -Write out the policy from `intlabel` to an extended attribute. This is called from `vop_stdcreatevnode_ea`. +Write out the policy from `intlabel` to an extended attribute. +This is called from `vop_stdcreatevnode_ea`. [[mac-mpo-update-devfsdirent]] ===== `mpo_update_devfsdirent` [source,c] ---- -void mpo_update_devfsdirent( devfs_dirent, - direntlabel, - vp, - vnodelabel); -struct devfs_dirent *devfs_dirent; -struct label *direntlabel; -struct vnode *vp; -struct label *vnodelabel; +void mpo_update_devfsdirent(struct devfs_dirent *devfs_dirent, + struct label *direntlabel, struct vnode *vp, struct label *vnodelabel); ---- [.informaltable] @@ -2092,14 +2083,15 @@ struct label *vnodelabel; |`vp` |Parent vnode |Locked -| |`vnodelabel` |Policy label for `vp` | |=== -Update the `devfs_dirent` label from the passed devfs vnode label. This call will be made when a devfs vnode has been successfully relabeled to commit the label change such that it lasts even if the vnode is recycled. It will also be made when a symlink is created in devfs, following a call to `mac_vnode_create_from_vnode` to initialize the vnode label. +Update the `devfs_dirent` label from the passed devfs vnode label. +This call will be made when a devfs vnode has been successfully relabeled to commit the label change such that it lasts even if the vnode is recycled. +It will also be made when a symlink is created in devfs, following a call to `mac_vnode_create_from_vnode` to initialize the vnode label. [[mac-ipc-label-ops]] ==== IPC Object Labeling Event Operations @@ -2109,14 +2101,8 @@ Update the `devfs_dirent` label from the passed devfs vnode label. This call wil [source,c] ---- -void mpo_create_mbuf_from_socket( so, - socketlabel, - m, - mbuflabel); -struct socket *so; -struct label *socketlabel; -struct mbuf *m; -struct label *mbuflabel; +void mpo_create_mbuf_from_socket(struct socket *so, struct label *socketlabel, + struct mbuf *m, struct label *mbuflabel); ---- [.informaltable] @@ -2143,19 +2129,16 @@ struct label *mbuflabel; | |=== -Set the label on a newly created mbuf header from the passed socket label. This call is made when a new datagram or message is generated by the socket and stored in the passed mbuf. +Set the label on a newly created mbuf header from the passed socket label. +This call is made when a new datagram or message is generated by the socket and stored in the passed mbuf. [[mac-mpo-create-pipe]] ===== `mpo_create_pipe` [source,c] ---- -void mpo_create_pipe( cred, - pipe, - pipelabel); -struct ucred *cred; -struct pipe *pipe; -struct label *pipelabel; +void mpo_create_pipe(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel); ---- [.informaltable] @@ -2178,19 +2161,16 @@ struct label *pipelabel; | |=== -Set the label on a newly created pipe from the passed subject credential. This call is made when a new pipe is created. +Set the label on a newly created pipe from the passed subject credential. +This call is made when a new pipe is created. [[mac-mpo-create-socket]] ===== `mpo_create_socket` [source,c] ---- -void mpo_create_socket( cred, - so, - socketlabel); -struct ucred *cred; -struct socket *so; -struct label *socketlabel; +void mpo_create_socket(struct ucred *cred, struct socket *so, + struct label *socketlabel); ---- [.informaltable] @@ -2213,21 +2193,17 @@ struct label *socketlabel; | |=== -Set the label on a newly created socket from the passed subject credential. This call is made when a socket is created. +Set the label on a newly created socket from the passed subject credential. +This call is made when a socket is created. [[mac-mpo-create-socket-from-socket]] ===== `mpo_create_socket_from_socket` [source,c] ---- -void mpo_create_socket_from_socket( oldsocket, - oldsocketlabel, - newsocket, - newsocketlabel); -struct socket *oldsocket; -struct label *oldsocketlabel; -struct socket *newsocket; -struct label *newsocketlabel; +void mpo_create_socket_from_socket(struct socket *oldsocket, + struct label *oldsocketlabel, struct socket *newsocket, + struct label *newsocketlabel); ---- [.informaltable] @@ -2261,14 +2237,8 @@ Label a socket, `newsocket`, newly man:accept[2]ed, based on the man:listen[2] s [source,c] ---- -void mpo_relabel_pipe( cred, - pipe, - oldlabel, - newlabel); -struct ucred *cred; -struct pipe *pipe; -struct label *oldlabel; -struct label *newlabel; +void mpo_relabel_pipe(struct ucred *cred, struct pipe *pipe, + struct label *oldlabel, struct label *newlabel); ---- [.informaltable] @@ -2302,14 +2272,8 @@ Apply a new label, `newlabel`, to `pipe`. [source,c] ---- -void mpo_relabel_socket( cred, - so, - oldlabel, - newlabel); -struct ucred *cred; -struct socket *so; -struct label *oldlabel; -struct label *newlabel; +void mpo_relabel_socket(struct ucred *cred, struct socket *so, + struct label *oldlabel, struct label *newlabel); ---- [.informaltable] @@ -2343,14 +2307,8 @@ Update the label on a socket from the passed socket label update. [source,c] ---- -void mpo_set_socket_peer_from_mbuf( mbuf, - mbuflabel, - oldlabel, - newlabel); -struct mbuf *mbuf; -struct label *mbuflabel; -struct label *oldlabel; -struct label *newlabel; +void mpo_set_socket_peer_from_mbuf(struct mbuf *mbuf, struct label *mbuflabel, + struct label *oldlabel, struct label *newlabel); ---- [.informaltable] @@ -2377,21 +2335,17 @@ struct label *newlabel; | |=== -Set the peer label on a stream socket from the passed mbuf label. This call will be made when the first datagram is received by the stream socket, with the exception of Unix domain sockets. +Set the peer label on a stream socket from the passed mbuf label. +This call will be made when the first datagram is received by the stream socket, with the exception of Unix domain sockets. [[mac-mpo-set-socket-peer-from-socket]] ===== `mpo_set_socket_peer_from_socket` [source,c] ---- -void mpo_set_socket_peer_from_socket( oldsocket, - oldsocketlabel, - newsocket, - newsocketpeerlabel); -struct socket *oldsocket; -struct label *oldsocketlabel; -struct socket *newsocket; -struct label *newsocketpeerlabel; +void mpo_set_socket_peer_from_socket(struct socket *oldsocket, + struct label *oldsocketlabel, struct socket *newsocket, + struct label *newsocketpeerlabel); ---- [.informaltable] @@ -2418,7 +2372,8 @@ struct label *newsocketpeerlabel; | |=== -Set the peer label on a stream UNIX domain socket from the passed remote socket endpoint. This call will be made when the socket pair is connected, and will be made for both endpoints. +Set the peer label on a stream UNIX domain socket from the passed remote socket endpoint. +This call will be made when the socket pair is connected, and will be made for both endpoints. [[mac-net-labeling-event-ops]] ==== Network Object Labeling Event Operations @@ -2428,12 +2383,8 @@ Set the peer label on a stream UNIX domain socket from the passed remote socket [source,c] ---- -void mpo_create_bpfdesc( cred, - bpf_d, - bpflabel); -struct ucred *cred; -struct bpf_d *bpf_d; -struct label *bpflabel; +void mpo_create_bpfdesc(struct ucred *cred, struct bpf_d *bpf_d, + struct label *bpflabel); ---- [.informaltable] @@ -2456,17 +2407,15 @@ struct label *bpflabel; | |=== -Set the label on a newly created BPF descriptor from the passed subject credential. This call will be made when a BPF device node is opened by a process with the passed subject credential. +Set the label on a newly created BPF descriptor from the passed subject credential. +This call will be made when a BPF device node is opened by a process with the passed subject credential. [[mac-mpo-create-ifnet]] ===== `mpo_create_ifnet` [source,c] ---- -void mpo_create_ifnet( ifnet, - ifnetlabel); -struct ifnet *ifnet; -struct label *ifnetlabel; +void mpo_create_ifnet(struct ifnet *ifnet, struct label *ifnetlabel); ---- [.informaltable] @@ -2485,21 +2434,16 @@ struct label *ifnetlabel; | |=== -Set the label on a newly created interface. This call may be made when a new physical interface becomes available to the system, or when a pseudo-interface is instantiated during the boot or as a result of a user action. +Set the label on a newly created interface. +This call may be made when a new physical interface becomes available to the system, or when a pseudo-interface is instantiated during the boot or as a result of a user action. [[mac-mpo-create-ipq]] ===== `mpo_create_ipq` [source,c] ---- -void mpo_create_ipq( fragment, - fragmentlabel, - ipq, - ipqlabel); -struct mbuf *fragment; -struct label *fragmentlabel; -struct ipq *ipq; -struct label *ipqlabel; +void mpo_create_ipq(struct mbuf *fragment, struct label *fragmentlabel, + struct ipq *ipq, struct label *ipqlabel); ---- [.informaltable] @@ -2533,14 +2477,8 @@ Set the label on a newly created IP fragment reassembly queue from the mbuf head [source,c] ---- -void mpo_create_create_datagram_from_ipq( ipq, - ipqlabel, - datagram, - datagramlabel); -struct ipq *ipq; -struct label *ipqlabel; -struct mbuf *datagram; -struct label *datagramlabel; +void mpo_create_create_datagram_from_ipq(struct ipq *ipq, + struct label *ipqlabel, struct mbuf *datagram, struct label *datagramlabel); ---- [.informaltable] @@ -2574,14 +2512,8 @@ Set the label on a newly reassembled IP datagram from the IP fragment reassembly [source,c] ---- -void mpo_create_fragment( datagram, - datagramlabel, - fragment, - fragmentlabel); -struct mbuf *datagram; -struct label *datagramlabel; -struct mbuf *fragment; -struct label *fragmentlabel; +void mpo_create_fragment(struct mbuf *datagram, struct label *datagramlabel, + struct mbuf *fragment, struct label *fragmentlabel); ---- [.informaltable] @@ -2615,14 +2547,8 @@ Set the label on the mbuf header of a newly created IP fragment from the label o [source,c] ---- -void mpo_create_mbuf_from_mbuf( oldmbuf, - oldmbuflabel, - newmbuf, - newmbuflabel); -struct mbuf *oldmbuf; -struct label *oldmbuflabel; -struct mbuf *newmbuf; -struct label *newmbuflabel; +void mpo_create_mbuf_from_mbuf(struct mbuf *oldmbuf, struct label *oldmbuflabel, + struct mbuf *newmbuf, struct label *newmbuflabel); ---- [.informaltable] @@ -2649,21 +2575,16 @@ struct label *newmbuflabel; | |=== -Set the label on the mbuf header of a newly created datagram from the mbuf header of an existing datagram. This call may be made in a number of situations, including when an mbuf is re-allocated for alignment purposes. +Set the label on the mbuf header of a newly created datagram from the mbuf header of an existing datagram. +This call may be made in a number of situations, including when an mbuf is re-allocated for alignment purposes. [[mac-mpo-create-mbuf-linklayer]] ===== `mpo_create_mbuf_linklayer` [source,c] ---- -void mpo_create_mbuf_linklayer( ifnet, - ifnetlabel, - mbuf, - mbuflabel); -struct ifnet *ifnet; -struct label *ifnetlabel; -struct mbuf *mbuf; -struct label *mbuflabel; +void mpo_create_mbuf_linklayer(struct ifnet *ifnet, struct label *ifnetlabel, + struct mbuf *mbuf, struct label *mbuflabel); ---- [.informaltable] @@ -2690,21 +2611,16 @@ struct label *mbuflabel; | |=== -Set the label on the mbuf header of a newly created datagram generated for the purposes of a link layer response for the passed interface. This call may be made in a number of situations, including for ARP or ND6 responses in the IPv4 and IPv6 stacks. +Set the label on the mbuf header of a newly created datagram generated for the purposes of a link layer response for the passed interface. +This call may be made in a number of situations, including for ARP or ND6 responses in the IPv4 and IPv6 stacks. [[mac-mpo-create-mbuf-from-bpfdesc]] ===== `mpo_create_mbuf_from_bpfdesc` [source,c] ---- -void mpo_create_mbuf_from_bpfdesc( bpf_d, - bpflabel, - mbuf, - mbuflabel); -struct bpf_d *bpf_d; -struct label *bpflabel; -struct mbuf *mbuf; -struct label *mbuflabel; +void mpo_create_mbuf_from_bpfdesc(struct bpf_d *bpf_d, struct label *bpflabel, + struct mbuf *mbuf, struct label *mbuflabel); ---- [.informaltable] @@ -2731,21 +2647,16 @@ struct label *mbuflabel; | |=== -Set the label on the mbuf header of a newly created datagram generated using the passed BPF descriptor. This call is made when a write is performed to the BPF device associated with the passed BPF descriptor. +Set the label on the mbuf header of a newly created datagram generated using the passed BPF descriptor. +This call is made when a write is performed to the BPF device associated with the passed BPF descriptor. [[mac-mpo-create-mbuf-from-ifnet]] ===== `mpo_create_mbuf_from_ifnet` [source,c] ---- -void mpo_create_mbuf_from_ifnet( ifnet, - ifnetlabel, - mbuf, - mbuflabel); -struct ifnet *ifnet; -struct label *ifnetlabel; -struct mbuf *mbuf; -struct label *mbuflabel; +void mpo_create_mbuf_from_ifnet(struct ifnet *ifnet, struct label *ifnetlabel, + struct mbuf *mbuf, struct label *mbuflabel); ---- [.informaltable] @@ -2779,18 +2690,9 @@ Set the label on the mbuf header of a newly created datagram generated from the [source,c] ---- -void mpo_create_mbuf_multicast_encap( oldmbuf, - oldmbuflabel, - ifnet, - ifnetlabel, - newmbuf, - newmbuflabel); -struct mbuf *oldmbuf; -struct label *oldmbuflabel; -struct ifnet *ifnet; -struct label *ifnetlabel; -struct mbuf *newmbuf; -struct label *newmbuflabel; +void mpo_create_mbuf_multicast_encap(struct mbuf *oldmbuf, + struct label *oldmbuflabel, struct ifnet *ifnet, struct label *ifnetlabel, + struct mbuf *newmbuf, struct label *newmbuflabel); ---- [.informaltable] @@ -2825,21 +2727,16 @@ struct label *newmbuflabel; | |=== -Set the label on the mbuf header of a newly created datagram generated from the existing passed datagram when it is processed by the passed multicast encapsulation interface. This call is made when an mbuf is to be delivered using the virtual interface. +Set the label on the mbuf header of a newly created datagram generated from the existing passed datagram when it is processed by the passed multicast encapsulation interface. +This call is made when an mbuf is to be delivered using the virtual interface. [[mac-mpo-create-mbuf-netlayer]] ===== `mpo_create_mbuf_netlayer` [source,c] ---- -void mpo_create_mbuf_netlayer( oldmbuf, - oldmbuflabel, - newmbuf, - newmbuflabel); -struct mbuf *oldmbuf; -struct label *oldmbuflabel; -struct mbuf *newmbuf; -struct label *newmbuflabel; +void mpo_create_mbuf_netlayer(struct mbuf *oldmbuf, struct label *oldmbuflabel, + struct mbuf *newmbuf, struct label *newmbuflabel); ---- [.informaltable] @@ -2866,21 +2763,16 @@ struct label *newmbuflabel; | |=== -Set the label on the mbuf header of a newly created datagram generated by the IP stack in response to an existing received datagram (`oldmbuf`). This call may be made in a number of situations, including when responding to ICMP request datagrams. +Set the label on the mbuf header of a newly created datagram generated by the IP stack in response to an existing received datagram (`oldmbuf`). +This call may be made in a number of situations, including when responding to ICMP request datagrams. [[mac-mpo-fragment-match]] ===== `mpo_fragment_match` [source,c] ---- -int mpo_fragment_match( fragment, - fragmentlabel, - ipq, - ipqlabel); -struct mbuf *fragment; -struct label *fragmentlabel; -struct ipq *ipq; -struct label *ipqlabel; +int mpo_fragment_match(struct mbuf *fragment, struct label *fragmentlabel, + struct ipq *ipq, struct label *ipqlabel); ---- [.informaltable] @@ -2907,21 +2799,18 @@ struct label *ipqlabel; | |=== -Determine whether an mbuf header containing an IP datagram (`fragment`) fragment matches the label of the passed IP fragment reassembly queue (`ipq`). Return (1) for a successful match, or (0) for no match. This call is made when the IP stack attempts to find an existing fragment reassembly queue for a newly received fragment; if this fails, a new fragment reassembly queue may be instantiated for the fragment. Policies may use this entry point to prevent the reassembly of otherwise matching IP fragments if policy does not permit them to be reassembled based on the label or other information. +Determine whether an mbuf header containing an IP datagram (`fragment`) fragment matches the label of the passed IP fragment reassembly queue (`ipq`). +Return (1) for a successful match, or (0) for no match. +This call is made when the IP stack attempts to find an existing fragment reassembly queue for a newly received fragment; if this fails, a new fragment reassembly queue may be instantiated for the fragment. +Policies may use this entry point to prevent the reassembly of otherwise matching IP fragments if policy does not permit them to be reassembled based on the label or other information. [[mac-mpo-ifnet-relabel]] ===== `mpo_relabel_ifnet` [source,c] ---- -void mpo_relabel_ifnet( cred, - ifnet, - ifnetlabel, - newlabel); -struct ucred *cred; -struct ifnet *ifnet; -struct label *ifnetlabel; -struct label *newlabel; +void mpo_relabel_ifnet(struct ucred *cred, struct ifnet *ifnet, + struct label *ifnetlabel, struct label *newlabel); ---- [.informaltable] @@ -2955,14 +2844,8 @@ Update the label of network interface, `ifnet`, based on the passed update label [source,c] ---- -void mpo_update_ipq( fragment, - fragmentlabel, - ipq, - ipqlabel); -struct mbuf *fragment; -struct label *fragmentlabel; -struct ipq *ipq; -struct label *ipqlabel; +void mpo_update_ipq(struct mbuf *fragment, struct label *fragmentlabel, + struct ipq *ipq, struct label *ipqlabel); ---- [.informaltable] @@ -2999,10 +2882,7 @@ Update the label on an IP fragment reassembly queue (`ipq`) based on the accepta [source,c] ---- -void mpo_create_cred( parent_cred, - child_cred); -struct ucred *parent_cred; -struct ucred *child_cred; +void mpo_create_cred(struct ucred *parent_cred, struct ucred *child_cred); ---- [.informaltable] @@ -3021,21 +2901,17 @@ struct ucred *child_cred; | |=== -Set the label of a newly created subject credential from the passed subject credential. This call will be made when man:crcopy[9] is invoked on a newly created struct ucred. This call should not be confused with a process forking or creation event. +Set the label of a newly created subject credential from the passed subject credential. +This call will be made when man:crcopy[9] is invoked on a newly created `struct ucred`. +This call should not be confused with a process forking or creation event. [[mac-mpo-execve-transition]] ===== `mpo_execve_transition` [source,c] ---- -void mpo_execve_transition( old, - new, - vp, - vnodelabel); -struct ucred *old; -struct ucred *new; -struct vnode *vp; -struct label *vnodelabel; +void mpo_execve_transition(struct ucred *old, struct ucred *new, + struct vnode *vp, struct label *vnodelabel); ---- @@ -3063,19 +2939,18 @@ struct label *vnodelabel; | |=== -Update the label of a newly created subject credential (`new`) from the passed existing subject credential (`old`) based on a label transition caused by executing the passed vnode (`vp`). This call occurs when a process executes the passed vnode and one of the policies returns a success from the `mpo_execve_will_transition` entry point. Policies may choose to implement this call simply by invoking `mpo_create_cred` and passing the two subject credentials so as not to implement a transitioning event. Policies should not leave this entry point unimplemented if they implement `mpo_create_cred`, even if they do not implement `mpo_execve_will_transition`. +Update the label of a newly created subject credential (`new`) from the passed existing subject credential (`old`) based on a label transition caused by executing the passed vnode (`vp`). +This call occurs when a process executes the passed vnode and one of the policies returns a success from the `mpo_execve_will_transition` entry point. +Policies may choose to implement this call simply by invoking `mpo_create_cred` and passing the two subject credentials so as not to implement a transitioning event. +Policies should not leave this entry point unimplemented if they implement `mpo_create_cred`, even if they do not implement `mpo_execve_will_transition`. [[mac-mpo-execve-will-transition]] ===== `mpo_execve_will_transition` [source,c] ---- -int mpo_execve_will_transition( old, - vp, - vnodelabel); -struct ucred *old; -struct vnode *vp; -struct label *vnodelabel; +int mpo_execve_will_transition(struct ucred *old, struct vnode *vp, + struct label *vnodelabel); ---- [.informaltable] @@ -3098,15 +2973,16 @@ struct label *vnodelabel; | |=== -Determine whether the policy will want to perform a transition event as a result of the execution of the passed vnode by the passed subject credential. Return 1 if a transition is required, 0 if not. Even if a policy returns 0, it should behave correctly in the presence of an unexpected invocation of `mpo_execve_transition`, as that call may happen as a result of another policy requesting a transition. +Determine whether the policy will want to perform a transition event as a result of the execution of the passed vnode by the passed subject credential. +Return 1 if a transition is required, 0 if not. +Even if a policy returns 0, it should behave correctly in the presence of an unexpected invocation of `mpo_execve_transition`, as that call may happen as a result of another policy requesting a transition. [[mac-mpo-create-proc0]] ===== `mpo_create_proc0` [source,c] ---- -void mpo_create_proc0( cred); -struct ucred *cred; +void mpo_create_proc0(struct ucred *cred); ---- [.informaltable] @@ -3128,8 +3004,7 @@ Create the subject credential of process 0, the parent of all kernel processes. [source,c] ---- -void mpo_create_proc1( cred); -struct ucred *cred; +void mpo_create_proc1(struct ucred *cred); ---- [.informaltable] @@ -3151,10 +3026,7 @@ Create the subject credential of process 1, the parent of all user processes. [source,c] ---- -void mpo_relabel_cred( cred, - newlabel); -struct ucred *cred; -struct label *newlabel; +void mpo_relabel_cred(struct ucred *cred, struct label *newlabel); ---- [.informaltable] @@ -3178,7 +3050,12 @@ Update the label on a subject credential from the passed update label. [[mac-access-control-checks]] === Access Control Checks -Access control entry points permit policy modules to influence access control decisions made by the kernel. Generally, although not always, arguments to an access control entry point will include one or more authorizing credentials, information (possibly including a label) for any other objects involved in the operation. An access control entry point may return 0 to permit the operation, or an man:errno[2] error value. The results of invoking the entry point across various registered policy modules will be composed as follows: if all modules permit the operation to succeed, success will be returned. If one or modules returns a failure, a failure will be returned. If more than one module returns a failure, the errno value to return to the user will be selected using the following precedence, implemented by the `error_select()` function in [.filename]#kern_mac.c#: +Access control entry points permit policy modules to influence access control decisions made by the kernel. +Generally, although not always, arguments to an access control entry point will include one or more authorizing credentials, information (possibly including a label) for any other objects involved in the operation. +An access control entry point may return 0 to permit the operation, or an man:errno[2] error value. +The results of invoking the entry point across various registered policy modules will be composed as follows: if all modules permit the operation to succeed, success will be returned. +If one or modules returns a failure, a failure will be returned. +If more than one module returns a failure, the errno value to return to the user will be selected using the following precedence, implemented by the `error_select()` function in [.filename]#kern_mac.c#: [.informaltable] [cols="1,1", frame="none"] @@ -3200,21 +3077,16 @@ Access control entry points permit policy modules to influence access control de |EPERM |=== -If none of the error values returned by all modules are listed in the precedence chart then an arbitrarily selected value from the set will be returned. In general, the rules provide precedence to errors in the following order: kernel failures, invalid arguments, object not present, access not permitted, other. +If none of the error values returned by all modules are listed in the precedence chart then an arbitrarily selected value from the set will be returned. +In general, the rules provide precedence to errors in the following order: kernel failures, invalid arguments, object not present, access not permitted, other. [[mac-mpo-bpfdesc-check-receive-from-ifnet]] ==== `mpo_check_bpfdesc_receive` [source,c] ---- -int mpo_check_bpfdesc_receive( bpf_d, - bpflabel, - ifnet, - ifnetlabel); -struct bpf_d *bpf_d; -struct label *bpflabel; -struct ifnet *ifnet; -struct label *ifnetlabel; +int mpo_check_bpfdesc_receive(struct bpf_d *bpf_d, struct label *bpflabel, + struct ifnet *ifnet, struct label *ifnetlabel); ---- [.informaltable] @@ -3241,15 +3113,15 @@ struct label *ifnetlabel; | |=== -Determine whether the MAC framework should permit datagrams from the passed interface to be delivered to the buffers of the passed BPF descriptor. Return (0) for success, or an `errno` value for failure Suggested failure: EACCES for label mismatches, EPERM for lack of privilege. +Determine whether the MAC framework should permit datagrams from the passed interface to be delivered to the buffers of the passed BPF descriptor. +Return (0) for success, or an `errno` value for failure Suggested failure: EACCES for label mismatches, EPERM for lack of privilege. [[mac-mpo-check-kenv-dump]] ==== `mpo_check_kenv_dump` [source,c] ---- -int mpo_check_kenv_dump( cred); -struct ucred *cred; +int mpo_check_kenv_dump(struct ucred *cred); ---- [.informaltable] @@ -3271,10 +3143,7 @@ Determine whether the subject should be allowed to retrieve the kernel environme [source,c] ---- -int mpo_check_kenv_get( cred, - name); -struct ucred *cred; -char *name; +int mpo_check_kenv_get(struct ucred *cred, char *name); ---- [.informaltable] @@ -3300,10 +3169,7 @@ Determine whether the subject should be allowed to retrieve the value of the spe [source,c] ---- -int mpo_check_kenv_set( cred, - name); -struct ucred *cred; -char *name; +int mpo_check_kenv_set(struct ucred *cred, char *name); ---- [.informaltable] @@ -3329,10 +3195,7 @@ Determine whether the subject should be allowed to set the specified kernel envi [source,c] ---- -int mpo_check_kenv_unset( cred, - name); -struct ucred *cred; -char *name; +int mpo_check_kenv_unset(struct ucred *cred, char *name); ---- [.informaltable] @@ -3358,12 +3221,8 @@ Determine whether the subject should be allowed to unset the specified kernel en [source,c] ---- -int mpo_check_kld_load( cred, - vp, - vlabel); -struct ucred *cred; -struct vnode *vp; -struct label *vlabel; +int mpo_check_kld_load(struct ucred *cred, struct vnode *vp, + struct label *vlabel); ---- [.informaltable] @@ -3393,8 +3252,7 @@ Determine whether the subject should be allowed to load the specified module fil [source,c] ---- -int mpo_check_kld_stat( cred); -struct ucred *cred; +int mpo_check_kld_stat(struct ucred *cred); ---- [.informaltable] @@ -3416,8 +3274,7 @@ Determine whether the subject should be allowed to retrieve a list of loaded ker [source,c] ---- -int mpo_check_kld_unload( cred); -struct ucred *cred; +int mpo_check_kld_unload(struct ucred *cred); ---- [.informaltable] @@ -3439,16 +3296,8 @@ Determine whether the subject should be allowed to unload a kernel module. [source,c] ---- -int mpo_check_pipe_ioctl( cred, - pipe, - pipelabel, - cmd, - data); -struct ucred *cred; -struct pipe *pipe; -struct label *pipelabel; -unsigned long cmd; -void *data; +int mpo_check_pipe_ioctl(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel, unsigned long cmd, void *data); ---- [.informaltable] @@ -3486,12 +3335,8 @@ Determine whether the subject should be allowed to make the specified man:ioctl[ [source,c] ---- -int mpo_check_pipe_poll( cred, - pipe, - pipelabel); -struct ucred *cred; -struct pipe *pipe; -struct label *pipelabel; +int mpo_check_pipe_poll(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel); ---- [.informaltable] @@ -3521,12 +3366,8 @@ Determine whether the subject should be allowed to poll `pipe`. [source,c] ---- -int mpo_check_pipe_read( cred, - pipe, - pipelabel); -struct ucred *cred; -struct pipe *pipe; -struct label *pipelabel; +int mpo_check_pipe_read(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel); ---- [.informaltable] @@ -3556,14 +3397,8 @@ Determine whether the subject should be allowed read access to `pipe`. [source,c] ---- -int mpo_check_pipe_relabel( cred, - pipe, - pipelabel, - newlabel); -struct ucred *cred; -struct pipe *pipe; -struct label *pipelabel; -struct label *newlabel; +int mpo_check_pipe_relabel(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel, struct label *newlabel); ---- [.informaltable] @@ -3597,12 +3432,8 @@ Determine whether the subject should be allowed to relabel `pipe`. [source,c] ---- -int mpo_check_pipe_stat( cred, - pipe, - pipelabel); -struct ucred *cred; -struct pipe *pipe; -struct label *pipelabel; +int mpo_check_pipe_stat(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel); ---- [.informaltable] @@ -3632,12 +3463,8 @@ Determine whether the subject should be allowed to retrieve statistics related t [source,c] ---- -int mpo_check_pipe_write( cred, - pipe, - pipelabel); -struct ucred *cred; -struct pipe *pipe; -struct label *pipelabel; +int mpo_check_pipe_write(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel); ---- [.informaltable] @@ -3667,14 +3494,8 @@ Determine whether the subject should be allowed to write to `pipe`. [source,c] ---- -int mpo_check_socket_bind( cred, - socket, - socketlabel, - sockaddr); -struct ucred *cred; -struct socket *socket; -struct label *socketlabel; -struct sockaddr *sockaddr; +int mpo_check_socket_bind(struct ucred *cred, struct socket *socket, + struct label *socketlabel, struct sockaddr *sockaddr); ---- [.informaltable] @@ -3706,14 +3527,8 @@ struct sockaddr *sockaddr; [source,c] ---- -int mpo_check_socket_connect( cred, - socket, - socketlabel, - sockaddr); -struct ucred *cred; -struct socket *socket; -struct label *socketlabel; -struct sockaddr *sockaddr; +int mpo_check_socket_connect(struct ucred *cred, struct socket *socket, + struct label *socketlabel, struct sockaddr *sockaddr); ---- [.informaltable] @@ -3740,19 +3555,17 @@ struct sockaddr *sockaddr; | |=== -Determine whether the subject credential (`cred`) can connect the passed socket (`socket`) to the passed socket address (`sockaddr`). Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatches, EPERM for lack of privilege. +Determine whether the subject credential (`cred`) can connect the passed socket (`socket`) to the passed socket address (`sockaddr`). +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatches, EPERM for lack of privilege. [[mac-mpo-check-socket-receive]] ==== `mpo_check_socket_receive` [source,c] ---- -int mpo_check_socket_receive( cred, - so, - socketlabel); -struct ucred *cred; -struct socket *so; -struct label *socketlabel; +int mpo_check_socket_receive(struct ucred *cred, struct socket *so, + struct label *socketlabel); ---- [.informaltable] @@ -3782,12 +3595,8 @@ Determine whether the subject should be allowed to receive information from the [source,c] ---- -int mpo_check_socket_send( cred, - so, - socketlabel); -struct ucred *cred; -struct socket *so; -struct label *socketlabel; +int mpo_check_socket_send(struct ucred *cred, struct socket *so, + struct label *socketlabel); ---- [.informaltable] @@ -3817,10 +3626,7 @@ Determine whether the subject should be allowed to send information across the s [source,c] ---- -int mpo_check_cred_visible( u1, - u2); -struct ucred *u1; -struct ucred *u2; +int mpo_check_cred_visible(struct ucred *u1, struct ucred *u2); ---- [.informaltable] @@ -3839,19 +3645,18 @@ struct ucred *u2; | |=== -Determine whether the subject credential `u1` can "see" other subjects with the passed subject credential `u2`. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatches, EPERM for lack of privilege, or ESRCH to hide visibility. This call may be made in a number of situations, including inter-process status sysctl's used by `ps`, and in procfs lookups. +Determine whether the subject credential `u1` can "see" other subjects with the passed subject credential `u2`. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatches, EPERM for lack of privilege, or ESRCH to hide visibility. +This call may be made in a number of situations, including inter-process status sysctl's used by `ps`, and in procfs lookups. [[mac-mpo-cred-check-socket-visible]] ==== `mpo_check_socket_visible` [source,c] ---- -int mpo_check_socket_visible( cred, - socket, - socketlabel); -struct ucred *cred; -struct socket *socket; -struct label *socketlabel; +int mpo_check_socket_visible(struct ucred *cred, struct socket *socket, + struct label *socketlabel); ---- [.informaltable] @@ -3879,14 +3684,8 @@ struct label *socketlabel; [source,c] ---- -int mpo_check_ifnet_relabel( cred, - ifnet, - ifnetlabel, - newlabel); -struct ucred *cred; -struct ifnet *ifnet; -struct label *ifnetlabel; -struct label *newlabel; +int mpo_check_ifnet_relabel(struct ucred *cred, struct ifnet *ifnet, + struct label *ifnetlabel, struct label *newlabel); ---- [.informaltable] @@ -3920,14 +3719,8 @@ Determine whether the subject credential can relabel the passed network interfac [source,c] ---- -int mpo_check_socket_relabel( cred, - socket, - socketlabel, - newlabel); -struct ucred *cred; -struct socket *socket; -struct label *socketlabel; -struct label *newlabel; +int mpo_check_socket_relabel(struct ucred *cred, struct socket *socket, + struct label *socketlabel, struct label *newlabel); ---- [.informaltable] @@ -3961,10 +3754,7 @@ Determine whether the subject credential can relabel the passed socket to the pa [source,c] ---- -int mpo_check_cred_relabel( cred, - newlabel); -struct ucred *cred; -struct label *newlabel; +int mpo_check_cred_relabel(struct ucred *cred, struct label *newlabel); ---- [.informaltable] @@ -3990,14 +3780,8 @@ Determine whether the subject credential can relabel itself to the passed label [source,c] ---- -int mpo_check_vnode_relabel( cred, - vp, - vnodelabel, - newlabel); -struct ucred *cred; -struct vnode *vp; -struct label *vnodelabel; -struct label *newlabel; +int mpo_check_vnode_relabel(struct ucred *cred, struct vnode *vp, + struct label *vnodelabel, struct label *newlabel); ---- [.informaltable] @@ -4031,12 +3815,8 @@ Determine whether the subject credential can relabel the passed vnode to the pas [source,c] ---- -int mpo_check_mount_stat( cred, - mp, - mountlabel); -struct ucred *cred; -struct mount *mp; -struct label *mountlabel; +int mpo_check_mount_stat(struct ucred *cred, struct mount *mp, + struct label *mountlabel); ---- [.informaltable] @@ -4059,17 +3839,17 @@ struct label *mountlabel; | |=== -Determine whether the subject credential can see the results of a statfs performed on the file system. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatches or EPERM for lack of privilege. This call may be made in a number of situations, including during invocations of man:statfs[2] and related calls, as well as to determine what file systems to exclude from listings of file systems, such as when man:getfsstat[2] is invoked. +Determine whether the subject credential can see the results of a statfs performed on the file system. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatches or EPERM for lack of privilege. +This call may be made in a number of situations, including during invocations of man:statfs[2] and related calls, as well as to determine what file systems to exclude from listings of file systems, such as when man:getfsstat[2] is invoked. [[mac-mpo-cred-check-proc-debug]] ==== `mpo_check_proc_debug` [source,c] ---- -int mpo_check_proc_debug( cred, - proc); -struct ucred *cred; -struct proc *proc; +int mpo_check_proc_debug(struct ucred *cred, struct proc *proc); ---- [.informaltable] @@ -4088,21 +3868,18 @@ struct proc *proc; | |=== -Determine whether the subject credential can debug the passed process. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to hide visibility of the target. This call may be made in a number of situations, including use of the man:ptrace[2] and man:ktrace[2] APIs, as well as for some types of procfs operations. +Determine whether the subject credential can debug the passed process. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to hide visibility of the target. +This call may be made in a number of situations, including use of the man:ptrace[2] and man:ktrace[2] APIs, as well as for some types of procfs operations. [[mac-mpo-cred-check-vnode-access]] ==== `mpo_check_vnode_access` [source,c] ---- -int mpo_check_vnode_access( cred, - vp, - label, - flags); -struct ucred *cred; -struct vnode *vp; -struct label *label; -int flags; +int mpo_check_vnode_access(struct ucred *cred, struct vnode *vp, + struct label *label, int flags); ---- [.informaltable] @@ -4129,19 +3906,18 @@ int flags; | |=== -Determine how invocations of man:access[2] and related calls by the subject credential should return when performed on the passed vnode using the passed access flags. This should generally be implemented using the same semantics used in `mpo_check_vnode_open`. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatches or EPERM for lack of privilege. +Determine how invocations of man:access[2] and related calls by the subject credential should return when performed on the passed vnode using the passed access flags. +This should generally be implemented using the same semantics used in `mpo_check_vnode_open`. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatches or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-chdir]] ==== `mpo_check_vnode_chdir` [source,c] ---- -int mpo_check_vnode_chdir( cred, - dvp, - dlabel); -struct ucred *cred; -struct vnode *dvp; -struct label *dlabel; +int mpo_check_vnode_chdir(struct ucred *cred, struct vnode *dvp, + struct label *dlabel); ---- [.informaltable] @@ -4164,19 +3940,17 @@ struct label *dlabel; | |=== -Determine whether the subject credential can change the process working directory to the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can change the process working directory to the passed vnode. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-check-vnode-chroot]] ==== `mpo_check_vnode_chroot` [source,c] ---- -int mpo_check_vnode_chroot( cred, - dvp, - dlabel); -struct ucred *cred; -struct vnode *dvp; -struct label *dlabel; +int mpo_check_vnode_chroot(struct ucred *cred, struct vnode *dvp, + struct label *dlabel); ---- [.informaltable] @@ -4206,16 +3980,8 @@ Determine whether the subject should be allowed to man:chroot[2] into the specif [source,c] ---- -int mpo_check_vnode_create( cred, - dvp, - dlabel, - cnp, - vap); -struct ucred *cred; -struct vnode *dvp; -struct label *dlabel; -struct componentname *cnp; -struct vattr *vap; +int mpo_check_vnode_create(struct ucred *cred, struct vnode *dvp, + struct label *dlabel, struct componentname *cnp, struct vattr *vap); ---- [.informaltable] @@ -4246,25 +4012,19 @@ struct vattr *vap; | |=== -Determine whether the subject credential can create a vnode with the passed parent directory, passed name information, and passed attribute information. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. This call may be made in a number of situations, including as a result of calls to man:open[2] with O_CREAT, man:mkfifo[2], and others. +Determine whether the subject credential can create a vnode with the passed parent directory, passed name information, and passed attribute information. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +This call may be made in a number of situations, including as a result of calls to man:open[2] with O_CREAT, man:mkfifo[2], and others. [[mac-mpo-cred-check-vnode-delete]] ==== `mpo_check_vnode_delete` [source,c] ---- -int mpo_check_vnode_delete( cred, - dvp, - dlabel, - vp, - label, - cnp); -struct ucred *cred; -struct vnode *dvp; -struct label *dlabel; -struct vnode *vp; -void *label; -struct componentname *cnp; +int mpo_check_vnode_delete(struct ucred *cred, struct vnode *dvp, + struct label *dlabel, struct vnode *vp, void *label, + struct componentname *cnp); ---- [.informaltable] @@ -4299,21 +4059,19 @@ struct componentname *cnp; | |=== -Determine whether the subject credential can delete a vnode from the passed parent directory and passed name information. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. This call may be made in a number of situations, including as a result of calls to man:unlink[2] and man:rmdir[2]. Policies implementing this entry point should also implement `mpo_check_rename_to` to authorize deletion of objects as a result of being the target of a rename. +Determine whether the subject credential can delete a vnode from the passed parent directory and passed name information. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +This call may be made in a number of situations, including as a result of calls to man:unlink[2] and man:rmdir[2]. +Policies implementing this entry point should also implement `mpo_check_rename_to` to authorize deletion of objects as a result of being the target of a rename. [[mac-mpo-cred-check-vnode-deleteacl]] ==== `mpo_check_vnode_deleteacl` [source,c] ---- -int mpo_check_vnode_deleteacl( cred, - vp, - label, - type); -struct ucred *cred; -struct vnode *vp; -struct label *label; -acl_type_t type; +int mpo_check_vnode_deleteacl(struct ucred *cred, struct vnode *vp, + struct label *label, acl_type_t type); ---- [.informaltable] @@ -4340,19 +4098,17 @@ acl_type_t type; | |=== -Determine whether the subject credential can delete the ACL of passed type from the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can delete the ACL of passed type from the passed vnode. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-exec]] ==== `mpo_check_vnode_exec` [source,c] ---- -int mpo_check_vnode_exec( cred, - vp, - label); -struct ucred *cred; -struct vnode *vp; -struct label *label; +int mpo_check_vnode_exec(struct ucred *cred, struct vnode *vp, + struct label *label); ---- [.informaltable] @@ -4375,21 +4131,18 @@ struct label *label; | |=== -Determine whether the subject credential can execute the passed vnode. Determination of execute privilege is made separately from decisions about any transitioning event. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can execute the passed vnode. +Determination of execute privilege is made separately from decisions about any transitioning event. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mpo-cred-check-vnode-getacl]] ==== `mpo_check_vnode_getacl` [source,c] ---- -int mpo_check_vnode_getacl( cred, - vp, - label, - type); -struct ucred *cred; -struct vnode *vp; -struct label *label; -acl_type_t type; +int mpo_check_vnode_getacl(struct ucred *cred, struct vnode *vp, + struct label *label, acl_type_t type); ---- [.informaltable] @@ -4416,25 +4169,17 @@ acl_type_t type; | |=== -Determine whether the subject credential can retrieve the ACL of passed type from the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can retrieve the ACL of passed type from the passed vnode. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-getextattr]] ==== `mpo_check_vnode_getextattr` [source,c] ---- -int mpo_check_vnode_getextattr( cred, - vp, - label, - attrnamespace, - name, - uio); -struct ucred *cred; -struct vnode *vp; -struct label *label; -int attrnamespace; -const char *name; -struct uio *uio; +int mpo_check_vnode_getextattr(struct ucred *cred, struct vnode *vp, + struct label *label, int attrnamespace, const char *name, struct uio *uio); ---- [.informaltable] @@ -4469,25 +4214,19 @@ struct uio *uio; | |=== -Determine whether the subject credential can retrieve the extended attribute with the passed namespace and name from the passed vnode. Policies implementing labeling using extended attributes may be interested in special handling of operations on those extended attributes. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can retrieve the extended attribute with the passed namespace and name from the passed vnode. +Policies implementing labeling using extended attributes may be interested in special handling of operations on those extended attributes. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-check-vnode-link]] ==== `mpo_check_vnode_link` [source,c] ---- -int mpo_check_vnode_link( cred, - dvp, - dlabel, - vp, - label, - cnp); -struct ucred *cred; -struct vnode *dvp; -struct label *dlabel; -struct vnode *vp; -struct label *label; -struct componentname *cnp; +int mpo_check_vnode_link(struct ucred *cred, struct vnode *dvp, + struct label *dlabel, struct vnode *vp, struct label *label, + struct componentname *cnp); ---- [.informaltable] @@ -4529,14 +4268,8 @@ Determine whether the subject should be allowed to create a link to the vnode `v [source,c] ---- -int mpo_check_vnode_mmap( cred, - vp, - label, - prot); -struct ucred *cred; -struct vnode *vp; -struct label *label; -int prot; +int mpo_check_vnode_mmap(struct ucred *cred, struct vnode *vp, + struct label *label, int prot); ---- [.informaltable] @@ -4570,14 +4303,8 @@ Determine whether the subject should be allowed to map the vnode `vp` with the p [source,c] ---- -void mpo_check_vnode_mmap_downgrade( cred, - vp, - label, - prot); -struct ucred *cred; -struct vnode *vp; -struct label *label; -int *prot; +void mpo_check_vnode_mmap_downgrade(struct ucred *cred, struct vnode *vp, + struct label *label, int *prot); ---- [.informaltable] @@ -4588,7 +4315,7 @@ int *prot; | Locking |`cred` -|See <<mac-mpo-check-vnode-mmap>>. +|See crossref:mac[mac-mpo-check-vnode-mmap, `mpo_check_vnode_mmap`]. | |`vp` @@ -4611,14 +4338,8 @@ Downgrade the mmap protections based on the subject and object labels. [source,c] ---- -int mpo_check_vnode_mprotect( cred, - vp, - label, - prot); -struct ucred *cred; -struct vnode *vp; -struct label *label; -int prot; +int mpo_check_vnode_mprotect(struct ucred *cred, struct vnode *vp, + struct label *label, int prot); ---- [.informaltable] @@ -4648,14 +4369,8 @@ Determine whether the subject should be allowed to set the specified memory prot [source,c] ---- -int mpo_check_vnode_poll( active_cred, - file_cred, - vp, - label); -struct ucred *active_cred; -struct ucred *file_cred; -struct vnode *vp; -struct label *label; +int mpo_check_vnode_poll(struct ucred *active_cred, struct ucred *file_cred, + struct vnode *vp, struct label *label); ---- [.informaltable] @@ -4689,18 +4404,9 @@ Determine whether the subject should be allowed to poll the vnode `vp`. [source,c] ---- -int mpo_vnode_rename_from( cred, - dvp, - dlabel, - vp, - label, - cnp); -struct ucred *cred; -struct vnode *dvp; -struct label *dlabel; -struct vnode *vp; -struct label *label; -struct componentname *cnp; +int mpo_vnode_rename_from(struct ucred *cred, struct vnode *dvp, + struct label *dlabel, struct vnode *vp, struct label *label, + struct componentname *cnp); ---- [.informaltable] @@ -4742,20 +4448,9 @@ Determine whether the subject should be allowed to rename the vnode `vp` to some [source,c] ---- -int mpo_check_vnode_rename_to( cred, - dvp, - dlabel, - vp, - label, - samedir, - cnp); -struct ucred *cred; -struct vnode *dvp; -struct label *dlabel; -struct vnode *vp; -struct label *label; -int samedir; -struct componentname *cnp; +int mpo_check_vnode_rename_to(struct ucred *cred, struct vnode *dvp, + struct label *dlabel, struct vnode *vp, struct label *label, int samedir, + struct componentname *cnp); ---- [.informaltable] @@ -4794,19 +4489,16 @@ struct componentname *cnp; | |=== -Determine whether the subject should be allowed to rename to the vnode `vp`, into the directory `dvp`, or to the name represented by `cnp`. If there is no existing file to overwrite, `vp` and `label` will be NULL. +Determine whether the subject should be allowed to rename to the vnode `vp`, into the directory `dvp`, or to the name represented by `cnp`. +If there is no existing file to overwrite, `vp` and `label` will be NULL. [[mac-mpo-cred-check-socket-listen]] ==== `mpo_check_socket_listen` [source,c] ---- -int mpo_check_socket_listen( cred, - socket, - socketlabel); -struct ucred *cred; -struct socket *socket; -struct label *socketlabel; +int mpo_check_socket_listen(struct ucred *cred, struct socket *socket, + struct label *socketlabel); ---- [.informaltable] @@ -4829,21 +4521,17 @@ struct label *socketlabel; | |=== -Determine whether the subject credential can listen on the passed socket. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can listen on the passed socket. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-lookup]] ==== `mpo_check_vnode_lookup` [source,c] ---- -int mpo_check_vnode_lookup( , - , - , - cnp); -struct ucred *cred; -struct vnode *dvp; -struct label *dlabel; -struct componentname *cnp; +int mpo_check_vnode_lookup(struct ucred *cred, struct vnode *dvp, + struct label *dlabel, struct componentname *cnp); ---- [.informaltable] @@ -4870,21 +4558,17 @@ struct componentname *cnp; | |=== -Determine whether the subject credential can perform a lookup in the passed directory vnode for the passed name. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can perform a lookup in the passed directory vnode for the passed name. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-open]] ==== `mpo_check_vnode_open` [source,c] ---- -int mpo_check_vnode_open( cred, - vp, - label, - acc_mode); -struct ucred *cred; -struct vnode *vp; -struct label *label; -int acc_mode; +int mpo_check_vnode_open(struct ucred *cred, struct vnode *vp, + struct label *label, int acc_mode); ---- [.informaltable] @@ -4911,19 +4595,17 @@ int acc_mode; | |=== -Determine whether the subject credential can perform an open operation on the passed vnode with the passed access mode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can perform an open operation on the passed vnode with the passed access mode. +Return 0 for success, or an errno value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-readdir]] ==== `mpo_check_vnode_readdir` [source,c] ---- -int mpo_check_vnode_readdir( , - , - ); -struct ucred *cred; -struct vnode *dvp; -struct label *dlabel; +int mpo_check_vnode_readdir(struct ucred *cred, struct vnode *dvp, + struct label *dlabel); ---- [.informaltable] @@ -4946,19 +4628,17 @@ struct label *dlabel; | |=== -Determine whether the subject credential can perform a `readdir` operation on the passed directory vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can perform a `readdir` operation on the passed directory vnode. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-readlink]] ==== `mpo_check_vnode_readlink` [source,c] ---- -int mpo_check_vnode_readlink( cred, - vp, - label); -struct ucred *cred; -struct vnode *vp; -struct label *label; +int mpo_check_vnode_readlink(struct ucred *cred, struct vnode *vp, + struct label *label); ---- [.informaltable] @@ -4981,19 +4661,18 @@ struct label *label; | |=== -Determine whether the subject credential can perform a `readlink` operation on the passed symlink vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. This call may be made in a number of situations, including an explicit `readlink` call by the user process, or as a result of an implicit `readlink` during a name lookup by the process. +Determine whether the subject credential can perform a `readlink` operation on the passed symlink vnode. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +This call may be made in a number of situations, including an explicit `readlink` call by the user process, or as a result of an implicit `readlink` during a name lookup by the process. [[mac-mpo-cred-check-vnode-revoke]] ==== `mpo_check_vnode_revoke` [source,c] ---- -int mpo_check_vnode_revoke( cred, - vp, - label); -struct ucred *cred; -struct vnode *vp; -struct label *label; +int mpo_check_vnode_revoke(struct ucred *cred, struct vnode *vp, + struct label *label); ---- [.informaltable] @@ -5016,23 +4695,17 @@ struct label *label; | |=== -Determine whether the subject credential can revoke access to the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can revoke access to the passed vnode. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-setacl]] ==== `mpo_check_vnode_setacl` [source,c] ---- -int mpo_check_vnode_setacl( cred, - vp, - label, - type, - acl); -struct ucred *cred; -struct vnode *vp; -struct label *label; -acl_type_t type; -struct acl *acl; +int mpo_check_vnode_setacl(struct ucred *cred, struct vnode *vp, + struct label *label, acl_type_t type, struct acl *acl); ---- [.informaltable] @@ -5063,25 +4736,17 @@ struct acl *acl; | |=== -Determine whether the subject credential can set the passed ACL of passed type on the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can set the passed ACL of passed type on the passed vnode. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-setextattr]] ==== `mpo_check_vnode_setextattr` [source,c] ---- -int mpo_check_vnode_setextattr( cred, - vp, - label, - attrnamespace, - name, - uio); -struct ucred *cred; -struct vnode *vp; -struct label *label; -int attrnamespace; -const char *name; -struct uio *uio; +int mpo_check_vnode_setextattr(struct ucred *cred, struct vnode *vp, + struct label *label, int attrnamespace, const char *name, struct uio *uio); ---- [.informaltable] @@ -5116,21 +4781,20 @@ struct uio *uio; | |=== -Determine whether the subject credential can set the extended attribute of passed name and passed namespace on the passed vnode. Policies implementing security labels backed into extended attributes may want to provide additional protections for those attributes. Additionally, policies should avoid making decisions based on the data referenced from `uio`, as there is a potential race condition between this check and the actual operation. The `uio` may also be `NULL` if a delete operation is being performed. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can set the extended attribute of passed name and passed namespace on the passed vnode. +Policies implementing security labels backed into extended attributes may want to provide additional protections for those attributes. +Additionally, policies should avoid making decisions based on the data referenced from `uio`, as there is a potential race condition between this check and the actual operation. +The `uio` may also be `NULL` if a delete operation is being performed. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-setflags]] ==== `mpo_check_vnode_setflags` [source,c] ---- -int mpo_check_vnode_setflags( cred, - vp, - label, - flags); -struct ucred *cred; -struct vnode *vp; -struct label *label; -u_long flags; +int mpo_check_vnode_setflags(struct ucred *cred, struct vnode *vp, + struct label *label, u_long flags); ---- [.informaltable] @@ -5157,21 +4821,17 @@ u_long flags; | |=== -Determine whether the subject credential can set the passed flags on the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can set the passed flags on the passed vnode. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-setmode]] ==== `mpo_check_vnode_setmode` [source,c] ---- -int mpo_check_vnode_setmode( cred, - vp, - label, - mode); -struct ucred *cred; -struct vnode *vp; -struct label *label; -mode_t mode; +int mpo_check_vnode_setmode(struct ucred *cred, struct vnode *vp, + struct label *label, mode_t mode); ---- [.informaltable] @@ -5198,23 +4858,17 @@ mode_t mode; | |=== -Determine whether the subject credential can set the passed mode on the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can set the passed mode on the passed vnode. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-setowner]] ==== `mpo_check_vnode_setowner` [source,c] ---- -int mpo_check_vnode_setowner( cred, - vp, - label, - uid, - gid); -struct ucred *cred; -struct vnode *vp; -struct label *label; -uid_t uid; -gid_t gid; +int mpo_check_vnode_setowner(struct ucred *cred, struct vnode *vp, + struct label *label, uid_t uid, gid_t gid); ---- [.informaltable] @@ -5245,23 +4899,18 @@ gid_t gid; | |=== -Determine whether the subject credential can set the passed uid and passed gid as file uid and file gid on the passed vnode. The IDs may be set to (`-1`) to request no update. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can set the passed uid and passed gid as file uid and file gid on the passed vnode. +The IDs may be set to (`-1`) to request no update. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-setutimes]] ==== `mpo_check_vnode_setutimes` [source,c] ---- -int mpo_check_vnode_setutimes( , - , - , - , - ); -struct ucred *cred; -struct vnode *vp; -struct label *label; -struct timespec atime; -struct timespec mtime; +int mpo_check_vnode_setutimes(struct ucred *cred, struct vnode *vp, + struct label *label, struct timespec atime, struct timespec mtime); ---- [.informaltable] @@ -5292,17 +4941,16 @@ struct timespec mtime; | |=== -Determine whether the subject credential can set the passed access timestamps on the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can set the passed access timestamps on the passed vnode. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-proc-sched]] ==== `mpo_check_proc_sched` [source,c] ---- -int mpo_check_proc_sched( ucred, - proc); -struct ucred *ucred; -struct proc *proc; +int mpo_check_proc_sched(struct ucred *ucred, struct proc *proc); ---- [.informaltable] @@ -5321,7 +4969,9 @@ struct proc *proc; | |=== -Determine whether the subject credential can change the scheduling parameters of the passed process. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to limit visibility. +Determine whether the subject credential can change the scheduling parameters of the passed process. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to limit visibility. See man:setpriority[2] for more information. @@ -5330,12 +4980,7 @@ See man:setpriority[2] for more information. [source,c] ---- -int mpo_check_proc_signal( cred, - proc, - signal); -struct ucred *cred; -struct proc *proc; -int signal; +int mpo_check_proc_signal(struct ucred *cred, struct proc *proc, int signal); ---- [.informaltable] @@ -5358,19 +5003,17 @@ int signal; | |=== -Determine whether the subject credential can deliver the passed signal to the passed process. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to limit visibility. +Determine whether the subject credential can deliver the passed signal to the passed process. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to limit visibility. [[mac-mpo-cred-check-vnode-stat]] ==== `mpo_check_vnode_stat` [source,c] ---- -int mpo_check_vnode_stat( cred, - vp, - label); -struct ucred *cred; -struct vnode *vp; -struct label *label; +int mpo_check_vnode_stat(struct ucred *cred, struct vnode *vp, + struct label *label); ---- [.informaltable] @@ -5393,7 +5036,9 @@ struct label *label; | |=== -Determine whether the subject credential can `stat` the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the subject credential can `stat` the passed vnode. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. See man:stat[2] for more information. @@ -5402,16 +5047,8 @@ See man:stat[2] for more information. [source,c] ---- -int mpo_check_ifnet_transmit( cred, - ifnet, - ifnetlabel, - mbuf, - mbuflabel); -struct ucred *cred; -struct ifnet *ifnet; -struct label *ifnetlabel; -struct mbuf *mbuf; -struct label *mbuflabel; +int mpo_check_ifnet_transmit(struct ucred *cred, struct ifnet *ifnet, + struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel); ---- [.informaltable] @@ -5442,23 +5079,17 @@ struct label *mbuflabel; | |=== -Determine whether the network interface can transmit the passed mbuf. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the network interface can transmit the passed mbuf. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-socket-deliver]] ==== `mpo_check_socket_deliver` [source,c] ---- -int mpo_check_socket_deliver( cred, - ifnet, - ifnetlabel, - mbuf, - mbuflabel); -struct ucred *cred; -struct ifnet *ifnet; -struct label *ifnetlabel; -struct mbuf *mbuf; -struct label *mbuflabel; +int mpo_check_socket_deliver(struct ucred *cred, struct ifnet *ifnet, + struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel); ---- [.informaltable] @@ -5489,19 +5120,17 @@ struct label *mbuflabel; | |=== -Determine whether the socket may receive the datagram stored in the passed mbuf header. Return 0 for success, or an `errno` value for failure. Suggested failures: EACCES for label mismatch, or EPERM for lack of privilege. +Determine whether the socket may receive the datagram stored in the passed mbuf header. +Return 0 for success, or an `errno` value for failure. +Suggested failures: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-check-socket-visible]] ==== `mpo_check_socket_visible` [source,c] ---- -int mpo_check_socket_visible( cred, - so, - socketlabel); -struct ucred *cred; -struct socket *so; -struct label *socketlabel; +int mpo_check_socket_visible(struct ucred *cred, struct socket *so, + struct label *socketlabel); ---- [.informaltable] @@ -5524,19 +5153,17 @@ struct label *socketlabel; | |=== -Determine whether the subject credential cred can "see" the passed socket (`socket`) using system monitoring functions, such as those employed by man:netstat[8] and man:sockstat[1]. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatches, EPERM for lack of privilege, or ESRCH to hide visibility. +Determine whether the subject credential cred can "see" the passed socket (`socket`) using system monitoring functions, such as those employed by man:netstat[8] and man:sockstat[1]. +Return 0 for success, or an `errno` value for failure. +Suggested failure: EACCES for label mismatches, EPERM for lack of privilege, or ESRCH to hide visibility. [[mac-mpo-check-system-acct]] ==== `mpo_check_system_acct` [source,c] ---- -int mpo_check_system_acct( ucred, - vp, - vlabel); -struct ucred *ucred; -struct vnode *vp; -struct label *vlabel; +int mpo_check_system_acct(struct ucred *ucred, struct vnode *vp, + struct label *vlabel); ---- [.informaltable] @@ -5566,8 +5193,7 @@ Determine whether the subject should be allowed to enable accounting, based on i [source,c] ---- -int mpo_check_system_nfsd( cred); -struct ucred *cred; +int mpo_check_system_nfsd(struct ucred *cred); ---- [.informaltable] @@ -5589,10 +5215,7 @@ Determine whether the subject should be allowed to call man:nfssvc[2]. [source,c] ---- -int mpo_check_system_reboot( cred, - howto); -struct ucred *cred; -int howto; +int mpo_check_system_reboot(struct ucred *cred, int howto); ---- [.informaltable] @@ -5618,8 +5241,7 @@ Determine whether the subject should be allowed to reboot the system in the spec [source,c] ---- -int mpo_check_system_settime( cred); -struct ucred *cred; +int mpo_check_system_settime(struct ucred *cred); ---- [.informaltable] @@ -5641,12 +5263,8 @@ Determine whether the user should be allowed to set the system clock. [source,c] ---- -int mpo_check_system_swapon( cred, - vp, - vlabel); -struct ucred *cred; -struct vnode *vp; -struct label *vlabel; +int mpo_check_system_swapon(struct ucred *cred, struct vnode *vp, + struct label *vlabel); ---- [.informaltable] @@ -5676,22 +5294,8 @@ Determine whether the subject should be allowed to add `vp` as a swap device. [source,c] ---- -int mpo_check_system_sysctl( cred, - name, - namelen, - old, - oldlenp, - inkernel, - new, - newlen); -struct ucred *cred; -int *name; -u_int *namelen; -void *old; -size_t *oldlenp; -int inkernel; -void *new; -size_t newlen; +int mpo_check_system_sysctl(struct ucred *cred, int *name, u_int *namelen, + void *old, size_t *oldlenp, int inkernel, void *new, size_t newlen); ---- [.informaltable] @@ -5739,36 +5343,56 @@ Determine whether the subject should be allowed to make the specified man:sysctl [[mac-label-management]] === Label Management Calls -Relabel events occur when a user process has requested that the label on an object be modified. A two-phase update occurs: first, an access control check will be performed to determine if the update is both valid and permitted, and then the update itself is performed via a separate entry point. Relabel entry points typically accept the object, object label reference, and an update label submitted by the process. Memory allocation during relabel is discouraged, as relabel calls are not permitted to fail (failure should be reported earlier in the relabel check). +Relabel events occur when a user process has requested that the label on an object be modified. +A two-phase update occurs: first, an access control check will be performed to determine if the update is both valid and permitted, and then the update itself is performed via a separate entry point. +Relabel entry points typically accept the object, object label reference, and an update label submitted by the process. +Memory allocation during relabel is discouraged, as relabel calls are not permitted to fail (failure should be reported earlier in the relabel check). [[mac-userland-arch]] == Userland Architecture -The TrustedBSD MAC Framework includes a number of policy-agnostic elements, including MAC library interfaces for abstractly managing labels, modifications to the system credential management and login libraries to support the assignment of MAC labels to users, and a set of tools to monitor and modify labels on processes, files, and network interfaces. More details on the user architecture will be added to this section in the near future. +The TrustedBSD MAC Framework includes a number of policy-agnostic elements, including MAC library interfaces for abstractly managing labels, modifications to the system credential management and login libraries to support the assignment of MAC labels to users, and a set of tools to monitor and modify labels on processes, files, and network interfaces. +More details on the user architecture will be added to this section in the near future. [[mac-userland-labels]] === APIs for Policy-Agnostic Label Management -The TrustedBSD MAC Framework provides a number of library and system calls permitting applications to manage MAC labels on objects using a policy-agnostic interface. This permits applications to manipulate labels for a variety of policies without being written to support specific policies. These interfaces are used by general-purpose tools such as man:ifconfig[8], man:ls[1] and man:ps[1] to view labels on network interfaces, files, and processes. The APIs also support MAC management tools including man:getfmac[8], man:getpmac[8], man:setfmac[8], man:setfsmac[8], and man:setpmac[8]. The MAC APIs are documented in man:mac[3]. +The TrustedBSD MAC Framework provides a number of library and system calls permitting applications to manage MAC labels on objects using a policy-agnostic interface. +This permits applications to manipulate labels for a variety of policies without being written to support specific policies. +These interfaces are used by general-purpose tools such as man:ifconfig[8], man:ls[1] and man:ps[1] to view labels on network interfaces, files, and processes. +The APIs also support MAC management tools including man:getfmac[8], man:getpmac[8], man:setfmac[8], man:setfsmac[8], and man:setpmac[8]. +The MAC APIs are documented in man:mac[3]. -Applications handle MAC labels in two forms: an internalized form used to return and set labels on processes and objects (`mac_t`), and externalized form based on C strings appropriate for storage in configuration files, display to the user, or input from the user. Each MAC label contains a number of elements, each consisting of a name and value pair. Policy modules in the kernel bind to specific names and interpret the values in policy-specific ways. In the externalized string form, labels are represented by a comma-delimited list of name and value pairs separated by the `/` character. Labels may be directly converted to and from text using provided APIs; when retrieving labels from the kernel, internalized label storage must first be prepared for the desired label element set. Typically, this is done in one of two ways: using man:mac_prepare[3] and an arbitrary list of desired label elements, or one of the variants of the call that loads a default element set from the man:mac.conf[5] configuration file. Per-object defaults permit application writers to usefully display labels associated with objects without being aware of the policies present in the system. +Applications handle MAC labels in two forms: an internalized form used to return and set labels on processes and objects (`mac_t`), and externalized form based on C strings appropriate for storage in configuration files, display to the user, or input from the user. +Each MAC label contains a number of elements, each consisting of a name and value pair. +Policy modules in the kernel bind to specific names and interpret the values in policy-specific ways. +In the externalized string form, labels are represented by a comma-delimited list of name and value pairs separated by the `/` character. +Labels may be directly converted to and from text using provided APIs; when retrieving labels from the kernel, internalized label storage must first be prepared for the desired label element set. +Typically, this is done in one of two ways: using man:mac_prepare[3] and an arbitrary list of desired label elements, or one of the variants of the call that loads a default element set from the man:mac.conf[5] configuration file. +Per-object defaults permit application writers to usefully display labels associated with objects without being aware of the policies present in the system. [NOTE] ==== -Currently, direct manipulation of label elements other than by conversion to a text string, string editing, and conversion back to an internalized label is not supported by the MAC library. Such interfaces may be added in the future if they prove necessary for application writers. +Currently, direct manipulation of label elements other than by conversion to a text string, string editing, and conversion back to an internalized label is not supported by the MAC library. +Such interfaces may be added in the future if they prove necessary for application writers. ==== [[mac-userland-credentials]] === Binding of Labels to Users -The standard user context management interface, man:setusercontext[3], has been modified to retrieve MAC labels associated with a user's class from man:login.conf[5]. These labels are then set along with other user context when either `LOGIN_SETALL` is specified, or when `LOGIN_SETMAC` is explicitly specified. +The standard user context management interface, man:setusercontext[3], has been modified to retrieve MAC labels associated with a user's class from man:login.conf[5]. +These labels are then set along with other user context when either `LOGIN_SETALL` is specified, or when `LOGIN_SETMAC` is explicitly specified. [NOTE] ==== -It is expected that, in a future version of FreeBSD, the MAC label database will be separated from the [.filename]#login.conf# user class abstraction, and be maintained in a separate database. However, the man:setusercontext[3] API should remain the same following such a change. +It is expected that, in a future version of FreeBSD, the MAC label database will be separated from the [.filename]#login.conf# user class abstraction, and be maintained in a separate database. +However, the man:setusercontext[3] API should remain the same following such a change. ==== [[mac-conclusion]] == Conclusion -The TrustedBSD MAC framework permits kernel modules to augment the system security policy in a highly integrated manner. They may do this based on existing object properties, or based on label data that is maintained with the assistance of the MAC framework. The framework is sufficiently flexible to implement a variety of policy types, including information flow security policies such as MLS and Biba, as well as policies based on existing BSD credentials or file protections. Policy authors may wish to consult this documentation as well as existing security modules when implementing a new security service. +The TrustedBSD MAC framework permits kernel modules to augment the system security policy in a highly integrated manner. +They may do this based on existing object properties, or based on label data that is maintained with the assistance of the MAC framework. +The framework is sufficiently flexible to implement a variety of policy types, including information flow security policies such as MLS and Biba, as well as policies based on existing BSD credentials or file protections. +Policy authors may wish to consult this documentation as well as existing security modules when implementing a new security service. diff --git a/documentation/content/en/books/arch-handbook/mac/_index.po b/documentation/content/en/books/arch-handbook/mac/_index.po new file mode 100644 index 0000000000..5686ee4026 --- /dev/null +++ b/documentation/content/en/books/arch-handbook/mac/_index.po @@ -0,0 +1,7422 @@ +# 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/mac/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:19 +#, no-wrap +msgid "The TrustedBSD MAC Framework" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1 +#, no-wrap +msgid "Chapter 6. The TrustedBSD MAC Framework" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:57 +#, no-wrap +msgid "MAC Documentation Copyright" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:60 +msgid "" +"This documentation was developed for the FreeBSD Project by Chris Costello " +"at Safeport Network Services and Network Associates Laboratories, the " +"Security Research Division of Network Associates, Inc. under DARPA/SPAWAR " +"contract N66001-01-C-8035 (\"CBOSS\"), as part of the DARPA CHATS research " +"program." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:62 +msgid "" +"Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, " +"HTML, PDF, PostScript, RTF and so forth) with or without modification, are " +"permitted provided that the following conditions are met:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:64 +msgid "" +"Redistributions of source code (SGML DocBook) must retain the above " +"copyright notice, this list of conditions and the following disclaimer as " +"the first lines of this file unmodified." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:65 +msgid "" +"Redistributions in compiled form (transformed to other DTDs, converted to " +"PDF, PostScript, RTF and other formats) must reproduce the above copyright " +"notice, this list of conditions and the following disclaimer in the " +"documentation and/or other materials provided with the distribution." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:70 +msgid "" +"THIS DOCUMENTATION IS PROVIDED BY THE NETWORKS ASSOCIATES TECHNOLOGY, INC " +"\"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED " +"TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR " +"PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NETWORKS ASSOCIATES TECHNOLOGY, " +"INC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR " +"CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF " +"SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS " +"INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN " +"CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) " +"ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF " +"THE POSSIBILITY OF SUCH DAMAGE." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:73 +#, no-wrap +msgid "Synopsis" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:78 +msgid "" +"FreeBSD includes experimental support for several mandatory access control " +"policies, as well as a framework for kernel security extensibility, the " +"TrustedBSD MAC Framework. The MAC Framework is a pluggable access control " +"framework, permitting new security policies to be easily linked into the " +"kernel, loaded at boot, or loaded dynamically at run-time. The framework " +"provides a variety of features to make it easier to implement new security " +"policies, including the ability to easily tag security labels (such as " +"confidentiality information) onto system objects." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:80 +msgid "" +"This chapter introduces the MAC policy framework and provides documentation " +"for a sample MAC policy module." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:82 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:88 +msgid "" +"The TrustedBSD MAC framework provides a mechanism to allow the compile-time " +"or run-time extension of the kernel access control model. New system " +"policies may be implemented as kernel modules and linked to the kernel; if " +"multiple policy modules are present, their results will be composed. The " +"MAC Framework provides a variety of access control infrastructure services " +"to assist policy writers, including support for transient and persistent " +"policy-agnostic object security labels. This support is currently " +"considered experimental." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:90 +msgid "" +"This chapter provides information appropriate for developers of policy " +"modules, as well as potential consumers of MAC-enabled environments, to " +"learn about how the MAC Framework supports access control extension of the " +"kernel." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:92 +#, no-wrap +msgid "Policy Background" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:99 +msgid "" +"Mandatory Access Control (MAC), refers to a set of access control policies " +"that are mandatorily enforced on users by the operating system. MAC " +"policies may be contrasted with Discretionary Access Control (DAC) " +"protections, by which non-administrative users may (at their discretion) " +"protect objects. In traditional UNIX systems, DAC protections include file " +"permissions and access control lists; MAC protections include process " +"controls preventing inter-user debugging and firewalls. A variety of MAC " +"policies have been formulated by operating system designers and security " +"researches, including the Multi-Level Security (MLS) confidentiality policy, " +"the Biba integrity policy, Role-Based Access Control (RBAC), Domain and Type " +"Enforcement (DTE), and Type Enforcement (TE). Each model bases decisions on " +"a variety of factors, including user identity, role, and security clearance, " +"as well as security labels on objects representing concepts such as data " +"sensitivity and integrity." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:102 +msgid "" +"The TrustedBSD MAC Framework is capable of supporting policy modules that " +"implement all of these policies, as well as a broad class of system " +"hardening policies, which may use existing security attributes, such as user " +"and group IDs, as well as extended attributes on files, and other system " +"properties. In addition, despite the name, the MAC Framework can also be " +"used to implement purely discretionary policies, as policy modules are given " +"substantial flexibility in how they authorize protections." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:104 +#, no-wrap +msgid "MAC Framework Kernel Architecture" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:108 +msgid "" +"The TrustedBSD MAC Framework permits kernel modules to extend the operating " +"system security policy, as well as providing infrastructure functionality " +"required by many access control modules. If multiple policies are " +"simultaneously loaded, the MAC Framework will usefully (for some definition " +"of useful) compose the results of the policies." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:110 +#, no-wrap +msgid "Kernel Elements" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:113 +msgid "The MAC Framework contains a number of kernel elements:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:115 +msgid "Framework management interfaces" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:116 +msgid "Concurrency and synchronization primitives." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:117 +msgid "Policy registration" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:118 +msgid "Extensible security label for kernel objects" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:119 +msgid "Policy entry point composition operators" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:120 +msgid "Label management primitives" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:121 +msgid "Entry point API invoked by kernel services" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:122 +msgid "Entry point API to policy modules" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:123 +msgid "" +"Entry points implementations (policy life cycle, object life cycle/label " +"management, access control checks)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:124 +msgid "Policy-agnostic label-management system calls" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:125 +msgid "`mac_syscall()` multiplex system call" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:126 +msgid "Various security policies implemented as MAC policy modules" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:128 +#, no-wrap +msgid "Framework Management Interfaces" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:131 +msgid "" +"The TrustedBSD MAC Framework may be directly managed using sysctl's, loader " +"tunables, and system calls." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:136 +msgid "" +"In most cases, sysctl's and loader tunables of the same name modify the same " +"parameters, and control behavior such as enforcement of protections relating " +"to various kernel subsystems. In addition, if MAC debugging support is " +"compiled into the kernel, several counters will be maintained tracking label " +"allocation. It is generally advisable that per-subsystem enforcement " +"controls not be used to control policy behavior in production environments, " +"as they broadly impact the operation of all active policies. Instead, per-" +"policy controls should be preferred, as they provide greater granularity and " +"greater operational consistency for policy modules." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:138 +msgid "" +"Loading and unloading of policy modules is performed using the system module " +"management system calls and other system interfaces, including boot loader " +"variables; policy modules will have the opportunity to influence load and " +"unload events, including preventing undesired unloading of the policy." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:140 +#, no-wrap +msgid "Policy List Concurrency and Synchronization" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:147 +msgid "" +"As the set of active policies may change at run-time, and the invocation of " +"entry points is non-atomic, synchronization is required to prevent loading " +"or unloading of policies while an entry point invocation is in progress, " +"freezing the set of active policies for the duration. This is accomplished " +"by means of a framework busy count: whenever an entry point is entered, the " +"busy count is incremented; whenever it is exited, the busy count is " +"decremented. While the busy count is elevated, policy list changes are not " +"permitted, and threads attempting to modify the policy list will sleep until " +"the list is not busy. The busy count is protected by a mutex, and a " +"condition variable is used to wake up sleepers waiting on policy list " +"modifications. One side effect of this synchronization model is that " +"recursion into the MAC Framework from within a policy module is permitted, " +"although not generally used." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:150 +msgid "" +"Various optimizations are used to reduce the overhead of the busy count, " +"including avoiding the full cost of incrementing and decrementing if the " +"list is empty or contains only static entries (policies that are loaded " +"before the system starts, and cannot be unloaded). A compile-time option is " +"also provided which prevents any change in the set of loaded policies at run-" +"time, which eliminates the mutex locking costs associated with supporting " +"dynamically loaded and unloaded policies as synchronization is no longer " +"required." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:152 +msgid "" +"As the MAC Framework is not permitted to block in some entry points, a " +"normal sleep lock cannot be used; as a result, it is possible for the load " +"or unload attempt to block for a substantial period of time waiting for the " +"framework to become idle." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:154 +#, no-wrap +msgid "Label Synchronization" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:161 +msgid "" +"As kernel objects of interest may generally be accessed from more than one " +"thread at a time, and simultaneous entry of more than one thread into the " +"MAC Framework is permitted, security attribute storage maintained by the MAC " +"Framework is carefully synchronized. In general, existing kernel " +"synchronization on kernel object data is used to protect MAC Framework " +"security labels on the object: for example, MAC labels on sockets are " +"protected using the existing socket mutex. Likewise, semantics for " +"concurrent access are generally identical to those of the container objects: " +"for credentials, copy-on-write semantics are maintained for label contents " +"as with the remainder of the credential structure. The MAC Framework " +"asserts necessary locks on objects when invoked with an object reference. " +"Policy authors must be aware of these synchronization semantics, as they " +"will sometimes limit the types of accesses permitted on labels: for example, " +"when a read-only reference to a credential is passed to a policy via an " +"entry point, only read operations are permitted on the label state attached " +"to the credential." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:163 +#, no-wrap +msgid "Policy Synchronization and Concurrency" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:169 +msgid "" +"Policy modules must be written to assume that many kernel threads may " +"simultaneously enter one more policy entry points due to the parallel and " +"preemptive nature of the FreeBSD kernel. If the policy module makes use of " +"mutable state, this may require the use of synchronization primitives within " +"the policy to prevent inconsistent views on that state resulting in " +"incorrect operation of the policy. Policies will generally be able to make " +"use of existing FreeBSD synchronization primitives for this purpose, " +"including mutexes, sleep locks, condition variables, and counting " +"semaphores. However, policies should be written to employ these primitives " +"carefully, respecting existing kernel lock orders, and recognizing that some " +"entry points are not permitted to sleep, limiting the use of primitives in " +"those entry points to mutexes and wakeup operations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:172 +msgid "" +"When policy modules call out to other kernel subsystems, they will generally " +"need to release any in-policy locks in order to avoid violating the kernel " +"lock order or risking lock recursion. This will maintain policy locks as " +"leaf locks in the global lock order, helping to avoid deadlock." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:174 +#, no-wrap +msgid "Policy Registration" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:181 +msgid "" +"The MAC Framework maintains two lists of active policies: a static list, and " +"a dynamic list. The lists differ only with regards to their locking " +"semantics: an elevated reference count is not required to make use of the " +"static list. When kernel modules containing MAC Framework policies are " +"loaded, the policy module will use `SYSINIT` to invoke a registration " +"function; when a policy module is unloaded, `SYSINIT` will likewise invoke a " +"de-registration function. Registration may fail if a policy module is " +"loaded more than once, if insufficient resources are available for the " +"registration (for example, the policy might require labeling and " +"insufficient labeling state might be available), or other policy " +"prerequisites might not be met (some policies may only be loaded prior to " +"boot). Likewise, de-registration may fail if a policy is flagged as not " +"unloadable." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:183 +#, no-wrap +msgid "Entry Points" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:190 +msgid "" +"Kernel services interact with the MAC Framework in two ways: they invoke a " +"series of APIs to notify the framework of relevant events, and they provide " +"a policy-agnostic label structure pointer in security-relevant objects. The " +"label pointer is maintained by the MAC Framework via label management entry " +"points, and permits the Framework to offer a labeling service to policy " +"modules through relatively non-invasive changes to the kernel subsystem " +"maintaining the object. For example, label pointers have been added to " +"processes, process credentials, sockets, pipes, vnodes, Mbufs, network " +"interfaces, IP reassembly queues, and a variety of other security-relevant " +"structures. Kernel services also invoke the MAC Framework when they perform " +"important security decisions, permitting policy modules to augment those " +"decisions based on their own criteria (possibly including data stored in " +"security labels). Most of these security critical decisions will be " +"explicit access control checks; however, some affect more general decision " +"functions such as packet matching for sockets and label transition at " +"program execution." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:192 +#, no-wrap +msgid "Policy Composition" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:200 +msgid "" +"When more than one policy module is loaded into the kernel at a time, the " +"results of the policy modules will be composed by the framework using a " +"composition operator. This operator is currently hard-coded, and requires " +"that all active policies must approve a request for it to return success. " +"As policies may return a variety of error conditions (success, access " +"denied, object does not exist, ...), a precedence operator selects the " +"resulting error from the set of errors returned by policies. In general, " +"errors indicating that an object does not exist will be preferred to errors " +"indicating that access to an object is denied. While it is not guaranteed " +"that the resulting composition will be useful or secure, we have found that " +"it is for many useful selections of policies. For example, traditional " +"trusted systems often ship with two or more policies using a similar " +"composition." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:202 +#, no-wrap +msgid "Labeling Support" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:208 +msgid "" +"As many interesting access control extensions rely on security labels on " +"objects, the MAC Framework provides a set of policy-agnostic label " +"management system calls covering a variety of user-exposed objects. Common " +"label types include partition identifiers, sensitivity labels, integrity " +"labels, compartments, domains, roles, and types. By policy agnostic, we " +"mean that policy modules are able to completely define the semantics of meta-" +"data associated with an object. Policy modules participate in the " +"internalization and externalization of string-based labels provides by user " +"applications, and can expose multiple label elements to applications if " +"desired." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:216 +msgid "" +"In-memory labels are stored in slab-allocated `struct label`, which consists " +"of a fixed-length array of unions, each holding a `void *` pointer and a " +"`long`. Policies registering for label storage will be assigned a \"slot\" " +"identifier, which may be used to dereference the label storage. The " +"semantics of the storage are left entirely up to the policy module: modules " +"are provided with a variety of entry points associated with the kernel " +"object life cycle, including initialization, association/creation, and " +"destruction. Using these interfaces, it is possible to implement reference " +"counting and other storage models. Direct access to the object structure is " +"generally not required by policy modules to retrieve a label, as the MAC " +"Framework generally passes both a pointer to the object and a direct pointer " +"to the object's label into entry points. The primary exception to this rule " +"is the process credential, which must be manually dereferenced to access the " +"credential label. This may change in future revisions of the MAC Framework." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:223 +msgid "" +"Initialization entry points frequently include a sleeping disposition flag " +"indicating whether or not an initialization is permitted to sleep; if " +"sleeping is not permitted, a failure may be returned to cancel allocation of " +"the label (and hence object). This may occur, for example, in the network " +"stack during interrupt handling, where sleeping is not permitted, or while " +"the caller holds a mutex. Due to the performance cost of maintaining labels " +"on in-flight network packets (Mbufs), policies must specifically declare a " +"requirement that Mbuf labels be allocated. Dynamically loaded policies " +"making use of labels must be able to handle the case where their init " +"function has not been called on an object, as objects may already exist when " +"the policy is loaded. The MAC Framework guarantees that uninitialized label " +"slots will hold a 0 or NULL value, which policies may use to detect " +"uninitialized values. However, as allocation of Mbuf labels is conditional, " +"policies must also be able to handle a NULL label pointer for Mbufs if they " +"have been loaded dynamically." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:229 +msgid "" +"In the case of file system labels, special support is provided for the " +"persistent storage of security labels in extended attributes. Where " +"available, extended attribute transactions are used to permit consistent " +"compound updates of security labels on vnodes--currently this support is " +"present only in the UFS2 file system. Policy authors may choose to " +"implement multilabel file system object labels using one (or more) extended " +"attributes. For efficiency reasons, the vnode label (`v_label`) is a cache " +"of any on-disk label; policies are able to load values into the cache when " +"the vnode is instantiated, and update the cache as needed. As a result, the " +"extended attribute need not be directly accessed with every access control " +"check." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:233 +msgid "" +"Currently, if a labeled policy permits dynamic unloading, its state slot " +"cannot be reclaimed, which places a strict (and relatively low) bound on the " +"number of unload-reload operations for labeled policies." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:236 +#, no-wrap +msgid "System Calls" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:239 +msgid "" +"The MAC Framework implements a number of system calls: most of these calls " +"support the policy-agnostic label retrieval and manipulation APIs exposed to " +"user applications." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:245 +msgid "" +"The label management calls accept a label description structure, `struct " +"mac`, which contains a series of MAC label elements. Each element contains " +"a character string name, and character string value. Each policy will be " +"given the chance to claim a particular element name, permitting policies to " +"expose multiple independent elements if desired. Policy modules perform the " +"internalization and externalization between kernel labels and user-provided " +"labels via entry points, permitting a variety of semantics. Label " +"management system calls are generally wrapped by user library functions to " +"perform memory allocation and error handling, simplifying user applications " +"that must manage labels." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:247 +msgid "" +"The following MAC-related system calls are present in the FreeBSD kernel:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:249 +msgid "" +"`mac_get_proc()` may be used to retrieve the label of the current process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:250 +msgid "" +"`mac_set_proc()` may be used to request a change in the label of the current " +"process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:251 +msgid "" +"`mac_get_fd()` may be used to retrieve the label of an object (file, socket, " +"pipe, ...) referenced by a file descriptor." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:252 +msgid "" +"`mac_get_file()` may be used to retrieve the label of an object referenced " +"by a file system path." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:253 +msgid "" +"`mac_set_fd()` may be used to request a change in the label of an object " +"(file, socket, pipe, ...) referenced by a file descriptor." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:254 +msgid "" +"`mac_set_file()` may be used to request a change in the label of an object " +"referenced by a file system path." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:255 +msgid "" +"`mac_syscall()` permits policy modules to create new system calls without " +"modifying the system call table; it accepts a target policy name, operation " +"number, and opaque argument for use by the policy." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:256 +msgid "" +"`mac_get_pid()` may be used to request the label of another process by " +"process id." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:257 +msgid "" +"`mac_get_link()` is identical to `mac_get_file()`, only it will not follow a " +"symbolic link if it is the final entry in the path, so may be used to " +"retrieve the label on a symlink." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:258 +msgid "" +"`mac_set_link()` is identical to `mac_set_file()`, only it will not follow a " +"symbolic link if it is the final entry in a path, so may be used to " +"manipulate the label on a symlink." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:260 +msgid "" +"`mac_execve()` is identical to the `execve()` system call, only it also " +"accepts a requested label to set the process label to when beginning " +"execution of a new program. This change in label on execution is referred " +"to as a \"transition\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:261 +msgid "" +"`mac_get_peer()`, actually implemented via a socket option, retrieves the " +"label of a remote peer on a socket, if available." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:263 +msgid "" +"In addition to these system calls, the `SIOCSIGMAC` and `SIOCSIFMAC` network " +"interface ioctls permit the labels on network interfaces to be retrieved and " +"set." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:265 +#, no-wrap +msgid "MAC Policy Architecture" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:270 +msgid "" +"Security policies are either linked directly into the kernel, or compiled " +"into loadable kernel modules that may be loaded at boot, or dynamically " +"using the module loading system calls at runtime. Policy modules interact " +"with the system through a set of declared entry points, providing access to " +"a stream of system events and permitting the policy to influence access " +"control decisions. Each policy contains a number of elements:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:272 +msgid "Optional configuration parameters for policy." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:273 +msgid "Centralized implementation of the policy logic and parameters." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:274 +msgid "" +"Optional implementation of policy life cycle events, such as initialization " +"and destruction." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:275 +msgid "" +"Optional support for initializing, maintaining, and destroying labels on " +"selected kernel objects." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:276 +msgid "" +"Optional support for user process inspection and modification of labels on " +"selected objects." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:277 +msgid "" +"Implementation of selected access control entry points that are of interest " +"to the policy." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:278 +msgid "" +"Declaration of policy identity, module entry points, and policy properties." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:280 +#, no-wrap +msgid "Policy Declaration" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:283 +msgid "" +"Modules may be declared using the `MAC_POLICY_SET()` macro, which names the " +"policy, provides a reference to the MAC entry point vector, provides load-" +"time flags determining how the policy framework should handle the policy, " +"and optionally requests the allocation of label state by the framework." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:297 +#, no-wrap +msgid "" +"static struct mac_policy_ops mac_policy_ops =\n" +"{\n" +" .mpo_destroy = mac_policy_destroy,\n" +" .mpo_init = mac_policy_init,\n" +" .mpo_init_bpfdesc_label = mac_policy_init_bpfdesc_label,\n" +" .mpo_init_cred_label = mac_policy_init_label,\n" +"/* ... */\n" +" .mpo_check_vnode_setutimes = mac_policy_check_vnode_setutimes,\n" +" .mpo_check_vnode_stat = mac_policy_check_vnode_stat,\n" +" .mpo_check_vnode_write = mac_policy_check_vnode_write,\n" +"};\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:302 +msgid "" +"The MAC policy entry point vector, `mac__policy__ops` in this example, " +"associates functions defined in the module with specific entry points. A " +"complete listing of available entry points and their prototypes may be found " +"in the MAC entry point reference section. Of specific interest during " +"module registration are the .mpo_destroy and .mpo_init entry points." +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:302 +#, no-wrap +msgid "mpo_init will be invoked once a policy is successfully registered with the module framework but prior to any other entry points becoming active." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:304 +msgid "" +"This permits the policy to perform any policy-specific allocation and " +"initialization, such as initialization of any data or locks." +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:304 +#, no-wrap +msgid "mpo_destroy will be invoked when a policy module is unloaded to permit releasing of any allocated memory and destruction of locks." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:306 +msgid "" +"Currently, these two entry points are invoked with the MAC policy list mutex " +"held to prevent any other entry points from being invoked: this will be " +"changed, but in the mean time, policies should be careful about what kernel " +"primitives they invoke so as to avoid lock ordering or sleeping problems." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:310 +msgid "" +"The policy declaration's module name field exists so that the module may be " +"uniquely identified for the purposes of module dependencies. An appropriate " +"string should be selected. The full string name of the policy is displayed " +"to the user via the kernel log during load and unload events, and also " +"exported when providing status information to userland processes." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:312 +#, no-wrap +msgid "Policy Flags" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:316 +msgid "" +"The policy declaration flags field permits the module to provide the " +"framework with information about its capabilities at the time the module is " +"loaded. Currently, three flags are defined:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:317 +#, no-wrap +msgid "MPC_LOADTIME_FLAG_UNLOADOK" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:321 +msgid "" +"This flag indicates that the policy module may be unloaded. If this flag is " +"not provided, then the policy framework will reject requests to unload the " +"module. This flag might be used by modules that allocate label state and " +"are unable to free that state at runtime." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:322 +#, no-wrap +msgid "MPC_LOADTIME_FLAG_NOTLATE" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:326 +msgid "" +"This flag indicates that the policy module must be loaded and initialized " +"early in the boot process. If the flag is specified, attempts to register " +"the module following boot will be rejected. The flag may be used by " +"policies that require pervasive labeling of all system objects, and cannot " +"handle objects that have not been properly initialized by the policy." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:327 +#, no-wrap +msgid "MPC_LOADTIME_FLAG_LABELMBUFS" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:332 +msgid "" +"This flag indicates that the policy module requires labeling of Mbufs, and " +"that memory should always be allocated for the storage of Mbuf labels. By " +"default, the MAC Framework will not allocate label storage for Mbufs unless " +"at least one loaded policy has this flag set. This measurably improves " +"network performance when policies do not require Mbuf labeling. A kernel " +"option, `MAC_ALWAYS_LABEL_MBUF`, exists to force the MAC Framework to " +"allocate Mbuf label storage regardless of the setting of this flag, and may " +"be useful in some environments." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:338 +msgid "" +"Policies using the `MPC_LOADTIME_FLAG_LABELMBUFS` without the " +"`MPC_LOADTIME_FLAG_NOTLATE` flag set must be able to correctly handle `NULL` " +"Mbuf label pointers passed into entry points. This is necessary as in-" +"flight Mbufs without label storage may persist after a policy enabling Mbuf " +"labeling has been loaded. If a policy is loaded before the network " +"subsystem is active (i.e., the policy is not being loaded late), then all " +"Mbufs are guaranteed to have label storage." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:341 +#, no-wrap +msgid "Policy Entry Points" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:345 +msgid "" +"Four classes of entry points are offered to policies registered with the " +"framework: entry points associated with the registration and management of " +"policies, entry points denoting initialization, creation, destruction, and " +"other life cycle events for kernel objects, events associated with access " +"control decisions that the policy module may influence, and calls associated " +"with the management of labels on objects. In addition, a `mac_syscall()` " +"entry point is provided so that policies may extend the kernel interface " +"without registering new system calls." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:350 +msgid "" +"Policy module writers should be aware of the kernel locking strategy, as " +"well as what object locks are available during which entry points. Writers " +"should attempt to avoid deadlock scenarios by avoiding grabbing non-leaf " +"locks inside of entry points, and also follow the locking protocol for " +"object access and modification. In particular, writers should be aware that " +"while necessary locks to access objects and their labels are generally held, " +"sufficient locks to modify an object or its label may not be present for all " +"entry points. Locking information for arguments is documented in the MAC " +"framework entry point document." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:354 +msgid "" +"Policy entry points will pass a reference to the object label along with the " +"object itself. This permits labeled policies to be unaware of the internals " +"of the object yet still make decisions based on the label. The exception to " +"this is the process credential, which is assumed to be understood by " +"policies as a first class security object in the kernel." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:356 +#, no-wrap +msgid "MAC Policy Entry Point Reference" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:359 +#, no-wrap +msgid "General-Purpose Module Entry Points" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:362 +#, no-wrap +msgid "`mpo_init`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:367 +#, no-wrap +msgid "void mpo_init(struct mac_policy_conf *conf);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:373 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:397 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:420 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:458 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:487 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:510 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:533 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:556 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:579 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:608 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:637 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:664 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:687 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:710 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:737 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:764 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:787 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:810 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:833 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:856 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:879 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:902 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:925 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:948 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:971 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:998 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1021 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1044 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1067 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1090 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1113 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1139 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1165 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1192 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1232 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1272 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1312 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1352 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1392 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1432 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1469 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1506 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1543 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1580 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1665 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1708 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1746 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1781 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1813 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1846 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1890 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1943 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1979 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2001 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2036 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2072 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2112 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2148 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2180 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2213 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2248 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2283 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2318 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2355 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2394 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2425 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2453 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2488 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2523 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2558 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2594 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2630 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2666 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2702 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2746 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2782 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2820 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2855 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2892 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2922 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2960 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2992 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3014 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3036 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3096 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3131 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3153 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3179 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3205 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3232 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3262 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3284 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3307 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3346 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3377 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3408 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3443 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3474 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3505 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3538 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3575 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3606 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3636 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3666 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3695 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3730 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3764 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3791 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3826 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3859 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3889 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3927 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3960 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3991 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4034 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4081 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4118 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4152 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4189 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4236 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4279 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4314 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4349 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4380 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4416 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4460 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4508 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4541 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4578 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4615 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4648 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4682 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4715 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4756 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4804 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4841 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4878 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4920 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4960 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4990 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5023 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5058 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5099 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5140 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5173 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5203 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5225 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5251 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5274 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5305 +#, no-wrap +msgid "Parameter" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:374 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:398 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:421 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:459 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:488 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:511 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:534 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:557 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:580 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:609 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:638 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:665 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:688 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:711 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:738 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:765 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:788 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:811 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:834 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:857 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:880 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:903 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:926 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:949 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:972 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:999 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1022 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1045 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1068 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1091 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1114 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1140 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1166 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1193 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1233 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1273 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1313 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1353 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1393 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1433 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1470 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1507 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1544 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1581 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1666 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1709 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1747 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1782 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1814 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1847 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1891 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1944 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1980 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2002 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2037 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2073 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2113 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2149 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2181 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2214 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2249 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2284 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2319 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2356 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2395 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2426 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2454 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2489 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2524 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2559 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2595 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2631 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2667 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2703 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2747 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2783 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2821 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2856 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2893 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2923 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2961 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2993 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3015 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3037 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3097 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3132 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3154 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3180 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3206 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3233 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3263 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3285 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3308 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3347 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3378 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3409 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3444 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3475 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3506 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3539 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3576 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3607 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3637 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3667 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3696 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3731 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3765 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3792 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3827 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3860 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3890 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3928 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3961 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3992 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4035 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4082 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4119 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4153 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4190 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4237 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4280 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4315 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4350 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4381 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4417 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4461 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4509 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4542 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4579 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4616 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4649 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4683 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4716 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4757 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4805 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4842 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4879 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4921 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4961 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4991 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5024 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5059 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5100 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5141 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5174 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5204 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5226 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5252 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5275 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5306 +#, no-wrap +msgid "Description" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:376 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:400 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:423 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:461 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:490 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:513 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:536 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:559 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:582 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:611 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:640 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:667 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:690 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:713 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:740 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:767 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:790 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:813 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:836 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:859 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:882 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:905 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:928 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:951 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:974 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1001 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1024 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1047 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1070 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1093 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1116 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1142 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1168 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1195 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1235 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1275 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1315 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1355 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1395 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1435 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1472 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1509 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1546 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1583 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1668 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1711 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1749 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1784 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1816 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1849 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1893 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1946 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1982 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2004 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2039 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2075 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2115 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2151 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2183 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2216 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2251 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2286 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2321 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2358 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2397 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2428 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2456 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2491 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2526 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2561 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2597 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2633 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2669 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2705 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2749 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2785 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2823 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2858 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2895 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2925 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2963 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2995 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3017 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3039 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3099 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3134 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3156 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3182 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3208 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3235 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3265 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3287 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3310 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3349 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3380 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3411 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3446 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3477 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3508 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3541 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3578 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3609 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3639 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3669 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3698 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3733 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3767 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3794 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3829 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3862 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3892 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3930 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3963 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3994 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4037 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4084 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4121 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4155 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4192 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4239 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4282 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4317 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4352 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4383 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4419 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4463 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4511 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4544 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4581 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4618 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4651 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4685 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4718 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4759 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4807 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4844 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4881 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4923 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4963 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4993 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5026 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5061 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5102 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5143 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5176 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5206 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5228 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5254 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5277 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5308 +#, no-wrap +msgid "Locking" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:377 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:401 +#, no-wrap +msgid "`conf`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:378 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:402 +#, no-wrap +msgid "MAC policy definition" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:384 +msgid "" +"Policy load event. The policy list mutex is held, so sleep operations " +"cannot be performed, and calls out to other kernel subsystems must be made " +"with caution. If potentially sleeping memory allocations are required " +"during policy initialization, they should be made using a separate module " +"SYSINIT()." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:386 +#, no-wrap +msgid "`mpo_destroy`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:391 +#, no-wrap +msgid "void mpo_destroy(struct mac_policy_conf *conf);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:407 +msgid "" +"Policy load event. The policy list mutex is held, so caution should be " +"applied." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:409 +#, no-wrap +msgid "`mpo_syscall`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:414 +#, no-wrap +msgid "int mpo_syscall(struct thread *td, int call, void *arg);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:424 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:462 +#, no-wrap +msgid "`td`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:425 +#, no-wrap +msgid "Calling thread" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:428 +#, no-wrap +msgid "`call`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:429 +#, no-wrap +msgid "Policy-specific syscall number" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:432 +#, no-wrap +msgid "`arg`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:433 +#, no-wrap +msgid "Pointer to syscall arguments" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:440 +msgid "" +"This entry point provides a policy-multiplexed system call so that policies " +"may provide additional services to user processes without registering " +"specific system calls. The policy name provided during registration is used " +"to demultiplexer calls from userland, and the arguments will be forwarded to " +"this entry point. When implementing new services, security modules should " +"be sure to invoke appropriate access control checks from the MAC framework " +"as needed. For example, if a policy implements an augmented signal " +"functionality, it should call the necessary signal access control checks to " +"invoke the MAC framework and other registered policies." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:444 +msgid "" +"Modules must currently perform the `copyin()` of the syscall data on their " +"own." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:447 +#, no-wrap +msgid "`mpo_thread_userret`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:452 +#, no-wrap +msgid "void mpo_thread_userret(struct thread *td);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:463 +#, no-wrap +msgid "Returning thread" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:471 +msgid "" +"This entry point permits policy modules to perform MAC-related events when a " +"thread returns to user space, via a system call return, trap return, or " +"otherwise. This is required for policies that have floating process labels, " +"as it is not always possible to acquire the process lock at arbitrary points " +"in the stack during system call processing; process labels might represent " +"traditional authentication data, process history information, or other " +"data. To employ this mechanism, intended changes to the process credential " +"label may be stored in the `p_label` protected by a per-policy spin lock, " +"and then set the per-thread `TDF_ASTPENDING` flag and per-process " +"`PS_MACPENDM` flag to schedule a call to the `userret` entry point. From " +"this entry point, the policy may create a replacement credential with less " +"concern about the locking context. Policy writers are cautioned that event " +"ordering relating to scheduling an AST and the AST being performed may be " +"complex and interlaced in multithreaded applications." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:473 +#, no-wrap +msgid "Label Operations" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:476 +#, no-wrap +msgid "`mpo_init_bpfdesc_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:481 +#, no-wrap +msgid "void mpo_init_bpfdesc_label(struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:491 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:514 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:537 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:560 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:583 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:616 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:668 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:691 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:714 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:741 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:768 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:791 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:814 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:837 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:860 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:883 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:906 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:929 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:952 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1002 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1048 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1071 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1094 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1196 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1236 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1276 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1316 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1356 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1396 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1436 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1473 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1510 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1547 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1584 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1793 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1902 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3901 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4054 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4093 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4130 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4164 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4201 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4256 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4291 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4326 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4396 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4436 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4480 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4590 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4660 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4694 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4727 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4768 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4816 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4853 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4890 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4932 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5035 +#, no-wrap +msgid "`label`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:492 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:538 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:561 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:584 +#, no-wrap +msgid "New label to apply" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:497 +msgid "" +"Initialize the label on a newly instantiated bpfdesc (BPF descriptor). " +"Sleeping is permitted." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:499 +#, no-wrap +msgid "`mpo_init_cred_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:504 +#, no-wrap +msgid "void mpo_init_cred_label(struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:515 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:715 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:742 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:769 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:792 +#, no-wrap +msgid "New label to initialize" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:520 +msgid "" +"Initialize the label for a newly instantiated user credential. Sleeping is " +"permitted." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:522 +#, no-wrap +msgid "`mpo_init_devfsdirent_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:527 +#, no-wrap +msgid "void mpo_init_devfsdirent_label(struct label *label);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:543 +msgid "" +"Initialize the label on a newly instantiated devfs entry. Sleeping is " +"permitted." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:545 +#, no-wrap +msgid "`mpo_init_ifnet_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:550 +#, no-wrap +msgid "void mpo_init_ifnet_label(struct label *label);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:566 +msgid "" +"Initialize the label on a newly instantiated network interface. Sleeping is " +"permitted." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:568 +#, no-wrap +msgid "`mpo_init_ipq_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:573 +#, no-wrap +msgid "void mpo_init_ipq_label(struct label *label, int flag);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:587 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:612 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:718 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:745 +#, no-wrap +msgid "`flag`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:588 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:613 +#, no-wrap +msgid "Sleeping/non-sleeping man:malloc[9]; see below" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:595 +msgid "" +"Initialize the label on a newly instantiated IP fragment reassembly queue. " +"The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed " +"to avoid performing a sleeping man:malloc[9] during this initialization " +"call. IP fragment reassembly queue allocation frequently occurs in " +"performance sensitive environments, and the implementation should be careful " +"to avoid sleeping or long-lived operations. This entry point is permitted " +"to fail resulting in the failure to allocate the IP fragment reassembly " +"queue." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:597 +#, no-wrap +msgid "`mpo_init_mbuf_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:602 +#, no-wrap +msgid "void mpo_init_mbuf_label(int flag, struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:617 +#, no-wrap +msgid "Policy label to initialize" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:624 +msgid "" +"Initialize the label on a newly instantiated mbuf packet header (`mbuf`). " +"The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed " +"to avoid performing a sleeping man:malloc[9] during this initialization " +"call. Mbuf allocation frequently occurs in performance sensitive " +"environments, and the implementation should be careful to avoid sleeping or " +"long-lived operations. This entry point is permitted to fail resulting in " +"the failure to allocate the mbuf header." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:626 +#, no-wrap +msgid "`mpo_init_mount_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:631 +#, no-wrap +msgid "void mpo_init_mount_label(struct label *mntlabel, struct label *fslabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:641 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:975 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1955 +#, no-wrap +msgid "`mntlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:642 +#, no-wrap +msgid "Policy label to be initialized for the mount itself" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:645 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:979 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1673 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1716 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1754 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1959 +#, no-wrap +msgid "`fslabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:646 +#, no-wrap +msgid "Policy label to be initialized for the file system" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:651 +msgid "" +"Initialize the labels on a newly instantiated mount point. Sleeping is " +"permitted." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:653 +#, no-wrap +msgid "`mpo_init_mount_fs_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:658 +#, no-wrap +msgid "void mpo_init_mount_fs_label(struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:669 +#, no-wrap +msgid "Label to be initialized" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:674 +msgid "" +"Initialize the label on a newly mounted file system. Sleeping is permitted" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:676 +#, no-wrap +msgid "`mpo_init_pipe_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:681 +#, no-wrap +msgid "void mpo_init_pipe_label(struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:692 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1437 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1474 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1511 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1548 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1585 +#, no-wrap +msgid "Label to be filled in" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:697 +msgid "" +"Initialize a label for a newly instantiated pipe. Sleeping is permitted." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:699 +#, no-wrap +msgid "`mpo_init_socket_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:704 +#, no-wrap +msgid "void mpo_init_socket_label(struct label *label, int flag);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:719 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:746 +#, no-wrap +msgid "man:malloc[9] flags" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:724 +msgid "" +"Initialize a label for a newly instantiated socket. The `flag` field may be " +"one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a " +"sleeping man:malloc[9] during this initialization call." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:726 +#, no-wrap +msgid "`mpo_init_socket_peer_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:731 +#, no-wrap +msgid "void mpo_init_socket_peer_label(struct label *label, int flag);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:751 +msgid "" +"Initialize the peer label for a newly instantiated socket. The `flag` field " +"may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid " +"performing a sleeping man:malloc[9] during this initialization call." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:753 +#, no-wrap +msgid "`mpo_init_proc_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:758 +#, no-wrap +msgid "void mpo_init_proc_label(struct label *label);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:774 +msgid "" +"Initialize the label for a newly instantiated process. Sleeping is " +"permitted." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:776 +#, no-wrap +msgid "`mpo_init_vnode_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:781 +#, no-wrap +msgid "void mpo_init_vnode_label(struct label *label);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:797 +msgid "" +"Initialize the label on a newly instantiated vnode. Sleeping is permitted." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:799 +#, no-wrap +msgid "`mpo_destroy_bpfdesc_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:804 +#, no-wrap +msgid "void mpo_destroy_bpfdesc_label(struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:815 +#, no-wrap +msgid "bpfdesc label" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:820 +msgid "" +"Destroy the label on a BPF descriptor. In this entry point a policy should " +"free any internal storage associated with `label` so that it may be " +"destroyed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:822 +#, no-wrap +msgid "`mpo_destroy_cred_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:827 +#, no-wrap +msgid "void mpo_destroy_cred_label(struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:838 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:861 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:884 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:907 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:930 +#, no-wrap +msgid "Label being destroyed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:843 +msgid "" +"Destroy the label on a credential. In this entry point, a policy module " +"should free any internal storage associated with `label` so that it may be " +"destroyed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:845 +#, no-wrap +msgid "`mpo_destroy_devfsdirent_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:850 +#, no-wrap +msgid "void mpo_destroy_devfsdirent_label(struct label *label);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:866 +msgid "" +"Destroy the label on a devfs entry. In this entry point, a policy module " +"should free any internal storage associated with `label` so that it may be " +"destroyed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:868 +#, no-wrap +msgid "`mpo_destroy_ifnet_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:873 +#, no-wrap +msgid "void mpo_destroy_ifnet_label(struct label *label);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:889 +msgid "" +"Destroy the label on a removed interface. In this entry point, a policy " +"module should free any internal storage associated with `label` so that it " +"may be destroyed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:891 +#, no-wrap +msgid "`mpo_destroy_ipq_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:896 +#, no-wrap +msgid "void mpo_destroy_ipq_label(struct label *label);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:912 +msgid "" +"Destroy the label on an IP fragment queue. In this entry point, a policy " +"module should free any internal storage associated with `label` so that it " +"may be destroyed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:914 +#, no-wrap +msgid "`mpo_destroy_mbuf_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:919 +#, no-wrap +msgid "void mpo_destroy_mbuf_label(struct label *label);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:935 +msgid "" +"Destroy the label on an mbuf header. In this entry point, a policy module " +"should free any internal storage associated with `label` so that it may be " +"destroyed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:937 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:960 +#, no-wrap +msgid "`mpo_destroy_mount_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:942 +#, no-wrap +msgid "void mpo_destroy_mount_label(struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:953 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:976 +#, no-wrap +msgid "Mount point label being destroyed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:958 +msgid "" +"Destroy the labels on a mount point. In this entry point, a policy module " +"should free the internal storage associated with `mntlabel` so that they may " +"be destroyed." +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:965 +#, no-wrap +msgid "void mpo_destroy_mount_label(struct label *mntlabel, struct label *fslabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:980 +#, no-wrap +msgid "File system label being destroyed>" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:985 +msgid "" +"Destroy the labels on a mount point. In this entry point, a policy module " +"should free the internal storage associated with `mntlabel` and `fslabel` so " +"that they may be destroyed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:987 +#, no-wrap +msgid "`mpo_destroy_socket_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:992 +#, no-wrap +msgid "void mpo_destroy_socket_label(struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1003 +#, no-wrap +msgid "Socket label being destroyed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1008 +msgid "" +"Destroy the label on a socket. In this entry point, a policy module should " +"free any internal storage associated with `label` so that it may be " +"destroyed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1010 +#, no-wrap +msgid "`mpo_destroy_socket_peer_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1015 +#, no-wrap +msgid "void mpo_destroy_socket_peer_label(struct label *peerlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1025 +#, no-wrap +msgid "`peerlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1026 +#, no-wrap +msgid "Socket peer label being destroyed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1031 +msgid "" +"Destroy the peer label on a socket. In this entry point, a policy module " +"should free any internal storage associated with `label` so that it may be " +"destroyed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1033 +#, no-wrap +msgid "`mpo_destroy_pipe_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1038 +#, no-wrap +msgid "void mpo_destroy_pipe_label(struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1049 +#, no-wrap +msgid "Pipe label" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1054 +msgid "" +"Destroy the label on a pipe. In this entry point, a policy module should " +"free any internal storage associated with `label` so that it may be " +"destroyed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1056 +#, no-wrap +msgid "`mpo_destroy_proc_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1061 +#, no-wrap +msgid "void mpo_destroy_proc_label(struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1072 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1095 +#, no-wrap +msgid "Process label" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1077 +msgid "" +"Destroy the label on a process. In this entry point, a policy module should " +"free any internal storage associated with `label` so that it may be " +"destroyed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1079 +#, no-wrap +msgid "`mpo_destroy_vnode_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1084 +#, no-wrap +msgid "void mpo_destroy_vnode_label(struct label *label);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1100 +msgid "" +"Destroy the label on a vnode. In this entry point, a policy module should " +"free any internal storage associated with `label` so that it may be " +"destroyed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1102 +#, no-wrap +msgid "`mpo_copy_mbuf_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1107 +#, no-wrap +msgid "void mpo_copy_mbuf_label(struct label *src, struct label *dest);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1117 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1143 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1169 +#, no-wrap +msgid "`src`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1118 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1144 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1170 +#, no-wrap +msgid "Source label" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1121 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1147 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1173 +#, no-wrap +msgid "`dest`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1122 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1148 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1174 +#, no-wrap +msgid "Destination label" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1126 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1152 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1178 +msgid "Copy the label information in `src` into `dest`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1128 +#, no-wrap +msgid "`mpo_copy_pipe_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1133 +#, no-wrap +msgid "void mpo_copy_pipe_label(struct label *src, struct label *dest);\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1154 +#, no-wrap +msgid "`mpo_copy_vnode_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1159 +#, no-wrap +msgid "void mpo_copy_vnode_label(struct label *src, struct label *dest);\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1180 +#, no-wrap +msgid "`mpo_externalize_cred_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1186 +#, no-wrap +msgid "" +"int mpo_externalize_cred_label(struct label *label, char *element_name,\n" +" struct sbuf *sb, int *claimed);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1197 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1237 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1277 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1317 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1357 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1397 +#, no-wrap +msgid "Label to be externalized" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1200 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1240 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1280 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1320 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1360 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1400 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1440 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1477 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1514 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1551 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1588 +#, no-wrap +msgid "`element_name`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1201 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1241 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1281 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1321 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1361 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1401 +#, no-wrap +msgid "Name of the policy whose label should be externalized" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1204 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1244 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1284 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1324 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1364 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1404 +#, no-wrap +msgid "`sb`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1205 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1245 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1285 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1325 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1365 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1405 +#, no-wrap +msgid "String buffer to be filled with a text representation of label" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1208 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1248 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1288 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1328 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1368 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1408 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1448 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1485 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1522 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1559 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1596 +#, no-wrap +msgid "`claimed`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1209 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1249 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1289 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1329 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1369 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1409 +#, no-wrap +msgid "Should be incremented when `element_data` can be filled in." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1218 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1258 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1298 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1338 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1378 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1418 +msgid "" +"Produce an externalized label based on the label structure passed. An " +"externalized label consists of a text representation of the label contents " +"that can be used with userland applications and read by the user. " +"Currently, all policies' `externalize` entry points will be called, so the " +"implementation should check the contents of `element_name` before attempting " +"to fill in `sb`. If `element_name` does not match the name of your policy, " +"simply return 0. Only return nonzero if an error occurs while externalizing " +"the label data. Once the policy fills in `element_data`, `*claimed` should " +"be incremented." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1220 +#, no-wrap +msgid "`mpo_externalize_ifnet_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1226 +#, no-wrap +msgid "" +"int mpo_externalize_ifnet_label(struct label *label, char *element_name,\n" +" struct sbuf *sb, int *claimed);\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1260 +#, no-wrap +msgid "`mpo_externalize_pipe_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1266 +#, no-wrap +msgid "" +"int mpo_externalize_pipe_label(struct label *label, char *element_name,\n" +" struct sbuf *sb, int *claimed);\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1300 +#, no-wrap +msgid "`mpo_externalize_socket_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1306 +#, no-wrap +msgid "" +"int mpo_externalize_socket_label(struct label *label, char *element_name,\n" +" struct sbuf *sb, int *claimed);\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1340 +#, no-wrap +msgid "`mpo_externalize_socket_peer_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1346 +#, no-wrap +msgid "" +"int mpo_externalize_socket_peer_label(struct label *label, char *element_name,\n" +" struct sbuf *sb, int *claimed);\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1380 +#, no-wrap +msgid "`mpo_externalize_vnode_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1386 +#, no-wrap +msgid "" +"int mpo_externalize_vnode_label(struct label *label, char *element_name,\n" +" struct sbuf *sb, int *claimed);\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1420 +#, no-wrap +msgid "`mpo_internalize_cred_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1426 +#, no-wrap +msgid "" +"int mpo_internalize_cred_label(struct label *label, char *element_name,\n" +" char *element_data, int *claimed);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1441 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1478 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1515 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1552 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1589 +#, no-wrap +msgid "Name of the policy whose label should be internalized" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1444 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1481 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1518 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1555 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1592 +#, no-wrap +msgid "`element_data`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1445 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1482 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1519 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1556 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1593 +#, no-wrap +msgid "Text data to be internalized" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1449 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1486 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1523 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1560 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1597 +#, no-wrap +msgid "Should be incremented when data can be successfully internalized." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1455 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1492 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1529 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1566 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1603 +msgid "" +"Produce an internal label structure based on externalized label data in text " +"format. Currently, all policies' `internalize` entry points are called when " +"internalization is requested, so the implementation should compare the " +"contents of `element_name` to its own name in order to be sure it should be " +"internalizing the data in `element_data`. Just as in the `externalize` " +"entry points, the entry point should return 0 if `element_name` does not " +"match its own name, or when data can successfully be internalized, in which " +"case `*claimed` should be incremented." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1457 +#, no-wrap +msgid "`mpo_internalize_ifnet_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1463 +#, no-wrap +msgid "" +"int mpo_internalize_ifnet_label(struct label *label, char *element_name,\n" +" char *element_data, int *claimed);\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1494 +#, no-wrap +msgid "`mpo_internalize_pipe_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1500 +#, no-wrap +msgid "" +"int mpo_internalize_pipe_label(struct label *label, char *element_name,\n" +" char *element_data, int *claimed);\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1531 +#, no-wrap +msgid "`mpo_internalize_socket_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1537 +#, no-wrap +msgid "" +"int mpo_internalize_socket_label(struct label *label, char *element_name,\n" +" char *element_data, int *claimed);\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1568 +#, no-wrap +msgid "`mpo_internalize_vnode_label`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1574 +#, no-wrap +msgid "" +"int mpo_internalize_vnode_label(struct label *label, char *element_name,\n" +" char *element_data, int *claimed);\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1605 +#, no-wrap +msgid "Label Events" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1613 +msgid "" +"This class of entry points is used by the MAC framework to permit policies " +"to maintain label information on kernel objects. For each labeled kernel " +"object of interest to a MAC policy, entry points may be registered for " +"relevant life cycle events. All objects implement initialization, creation, " +"and destruction hooks. Some objects will also implement relabeling, " +"allowing user processes to change the labels on objects. Some objects will " +"also implement object-specific events, such as label events associated with " +"IP reassembly. A typical labeled object will have the following life cycle " +"of entry points:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1625 +#, no-wrap +msgid "" +"Label initialization o\n" +"(object-specific wait) \\\n" +"Label creation o\n" +" \\\n" +"Relabel events, o--<--.\n" +"Various object-specific, | |\n" +"Access control events ~-->--o\n" +" \\\n" +"Label destruction o\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1629 +msgid "" +"Label initialization permits policies to allocate memory and set initial " +"values for labels without context for the use of the object. The label slot " +"allocated to a policy will be zeroed by default, so some policies may not " +"need to perform initialization." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1636 +msgid "" +"Label creation occurs when the kernel structure is associated with an actual " +"kernel object. For example, Mbufs may be allocated and remain unused in a " +"pool until they are required. mbuf allocation causes label initialization " +"on the mbuf to take place, but mbuf creation occurs when the mbuf is " +"associated with a datagram. Typically, context will be provided for a " +"creation event, including the circumstances of the creation, and labels of " +"other relevant objects in the creation process. For example, when an mbuf " +"is created from a socket, the socket and its label will be presented to " +"registered policies in addition to the new mbuf and its label. Memory " +"allocation in creation events is discouraged, as it may occur in performance " +"sensitive ports of the kernel; in addition, creation calls are not permitted " +"to fail so a failure to allocate memory cannot be reported." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1639 +msgid "" +"Object specific events do not generally fall into the other broad classes of " +"label events, but will generally provide an opportunity to modify or update " +"the label on an object based on additional context. For example, the label " +"on an IP fragment reassembly queue may be updated during the MAC_UPDATE_IPQ " +"entry point as a result of the acceptance of an additional mbuf to that " +"queue." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1641 +msgid "Access control events are discussed in detail in the following section." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1643 +msgid "" +"Label destruction permits policies to release storage or state associated " +"with a label during its association with an object so that the kernel data " +"structures supporting the object may be reused or released." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1647 +msgid "" +"In addition to labels associated with specific kernel objects, an additional " +"class of labels exists: temporary labels. These labels are used to store " +"update information submitted by user processes. These labels are " +"initialized and destroyed as with other label types, but the creation event " +"is MAC_INTERNALIZE, which accepts a user label to be converted to an in-" +"kernel representation." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1649 +#, no-wrap +msgid "File System Object Labeling Event Operations" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1652 +#, no-wrap +msgid "`mpo_associate_vnode_devfs`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1659 +#, no-wrap +msgid "" +"void mpo_associate_vnode_devfs(struct mount *mp, struct label *fslabel,\n" +" struct devfs_dirent *de, struct label *delabel, struct vnode *vp,\n" +" struct label *vlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1669 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1712 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1750 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1854 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1951 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3834 +#, no-wrap +msgid "`mp`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1670 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1855 +#, no-wrap +msgid "Devfs mount point" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1674 +#, no-wrap +msgid "Devfs file system label (`mp->mnt_fslabel`)" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1677 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1866 +#, no-wrap +msgid "`de`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1678 +#, no-wrap +msgid "Devfs directory entry" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1681 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1870 +#, no-wrap +msgid "`delabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1682 +#, no-wrap +msgid "Policy label associated with `de`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1685 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1720 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1758 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1914 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2009 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2044 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2084 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2934 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2968 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3240 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3799 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3897 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4050 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4089 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4126 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4160 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4197 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4252 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4287 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4322 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4357 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4392 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4432 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4476 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4586 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4656 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4690 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4723 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4764 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4812 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4849 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4886 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4928 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5031 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5181 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5282 +#, no-wrap +msgid "`vp`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1686 +#, no-wrap +msgid "vnode associated with `de`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1689 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1724 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1762 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1918 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2048 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3244 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5185 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5286 +#, no-wrap +msgid "`vlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1690 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1725 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1763 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1919 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2049 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4257 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4292 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4397 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4437 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4481 +#, no-wrap +msgid "Policy label associated with `vp`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1694 +msgid "" +"Fill in the label (`vlabel`) for a newly created devfs vnode based on the " +"devfs directory entry passed in `de` and its label." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1696 +#, no-wrap +msgid "`mpo_associate_vnode_extattr`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1702 +#, no-wrap +msgid "" +"int mpo_associate_vnode_extattr(struct mount *mp, struct label *fslabel,\n" +" struct vnode *vp, struct label *vlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1713 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1751 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1899 +#, no-wrap +msgid "File system mount point" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1717 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1755 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1903 +#, no-wrap +msgid "File system label" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1721 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1759 +#, no-wrap +msgid "Vnode to label" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1732 +msgid "" +"Attempt to retrieve the label for `vp` from the file system extended " +"attributes. Upon success, the value `0` is returned. Should extended " +"attribute retrieval not be supported, an accepted fallback is to copy " +"`fslabel` into `vlabel`. In the event of an error, an appropriate value for " +"`errno` should be returned." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1734 +#, no-wrap +msgid "`mpo_associate_vnode_singlelabel`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1740 +#, no-wrap +msgid "" +"void mpo_associate_vnode_singlelabel(struct mount *mp, struct label *fslabel,\n" +" struct vnode *vp, struct label *vlabel);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1767 +msgid "" +"On non-multilabel file systems, this entry point is called to set the policy " +"label for `vp` based on the file system label, `fslabel`." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1769 +#, no-wrap +msgid "`mpo_create_devfs_device`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1775 +#, no-wrap +msgid "" +"void mpo_create_devfs_device(dev_t dev, struct devfs_dirent *devfs_dirent,\n" +" struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1785 +#, no-wrap +msgid "`dev`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1786 +#, no-wrap +msgid "Device corresponding with `devfs_dirent`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1789 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1825 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2076 +#, no-wrap +msgid "`devfs_dirent`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1790 +#, no-wrap +msgid "Devfs directory entry to be labeled." +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1794 +#, no-wrap +msgid "Label for `devfs_dirent` to be filled in." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1799 +msgid "" +"Fill out the label on a devfs_dirent being created for the passed device. " +"This call will be made when the device file system is mounted, regenerated, " +"or a new device is made available." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1801 +#, no-wrap +msgid "`mpo_create_devfs_directory`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1807 +#, no-wrap +msgid "" +"void mpo_create_devfs_directory(char *dirname, int dirnamelen,\n" +" struct devfs_dirent *devfs_dirent, struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1817 +#, no-wrap +msgid "`dirname`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1818 +#, no-wrap +msgid "Name of directory being created" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1821 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5317 +#, no-wrap +msgid "`namelen`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1822 +#, no-wrap +msgid "Length of string `dirname`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1826 +#, no-wrap +msgid "Devfs directory entry for directory being created." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1831 +msgid "" +"Fill out the label on a devfs_dirent being created for the passed " +"directory. This call will be made when the device file system is mounted, " +"regenerated, or a new device requiring a specific directory hierarchy is " +"made available." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1833 +#, no-wrap +msgid "`mpo_create_devfs_symlink`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1840 +#, no-wrap +msgid "" +"void mpo_create_devfs_symlink(struct ucred *cred, struct mount *mp,\n" +" struct devfs_dirent *dd, struct label *ddlabel, struct devfs_dirent *de,\n" +" struct label *delabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1850 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1894 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1947 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2005 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2040 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2152 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2184 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2252 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2287 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2398 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2824 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2996 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3018 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3040 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3135 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3157 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3183 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3209 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3236 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3266 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3288 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3311 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3350 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3381 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3412 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3447 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3478 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3509 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3542 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3579 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3610 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3670 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3699 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3734 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3768 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3795 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3830 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3863 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3893 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3931 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3964 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3995 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4038 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4085 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4122 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4156 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4193 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4240 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4283 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4318 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4353 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4420 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4464 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4512 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4545 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4582 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4619 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4652 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4686 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4719 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4760 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4808 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4845 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4882 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4924 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4964 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4994 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5027 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5062 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5103 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5144 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5207 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5229 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5255 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5278 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5309 +#, no-wrap +msgid "`cred`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1851 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1895 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1948 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2006 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2041 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2153 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2185 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2253 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2288 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2399 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2825 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3041 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3136 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3158 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3184 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3210 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3237 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3267 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3289 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3312 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3351 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3382 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3413 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3448 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3479 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3510 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3543 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3580 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3611 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3641 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3671 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3700 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3735 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3769 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3796 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3831 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3864 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3894 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3932 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3965 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3996 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4039 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4086 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4123 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4157 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4194 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4241 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4284 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4354 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4385 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4421 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4465 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4513 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4546 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4583 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4620 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4653 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4687 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4720 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4761 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4809 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4846 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4883 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4925 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4965 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4995 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5028 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5063 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5104 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5145 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5178 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5208 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5230 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5256 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5279 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5310 +#, no-wrap +msgid "Subject credential" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1858 +#, no-wrap +msgid "`dd`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1859 +#, no-wrap +msgid "Link destination" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1862 +#, no-wrap +msgid "`ddlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1863 +#, no-wrap +msgid "Label associated with `dd`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1867 +#, no-wrap +msgid "Symlink entry" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1871 +#, no-wrap +msgid "Label associated with `de`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1875 +msgid "" +"Fill in the label (`delabel`) for a newly created man:devfs[5] symbolic link " +"entry." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1877 +#, no-wrap +msgid "`mpo_create_vnode_extattr`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1884 +#, no-wrap +msgid "" +"int mpo_create_vnode_extattr(struct ucred *cred, struct mount *mp,\n" +" struct label *fslabel, struct vnode *dvp, struct label *dlabel,\n" +" struct vnode *vp, struct label *vlabel, struct componentname *cnp);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1898 +#, no-wrap +msgid "`mount`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1906 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3935 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3968 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3999 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4042 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4244 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4424 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4468 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4549 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4623 +#, no-wrap +msgid "`dvp`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1907 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4043 +#, no-wrap +msgid "Parent directory vnode" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1910 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3939 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3972 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4003 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4046 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4248 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4428 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4472 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4553 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4627 +#, no-wrap +msgid "`dlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1911 +#, no-wrap +msgid "Label associated with `dvp`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1915 +#, no-wrap +msgid "Newly created vnode" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1922 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4007 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4058 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4260 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4440 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4488 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4557 +#, no-wrap +msgid "`cnp`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1923 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4059 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4441 +#, no-wrap +msgid "Component name for `vp`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1929 +msgid "" +"Write out the label for `vp` to the appropriate extended attribute. If the " +"write succeeds, fill in `vlabel` with the label, and return 0. Otherwise, " +"return an appropriate error." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1931 +#, no-wrap +msgid "`mpo_create_mount`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1937 +#, no-wrap +msgid "" +"void mpo_create_mount(struct ucred *cred, struct mount *mp, struct label *mnt,\n" +" struct label *fslabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1952 +#, no-wrap +msgid "Object; file system being mounted" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1956 +#, no-wrap +msgid "Policy label to be filled in for `mp`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1960 +#, no-wrap +msgid "Policy label for the file system `mp` mounts." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1965 +msgid "" +"Fill out the labels on the mount point being created by the passed subject " +"credential. This call will be made when a new file system is mounted." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1967 +#, no-wrap +msgid "`mpo_create_root_mount`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1973 +#, no-wrap +msgid "" +"void mpo_create_root_mount(struct ucred *cred, struct mount *mp,\n" +" struct label *mntlabel, struct label *fslabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1983 +#, no-wrap +msgid "See crossref:mac[mac-mpo-create-mount, `mpo_create_mount`]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1987 +msgid "" +"Fill out the labels on the mount point being created by the passed subject " +"credential. This call will be made when the root file system is mounted, " +"after `mpo_create_mount;`." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1989 +#, no-wrap +msgid "`mpo_relabel_vnode`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1995 +#, no-wrap +msgid "" +"void mpo_relabel_vnode(struct ucred *cred, struct vnode *vp,\n" +" struct label *vnodelabel, struct label *newlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2010 +#, no-wrap +msgid "vnode to relabel" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2013 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2088 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2938 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2972 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3803 +#, no-wrap +msgid "`vnodelabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2014 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3804 +#, no-wrap +msgid "Existing policy label for `vp`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2017 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2264 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2299 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2334 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2836 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3044 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3424 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3711 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3746 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3772 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3807 +#, no-wrap +msgid "`newlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2018 +#, no-wrap +msgid "New, possibly partial label to replace `vnodelabel`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2022 +msgid "" +"Update the label on the passed vnode given the passed update vnode label and " +"the passed subject credential." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2024 +#, no-wrap +msgid "`mpo_setlabel_vnode_extattr`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2030 +#, no-wrap +msgid "" +"int mpo_setlabel_vnode_extattr(struct ucred *cred, struct vnode *vp,\n" +" struct label *vlabel, struct label *intlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2045 +#, no-wrap +msgid "Vnode for which the label is being written" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2052 +#, no-wrap +msgid "`intlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2053 +#, no-wrap +msgid "Label to write out" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2058 +msgid "" +"Write out the policy from `intlabel` to an extended attribute. This is " +"called from `vop_stdcreatevnode_ea`." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2060 +#, no-wrap +msgid "`mpo_update_devfsdirent`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2066 +#, no-wrap +msgid "" +"void mpo_update_devfsdirent(struct devfs_dirent *devfs_dirent,\n" +" struct label *direntlabel, struct vnode *vp, struct label *vnodelabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2077 +#, no-wrap +msgid "Object; devfs directory entry" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2080 +#, no-wrap +msgid "`direntlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2081 +#, no-wrap +msgid "Policy label for `devfs_dirent` to be updated." +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2085 +#, no-wrap +msgid "Parent vnode" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2087 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2937 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3802 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4092 +#, no-wrap +msgid "Locked" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2089 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2939 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2973 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3902 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4055 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4094 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4131 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4165 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4202 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4591 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4661 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4695 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4728 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4769 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4817 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4854 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4891 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4933 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5036 +#, no-wrap +msgid "Policy label for `vp`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2095 +msgid "" +"Update the `devfs_dirent` label from the passed devfs vnode label. This " +"call will be made when a devfs vnode has been successfully relabeled to " +"commit the label change such that it lasts even if the vnode is recycled. " +"It will also be made when a symlink is created in devfs, following a call to " +"`mac_vnode_create_from_vnode` to initialize the vnode label." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2097 +#, no-wrap +msgid "IPC Object Labeling Event Operations" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2100 +#, no-wrap +msgid "`mpo_create_mbuf_from_socket`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2106 +#, no-wrap +msgid "" +"void mpo_create_mbuf_from_socket(struct socket *so, struct label *socketlabel,\n" +" struct mbuf *m, struct label *mbuflabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2116 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3513 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3546 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3674 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3738 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4516 +#, no-wrap +msgid "`socket`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2117 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3584 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3615 +#, no-wrap +msgid "Socket" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2119 +#, no-wrap +msgid "Socket locking WIP" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2120 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2192 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3517 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3550 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3587 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3618 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3678 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3742 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4520 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5152 +#, no-wrap +msgid "`socketlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2121 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3518 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3551 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3679 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4521 +#, no-wrap +msgid "Policy label for `socket`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2124 +#, no-wrap +msgid "`m`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2125 +#, no-wrap +msgid "Object; mbuf" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2128 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2326 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2610 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2646 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2682 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2863 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5078 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5119 +#, no-wrap +msgid "`mbuflabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2129 +#, no-wrap +msgid "Policy label to fill in for `m`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2134 +msgid "" +"Set the label on a newly created mbuf header from the passed socket label. " +"This call is made when a new datagram or message is generated by the socket " +"and stored in the passed mbuf." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2136 +#, no-wrap +msgid "`mpo_create_pipe`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2142 +#, no-wrap +msgid "" +"void mpo_create_pipe(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2156 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2256 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3315 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3354 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3385 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3416 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3451 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3482 +#, no-wrap +msgid "`pipe`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2157 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2257 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3316 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3355 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3386 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3417 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3452 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3483 +#, no-wrap +msgid "Pipe" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2160 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3319 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3358 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3389 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3420 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3455 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3486 +#, no-wrap +msgid "`pipelabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2161 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3320 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3359 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3390 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3456 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3487 +#, no-wrap +msgid "Policy label associated with `pipe`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2166 +msgid "" +"Set the label on a newly created pipe from the passed subject credential. " +"This call is made when a new pipe is created." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2168 +#, no-wrap +msgid "`mpo_create_socket`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2174 +#, no-wrap +msgid "" +"void mpo_create_socket(struct ucred *cred, struct socket *so,\n" +" struct label *socketlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2187 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2290 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2401 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2929 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2967 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3798 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3866 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4088 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5147 +#, no-wrap +msgid "Immutable" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2188 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2291 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3583 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3614 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5148 +#, no-wrap +msgid "`so`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2189 +#, no-wrap +msgid "Object; socket to label" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2193 +#, no-wrap +msgid "Label to fill in for `so`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2198 +msgid "" +"Set the label on a newly created socket from the passed subject credential. " +"This call is made when a socket is created." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2200 +#, no-wrap +msgid "`mpo_create_socket_from_socket`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2207 +#, no-wrap +msgid "" +"void mpo_create_socket_from_socket(struct socket *oldsocket,\n" +" struct label *oldsocketlabel, struct socket *newsocket,\n" +" struct label *newsocketlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2217 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2359 +#, no-wrap +msgid "`oldsocket`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2218 +#, no-wrap +msgid "Listening socket" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2221 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2363 +#, no-wrap +msgid "`oldsocketlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2222 +#, no-wrap +msgid "Policy label associated with `oldsocket`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2225 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2367 +#, no-wrap +msgid "`newsocket`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2226 +#, no-wrap +msgid "New socket" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2229 +#, no-wrap +msgid "`newsocketlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2230 +#, no-wrap +msgid "Policy label associated with `newsocketlabel`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2234 +msgid "" +"Label a socket, `newsocket`, newly man:accept[2]ed, based on the " +"man:listen[2] socket, `oldsocket`." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2236 +#, no-wrap +msgid "`mpo_relabel_pipe`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2242 +#, no-wrap +msgid "" +"void mpo_relabel_pipe(struct ucred *cred, struct pipe *pipe,\n" +" struct label *oldlabel, struct label *newlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2260 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2295 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2330 +#, no-wrap +msgid "`oldlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2261 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3421 +#, no-wrap +msgid "Current policy label associated with `pipe`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2265 +#, no-wrap +msgid "Policy label update to apply to `pipe`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2269 +msgid "Apply a new label, `newlabel`, to `pipe`." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2271 +#, no-wrap +msgid "`mpo_relabel_socket`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2277 +#, no-wrap +msgid "" +"void mpo_relabel_socket(struct ucred *cred, struct socket *so,\n" +" struct label *oldlabel, struct label *newlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2292 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3675 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3739 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4517 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5149 +#, no-wrap +msgid "Object; socket" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2296 +#, no-wrap +msgid "Current label for `so`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2300 +#, no-wrap +msgid "Label update for `so`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2304 +msgid "Update the label on a socket from the passed socket label update." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2306 +#, no-wrap +msgid "`mpo_set_socket_peer_from_mbuf`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2312 +#, no-wrap +msgid "" +"void mpo_set_socket_peer_from_mbuf(struct mbuf *mbuf, struct label *mbuflabel,\n" +" struct label *oldlabel, struct label *newlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2322 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2606 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2642 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2678 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2859 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5074 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5115 +#, no-wrap +msgid "`mbuf`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2323 +#, no-wrap +msgid "First datagram received over socket" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2327 +#, no-wrap +msgid "Label for `mbuf`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2331 +#, no-wrap +msgid "Current label for the socket" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2335 +#, no-wrap +msgid "Policy label to be filled out for the socket" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2340 +msgid "" +"Set the peer label on a stream socket from the passed mbuf label. This call " +"will be made when the first datagram is received by the stream socket, with " +"the exception of Unix domain sockets." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2342 +#, no-wrap +msgid "`mpo_set_socket_peer_from_socket`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2349 +#, no-wrap +msgid "" +"void mpo_set_socket_peer_from_socket(struct socket *oldsocket,\n" +" struct label *oldsocketlabel, struct socket *newsocket,\n" +" struct label *newsocketpeerlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2360 +#, no-wrap +msgid "Local socket" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2364 +#, no-wrap +msgid "Policy label for `oldsocket`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2368 +#, no-wrap +msgid "Peer socket" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2371 +#, no-wrap +msgid "`newsocketpeerlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2372 +#, no-wrap +msgid "Policy label to fill in for `newsocket`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2377 +msgid "" +"Set the peer label on a stream UNIX domain socket from the passed remote " +"socket endpoint. This call will be made when the socket pair is connected, " +"and will be made for both endpoints." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2379 +#, no-wrap +msgid "Network Object Labeling Event Operations" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2382 +#, no-wrap +msgid "`mpo_create_bpfdesc`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2388 +#, no-wrap +msgid "" +"void mpo_create_bpfdesc(struct ucred *cred, struct bpf_d *bpf_d,\n" +" struct label *bpflabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2402 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2634 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3100 +#, no-wrap +msgid "`bpf_d`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2403 +#, no-wrap +msgid "Object; bpf descriptor" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2406 +#, no-wrap +msgid "`bpf`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2407 +#, no-wrap +msgid "Policy label to be filled in for `bpf_d`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2412 +msgid "" +"Set the label on a newly created BPF descriptor from the passed subject " +"credential. This call will be made when a BPF device node is opened by a " +"process with the passed subject credential." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2414 +#, no-wrap +msgid "`mpo_create_ifnet`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2419 +#, no-wrap +msgid "void mpo_create_ifnet(struct ifnet *ifnet, struct label *ifnetlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2429 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2598 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2670 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2714 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2828 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3108 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3703 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5066 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5107 +#, no-wrap +msgid "`ifnet`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2430 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2599 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2671 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2715 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5067 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5108 +#, no-wrap +msgid "Network interface" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2433 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2602 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2674 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2718 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2832 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3112 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3707 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5070 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5111 +#, no-wrap +msgid "`ifnetlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2434 +#, no-wrap +msgid "Policy label to fill in for `ifnet`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2439 +msgid "" +"Set the label on a newly created interface. This call may be made when a " +"new physical interface becomes available to the system, or when a pseudo-" +"interface is instantiated during the boot or as a result of a user action." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2441 +#, no-wrap +msgid "`mpo_create_ipq`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2447 +#, no-wrap +msgid "" +"void mpo_create_ipq(struct mbuf *fragment, struct label *fragmentlabel,\n" +" struct ipq *ipq, struct label *ipqlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2457 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2535 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2786 +#, no-wrap +msgid "`fragment`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2458 +#, no-wrap +msgid "First received IP fragment" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2461 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2539 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2790 +#, no-wrap +msgid "`fragmentlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2462 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2791 +#, no-wrap +msgid "Policy label for `fragment`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2465 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2492 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2794 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2867 +#, no-wrap +msgid "`ipq`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2466 +#, no-wrap +msgid "IP reassembly queue to be labeled" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2469 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2496 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2798 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2871 +#, no-wrap +msgid "`ipqlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2470 +#, no-wrap +msgid "Policy label to be filled in for `ipq`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2474 +msgid "" +"Set the label on a newly created IP fragment reassembly queue from the mbuf " +"header of the first received fragment." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2476 +#, no-wrap +msgid "`mpo_create_datagram_from_ipq`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2482 +#, no-wrap +msgid "" +"void mpo_create_create_datagram_from_ipq(struct ipq *ipq,\n" +" struct label *ipqlabel, struct mbuf *datagram, struct label *datagramlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2493 +#, no-wrap +msgid "IP reassembly queue" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2497 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2799 +#, no-wrap +msgid "Policy label for `ipq`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2500 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2527 +#, no-wrap +msgid "`datagram`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2501 +#, no-wrap +msgid "Datagram to be labeled" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2504 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2531 +#, no-wrap +msgid "`datagramlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2505 +#, no-wrap +msgid "Policy label to be filled in for `datagramlabel`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2509 +msgid "" +"Set the label on a newly reassembled IP datagram from the IP fragment " +"reassembly queue from which it was generated." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2511 +#, no-wrap +msgid "`mpo_create_fragment`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2517 +#, no-wrap +msgid "" +"void mpo_create_fragment(struct mbuf *datagram, struct label *datagramlabel,\n" +" struct mbuf *fragment, struct label *fragmentlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2528 +#, no-wrap +msgid "Datagram" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2532 +#, no-wrap +msgid "Policy label for `datagram`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2536 +#, no-wrap +msgid "Fragment to be labeled" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2540 +#, no-wrap +msgid "Policy label to be filled in for `datagram`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2544 +msgid "" +"Set the label on the mbuf header of a newly created IP fragment from the " +"label on the mbuf header of the datagram it was generate from." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2546 +#, no-wrap +msgid "`mpo_create_mbuf_from_mbuf`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2552 +#, no-wrap +msgid "" +"void mpo_create_mbuf_from_mbuf(struct mbuf *oldmbuf, struct label *oldmbuflabel,\n" +" struct mbuf *newmbuf, struct label *newmbuflabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2562 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2706 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2750 +#, no-wrap +msgid "`oldmbuf`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2563 +#, no-wrap +msgid "Existing (source) mbuf" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2566 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2710 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2754 +#, no-wrap +msgid "`oldmbuflabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2567 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2711 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2755 +#, no-wrap +msgid "Policy label for `oldmbuf`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2570 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2722 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2758 +#, no-wrap +msgid "`newmbuf`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2571 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2643 +#, no-wrap +msgid "New mbuf to be labeled" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2574 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2726 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2762 +#, no-wrap +msgid "`newmbuflabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2575 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2727 +#, no-wrap +msgid "Policy label to be filled in for `newmbuf`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2580 +msgid "" +"Set the label on the mbuf header of a newly created datagram from the mbuf " +"header of an existing datagram. This call may be made in a number of " +"situations, including when an mbuf is re-allocated for alignment purposes." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2582 +#, no-wrap +msgid "`mpo_create_mbuf_linklayer`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2588 +#, no-wrap +msgid "" +"void mpo_create_mbuf_linklayer(struct ifnet *ifnet, struct label *ifnetlabel,\n" +" struct mbuf *mbuf, struct label *mbuflabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2603 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2719 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2833 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3113 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5071 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5112 +#, no-wrap +msgid "Policy label for `ifnet`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2607 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2679 +#, no-wrap +msgid "mbuf header for new datagram" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2611 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2683 +#, no-wrap +msgid "Policy label to be filled in for `mbuf`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2616 +msgid "" +"Set the label on the mbuf header of a newly created datagram generated for " +"the purposes of a link layer response for the passed interface. This call " +"may be made in a number of situations, including for ARP or ND6 responses in " +"the IPv4 and IPv6 stacks." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2618 +#, no-wrap +msgid "`mpo_create_mbuf_from_bpfdesc`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2624 +#, no-wrap +msgid "" +"void mpo_create_mbuf_from_bpfdesc(struct bpf_d *bpf_d, struct label *bpflabel,\n" +" struct mbuf *mbuf, struct label *mbuflabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2635 +#, no-wrap +msgid "BPF descriptor" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2638 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3104 +#, no-wrap +msgid "`bpflabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2639 +#, no-wrap +msgid "Policy label for `bpflabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2647 +#, no-wrap +msgid "Policy label to fill in for `mbuf`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2652 +msgid "" +"Set the label on the mbuf header of a newly created datagram generated using " +"the passed BPF descriptor. This call is made when a write is performed to " +"the BPF device associated with the passed BPF descriptor." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2654 +#, no-wrap +msgid "`mpo_create_mbuf_from_ifnet`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2660 +#, no-wrap +msgid "" +"void mpo_create_mbuf_from_ifnet(struct ifnet *ifnet, struct label *ifnetlabel,\n" +" struct mbuf *mbuf, struct label *mbuflabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2675 +#, no-wrap +msgid "Policy label for `ifnetlabel`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2687 +msgid "" +"Set the label on the mbuf header of a newly created datagram generated from " +"the passed network interface." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2689 +#, no-wrap +msgid "`mpo_create_mbuf_multicast_encap`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2696 +#, no-wrap +msgid "" +"void mpo_create_mbuf_multicast_encap(struct mbuf *oldmbuf,\n" +" struct label *oldmbuflabel, struct ifnet *ifnet, struct label *ifnetlabel,\n" +" struct mbuf *newmbuf, struct label *newmbuflabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2707 +#, no-wrap +msgid "mbuf header for existing datagram" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2723 +#, no-wrap +msgid "mbuf header to be labeled for new datagram" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2732 +msgid "" +"Set the label on the mbuf header of a newly created datagram generated from " +"the existing passed datagram when it is processed by the passed multicast " +"encapsulation interface. This call is made when an mbuf is to be delivered " +"using the virtual interface." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2734 +#, no-wrap +msgid "`mpo_create_mbuf_netlayer`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2740 +#, no-wrap +msgid "" +"void mpo_create_mbuf_netlayer(struct mbuf *oldmbuf, struct label *oldmbuflabel,\n" +" struct mbuf *newmbuf, struct label *newmbuflabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2751 +#, no-wrap +msgid "Received datagram" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2759 +#, no-wrap +msgid "Newly created datagram" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2763 +#, no-wrap +msgid "Policy label for `newmbuf`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2768 +msgid "" +"Set the label on the mbuf header of a newly created datagram generated by " +"the IP stack in response to an existing received datagram (`oldmbuf`). This " +"call may be made in a number of situations, including when responding to " +"ICMP request datagrams." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2770 +#, no-wrap +msgid "`mpo_fragment_match`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2776 +#, no-wrap +msgid "" +"int mpo_fragment_match(struct mbuf *fragment, struct label *fragmentlabel,\n" +" struct ipq *ipq, struct label *ipqlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2787 +#, no-wrap +msgid "IP datagram fragment" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2795 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2868 +#, no-wrap +msgid "IP fragment reassembly queue" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2806 +msgid "" +"Determine whether an mbuf header containing an IP datagram (`fragment`) " +"fragment matches the label of the passed IP fragment reassembly queue " +"(`ipq`). Return (1) for a successful match, or (0) for no match. This call " +"is made when the IP stack attempts to find an existing fragment reassembly " +"queue for a newly received fragment; if this fails, a new fragment " +"reassembly queue may be instantiated for the fragment. Policies may use " +"this entry point to prevent the reassembly of otherwise matching IP " +"fragments if policy does not permit them to be reassembled based on the " +"label or other information." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2808 +#, no-wrap +msgid "`mpo_relabel_ifnet`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2814 +#, no-wrap +msgid "" +"void mpo_relabel_ifnet(struct ucred *cred, struct ifnet *ifnet,\n" +" struct label *ifnetlabel, struct label *newlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2829 +#, no-wrap +msgid "Object; Network interface" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2837 +#, no-wrap +msgid "Label update to apply to `ifnet`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2841 +msgid "" +"Update the label of network interface, `ifnet`, based on the passed update " +"label, `newlabel`, and the passed subject credential, `cred`." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2843 +#, no-wrap +msgid "`mpo_update_ipq`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2849 +#, no-wrap +msgid "" +"void mpo_update_ipq(struct mbuf *fragment, struct label *fragmentlabel,\n" +" struct ipq *ipq, struct label *ipqlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2860 +#, no-wrap +msgid "IP fragment" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2864 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5079 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5120 +#, no-wrap +msgid "Policy label for `mbuf`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2872 +#, no-wrap +msgid "Policy label to be updated for `ipq`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2876 +msgid "" +"Update the label on an IP fragment reassembly queue (`ipq`) based on the " +"acceptance of the passed IP fragment mbuf header (`mbuf`)." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2878 +#, no-wrap +msgid "Process Labeling Event Operations" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2881 +#, no-wrap +msgid "`mpo_create_cred`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2886 +#, no-wrap +msgid "void mpo_create_cred(struct ucred *parent_cred, struct ucred *child_cred);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2896 +#, no-wrap +msgid "`parent_cred`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2897 +#, no-wrap +msgid "Parent subject credential" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2900 +#, no-wrap +msgid "`child_cred`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2901 +#, no-wrap +msgid "Child subject credential" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2907 +msgid "" +"Set the label of a newly created subject credential from the passed subject " +"credential. This call will be made when man:crcopy[9] is invoked on a newly " +"created `struct ucred`. This call should not be confused with a process " +"forking or creation event." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2909 +#, no-wrap +msgid "`mpo_execve_transition`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2915 +#, no-wrap +msgid "" +"void mpo_execve_transition(struct ucred *old, struct ucred *new,\n" +" struct vnode *vp, struct label *vnodelabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2926 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2964 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5321 +#, no-wrap +msgid "`old`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2927 +#, no-wrap +msgid "Existing subject credential" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2930 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5333 +#, no-wrap +msgid "`new`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2931 +#, no-wrap +msgid "New subject credential to be labeled" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2935 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2969 +#, no-wrap +msgid "File to execute" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2946 +msgid "" +"Update the label of a newly created subject credential (`new`) from the " +"passed existing subject credential (`old`) based on a label transition " +"caused by executing the passed vnode (`vp`). This call occurs when a " +"process executes the passed vnode and one of the policies returns a success " +"from the `mpo_execve_will_transition` entry point. Policies may choose to " +"implement this call simply by invoking `mpo_create_cred` and passing the two " +"subject credentials so as not to implement a transitioning event. Policies " +"should not leave this entry point unimplemented if they implement " +"`mpo_create_cred`, even if they do not implement " +"`mpo_execve_will_transition`." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2948 +#, no-wrap +msgid "`mpo_execve_will_transition`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2954 +#, no-wrap +msgid "" +"int mpo_execve_will_transition(struct ucred *old, struct vnode *vp,\n" +" struct label *vnodelabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2965 +#, no-wrap +msgid "Subject credential prior to man:execve[2]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2979 +msgid "" +"Determine whether the policy will want to perform a transition event as a " +"result of the execution of the passed vnode by the passed subject " +"credential. Return 1 if a transition is required, 0 if not. Even if a " +"policy returns 0, it should behave correctly in the presence of an " +"unexpected invocation of `mpo_execve_transition`, as that call may happen as " +"a result of another policy requesting a transition." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2981 +#, no-wrap +msgid "`mpo_create_proc0`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2986 +#, no-wrap +msgid "void mpo_create_proc0(struct ucred *cred);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2997 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3019 +#, no-wrap +msgid "Subject credential to be filled in" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3001 +msgid "" +"Create the subject credential of process 0, the parent of all kernel " +"processes." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3003 +#, no-wrap +msgid "`mpo_create_proc1`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3008 +#, no-wrap +msgid "void mpo_create_proc1(struct ucred *cred);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3023 +msgid "" +"Create the subject credential of process 1, the parent of all user processes." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3025 +#, no-wrap +msgid "`mpo_relabel_cred`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3030 +#, no-wrap +msgid "void mpo_relabel_cred(struct ucred *cred, struct label *newlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3045 +#, no-wrap +msgid "Label update to apply to `cred`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3049 +msgid "Update the label on a subject credential from the passed update label." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3051 +#, no-wrap +msgid "Access Control Checks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3059 +msgid "" +"Access control entry points permit policy modules to influence access " +"control decisions made by the kernel. Generally, although not always, " +"arguments to an access control entry point will include one or more " +"authorizing credentials, information (possibly including a label) for any " +"other objects involved in the operation. An access control entry point may " +"return 0 to permit the operation, or an man:errno[2] error value. The " +"results of invoking the entry point across various registered policy modules " +"will be composed as follows: if all modules permit the operation to succeed, " +"success will be returned. If one or modules returns a failure, a failure " +"will be returned. If more than one module returns a failure, the errno " +"value to return to the user will be selected using the following precedence, " +"implemented by the `error_select()` function in [.filename]#kern_mac.c#:" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3065 +#, no-wrap +msgid "Most precedence" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3067 +#, no-wrap +msgid "EDEADLK" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3070 +#, no-wrap +msgid "EINVAL" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3073 +#, no-wrap +msgid "ESRCH" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3076 +#, no-wrap +msgid "EACCES" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3077 +#, no-wrap +msgid "Least precedence" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3078 +#, no-wrap +msgid "EPERM" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3082 +msgid "" +"If none of the error values returned by all modules are listed in the " +"precedence chart then an arbitrarily selected value from the set will be " +"returned. In general, the rules provide precedence to errors in the " +"following order: kernel failures, invalid arguments, object not present, " +"access not permitted, other." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3084 +#, no-wrap +msgid "`mpo_check_bpfdesc_receive`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3090 +#, no-wrap +msgid "" +"int mpo_check_bpfdesc_receive(struct bpf_d *bpf_d, struct label *bpflabel,\n" +" struct ifnet *ifnet, struct label *ifnetlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3101 +#, no-wrap +msgid "Subject; BPF descriptor" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3105 +#, no-wrap +msgid "Policy label for `bpf_d`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3109 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3704 +#, no-wrap +msgid "Object; network interface" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3118 +msgid "" +"Determine whether the MAC framework should permit datagrams from the passed " +"interface to be delivered to the buffers of the passed BPF descriptor. " +"Return (0) for success, or an `errno` value for failure Suggested failure: " +"EACCES for label mismatches, EPERM for lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3120 +#, no-wrap +msgid "`mpo_check_kenv_dump`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3125 +#, no-wrap +msgid "int mpo_check_kenv_dump(struct ucred *cred);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3140 +msgid "" +"Determine whether the subject should be allowed to retrieve the kernel " +"environment (see man:kenv[2])." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3142 +#, no-wrap +msgid "`mpo_check_kenv_get`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3147 +#, no-wrap +msgid "int mpo_check_kenv_get(struct ucred *cred, char *name);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3161 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3187 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3213 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4209 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4776 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5313 +#, no-wrap +msgid "`name`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3162 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3188 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3214 +#, no-wrap +msgid "Kernel environment variable name" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3166 +msgid "" +"Determine whether the subject should be allowed to retrieve the value of the " +"specified kernel environment variable." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3168 +#, no-wrap +msgid "`mpo_check_kenv_set`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3173 +#, no-wrap +msgid "int mpo_check_kenv_set(struct ucred *cred, char *name);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3192 +msgid "" +"Determine whether the subject should be allowed to set the specified kernel " +"environment variable." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3194 +#, no-wrap +msgid "`mpo_check_kenv_unset`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3199 +#, no-wrap +msgid "int mpo_check_kenv_unset(struct ucred *cred, char *name);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3218 +msgid "" +"Determine whether the subject should be allowed to unset the specified " +"kernel environment variable." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3220 +#, no-wrap +msgid "`mpo_check_kld_load`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3226 +#, no-wrap +msgid "" +"int mpo_check_kld_load(struct ucred *cred, struct vnode *vp,\n" +" struct label *vlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3241 +#, no-wrap +msgid "Kernel module vnode" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3245 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5186 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5287 +#, no-wrap +msgid "Label associated with `vp`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3249 +msgid "" +"Determine whether the subject should be allowed to load the specified module " +"file." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3251 +#, no-wrap +msgid "`mpo_check_kld_stat`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3256 +#, no-wrap +msgid "int mpo_check_kld_stat(struct ucred *cred);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3271 +msgid "" +"Determine whether the subject should be allowed to retrieve a list of loaded " +"kernel module files and associated statistics." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3273 +#, no-wrap +msgid "`mpo_check_kld_unload`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3278 +#, no-wrap +msgid "int mpo_check_kld_unload(struct ucred *cred);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3293 +msgid "" +"Determine whether the subject should be allowed to unload a kernel module." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3295 +#, no-wrap +msgid "`mpo_check_pipe_ioctl`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3301 +#, no-wrap +msgid "" +"int mpo_check_pipe_ioctl(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel, unsigned long cmd, void *data);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3323 +#, no-wrap +msgid "`cmd`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3324 +#, no-wrap +msgid "man:ioctl[2] command" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3327 +#, no-wrap +msgid "`data`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3328 +#, no-wrap +msgid "man:ioctl[2] data" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3332 +msgid "" +"Determine whether the subject should be allowed to make the specified " +"man:ioctl[2] call." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3334 +#, no-wrap +msgid "`mpo_check_pipe_poll`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3340 +#, no-wrap +msgid "" +"int mpo_check_pipe_poll(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3363 +msgid "Determine whether the subject should be allowed to poll `pipe`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3365 +#, no-wrap +msgid "`mpo_check_pipe_read`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3371 +#, no-wrap +msgid "" +"int mpo_check_pipe_read(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3394 +msgid "Determine whether the subject should be allowed read access to `pipe`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3396 +#, no-wrap +msgid "`mpo_check_pipe_relabel`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3402 +#, no-wrap +msgid "" +"int mpo_check_pipe_relabel(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel, struct label *newlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3425 +#, no-wrap +msgid "Label update to `pipelabel`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3429 +msgid "Determine whether the subject should be allowed to relabel `pipe`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3431 +#, no-wrap +msgid "`mpo_check_pipe_stat`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3437 +#, no-wrap +msgid "" +"int mpo_check_pipe_stat(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3460 +msgid "" +"Determine whether the subject should be allowed to retrieve statistics " +"related to `pipe`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3462 +#, no-wrap +msgid "`mpo_check_pipe_write`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3468 +#, no-wrap +msgid "" +"int mpo_check_pipe_write(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3491 +msgid "Determine whether the subject should be allowed to write to `pipe`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3493 +#, no-wrap +msgid "`mpo_check_socket_bind`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3499 +#, no-wrap +msgid "" +"int mpo_check_socket_bind(struct ucred *cred, struct socket *socket,\n" +" struct label *socketlabel, struct sockaddr *sockaddr);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3514 +#, no-wrap +msgid "Socket to be bound" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3521 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3554 +#, no-wrap +msgid "`sockaddr`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3522 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3555 +#, no-wrap +msgid "Address of `socket`" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3526 +#, no-wrap +msgid "`mpo_check_socket_connect`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3532 +#, no-wrap +msgid "" +"int mpo_check_socket_connect(struct ucred *cred, struct socket *socket,\n" +" struct label *socketlabel, struct sockaddr *sockaddr);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3547 +#, no-wrap +msgid "Socket to be connected" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3561 +msgid "" +"Determine whether the subject credential (`cred`) can connect the passed " +"socket (`socket`) to the passed socket address (`sockaddr`). Return 0 for " +"success, or an `errno` value for failure. Suggested failure: EACCES for " +"label mismatches, EPERM for lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3563 +#, no-wrap +msgid "`mpo_check_socket_receive`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3569 +#, no-wrap +msgid "" +"int mpo_check_socket_receive(struct ucred *cred, struct socket *so,\n" +" struct label *socketlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3588 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3619 +#, no-wrap +msgid "Policy label associated with `so`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3592 +msgid "" +"Determine whether the subject should be allowed to receive information from " +"the socket `so`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3594 +#, no-wrap +msgid "`mpo_check_socket_send`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3600 +#, no-wrap +msgid "" +"int mpo_check_socket_send(struct ucred *cred, struct socket *so,\n" +" struct label *socketlabel);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3623 +msgid "" +"Determine whether the subject should be allowed to send information across " +"the socket `so`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3625 +#, no-wrap +msgid "`mpo_check_cred_visible`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3630 +#, no-wrap +msgid "int mpo_check_cred_visible(struct ucred *u1, struct ucred *u2);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3640 +#, no-wrap +msgid "`u1`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3644 +#, no-wrap +msgid "`u2`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3645 +#, no-wrap +msgid "Object credential" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3652 +msgid "" +"Determine whether the subject credential `u1` can \"see\" other subjects " +"with the passed subject credential `u2`. Return 0 for success, or an " +"`errno` value for failure. Suggested failure: EACCES for label mismatches, " +"EPERM for lack of privilege, or ESRCH to hide visibility. This call may be " +"made in a number of situations, including inter-process status sysctl's used " +"by `ps`, and in procfs lookups." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3654 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5128 +#, no-wrap +msgid "`mpo_check_socket_visible`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3660 +#, no-wrap +msgid "" +"int mpo_check_socket_visible(struct ucred *cred, struct socket *socket,\n" +" struct label *socketlabel);\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3683 +#, no-wrap +msgid "`mpo_check_ifnet_relabel`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3689 +#, no-wrap +msgid "" +"int mpo_check_ifnet_relabel(struct ucred *cred, struct ifnet *ifnet,\n" +" struct label *ifnetlabel, struct label *newlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3708 +#, no-wrap +msgid "Existing policy label for `ifnet`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3712 +#, no-wrap +msgid "Policy label update to later be applied to `ifnet`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3716 +msgid "" +"Determine whether the subject credential can relabel the passed network " +"interface to the passed label update." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3718 +#, no-wrap +msgid "`mpo_check_socket_relabel`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3724 +#, no-wrap +msgid "" +"int mpo_check_socket_relabel(struct ucred *cred, struct socket *socket,\n" +" struct label *socketlabel, struct label *newlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3743 +#, no-wrap +msgid "Existing policy label for `socket`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3747 +#, no-wrap +msgid "Label update to later be applied to `socketlabel`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3751 +msgid "" +"Determine whether the subject credential can relabel the passed socket to " +"the passed label update." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3753 +#, no-wrap +msgid "`mpo_check_cred_relabel`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3758 +#, no-wrap +msgid "int mpo_check_cred_relabel(struct ucred *cred, struct label *newlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3773 +#, no-wrap +msgid "Label update to later be applied to `cred`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3777 +msgid "" +"Determine whether the subject credential can relabel itself to the passed " +"label update." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3779 +#, no-wrap +msgid "`mpo_check_vnode_relabel`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3785 +#, no-wrap +msgid "" +"int mpo_check_vnode_relabel(struct ucred *cred, struct vnode *vp,\n" +" struct label *vnodelabel, struct label *newlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3800 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3898 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4000 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4090 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4161 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4198 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4550 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4587 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4657 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4691 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4724 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4765 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4813 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4850 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4887 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5032 +#, no-wrap +msgid "Object; vnode" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3808 +#, no-wrap +msgid "Policy label update to later be applied to `vp`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3812 +msgid "" +"Determine whether the subject credential can relabel the passed vnode to the " +"passed label update." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3814 +#, no-wrap +msgid "`mpo_check_mount_stat`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3820 +#, no-wrap +msgid "" +"int mpo_check_mount_stat(struct ucred *cred, struct mount *mp,\n" +" struct label *mountlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3835 +#, no-wrap +msgid "Object; file system mount" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3838 +#, no-wrap +msgid "`mountlabel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3839 +#, no-wrap +msgid "Policy label for `mp`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3846 +msgid "" +"Determine whether the subject credential can see the results of a statfs " +"performed on the file system. Return 0 for success, or an `errno` value for " +"failure. Suggested failure: EACCES for label mismatches or EPERM for lack " +"of privilege. This call may be made in a number of situations, including " +"during invocations of man:statfs[2] and related calls, as well as to " +"determine what file systems to exclude from listings of file systems, such " +"as when man:getfsstat[2] is invoked." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3848 +#, no-wrap +msgid "`mpo_check_proc_debug`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3853 +#, no-wrap +msgid "int mpo_check_proc_debug(struct ucred *cred, struct proc *proc);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3867 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4968 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4998 +#, no-wrap +msgid "`proc`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3868 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4969 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4999 +#, no-wrap +msgid "Object; process" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3875 +msgid "" +"Determine whether the subject credential can debug the passed process. " +"Return 0 for success, or an `errno` value for failure. Suggested failure: " +"EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to hide " +"visibility of the target. This call may be made in a number of situations, " +"including use of the man:ptrace[2] and man:ktrace[2] APIs, as well as for " +"some types of procfs operations." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3877 +#, no-wrap +msgid "`mpo_check_vnode_access`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3883 +#, no-wrap +msgid "" +"int mpo_check_vnode_access(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int flags);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3905 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4820 +#, no-wrap +msgid "`flags`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3906 +#, no-wrap +msgid "man:access[2] flags" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3913 +msgid "" +"Determine how invocations of man:access[2] and related calls by the subject " +"credential should return when performed on the passed vnode using the passed " +"access flags. This should generally be implemented using the same semantics " +"used in `mpo_check_vnode_open`. Return 0 for success, or an `errno` value " +"for failure. Suggested failure: EACCES for label mismatches or EPERM for " +"lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3915 +#, no-wrap +msgid "`mpo_check_vnode_chdir`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3921 +#, no-wrap +msgid "" +"int mpo_check_vnode_chdir(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3936 +#, no-wrap +msgid "Object; vnode to man:chdir[2] into" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3940 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4004 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4047 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4554 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4628 +#, no-wrap +msgid "Policy label for `dvp`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3946 +msgid "" +"Determine whether the subject credential can change the process working " +"directory to the passed vnode. Return 0 for success, or an `errno` value " +"for failure. Suggested failure: EACCES for label mismatch, or EPERM for " +"lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3948 +#, no-wrap +msgid "`mpo_check_vnode_chroot`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3954 +#, no-wrap +msgid "" +"int mpo_check_vnode_chroot(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3969 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4245 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4425 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4469 +#, no-wrap +msgid "Directory vnode" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3973 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4249 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4429 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4473 +#, no-wrap +msgid "Policy label associated with `dvp`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3977 +msgid "" +"Determine whether the subject should be allowed to man:chroot[2] into the " +"specified directory (`dvp`)." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3979 +#, no-wrap +msgid "`mpo_check_vnode_create`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3985 +#, no-wrap +msgid "" +"int mpo_check_vnode_create(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel, struct componentname *cnp, struct vattr *vap);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4008 +#, no-wrap +msgid "Component name for `dvp`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4011 +#, no-wrap +msgid "`vap`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4012 +#, no-wrap +msgid "vnode attributes for `vap`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4019 +msgid "" +"Determine whether the subject credential can create a vnode with the passed " +"parent directory, passed name information, and passed attribute " +"information. Return 0 for success, or an `errno` value for failure. " +"Suggested failure: EACCES for label mismatch, or EPERM for lack of " +"privilege. This call may be made in a number of situations, including as a " +"result of calls to man:open[2] with O_CREAT, man:mkfifo[2], and others." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4021 +#, no-wrap +msgid "`mpo_check_vnode_delete`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4028 +#, no-wrap +msgid "" +"int mpo_check_vnode_delete(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel, struct vnode *vp, void *label,\n" +" struct componentname *cnp);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4051 +#, no-wrap +msgid "Object; vnode to delete" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4067 +msgid "" +"Determine whether the subject credential can delete a vnode from the passed " +"parent directory and passed name information. Return 0 for success, or an " +"`errno` value for failure. Suggested failure: EACCES for label mismatch, or " +"EPERM for lack of privilege. This call may be made in a number of " +"situations, including as a result of calls to man:unlink[2] and " +"man:rmdir[2]. Policies implementing this entry point should also implement " +"`mpo_check_rename_to` to authorize deletion of objects as a result of being " +"the target of a rename." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4069 +#, no-wrap +msgid "`mpo_check_vnode_deleteacl`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4075 +#, no-wrap +msgid "" +"int mpo_check_vnode_deleteacl(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, acl_type_t type);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4097 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4168 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4731 +#, no-wrap +msgid "`type`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4098 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4169 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4732 +#, no-wrap +msgid "ACL type" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4104 +msgid "" +"Determine whether the subject credential can delete the ACL of passed type " +"from the passed vnode. Return 0 for success, or an `errno` value for " +"failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of " +"privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4106 +#, no-wrap +msgid "`mpo_check_vnode_exec`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4112 +#, no-wrap +msgid "" +"int mpo_check_vnode_exec(struct ucred *cred, struct vnode *vp,\n" +" struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4127 +#, no-wrap +msgid "Object; vnode to execute" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4138 +msgid "" +"Determine whether the subject credential can execute the passed vnode. " +"Determination of execute privilege is made separately from decisions about " +"any transitioning event. Return 0 for success, or an `errno` value for " +"failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of " +"privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4140 +#, no-wrap +msgid "`mpo_check_vnode_getacl`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4146 +#, no-wrap +msgid "" +"int mpo_check_vnode_getacl(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, acl_type_t type);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4175 +msgid "" +"Determine whether the subject credential can retrieve the ACL of passed type " +"from the passed vnode. Return 0 for success, or an `errno` value for " +"failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of " +"privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4177 +#, no-wrap +msgid "`mpo_check_vnode_getextattr`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4183 +#, no-wrap +msgid "" +"int mpo_check_vnode_getextattr(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int attrnamespace, const char *name, struct uio *uio);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4205 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4772 +#, no-wrap +msgid "`attrnamespace`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4206 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4773 +#, no-wrap +msgid "Extended attribute namespace" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4210 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4777 +#, no-wrap +msgid "Extended attribute name" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4213 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4780 +#, no-wrap +msgid "`uio`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4214 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4781 +#, no-wrap +msgid "I/O structure pointer; see man:uio[9]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4221 +msgid "" +"Determine whether the subject credential can retrieve the extended attribute " +"with the passed namespace and name from the passed vnode. Policies " +"implementing labeling using extended attributes may be interested in special " +"handling of operations on those extended attributes. Return 0 for success, " +"or an `errno` value for failure. Suggested failure: EACCES for label " +"mismatch, or EPERM for lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4223 +#, no-wrap +msgid "`mpo_check_vnode_link`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4230 +#, no-wrap +msgid "" +"int mpo_check_vnode_link(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel, struct vnode *vp, struct label *label,\n" +" struct componentname *cnp);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4253 +#, no-wrap +msgid "Link destination vnode" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4261 +#, no-wrap +msgid "Component name for the link being created" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4265 +msgid "" +"Determine whether the subject should be allowed to create a link to the " +"vnode `vp` with the name specified by `cnp`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4267 +#, no-wrap +msgid "`mpo_check_vnode_mmap`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4273 +#, no-wrap +msgid "" +"int mpo_check_vnode_mmap(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int prot);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4288 +#, no-wrap +msgid "Vnode to map" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4295 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4330 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4361 +#, no-wrap +msgid "`prot`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4296 +#, no-wrap +msgid "Mmap protections (see man:mmap[2])" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4300 +msgid "" +"Determine whether the subject should be allowed to map the vnode `vp` with " +"the protections specified in `prot`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4302 +#, no-wrap +msgid "`mpo_check_vnode_mmap_downgrade`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4308 +#, no-wrap +msgid "" +"void mpo_check_vnode_mmap_downgrade(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int *prot);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4319 +#, no-wrap +msgid "See crossref:mac[mac-mpo-check-vnode-mmap, `mpo_check_vnode_mmap`]." +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4331 +#, no-wrap +msgid "Mmap protections to be downgraded" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4335 +msgid "Downgrade the mmap protections based on the subject and object labels." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4337 +#, no-wrap +msgid "`mpo_check_vnode_mprotect`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4343 +#, no-wrap +msgid "" +"int mpo_check_vnode_mprotect(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int prot);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4358 +#, no-wrap +msgid "Mapped vnode" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4362 +#, no-wrap +msgid "Memory protections" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4366 +msgid "" +"Determine whether the subject should be allowed to set the specified memory " +"protections on memory mapped from the vnode `vp`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4368 +#, no-wrap +msgid "`mpo_check_vnode_poll`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4374 +#, no-wrap +msgid "" +"int mpo_check_vnode_poll(struct ucred *active_cred, struct ucred *file_cred,\n" +" struct vnode *vp, struct label *label);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4384 +#, no-wrap +msgid "`active_cred`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4388 +#, no-wrap +msgid "`file_cred`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4389 +#, no-wrap +msgid "Credential associated with the struct file" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4393 +#, no-wrap +msgid "Polled vnode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4401 +msgid "Determine whether the subject should be allowed to poll the vnode `vp`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4403 +#, no-wrap +msgid "`mpo_check_vnode_rename_from`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4410 +#, no-wrap +msgid "" +"int mpo_vnode_rename_from(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel, struct vnode *vp, struct label *label,\n" +" struct componentname *cnp);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4433 +#, no-wrap +msgid "Vnode to be renamed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4445 +msgid "" +"Determine whether the subject should be allowed to rename the vnode `vp` to " +"something else." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4447 +#, no-wrap +msgid "`mpo_check_vnode_rename_to`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4454 +#, no-wrap +msgid "" +"int mpo_check_vnode_rename_to(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel, struct vnode *vp, struct label *label, int samedir,\n" +" struct componentname *cnp);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4477 +#, no-wrap +msgid "Overwritten vnode" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4484 +#, no-wrap +msgid "`samedir`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4485 +#, no-wrap +msgid "Boolean; `1` if the source and destination directories are the same" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4489 +#, no-wrap +msgid "Destination component name" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4494 +msgid "" +"Determine whether the subject should be allowed to rename to the vnode `vp`, " +"into the directory `dvp`, or to the name represented by `cnp`. If there is " +"no existing file to overwrite, `vp` and `label` will be NULL." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4496 +#, no-wrap +msgid "`mpo_check_socket_listen`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4502 +#, no-wrap +msgid "" +"int mpo_check_socket_listen(struct ucred *cred, struct socket *socket,\n" +" struct label *socketlabel);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4527 +msgid "" +"Determine whether the subject credential can listen on the passed socket. " +"Return 0 for success, or an `errno` value for failure. Suggested failure: " +"EACCES for label mismatch, or EPERM for lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4529 +#, no-wrap +msgid "`mpo_check_vnode_lookup`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4535 +#, no-wrap +msgid "" +"int mpo_check_vnode_lookup(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel, struct componentname *cnp);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4558 +#, no-wrap +msgid "Component name being looked up" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4564 +msgid "" +"Determine whether the subject credential can perform a lookup in the passed " +"directory vnode for the passed name. Return 0 for success, or an `errno` " +"value for failure. Suggested failure: EACCES for label mismatch, or EPERM " +"for lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4566 +#, no-wrap +msgid "`mpo_check_vnode_open`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4572 +#, no-wrap +msgid "" +"int mpo_check_vnode_open(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int acc_mode);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4594 +#, no-wrap +msgid "`acc_mode`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4595 +#, no-wrap +msgid "man:open[2] access mode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4601 +msgid "" +"Determine whether the subject credential can perform an open operation on " +"the passed vnode with the passed access mode. Return 0 for success, or an " +"errno value for failure. Suggested failure: EACCES for label mismatch, or " +"EPERM for lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4603 +#, no-wrap +msgid "`mpo_check_vnode_readdir`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4609 +#, no-wrap +msgid "" +"int mpo_check_vnode_readdir(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4624 +#, no-wrap +msgid "Object; directory vnode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4634 +msgid "" +"Determine whether the subject credential can perform a `readdir` operation " +"on the passed directory vnode. Return 0 for success, or an `errno` value " +"for failure. Suggested failure: EACCES for label mismatch, or EPERM for " +"lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4636 +#, no-wrap +msgid "`mpo_check_vnode_readlink`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4642 +#, no-wrap +msgid "" +"int mpo_check_vnode_readlink(struct ucred *cred, struct vnode *vp,\n" +" struct label *label);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4668 +msgid "" +"Determine whether the subject credential can perform a `readlink` operation " +"on the passed symlink vnode. Return 0 for success, or an `errno` value for " +"failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of " +"privilege. This call may be made in a number of situations, including an " +"explicit `readlink` call by the user process, or as a result of an implicit " +"`readlink` during a name lookup by the process." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4670 +#, no-wrap +msgid "`mpo_check_vnode_revoke`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4676 +#, no-wrap +msgid "" +"int mpo_check_vnode_revoke(struct ucred *cred, struct vnode *vp,\n" +" struct label *label);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4701 +msgid "" +"Determine whether the subject credential can revoke access to the passed " +"vnode. Return 0 for success, or an `errno` value for failure. Suggested " +"failure: EACCES for label mismatch, or EPERM for lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4703 +#, no-wrap +msgid "`mpo_check_vnode_setacl`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4709 +#, no-wrap +msgid "" +"int mpo_check_vnode_setacl(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, acl_type_t type, struct acl *acl);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4735 +#, no-wrap +msgid "`acl`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4736 +#, no-wrap +msgid "ACL" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4742 +msgid "" +"Determine whether the subject credential can set the passed ACL of passed " +"type on the passed vnode. Return 0 for success, or an `errno` value for " +"failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of " +"privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4744 +#, no-wrap +msgid "`mpo_check_vnode_setextattr`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4750 +#, no-wrap +msgid "" +"int mpo_check_vnode_setextattr(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int attrnamespace, const char *name, struct uio *uio);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4790 +msgid "" +"Determine whether the subject credential can set the extended attribute of " +"passed name and passed namespace on the passed vnode. Policies implementing " +"security labels backed into extended attributes may want to provide " +"additional protections for those attributes. Additionally, policies should " +"avoid making decisions based on the data referenced from `uio`, as there is " +"a potential race condition between this check and the actual operation. The " +"`uio` may also be `NULL` if a delete operation is being performed. Return 0 " +"for success, or an `errno` value for failure. Suggested failure: EACCES for " +"label mismatch, or EPERM for lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4792 +#, no-wrap +msgid "`mpo_check_vnode_setflags`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4798 +#, no-wrap +msgid "" +"int mpo_check_vnode_setflags(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, u_long flags);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4821 +#, no-wrap +msgid "File flags; see man:chflags[2]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4827 +msgid "" +"Determine whether the subject credential can set the passed flags on the " +"passed vnode. Return 0 for success, or an `errno` value for failure. " +"Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4829 +#, no-wrap +msgid "`mpo_check_vnode_setmode`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4835 +#, no-wrap +msgid "" +"int mpo_check_vnode_setmode(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, mode_t mode);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4857 +#, no-wrap +msgid "`mode`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4858 +#, no-wrap +msgid "File mode; see man:chmod[2]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4864 +msgid "" +"Determine whether the subject credential can set the passed mode on the " +"passed vnode. Return 0 for success, or an `errno` value for failure. " +"Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4866 +#, no-wrap +msgid "`mpo_check_vnode_setowner`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4872 +#, no-wrap +msgid "" +"int mpo_check_vnode_setowner(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, uid_t uid, gid_t gid);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4894 +#, no-wrap +msgid "`uid`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4895 +#, no-wrap +msgid "User ID" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4898 +#, no-wrap +msgid "`gid`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4899 +#, no-wrap +msgid "Group ID" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4906 +msgid "" +"Determine whether the subject credential can set the passed uid and passed " +"gid as file uid and file gid on the passed vnode. The IDs may be set to " +"(`-1`) to request no update. Return 0 for success, or an `errno` value for " +"failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of " +"privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4908 +#, no-wrap +msgid "`mpo_check_vnode_setutimes`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4914 +#, no-wrap +msgid "" +"int mpo_check_vnode_setutimes(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, struct timespec atime, struct timespec mtime);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4929 +#, no-wrap +msgid "Object; vp" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4936 +#, no-wrap +msgid "`atime`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4937 +#, no-wrap +msgid "Access time; see man:utimes[2]" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4940 +#, no-wrap +msgid "`mtime`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4941 +#, no-wrap +msgid "Modification time; see man:utimes[2]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4947 +msgid "" +"Determine whether the subject credential can set the passed access " +"timestamps on the passed vnode. Return 0 for success, or an `errno` value " +"for failure. Suggested failure: EACCES for label mismatch, or EPERM for " +"lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4949 +#, no-wrap +msgid "`mpo_check_proc_sched`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4954 +#, no-wrap +msgid "int mpo_check_proc_sched(struct ucred *ucred, struct proc *proc);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4975 +msgid "" +"Determine whether the subject credential can change the scheduling " +"parameters of the passed process. Return 0 for success, or an `errno` value " +"for failure. Suggested failure: EACCES for label mismatch, EPERM for lack " +"of privilege, or ESRCH to limit visibility." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4977 +msgid "See man:setpriority[2] for more information." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4979 +#, no-wrap +msgid "`mpo_check_proc_signal`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4984 +#, no-wrap +msgid "int mpo_check_proc_signal(struct ucred *cred, struct proc *proc, int signal);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5002 +#, no-wrap +msgid "`signal`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5003 +#, no-wrap +msgid "Signal; see man:kill[2]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5009 +msgid "" +"Determine whether the subject credential can deliver the passed signal to " +"the passed process. Return 0 for success, or an `errno` value for failure. " +"Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, " +"or ESRCH to limit visibility." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5011 +#, no-wrap +msgid "`mpo_check_vnode_stat`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5017 +#, no-wrap +msgid "" +"int mpo_check_vnode_stat(struct ucred *cred, struct vnode *vp,\n" +" struct label *label);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5042 +msgid "" +"Determine whether the subject credential can `stat` the passed vnode. " +"Return 0 for success, or an `errno` value for failure. Suggested failure: " +"EACCES for label mismatch, or EPERM for lack of privilege." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5044 +msgid "See man:stat[2] for more information." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5046 +#, no-wrap +msgid "`mpo_check_ifnet_transmit`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5052 +#, no-wrap +msgid "" +"int mpo_check_ifnet_transmit(struct ucred *cred, struct ifnet *ifnet,\n" +" struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5075 +#, no-wrap +msgid "Object; mbuf to be sent" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5085 +msgid "" +"Determine whether the network interface can transmit the passed mbuf. " +"Return 0 for success, or an `errno` value for failure. Suggested failure: " +"EACCES for label mismatch, or EPERM for lack of privilege." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5087 +#, no-wrap +msgid "`mpo_check_socket_deliver`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5093 +#, no-wrap +msgid "" +"int mpo_check_socket_deliver(struct ucred *cred, struct ifnet *ifnet,\n" +" struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5116 +#, no-wrap +msgid "Object; mbuf to be delivered" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5126 +msgid "" +"Determine whether the socket may receive the datagram stored in the passed " +"mbuf header. Return 0 for success, or an `errno` value for failure. " +"Suggested failures: EACCES for label mismatch, or EPERM for lack of " +"privilege." +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5134 +#, no-wrap +msgid "" +"int mpo_check_socket_visible(struct ucred *cred, struct socket *so,\n" +" struct label *socketlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5153 +#, no-wrap +msgid "Policy label for `so`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5159 +msgid "" +"Determine whether the subject credential cred can \"see\" the passed socket " +"(`socket`) using system monitoring functions, such as those employed by " +"man:netstat[8] and man:sockstat[1]. Return 0 for success, or an `errno` " +"value for failure. Suggested failure: EACCES for label mismatches, EPERM " +"for lack of privilege, or ESRCH to hide visibility." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5161 +#, no-wrap +msgid "`mpo_check_system_acct`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5167 +#, no-wrap +msgid "" +"int mpo_check_system_acct(struct ucred *ucred, struct vnode *vp,\n" +" struct label *vlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5177 +#, no-wrap +msgid "`ucred`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5182 +#, no-wrap +msgid "Accounting file; man:acct[5]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5190 +msgid "" +"Determine whether the subject should be allowed to enable accounting, based " +"on its label and the label of the accounting log file." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5192 +#, no-wrap +msgid "`mpo_check_system_nfsd`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5197 +#, no-wrap +msgid "int mpo_check_system_nfsd(struct ucred *cred);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5212 +msgid "Determine whether the subject should be allowed to call man:nfssvc[2]." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5214 +#, no-wrap +msgid "`mpo_check_system_reboot`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5219 +#, no-wrap +msgid "int mpo_check_system_reboot(struct ucred *cred, int howto);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5233 +#, no-wrap +msgid "`howto`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5234 +#, no-wrap +msgid "`howto` parameter from man:reboot[2]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5238 +msgid "" +"Determine whether the subject should be allowed to reboot the system in the " +"specified manner." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5240 +#, no-wrap +msgid "`mpo_check_system_settime`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5245 +#, no-wrap +msgid "int mpo_check_system_settime(struct ucred *cred);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5260 +msgid "Determine whether the user should be allowed to set the system clock." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5262 +#, no-wrap +msgid "`mpo_check_system_swapon`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5268 +#, no-wrap +msgid "" +"int mpo_check_system_swapon(struct ucred *cred, struct vnode *vp,\n" +" struct label *vlabel);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5283 +#, no-wrap +msgid "Swap device" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5291 +msgid "" +"Determine whether the subject should be allowed to add `vp` as a swap device." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5293 +#, no-wrap +msgid "`mpo_check_system_sysctl`" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5299 +#, no-wrap +msgid "" +"int mpo_check_system_sysctl(struct ucred *cred, int *name, u_int *namelen,\n" +" void *old, size_t *oldlenp, int inkernel, void *new, size_t newlen);\n" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5314 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5334 +#, no-wrap +msgid "See man:sysctl[3]" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5325 +#, no-wrap +msgid "`oldlenp`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5329 +#, no-wrap +msgid "`inkernel`" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5330 +#, no-wrap +msgid "Boolean; `1` if called from kernel" +msgstr "" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5337 +#, no-wrap +msgid "`newlen`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5342 +msgid "" +"Determine whether the subject should be allowed to make the specified " +"man:sysctl[3] transaction." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5344 +#, no-wrap +msgid "Label Management Calls" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5350 +msgid "" +"Relabel events occur when a user process has requested that the label on an " +"object be modified. A two-phase update occurs: first, an access control " +"check will be performed to determine if the update is both valid and " +"permitted, and then the update itself is performed via a separate entry " +"point. Relabel entry points typically accept the object, object label " +"reference, and an update label submitted by the process. Memory allocation " +"during relabel is discouraged, as relabel calls are not permitted to fail " +"(failure should be reported earlier in the relabel check)." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5352 +#, no-wrap +msgid "Userland Architecture" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5356 +msgid "" +"The TrustedBSD MAC Framework includes a number of policy-agnostic elements, " +"including MAC library interfaces for abstractly managing labels, " +"modifications to the system credential management and login libraries to " +"support the assignment of MAC labels to users, and a set of tools to monitor " +"and modify labels on processes, files, and network interfaces. More details " +"on the user architecture will be added to this section in the near future." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5358 +#, no-wrap +msgid "APIs for Policy-Agnostic Label Management" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5365 +msgid "" +"The TrustedBSD MAC Framework provides a number of library and system calls " +"permitting applications to manage MAC labels on objects using a policy-" +"agnostic interface. This permits applications to manipulate labels for a " +"variety of policies without being written to support specific policies. " +"These interfaces are used by general-purpose tools such as man:ifconfig[8], " +"man:ls[1] and man:ps[1] to view labels on network interfaces, files, and " +"processes. The APIs also support MAC management tools including " +"man:getfmac[8], man:getpmac[8], man:setfmac[8], man:setfsmac[8], and " +"man:setpmac[8]. The MAC APIs are documented in man:mac[3]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5373 +msgid "" +"Applications handle MAC labels in two forms: an internalized form used to " +"return and set labels on processes and objects (`mac_t`), and externalized " +"form based on C strings appropriate for storage in configuration files, " +"display to the user, or input from the user. Each MAC label contains a " +"number of elements, each consisting of a name and value pair. Policy " +"modules in the kernel bind to specific names and interpret the values in " +"policy-specific ways. In the externalized string form, labels are " +"represented by a comma-delimited list of name and value pairs separated by " +"the `/` character. Labels may be directly converted to and from text using " +"provided APIs; when retrieving labels from the kernel, internalized label " +"storage must first be prepared for the desired label element set. " +"Typically, this is done in one of two ways: using man:mac_prepare[3] and an " +"arbitrary list of desired label elements, or one of the variants of the call " +"that loads a default element set from the man:mac.conf[5] configuration " +"file. Per-object defaults permit application writers to usefully display " +"labels associated with objects without being aware of the policies present " +"in the system." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5378 +msgid "" +"Currently, direct manipulation of label elements other than by conversion to " +"a text string, string editing, and conversion back to an internalized label " +"is not supported by the MAC library. Such interfaces may be added in the " +"future if they prove necessary for application writers." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5381 +#, no-wrap +msgid "Binding of Labels to Users" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5385 +msgid "" +"The standard user context management interface, man:setusercontext[3], has " +"been modified to retrieve MAC labels associated with a user's class from " +"man:login.conf[5]. These labels are then set along with other user context " +"when either `LOGIN_SETALL` is specified, or when `LOGIN_SETMAC` is " +"explicitly specified." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5390 +msgid "" +"It is expected that, in a future version of FreeBSD, the MAC label database " +"will be separated from the [.filename]#login.conf# user class abstraction, " +"and be maintained in a separate database. However, the " +"man:setusercontext[3] API should remain the same following such a change." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5393 +#, no-wrap +msgid "Conclusion" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5398 +msgid "" +"The TrustedBSD MAC framework permits kernel modules to augment the system " +"security policy in a highly integrated manner. They may do this based on " +"existing object properties, or based on label data that is maintained with " +"the assistance of the MAC framework. The framework is sufficiently flexible " +"to implement a variety of policy types, including information flow security " +"policies such as MLS and Biba, as well as policies based on existing BSD " +"credentials or file protections. Policy authors may wish to consult this " +"documentation as well as existing security modules when implementing a new " +"security service." +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/newbus/_index.adoc b/documentation/content/en/books/arch-handbook/newbus/_index.adoc index 4457a08aca..07eb0a120d 100644 --- a/documentation/content/en/books/arch-handbook/newbus/_index.adoc +++ b/documentation/content/en/books/arch-handbook/newbus/_index.adoc @@ -11,7 +11,8 @@ description: Newbus tags: ["Newbus", "overview", "API"] showBookMenu: true weight: 16 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/newbus/" --- [[newbus]] diff --git a/documentation/content/en/books/arch-handbook/newbus/_index.po b/documentation/content/en/books/arch-handbook/newbus/_index.po new file mode 100644 index 0000000000..719896caaf --- /dev/null +++ b/documentation/content/en/books/arch-handbook/newbus/_index.po @@ -0,0 +1,531 @@ +# 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/newbus/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:19 +#, no-wrap +msgid "Newbus" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:1 +#, no-wrap +msgid "Chapter 14. Newbus" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:57 +msgid "" +"_Special thanks to Matthew N. Dodd, Warner Losh, Bill Paul, Doug Rabson, " +"Mike Smith, Peter Wemm and Scott Long_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:59 +msgid "This chapter explains the Newbus device framework in detail." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:61 +#, no-wrap +msgid "Device Drivers" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:63 +#, no-wrap +msgid "Purpose of a Device Driver" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:66 +msgid "" +"A device driver is a software component which provides the interface between " +"the kernel's generic view of a peripheral (e.g., disk, network adapter) and " +"the actual implementation of the peripheral. The _device driver interface " +"(DDI)_ is the defined interface between the kernel and the device driver " +"component." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:67 +#, no-wrap +msgid "Types of Device Drivers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:70 +msgid "" +"There used to be days in UNIX(R), and thus FreeBSD, in which there were four " +"types of devices defined:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:72 +msgid "block device drivers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:73 +msgid "character device drivers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:74 +msgid "network device drivers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:75 +msgid "pseudo-device drivers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:77 +msgid "" +"_Block devices_ performed in a way that used fixed size blocks [of data]. " +"This type of driver depended on the so-called _buffer cache_, which had " +"cached accessed blocks of data in a dedicated part of memory. Often this " +"buffer cache was based on write-behind, which meant that when data was " +"modified in memory it got synced to disk whenever the system did its " +"periodical disk flushing, thus optimizing writes." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:78 +#, no-wrap +msgid "Character Devices" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:81 +msgid "" +"However, in the versions of FreeBSD 4.0 and onward the distinction between " +"block and character devices became non-existent." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:83 +#, no-wrap +msgid "Overview of Newbus" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:86 +msgid "" +"_Newbus_ is the implementation of a new bus architecture based on " +"abstraction layers which saw its introduction in FreeBSD 3.0 when the Alpha " +"port was imported into the source tree. It was not until 4.0 before it " +"became the default system to use for device drivers. Its goals are to " +"provide a more object-oriented means of interconnecting the various busses " +"and devices which a host system provides to the _Operating System_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:88 +msgid "Its main features include amongst others:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:90 +msgid "dynamic attaching" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:91 +msgid "easy modularization of drivers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:92 +msgid "pseudo-busses" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:94 +msgid "" +"One of the most prominent changes is the migration from the flat and ad-hoc " +"system to a device tree layout." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:96 +msgid "" +"At the top level resides the _\"root\"_ device which is the parent to hang " +"all other devices on. For each architecture, there is typically a single " +"child of \"root\" which has such things as _host-to-PCI bridges_, etc. " +"attached to it. For x86, this \"root\" device is the _\"nexus\"_ device. For " +"Alpha, various different models of Alpha have different top-level devices " +"corresponding to the different hardware chipsets, including _lca_, _apecs_, " +"_cia_ and _tsunami_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:98 +msgid "" +"A device in the Newbus context represents a single hardware entity in the " +"system. For instance each PCI device is represented by a Newbus device. Any " +"device in the system can have children; a device which has children is often " +"called a _\"bus\"_. Examples of common busses in the system are ISA and PCI, " +"which manage lists of devices attached to ISA and PCI busses respectively." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:100 +msgid "" +"Often, a connection between different kinds of bus is represented by a " +"_\"bridge\"_ device, which normally has one child for the attached bus. An " +"example of this is a _PCI-to-PCI bridge_ which is represented by a device " +"_[.filename]#pcibN#_ on the parent PCI bus and has a child " +"_[.filename]#pciN#_ for the attached bus. This layout simplifies the " +"implementation of the PCI bus tree, allowing common code to be used for both " +"top-level and bridged busses." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:102 +msgid "" +"Each device in the Newbus architecture asks its parent to map its resources. " +"The parent then asks its own parent until the nexus is reached. So, " +"basically the nexus is the only part of the Newbus system which knows about " +"all resources." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:106 +msgid "" +"An ISA device might want to map its IO port at `0x230`, so it asks its " +"parent, in this case the ISA bus. The ISA bus hands it over to the PCI-to-" +"ISA bridge which in its turn asks the PCI bus, which reaches the host-to-PCI " +"bridge and finally the nexus. The beauty of this transition upwards is that " +"there is room to translate the requests. For example, the `0x230` IO port " +"request might become memory-mapped at `0xb0000230` on a MIPS box by the PCI " +"bridge." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:109 +msgid "" +"Resource allocation can be controlled at any place in the device tree. For " +"instance on many Alpha platforms, ISA interrupts are managed separately from " +"PCI interrupts and resource allocations for ISA interrupts are managed by " +"the Alpha's ISA bus device. On IA-32, ISA and PCI interrupts are both " +"managed by the top-level nexus device. For both ports, memory and port " +"address space is managed by a single entity - nexus for IA-32 and the " +"relevant chipset driver on Alpha (e.g., CIA or tsunami)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:111 +msgid "" +"In order to normalize access to memory and port mapped resources, Newbus " +"integrates the `bus_space` APIs from NetBSD. These provide a single API to " +"replace inb/outb and direct memory reads/writes. The advantage of this is " +"that a single driver can easily use either memory-mapped registers or port-" +"mapped registers (some hardware supports both)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:113 +msgid "" +"This support is integrated into the resource allocation mechanism. When a " +"resource is allocated, a driver can retrieve the associated " +"`bus_space_tag_t` and `bus_space_handle_t` from the resource." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:115 +msgid "" +"Newbus also allows for definitions of interface methods in files dedicated " +"to this purpose. These are the [.filename]#.m# files that are found under " +"the [.filename]#src/sys# hierarchy." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:117 +msgid "" +"The core of the Newbus system is an extensible \"object-based programming\" " +"model. Each device in the system has a table of methods which it supports. " +"The system and other devices uses those methods to control the device and " +"request services. The different methods supported by a device are defined by " +"a number of \"interfaces\". An \"interface\" is simply a group of related " +"methods which can be implemented by a device." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:119 +msgid "" +"In the Newbus system, the methods for a device are provided by the various " +"device drivers in the system. When a device is attached to a driver during " +"_auto-configuration_, it uses the method table declared by the driver. A " +"device can later _detach_ from its driver and _re-attach_ to a new driver " +"with a new method table. This allows dynamic replacement of drivers which " +"can be useful for driver development." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:121 +msgid "" +"The interfaces are described by an interface definition language similar to " +"the language used to define vnode operations for file systems. The interface " +"would be stored in a methods file (which would normally be named " +"[.filename]#foo_if.m#)." +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:122 +#, no-wrap +msgid "Newbus Methods" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:128 +#, no-wrap +msgid " # Foo subsystem/driver (a comment...)\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:130 +#, no-wrap +msgid "\t INTERFACE foo\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:134 +#, no-wrap +msgid "" +"\tMETHOD int doit {\n" +"\t\tdevice_t dev;\n" +"\t};\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:137 +#, no-wrap +msgid "" +"\t# DEFAULT is the method that will be used, if a method was not\n" +"\t# provided via: DEVMETHOD()\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:142 +#, no-wrap +msgid "" +"\tMETHOD void doit_to_child {\n" +"\t\tdevice_t dev;\n" +"\t\tdriver_t child;\n" +"\t} DEFAULT doit_generic_to_child;\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:146 +msgid "" +"When this interface is compiled, it generates a header file " +"\"[.filename]#foo_if.h#\" which contains function declarations:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:151 +#, no-wrap +msgid "" +" int FOO_DOIT(device_t dev);\n" +" int FOO_DOIT_TO_CHILD(device_t dev, device_t child);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:154 +msgid "" +"A source file, \"[.filename]#foo_if.c#\" is also created to accompany the " +"automatically generated header file; it contains implementations of those " +"functions which look up the location of the relevant functions in the " +"object's method table and call that function." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:156 +msgid "" +"The system defines two main interfaces. The first fundamental interface is " +"called _\"device\"_ and includes methods which are relevant to all devices. " +"Methods in the _\"device\"_ interface include _\"probe\"_, _\"attach\"_ and " +"_\"detach\"_ to control detection of hardware and _\"shutdown\"_, " +"_\"suspend\"_ and _\"resume\"_ for critical event notification." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:158 +msgid "" +"The second, more complex interface is _\"bus\"_. This interface contains " +"methods suitable for devices which have children, including methods to " +"access bus specific per-device information footnote:" +"[man:bus_generic_read_ivar[9] and man:bus_generic_write_ivar[9]], event " +"notification (`_child_detached_`, `_driver_added_`) and resource management " +"(`_alloc_resource_`, `_activate_resource_`, `_deactivate_resource_`, " +"`_release_resource_`)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:160 +msgid "" +"Many methods in the \"bus\" interface are performing services for some child " +"of the bus device. These methods would normally use the first two arguments " +"to specify the bus providing the service and the child device which is " +"requesting the service. To simplify driver code, many of these methods have " +"accessor functions which lookup the parent and call a method on the parent. " +"For instance the method `BUS_TEARDOWN_INTR(device_t dev, device_t " +"child, ...)` can be called using the function `bus_teardown_intr(device_t " +"child, ...)`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:162 +msgid "" +"Some bus types in the system define additional interfaces to provide access " +"to bus-specific functionality. For instance, the PCI bus driver defines the " +"\"pci\" interface which has two methods `_read_config_` and `_write_config_` " +"for accessing the configuration registers of a PCI device." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:164 +#, no-wrap +msgid "Newbus API" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:167 +msgid "" +"As the Newbus API is huge, this section makes some effort at documenting it. " +"More information to come in the next revision of this document." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:168 +#, no-wrap +msgid "Important Locations in the Source Hierarchy" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:171 +msgid "" +"[.filename]#src/sys/[arch]/[arch]# - Kernel code for a specific machine " +"architecture resides in this directory. For example, the `i386` " +"architecture, or the `SPARC64` architecture." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:173 +msgid "" +"[.filename]#src/sys/dev/[bus]# - device support for a specific `[bus]` " +"resides in this directory." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:175 +msgid "" +"[.filename]#src/sys/dev/pci# - PCI bus support code resides in this " +"directory." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:177 +msgid "" +"[.filename]#src/sys/[isa|pci]# - PCI/ISA device drivers reside in this " +"directory. The PCI/ISA bus support code used to exist in this directory in " +"FreeBSD version `4.0`." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:178 +#, no-wrap +msgid "Important Structures and Type Definitions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:181 +msgid "" +"`devclass_t` - This is a type definition of a pointer to a `struct devclass`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:183 +msgid "" +"`device_method_t` - This is the same as `kobj_method_t` (see [.filename]#src/" +"sys/kobj.h#)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:185 +msgid "" +"`device_t` - This is a type definition of a pointer to a `struct device`. " +"`device_t` represents a device in the system. It is a kernel object. See " +"[.filename]#src/sys/sys/bus_private.h# for implementation details." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:187 +msgid "" +"`driver_t` - This is a type definition which references `struct driver`. The " +"`driver` struct is a class of the `device` kernel object; it also holds data " +"private to the driver." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:189 +#, no-wrap +msgid "*_driver_t_ Implementation*\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:195 +#, no-wrap +msgid "" +"\t struct driver {\n" +"\t\tKOBJ_CLASS_FIELDS;\n" +"\t\tvoid\t*priv;\t\t\t/* driver private data */\n" +"\t };\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:198 +msgid "" +"A `device_state_t` type, which is an enumeration, `device_state`. It " +"contains the possible states of a Newbus device before and after the " +"autoconfiguration process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:200 +#, no-wrap +msgid "*Device States _device_state_t*\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:211 +#, no-wrap +msgid "" +"\t /*\n" +"\t * src/sys/sys/bus.h\n" +"\t */\n" +"\t typedef enum device_state {\n" +"\t\tDS_NOTPRESENT,\t/* not probed or probe failed */\n" +"\t\tDS_ALIVE,\t\t/* probe succeeded */\n" +"\t\tDS_ATTACHED,\t/* attach method called */\n" +"\t\tDS_BUSY\t\t\t/* device is open */\n" +"\t } device_state_t;\n" +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/parti.adoc b/documentation/content/en/books/arch-handbook/parti.adoc index b86632b2be..c094b1be5d 100644 --- a/documentation/content/en/books/arch-handbook/parti.adoc +++ b/documentation/content/en/books/arch-handbook/parti.adoc @@ -4,7 +4,9 @@ prev: books/arch-handbook next: books/arch-handbook/boot showBookMenu: true weight: 1 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/parti/" +BundleType: branch --- [[kernel]] diff --git a/documentation/content/en/books/arch-handbook/parti.po b/documentation/content/en/books/arch-handbook/parti.po new file mode 100644 index 0000000000..e467ec08e6 --- /dev/null +++ b/documentation/content/en/books/arch-handbook/parti.po @@ -0,0 +1,29 @@ +# 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: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/parti.adoc:1 +#, no-wrap +msgid "Part I. Kernel" +msgstr "" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/parti.adoc:13 +#, no-wrap +msgid "Kernel" +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/partii.adoc b/documentation/content/en/books/arch-handbook/partii.adoc index 0203b4e249..7b4a98c25a 100644 --- a/documentation/content/en/books/arch-handbook/partii.adoc +++ b/documentation/content/en/books/arch-handbook/partii.adoc @@ -4,7 +4,8 @@ prev: books/arch-handbook/smp next: books/arch-handbook/driverbasics showBookMenu: true weight: 10 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/partii/" --- [[devicedrivers]] diff --git a/documentation/content/en/books/arch-handbook/partii.po b/documentation/content/en/books/arch-handbook/partii.po new file mode 100644 index 0000000000..87be6cbe8e --- /dev/null +++ b/documentation/content/en/books/arch-handbook/partii.po @@ -0,0 +1,29 @@ +# 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: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/partii.adoc:1 +#, no-wrap +msgid "Part II. Device Drivers" +msgstr "" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/partii.adoc:12 +#, no-wrap +msgid "Device Drivers" +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/partiii.adoc b/documentation/content/en/books/arch-handbook/partiii.adoc index 67152e4836..6faa17a9f2 100644 --- a/documentation/content/en/books/arch-handbook/partiii.adoc +++ b/documentation/content/en/books/arch-handbook/partiii.adoc @@ -4,7 +4,8 @@ prev: books/arch-handbook/pccard next: books/arch-handbook/bibliography showBookMenu: true weight: 19 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/partiii/" --- [[appendices]] diff --git a/documentation/content/en/books/arch-handbook/partiii.po b/documentation/content/en/books/arch-handbook/partiii.po new file mode 100644 index 0000000000..ac563f7d46 --- /dev/null +++ b/documentation/content/en/books/arch-handbook/partiii.po @@ -0,0 +1,29 @@ +# 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: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/partiii.adoc:1 +#, no-wrap +msgid "Part III. Appendices" +msgstr "" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/partiii.adoc:12 +#, no-wrap +msgid "Appendices" +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/pccard/_index.adoc b/documentation/content/en/books/arch-handbook/pccard/_index.adoc index 26df7323b9..f608c63e55 100644 --- a/documentation/content/en/books/arch-handbook/pccard/_index.adoc +++ b/documentation/content/en/books/arch-handbook/pccard/_index.adoc @@ -6,7 +6,8 @@ description: PC Card tags: ["pc card", "overview"] showBookMenu: true weight: 18 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/pccard/" --- [[pccard]] diff --git a/documentation/content/en/books/arch-handbook/pccard/_index.po b/documentation/content/en/books/arch-handbook/pccard/_index.po new file mode 100644 index 0000000000..16fba83ec3 --- /dev/null +++ b/documentation/content/en/books/arch-handbook/pccard/_index.po @@ -0,0 +1,483 @@ +# 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/pccard/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:14 +#, no-wrap +msgid "PC Card" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:1 +#, no-wrap +msgid "Chapter 16. PC Card" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:52 +msgid "" +"This chapter will talk about the FreeBSD mechanisms for writing a device " +"driver for a PC Card or CardBus device. However, at present it just " +"documents how to add a new device to an existing pccard driver." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:54 +#, no-wrap +msgid "Adding a Device" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:57 +msgid "" +"Device drivers know what devices they support. There is a table of supported " +"devices in the kernel that drivers use to attach to a device." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:59 +#, no-wrap +msgid "Overview" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:62 +msgid "" +"PC Cards are identified in one of two ways, both based on the _Card " +"Information Structure_ (CIS) stored on the card. The first method is to use " +"numeric manufacturer and product numbers. The second method is to use the " +"human readable strings that are also contained in the CIS. The PC Card bus " +"uses a centralized database and some macros to facilitate a design pattern " +"to help the driver writer match devices to his driver." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:64 +msgid "" +"Original equipment manufacturers (OEMs) often develop a reference design for " +"a PC Card product, then sell this design to other companies to market. Those " +"companies refine the design, market the product to their target audience or " +"geographic area, and put their own name plate onto the card. The refinements " +"to the physical card are typically very minor, if any changes are made at " +"all. To strengthen their brand, these vendors place their company name in " +"the human readable strings in the CIS space, but leave the manufacturer and " +"product IDs unchanged." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:66 +msgid "" +"Due to this practice, FreeBSD drivers usually rely on numeric IDs for device " +"identification. Using numeric IDs and a centralized database complicates " +"adding IDs and support for cards to the system. One must carefully check to " +"see who really made the card, especially when it appears that the vendor who " +"made the card might already have a different manufacturer ID listed in the " +"central database. Linksys, D-Link, and NetGear are a number of US " +"manufacturers of LAN hardware that often sell the same design. These same " +"designs can be sold in Japan under names such as Buffalo and Corega. Often, " +"these devices will all have the same manufacturer and product IDs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:68 +msgid "" +"The PC Card bus code keeps a central database of card information, but not " +"which driver is associated with them, in [.filename]#/sys/dev/pccard/" +"pccarddevs#. It also provides a set of macros that allow one to easily " +"construct simple entries in the table the driver uses to claim devices." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:70 +msgid "" +"Finally, some really low end devices do not contain manufacturer " +"identification at all. These devices must be detected by matching the human " +"readable CIS strings. While it would be nice if we did not need this method " +"as a fallback, it is necessary for some very low end CD-ROM players and " +"Ethernet cards. This method should generally be avoided, but a number of " +"devices are listed in this section because they were added prior to the " +"recognition of the OEM nature of the PC Card business. When adding new " +"devices, prefer using the numeric method." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:72 +#, no-wrap +msgid "Format of [.filename]#pccarddevs#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:75 +msgid "" +"There are four sections in the [.filename]#pccarddevs# files. The first " +"section lists the manufacturer numbers for vendors that use them. This " +"section is sorted in numerical order. The next section has all of the " +"products that are used by these vendors, along with their product ID numbers " +"and a description string. The description string typically is not used " +"(instead we set the device's description based on the human readable CIS, " +"even if we match on the numeric version). These two sections are then " +"repeated for devices that use the string matching method. Finally, C-style " +"comments enclosed in `/*` and `*/` characters are allowed anywhere in the " +"file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:77 +msgid "" +"The first section of the file contains the vendor IDs. Please keep this list " +"sorted in numeric order. Also, please coordinate changes to this file " +"because we share it with NetBSD to help facilitate a common clearing house " +"for this information. For example, here are the first few vendor IDs:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:84 +#, no-wrap +msgid "" +"vendor FUJITSU\t\t\t0x0004 Fujitsu Corporation\n" +"vendor NETGEAR_2\t\t0x000b Netgear\n" +"vendor PANASONIC\t\t0x0032\tMatsushita Electric Industrial Co.\n" +"vendor SANDISK\t\t\t0x0045\tSandisk Corporation\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:87 +msgid "" +"Chances are very good that the `NETGEAR_2` entry is really an OEM that " +"NETGEAR purchased cards from and the author of support for those cards was " +"unaware at the time that Netgear was using someone else's ID. These entries " +"are fairly straightforward. The vendor keyword denotes the kind of line that " +"this is, followed by the name of the vendor. This name will be repeated " +"later in [.filename]#pccarddevs#, as well as used in the driver's match " +"tables, so keep it short and a valid C identifier. A numeric ID in hex " +"identifies the manufacturer. Do not add IDs of the form `0xffffffff` or " +"`0xffff` because these are reserved IDs (the former is \"no ID set\" while " +"the latter is sometimes seen in extremely poor quality cards to try to " +"indicate \"none\"). Finally there is a string description of the company " +"that makes the card. This string is not used in FreeBSD for anything but " +"commentary purposes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:89 +msgid "" +"The second section of the file contains the products. As shown in this " +"example, the format is similar to the vendor lines:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:94 +#, no-wrap +msgid "" +"/* Allied Telesis K.K. */\n" +"product ALLIEDTELESIS LA_PCM\t0x0002 Allied Telesis LA-PCM\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:97 +#, no-wrap +msgid "" +"/* Archos */\n" +"product\tARCHOS ARC_ATAPI\t0x0043 MiniCD\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:100 +msgid "" +"The `product` keyword is followed by the vendor name, repeated from above. " +"This is followed by the product name, which is used by the driver and should " +"be a valid C identifier, but may also start with a number. As with the " +"vendors, the hex product ID for this card follows the same convention for " +"`0xffffffff` and `0xffff`. Finally, there is a string description of the " +"device itself. This string typically is not used in FreeBSD, since FreeBSD's " +"pccard bus driver will construct a string from the human readable CIS " +"entries, but it can be used in the rare cases where this is somehow " +"insufficient. The products are in alphabetical order by manufacturer, then " +"numerical order by product ID. They have a C comment before each " +"manufacturer's entries and there is a blank line between entries." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:102 +msgid "" +"The third section is like the previous vendor section, but with all of the " +"manufacturer numeric IDs set to `-1`, meaning \"match anything found\" in " +"the FreeBSD pccard bus code. Since these are C identifiers, their names must " +"be unique. Otherwise the format is identical to the first section of the " +"file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:104 +msgid "" +"The final section contains the entries for those cards that must be " +"identified by string entries. This section's format is a little different " +"from the generic section:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:109 +#, no-wrap +msgid "" +"product ADDTRON AWP100\t\t{ \"Addtron\", \"AWP-100&spWireless&spPCMCIA\", \"Version&sp01.02\", NULL }\n" +"product ALLIEDTELESIS WR211PCM\t{ \"Allied&spTelesis&spK.K.\", \"WR211PCM\", NULL, NULL } Allied Telesis WR211PCM\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:112 +msgid "" +"The familiar `product` keyword is followed by the vendor name and the card " +"name, just as in the second section of the file. Here the format deviates " +"from that used earlier. There is a {} grouping, followed by a number of " +"strings. These strings correspond to the vendor, product, and extra " +"information that is defined in a CIS_INFO tuple. These strings are filtered " +"by the program that generates [.filename]#pccarddevs.h# to replace &sp with " +"a real space. NULL strings mean that the corresponding part of the entry " +"should be ignored. The example shown here contains a bad entry. It should " +"not contain the version number unless that is critical for the operation of " +"the card. Sometimes vendors will have many different versions of the card in " +"the field that all work, in which case that information only makes it harder " +"for someone with a similar card to use it with FreeBSD. Sometimes it is " +"necessary when a vendor wishes to sell many different parts under the same " +"brand due to market considerations (availability, price, and so forth). Then " +"it can be critical to disambiguating the card in those rare cases where the " +"vendor kept the same manufacturer/product pair. Regular expression matching " +"is not available at this time." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:114 +#, no-wrap +msgid "Sample Probe Routine" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:117 +msgid "" +"To understand how to add a device to the list of supported devices, one must " +"understand the probe and/or match routines that many drivers have. It is " +"complicated a little in FreeBSD 5.x because there is a compatibility layer " +"for OLDCARD present as well. Since only the window-dressing is different, an " +"idealized version will be presented here." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:127 +#, no-wrap +msgid "" +"static const struct pccard_product wi_pccard_products[] = {\n" +"\tPCMCIA_CARD(3COM, 3CRWE737A, 0),\n" +"\tPCMCIA_CARD(BUFFALO, WLI_PCM_S11, 0),\n" +"\tPCMCIA_CARD(BUFFALO, WLI_CF_S11G, 0),\n" +"\tPCMCIA_CARD(TDK, LAK_CD011WL, 0),\n" +"\t{ NULL }\n" +"};\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:133 +#, no-wrap +msgid "" +"static int\n" +"wi_pccard_probe(dev)\n" +"\tdevice_t\tdev;\n" +"{\n" +"\tconst struct pccard_product *pp;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:142 +#, no-wrap +msgid "" +"\tif ((pp = pccard_product_lookup(dev, wi_pccard_products,\n" +"\t sizeof(wi_pccard_products[0]), NULL)) != NULL) {\n" +"\t\tif (pp->pp_name != NULL)\n" +"\t\t\tdevice_set_desc(dev, pp->pp_name);\n" +"\t\treturn (0);\n" +"\t}\n" +"\treturn (ENXIO);\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:145 +msgid "" +"Here we have a simple pccard probe routine that matches a few devices. As " +"stated above, the name may vary (if it is not `foo_pccard_probe()` it will " +"be `foo_pccard_match()`). The function `pccard_product_lookup()` is a " +"generalized function that walks the table and returns a pointer to the first " +"entry that it matches. Some drivers may use this mechanism to convey " +"additional information about some cards to the rest of the driver, so there " +"may be some variance in the table. The only requirement is that each row of " +"the table must have a `struct pccard_product` as the first element." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:147 +msgid "" +"Looking at the table `wi_pccard_products`, one notices that all the entries " +"are of the form `PCMCIA_CARD(_foo_, _bar_, _baz_)`. The _foo_ part is the " +"manufacturer ID from [.filename]#pccarddevs#. The _bar_ part is the product " +"ID. _baz_ is the expected function number for this card. Many pccards can " +"have multiple functions, and some way to disambiguate function 1 from " +"function 0 is needed. You may see `PCMCIA_CARD_D`, which includes the device " +"description from [.filename]#pccarddevs#. You may also see `PCMCIA_CARD2` " +"and `PCMCIA_CARD2_D` which are used when you need to match both CIS strings " +"and manufacturer numbers, in the \"use the default description\" and \"take " +"the description from pccarddevs\" flavors." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:149 +#, no-wrap +msgid "Putting it All Together" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:152 +msgid "" +"To add a new device, one must first obtain the identification information " +"from the device. The easiest way to do this is to insert the device into a " +"PC Card or CF slot and issue `devinfo -v`. Sample output:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:159 +#, no-wrap +msgid "" +" cbb1 pnpinfo vendor=0x104c device=0xac51 subvendor=0x1265 subdevice=0x0300 class=0x060700 at slot=10 function=1\n" +" cardbus1\n" +" pccard1\n" +" unknown pnpinfo manufacturer=0x026f product=0x030c cisvendor=\"BUFFALO\" cisproduct=\"WLI2-CF-S11\" function_type=6 at function=0\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:162 +msgid "" +"`manufacturer` and `product` are the numeric IDs for this product, while " +"`cisvendor` and `cisproduct` are the product description strings from the " +"CIS." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:164 +msgid "" +"Since we first want to prefer the numeric option, first try to construct an " +"entry based on that. The above card has been slightly fictionalized for the " +"purpose of this example. The vendor is BUFFALO, which we see already has an " +"entry:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:168 +#, no-wrap +msgid "vendor BUFFALO\t\t\t0x026f\tBUFFALO (Melco Corporation)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:171 +msgid "But there is no entry for this particular card. Instead we find:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:179 +#, no-wrap +msgid "" +"/* BUFFALO */\n" +"product BUFFALO WLI_PCM_S11\t0x0305\tBUFFALO AirStation 11Mbps WLAN\n" +"product BUFFALO LPC_CF_CLT\t0x0307\tBUFFALO LPC-CF-CLT\n" +"product\tBUFFALO\tLPC3_CLT\t0x030a\tBUFFALO LPC3-CLT Ethernet Adapter\n" +"product BUFFALO WLI_CF_S11G\t0x030b\tBUFFALO AirStation 11Mbps CF WLAN\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:182 +msgid "" +"To add the device, we can just add this entry to [.filename]#pccarddevs#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:186 +#, no-wrap +msgid "product BUFFALO WLI2_CF_S11G\t0x030c\tBUFFALO AirStation ultra 802.11b CF\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:189 +msgid "" +"Once these steps are complete, the card can be added to the driver. That is " +"a simple operation of adding one line:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:200 +#, no-wrap +msgid "" +"static const struct pccard_product wi_pccard_products[] = {\n" +"\tPCMCIA_CARD(3COM, 3CRWE737A, 0),\n" +"\tPCMCIA_CARD(BUFFALO, WLI_PCM_S11, 0),\n" +"\tPCMCIA_CARD(BUFFALO, WLI_CF_S11G, 0),\n" +"+\tPCMCIA_CARD(BUFFALO, WLI_CF2_S11G, 0),\n" +"\tPCMCIA_CARD(TDK, LAK_CD011WL, 0),\n" +"\t{ NULL }\n" +"};\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:203 +msgid "" +"Note that I have included a '`+`' in the line before the line that I added, " +"but that is simply to highlight the line. Do not add it to the actual " +"driver. Once you have added the line, you can recompile your kernel or " +"module and test it. If the device is recognized and works, please submit a " +"patch. If it does not work, please figure out what is needed to make it work " +"and submit a patch. If the device is not recognized at all, you have done " +"something wrong and should recheck each step." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:205 +msgid "" +"If you are a FreeBSD src committer, and everything appears to be working, " +"then you can commit the changes to the tree. However, there are some minor " +"tricky things to be considered. [.filename]#pccarddevs# must be committed to " +"the tree first. Then [.filename]#pccarddevs.h# must be regenerated and " +"committed as a second step, ensuring that the right $FreeBSD$ tag is in the " +"latter file. Finally, commit the additions to the driver." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:207 +#, no-wrap +msgid "Submitting a New Device" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:209 +msgid "" +"Please do not send entries for new devices to the author directly. Instead, " +"submit them as a PR and send the author the PR number for his records. This " +"ensures that entries are not lost. When submitting a PR, it is unnecessary " +"to include the [.filename]#pccardevs.h# diffs in the patch, since those will " +"be regenerated. It is necessary to include a description of the device, as " +"well as the patches to the client driver. If you do not know the name, use " +"OEM99 as the name, and the author will adjust OEM99 accordingly after " +"investigation. Committers should not commit OEM99, but instead find the " +"highest OEM entry and commit one more than that." +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/pci/_index.adoc b/documentation/content/en/books/arch-handbook/pci/_index.adoc index f5dd920f9b..564e361b59 100644 --- a/documentation/content/en/books/arch-handbook/pci/_index.adoc +++ b/documentation/content/en/books/arch-handbook/pci/_index.adoc @@ -6,7 +6,8 @@ description: PCI Devices tags: ["PCI", "Devices", "example", "guide"] showBookMenu: true weight: 13 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/pci/" --- [[pci]] diff --git a/documentation/content/en/books/arch-handbook/pci/_index.po b/documentation/content/en/books/arch-handbook/pci/_index.po new file mode 100644 index 0000000000..5e5a216694 --- /dev/null +++ b/documentation/content/en/books/arch-handbook/pci/_index.po @@ -0,0 +1,787 @@ +# 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/pci/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:14 +#, no-wrap +msgid "PCI Devices" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:1 +#, no-wrap +msgid "Chapter 11. PCI Devices" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:52 +msgid "" +"This chapter will talk about the FreeBSD mechanisms for writing a device " +"driver for a device on a PCI bus." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:54 +#, no-wrap +msgid "Probe and Attach" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:57 +msgid "" +"Information here about how the PCI bus code iterates through the unattached " +"devices and see if a newly loaded kld will attach to any of them." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:58 +#, no-wrap +msgid "Sample Driver Source ([.filename]#mypci.c#)" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:67 +#, no-wrap +msgid "" +"/*\n" +" * Simple KLD to play with the PCI functions.\n" +" *\n" +" * Murray Stokely\n" +" */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:77 +#, no-wrap +msgid "" +"#include <sys/param.h>\t\t/* defines used in kernel.h */\n" +"#include <sys/module.h>\n" +"#include <sys/systm.h>\n" +"#include <sys/errno.h>\n" +"#include <sys/kernel.h>\t\t/* types used in module initialization */\n" +"#include <sys/conf.h>\t\t/* cdevsw struct */\n" +"#include <sys/uio.h>\t\t/* uio struct */\n" +"#include <sys/malloc.h>\n" +"#include <sys/bus.h>\t\t/* structs, prototypes for pci bus stuff and DEVMETHOD macros! */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:81 +#, no-wrap +msgid "" +"#include <machine/bus.h>\n" +"#include <sys/rman.h>\n" +"#include <machine/resource.h>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:84 +#, no-wrap +msgid "" +"#include <dev/pci/pcivar.h>\t/* For pci_get macros! */\n" +"#include <dev/pci/pcireg.h>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:90 +#, no-wrap +msgid "" +"/* The softc holds our per-instance data. */\n" +"struct mypci_softc {\n" +"\tdevice_t\tmy_dev;\n" +"\tstruct cdev\t*my_cdev;\n" +"};\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:96 +#, no-wrap +msgid "" +"/* Function prototypes */\n" +"static d_open_t\t\tmypci_open;\n" +"static d_close_t\tmypci_close;\n" +"static d_read_t\t\tmypci_read;\n" +"static d_write_t\tmypci_write;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:98 +#, no-wrap +msgid "/* Character device entry points */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:107 +#, no-wrap +msgid "" +"static struct cdevsw mypci_cdevsw = {\n" +"\t.d_version =\tD_VERSION,\n" +"\t.d_open =\tmypci_open,\n" +"\t.d_close =\tmypci_close,\n" +"\t.d_read =\tmypci_read,\n" +"\t.d_write =\tmypci_write,\n" +"\t.d_name =\t\"mypci\",\n" +"};\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:113 +#, no-wrap +msgid "" +"/*\n" +" * In the cdevsw routines, we find our softc by using the si_drv1 member\n" +" * of struct cdev. We set this variable to point to our softc in our\n" +" * attach routine when we create the /dev entry.\n" +" */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:118 +#, no-wrap +msgid "" +"int\n" +"mypci_open(struct cdev *dev, int oflags, int devtype, struct thread *td)\n" +"{\n" +"\tstruct mypci_softc *sc;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:124 +#, no-wrap +msgid "" +"\t/* Look up our softc. */\n" +"\tsc = dev->si_drv1;\n" +"\tdevice_printf(sc->my_dev, \"Opened successfully.\\n\");\n" +"\treturn (0);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:129 +#, no-wrap +msgid "" +"int\n" +"mypci_close(struct cdev *dev, int fflag, int devtype, struct thread *td)\n" +"{\n" +"\tstruct mypci_softc *sc;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:135 +#, no-wrap +msgid "" +"\t/* Look up our softc. */\n" +"\tsc = dev->si_drv1;\n" +"\tdevice_printf(sc->my_dev, \"Closed.\\n\");\n" +"\treturn (0);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:140 +#, no-wrap +msgid "" +"int\n" +"mypci_read(struct cdev *dev, struct uio *uio, int ioflag)\n" +"{\n" +"\tstruct mypci_softc *sc;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:146 +#, no-wrap +msgid "" +"\t/* Look up our softc. */\n" +"\tsc = dev->si_drv1;\n" +"\tdevice_printf(sc->my_dev, \"Asked to read %zd bytes.\\n\", uio->uio_resid);\n" +"\treturn (0);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:151 +#, no-wrap +msgid "" +"int\n" +"mypci_write(struct cdev *dev, struct uio *uio, int ioflag)\n" +"{\n" +"\tstruct mypci_softc *sc;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:157 +#, no-wrap +msgid "" +"\t/* Look up our softc. */\n" +"\tsc = dev->si_drv1;\n" +"\tdevice_printf(sc->my_dev, \"Asked to write %zd bytes.\\n\", uio->uio_resid);\n" +"\treturn (0);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:159 +#, no-wrap +msgid "/* PCI Support Functions */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:167 +#, no-wrap +msgid "" +"/*\n" +" * Compare the device ID of this device against the IDs that this driver\n" +" * supports. If there is a match, set the description and return success.\n" +" */\n" +"static int\n" +"mypci_probe(device_t dev)\n" +"{\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:170 +#, no-wrap +msgid "" +"\tdevice_printf(dev, \"MyPCI Probe\\nVendor ID : 0x%x\\nDevice ID : 0x%x\\n\",\n" +"\t pci_get_vendor(dev), pci_get_device(dev));\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:178 +#, no-wrap +msgid "" +"\tif (pci_get_vendor(dev) == 0x11c1) {\n" +"\t\tprintf(\"We've got the Winmodem, probe successful!\\n\");\n" +"\t\tdevice_set_desc(dev, \"WinModem\");\n" +"\t\treturn (BUS_PROBE_DEFAULT);\n" +"\t}\n" +"\treturn (ENXIO);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:180 +#, no-wrap +msgid "/* Attach function is only called if the probe is successful. */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:185 +#, no-wrap +msgid "" +"static int\n" +"mypci_attach(device_t dev)\n" +"{\n" +"\tstruct mypci_softc *sc;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:187 +#, no-wrap +msgid "\tprintf(\"MyPCI Attach for : deviceID : 0x%x\\n\", pci_get_devid(dev));\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:191 +#, no-wrap +msgid "" +"\t/* Look up our softc and initialize its fields. */\n" +"\tsc = device_get_softc(dev);\n" +"\tsc->my_dev = dev;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:204 +#, no-wrap +msgid "" +"\t/*\n" +"\t * Create a /dev entry for this device. The kernel will assign us\n" +"\t * a major number automatically. We use the unit number of this\n" +"\t * device as the minor number and name the character device\n" +"\t * \"mypci<unit>\".\n" +"\t */\n" +"\tsc->my_cdev = make_dev(&mypci_cdevsw, device_get_unit(dev),\n" +"\t UID_ROOT, GID_WHEEL, 0600, \"mypci%u\", device_get_unit(dev));\n" +"\tsc->my_cdev->si_drv1 = sc;\n" +"\tprintf(\"Mypci device loaded.\\n\");\n" +"\treturn (0);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:206 +#, no-wrap +msgid "/* Detach device. */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:211 +#, no-wrap +msgid "" +"static int\n" +"mypci_detach(device_t dev)\n" +"{\n" +"\tstruct mypci_softc *sc;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:218 +#, no-wrap +msgid "" +"\t/* Teardown the state in our softc created in our attach routine. */\n" +"\tsc = device_get_softc(dev);\n" +"\tdestroy_dev(sc->my_cdev);\n" +"\tprintf(\"Mypci detach!\\n\");\n" +"\treturn (0);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:220 +#, no-wrap +msgid "/* Called during system shutdown after sync. */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:224 +#, no-wrap +msgid "" +"static int\n" +"mypci_shutdown(device_t dev)\n" +"{\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:228 +#, no-wrap +msgid "" +"\tprintf(\"Mypci shutdown!\\n\");\n" +"\treturn (0);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:235 +#, no-wrap +msgid "" +"/*\n" +" * Device suspend routine.\n" +" */\n" +"static int\n" +"mypci_suspend(device_t dev)\n" +"{\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:239 +#, no-wrap +msgid "" +"\tprintf(\"Mypci suspend!\\n\");\n" +"\treturn (0);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:246 +#, no-wrap +msgid "" +"/*\n" +" * Device resume routine.\n" +" */\n" +"static int\n" +"mypci_resume(device_t dev)\n" +"{\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:250 +#, no-wrap +msgid "" +"\tprintf(\"Mypci resume!\\n\");\n" +"\treturn (0);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:259 +#, no-wrap +msgid "" +"static device_method_t mypci_methods[] = {\n" +"\t/* Device interface */\n" +"\tDEVMETHOD(device_probe,\t\tmypci_probe),\n" +"\tDEVMETHOD(device_attach,\tmypci_attach),\n" +"\tDEVMETHOD(device_detach,\tmypci_detach),\n" +"\tDEVMETHOD(device_shutdown,\tmypci_shutdown),\n" +"\tDEVMETHOD(device_suspend,\tmypci_suspend),\n" +"\tDEVMETHOD(device_resume,\tmypci_resume),\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:262 +#, no-wrap +msgid "" +"\tDEVMETHOD_END\n" +"};\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:264 +#, no-wrap +msgid "static devclass_t mypci_devclass;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:267 +#, no-wrap +msgid "" +"DEFINE_CLASS_0(mypci, mypci_driver, mypci_methods, sizeof(struct mypci_softc));\n" +"DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0);\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:269 +#, no-wrap +msgid "[.filename]#Makefile# for Sample Driver" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:274 +#, no-wrap +msgid "# Makefile for mypci driver\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:278 +#, no-wrap +msgid "" +"KMOD=\tmypci\n" +"SRCS=\tmypci.c\n" +"SRCS+=\tdevice_if.h bus_if.h pci_if.h\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:280 +#, no-wrap +msgid ".include <bsd.kmod.mk>\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:283 +msgid "" +"If you place the above source file and [.filename]#Makefile# into a " +"directory, you may run `make` to compile the sample driver. Additionally, " +"you may run `make load` to load the driver into the currently running kernel " +"and `make unload` to unload the driver after it is loaded." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:284 +#, no-wrap +msgid "Additional Resources" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:287 +msgid "http://www.pcisig.org/[PCI Special Interest Group]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:288 +msgid "PCI System Architecture, Fourth Edition by Tom Shanley, et al." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:290 +#, no-wrap +msgid "Bus Resources" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:293 +msgid "" +"FreeBSD provides an object-oriented mechanism for requesting resources from " +"a parent bus. Almost all devices will be a child member of some sort of bus " +"(PCI, ISA, USB, SCSI, etc) and these devices need to acquire resources from " +"their parent bus (such as memory segments, interrupt lines, or DMA channels)." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:294 +#, no-wrap +msgid "Base Address Registers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:297 +msgid "" +"To do anything particularly useful with a PCI device you will need to obtain " +"the _Base Address Registers_ (BARs) from the PCI Configuration space. The " +"PCI-specific details of obtaining the BAR are abstracted in the " +"`bus_alloc_resource()` function." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:299 +msgid "" +"For example, a typical driver might have something similar to this in the " +"`attach()` function:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:310 +#, no-wrap +msgid "" +" sc->bar0id = PCIR_BAR(0);\n" +" sc->bar0res = bus_alloc_resource(dev, SYS_RES_MEMORY, &sc->bar0id,\n" +"\t\t\t\t 0, ~0, 1, RF_ACTIVE);\n" +" if (sc->bar0res == NULL) {\n" +" printf(\"Memory allocation of PCI base register 0 failed!\\n\");\n" +" error = ENXIO;\n" +" goto fail1;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:323 +#, no-wrap +msgid "" +" sc->bar1id = PCIR_BAR(1);\n" +" sc->bar1res = bus_alloc_resource(dev, SYS_RES_MEMORY, &sc->bar1id,\n" +"\t\t\t\t 0, ~0, 1, RF_ACTIVE);\n" +" if (sc->bar1res == NULL) {\n" +" printf(\"Memory allocation of PCI base register 1 failed!\\n\");\n" +" error = ENXIO;\n" +" goto fail2;\n" +" }\n" +" sc->bar0_bt = rman_get_bustag(sc->bar0res);\n" +" sc->bar0_bh = rman_get_bushandle(sc->bar0res);\n" +" sc->bar1_bt = rman_get_bustag(sc->bar1res);\n" +" sc->bar1_bh = rman_get_bushandle(sc->bar1res);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:326 +msgid "" +"Handles for each base address register are kept in the `softc` structure so " +"that they can be used to write to the device later." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:328 +msgid "" +"These handles can then be used to read or write from the device registers " +"with the `bus_space_*` functions. For example, a driver might contain a " +"shorthand function to read from a board specific register like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:336 +#, no-wrap +msgid "" +"uint16_t\n" +"board_read(struct ni_softc *sc, uint16_t address)\n" +"{\n" +" return bus_space_read_2(sc->bar1_bt, sc->bar1_bh, address);\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:339 +msgid "Similarly, one could write to the registers with:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:347 +#, no-wrap +msgid "" +"void\n" +"board_write(struct ni_softc *sc, uint16_t address, uint16_t value)\n" +"{\n" +" bus_space_write_2(sc->bar1_bt, sc->bar1_bh, address, value);\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:350 +msgid "" +"These functions exist in 8bit, 16bit, and 32bit versions and you should use " +"`bus_space_{read|write}_{1|2|4}` accordingly." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:354 +msgid "" +"In FreeBSD 7.0 and later, you can use the `bus_*` functions instead of " +"`bus_space_*`. The `bus_*` functions take a struct resource * pointer " +"instead of a bus tag and handle. Thus, you could drop the bus tag and bus " +"handle members from the `softc` and rewrite the `board_read()` function as:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:362 +#, no-wrap +msgid "" +"uint16_t\n" +"board_read(struct ni_softc *sc, uint16_t address)\n" +"{\n" +"\treturn (bus_read(sc->bar1res, address));\n" +"}\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:366 +#, no-wrap +msgid "Interrupts" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:369 +msgid "" +"Interrupts are allocated from the object-oriented bus code in a way similar " +"to the memory resources. First an IRQ resource must be allocated from the " +"parent bus, and then the interrupt handler must be set up to deal with this " +"IRQ." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:371 +msgid "Again, a sample from a device `attach()` function says more than words." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:375 +#, no-wrap +msgid "/* Get the IRQ resource */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:384 +#, no-wrap +msgid "" +" sc->irqid = 0x0;\n" +" sc->irqres = bus_alloc_resource(dev, SYS_RES_IRQ, &(sc->irqid),\n" +"\t\t\t\t 0, ~0, 1, RF_SHAREABLE | RF_ACTIVE);\n" +" if (sc->irqres == NULL) {\n" +"\tprintf(\"IRQ allocation failed!\\n\");\n" +"\terror = ENXIO;\n" +"\tgoto fail3;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:386 +#, no-wrap +msgid " /* Now we should set up the interrupt handler */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:393 +#, no-wrap +msgid "" +" error = bus_setup_intr(dev, sc->irqres, INTR_TYPE_MISC,\n" +"\t\t\t my_handler, sc, &(sc->handler));\n" +" if (error) {\n" +"\tprintf(\"Couldn't set up irq\\n\");\n" +"\tgoto fail4;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:396 +msgid "" +"Some care must be taken in the detach routine of the driver. You must " +"quiesce the device's interrupt stream, and remove the interrupt handler. " +"Once `bus_teardown_intr()` has returned, you know that your interrupt " +"handler will no longer be called and that all threads that might have been " +"executing this interrupt handler have returned. Since this function can " +"sleep, you must not hold any mutexes when calling this function." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:397 +#, no-wrap +msgid "DMA" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:400 +msgid "" +"This section is obsolete, and present only for historical reasons. The " +"proper methods for dealing with these issues is to use the " +"`bus_space_dma*()` functions instead. This paragraph can be removed when " +"this section is updated to reflect that usage. However, at the moment, the " +"API is in a bit of flux, so once that settles down, it would be good to " +"update this section to reflect that." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:402 +msgid "" +"On the PC, peripherals that want to do bus-mastering DMA must deal with " +"physical addresses. This is a problem since FreeBSD uses virtual memory and " +"deals almost exclusively with virtual addresses. Fortunately, there is a " +"function, `vtophys()` to help." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:407 +#, no-wrap +msgid "" +"#include <vm/vm.h>\n" +"#include <vm/pmap.h>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:409 +#, no-wrap +msgid "#define vtophys(virtual_address) (...)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:412 +msgid "" +"The solution is a bit different on the alpha however, and what we really " +"want is a function called `vtobus()`." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:420 +#, no-wrap +msgid "" +"#if defined(__alpha__)\n" +"#define vtobus(va) alpha_XXX_dmamap((vm_offset_t)va)\n" +"#else\n" +"#define vtobus(va) vtophys(va)\n" +"#endif\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:422 +#, no-wrap +msgid "Deallocating Resources" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:424 +msgid "" +"It is very important to deallocate all of the resources that were allocated " +"during `attach()`. Care must be taken to deallocate the correct stuff even " +"on a failure condition so that the system will remain usable while your " +"driver dies." +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/scsi/_index.adoc b/documentation/content/en/books/arch-handbook/scsi/_index.adoc index 61dfcd6c45..0bee25e87f 100644 --- a/documentation/content/en/books/arch-handbook/scsi/_index.adoc +++ b/documentation/content/en/books/arch-handbook/scsi/_index.adoc @@ -6,7 +6,8 @@ description: Common Access Method SCSI Controllers tags: ["SCSI", "Controller", "Architecture"] showBookMenu: true weight: 14 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/scsi/" --- [[scsi]] diff --git a/documentation/content/en/books/arch-handbook/scsi/_index.po b/documentation/content/en/books/arch-handbook/scsi/_index.po new file mode 100644 index 0000000000..3c5c997bae --- /dev/null +++ b/documentation/content/en/books/arch-handbook/scsi/_index.po @@ -0,0 +1,3093 @@ +# 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/scsi/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:14 +#, no-wrap +msgid "Common Access Method SCSI Controllers" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1 +#, no-wrap +msgid "Chapter 12. Common Access Method SCSI Controllers" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:52 +#, no-wrap +msgid "Synopsis" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:56 +msgid "" +"This document assumes that the reader has a general understanding of device " +"drivers in FreeBSD and of the SCSI protocol. Much of the information in " +"this document was extracted from the drivers:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:58 +msgid "" +"ncr ([.filename]#/sys/pci/ncr.c#) by Wolfgang Stanglmeier and Stefan Esser" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:59 +msgid "sym ([.filename]#/sys/dev/sym/sym_hipd.c#) by Gerard Roudier" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:60 +msgid "aic7xxx ([.filename]#/sys/dev/aic7xxx/aic7xxx.c#) by Justin T. Gibbs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:63 +msgid "" +"and from the CAM code itself (by Justin T. Gibbs, see [.filename]#/sys/cam/" +"*#). When some solution looked the most logical and was essentially " +"verbatim extracted from the code by Justin T. Gibbs, I marked it as " +"\"recommended\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:71 +msgid "" +"The document is illustrated with examples in pseudo-code. Although " +"sometimes the examples have many details and look like real code, it is " +"still pseudo-code. It was written to demonstrate the concepts in an " +"understandable way. For a real driver other approaches may be more modular " +"and efficient. It also abstracts from the hardware details, as well as " +"issues that would cloud the demonstrated concepts or that are supposed to be " +"described in the other chapters of the developers handbook. Such details " +"are commonly shown as calls to functions with descriptive names, comments or " +"pseudo-statements. Fortunately real life full-size examples with all the " +"details can be found in the real drivers." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:73 +#, no-wrap +msgid "General Architecture" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:79 +msgid "" +"CAM stands for Common Access Method. It is a generic way to address the I/O " +"buses in a SCSI-like way. This allows a separation of the generic device " +"drivers from the drivers controlling the I/O bus: for example the disk " +"driver becomes able to control disks on both SCSI, IDE, and/or any other bus " +"so the disk driver portion does not have to be rewritten (or copied and " +"modified) for every new I/O bus. Thus the two most important active " +"entities are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:81 +msgid "" +"_Peripheral Modules_ - a driver for peripheral devices (disk, tape, CD-ROM, " +"etc.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:82 +msgid "" +"_SCSI Interface Modules_ (SIM) - a Host Bus Adapter drivers for connecting " +"to an I/O bus such as SCSI or IDE." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:85 +msgid "" +"A peripheral driver receives requests from the OS, converts them to a " +"sequence of SCSI commands and passes these SCSI commands to a SCSI Interface " +"Module. The SCSI Interface Module is responsible for passing these commands " +"to the actual hardware (or if the actual hardware is not SCSI but, for " +"example, IDE then also converting the SCSI commands to the native commands " +"of the hardware)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:87 +msgid "" +"As we are interested in writing a SCSI adapter driver here, from this point " +"on we will consider everything from the SIM standpoint." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:88 +#, no-wrap +msgid "Globals and Boilerplate" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:91 +msgid "" +"A typical SIM driver needs to include the following CAM-related header files:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:100 +#, no-wrap +msgid "" +"#include <cam/cam.h>\n" +"#include <cam/cam_ccb.h>\n" +"#include <cam/cam_sim.h>\n" +"#include <cam/cam_xpt_sim.h>\n" +"#include <cam/cam_debug.h>\n" +"#include <cam/scsi/scsi_all.h>\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:102 +#, no-wrap +msgid "Device configuration: xxx_attach" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:107 +msgid "" +"The first thing each SIM driver must do is register itself with the CAM " +"subsystem. This is done during the driver's `xxx_attach()` function (here " +"and further xxx_ is used to denote the unique driver name prefix). The " +"`xxx_attach()` function itself is called by the system bus auto-" +"configuration code which we do not describe here." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:109 +msgid "" +"This is achieved in multiple steps: first it is necessary to allocate the " +"queue of requests associated with this SIM:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:113 +#, no-wrap +msgid " struct cam_devq *devq;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:117 +#, no-wrap +msgid "" +" if ((devq = cam_simq_alloc(SIZE)) == NULL) {\n" +" error; /* some code to handle the error */\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:122 +msgid "" +"Here `SIZE` is the size of the queue to be allocated, maximal number of " +"requests it could contain. It is the number of requests that the SIM driver " +"can handle in parallel on one SCSI card. Commonly it can be calculated as:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:126 +#, no-wrap +msgid "SIZE = NUMBER_OF_SUPPORTED_TARGETS * MAX_SIMULTANEOUS_COMMANDS_PER_TARGET\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:129 +msgid "Next we create a descriptor of our SIM:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:133 +#, no-wrap +msgid " struct cam_sim *sim;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:140 +#, no-wrap +msgid "" +" if ((sim = cam_sim_alloc(action_func, poll_func, driver_name,\n" +" softc, unit, mtx, max_dev_transactions,\n" +" max_tagged_dev_transactions, devq)) == NULL) {\n" +" cam_simq_free(devq);\n" +" error; /* some code to handle the error */\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:143 +msgid "" +"Note that if we are not able to create a SIM descriptor we free the `devq` " +"also because we can do nothing else with it and we want to conserve memory." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:145 +msgid "" +"If a SCSI card has multiple SCSI buses on it then each bus requires its own " +"`cam_sim` structure." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:148 +msgid "" +"An interesting question is what to do if a SCSI card has more than one SCSI " +"bus, do we need one `devq` structure per card or per SCSI bus? The answer " +"given in the comments to the CAM code is: either way, as the driver's author " +"prefers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:150 +msgid "The arguments are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:152 +msgid "`action_func` - pointer to the driver's `xxx_action` function." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:156 +#, no-wrap +msgid "static void xxx_action(struct cam_sim *, union ccb *);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:158 +msgid "`poll_func` - pointer to the driver's `xxx_poll()`" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:162 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1020 +#, no-wrap +msgid "static void xxx_poll(struct cam_sim *);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:164 +msgid "" +"driver_name - the name of the actual driver, such as \"ncr\" or \"wds\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:166 +msgid "" +"`softc` - pointer to the driver's internal descriptor for this SCSI card. " +"This pointer will be used by the driver in future to get private data." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:167 +msgid "" +"unit - the controller unit number, for example for controller \"mps0\" this " +"number will be 0" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:171 +msgid "" +"mtx - Lock associated with this SIM. For SIMs that don't know about " +"locking, pass in Giant. For SIMs that do, pass in the lock used to guard " +"this SIM's data structures. This lock will be held when xxx_action and " +"xxx_poll are called." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:174 +msgid "" +"max_dev_transactions - maximal number of simultaneous transactions per SCSI " +"target in the non-tagged mode. This value will be almost universally equal " +"to 1, with possible exceptions only for the non-SCSI cards. Also the " +"drivers that hope to take advantage by preparing one transaction while " +"another one is executed may set it to 2 but this does not seem to be worth " +"the complexity." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:179 +msgid "" +"max_tagged_dev_transactions - the same thing, but in the tagged mode. Tags " +"are the SCSI way to initiate multiple transactions on a device: each " +"transaction is assigned a unique tag and the transaction is sent to the " +"device. When the device completes some transaction it sends back the result " +"together with the tag so that the SCSI adapter (and the driver) can tell " +"which transaction was completed. This argument is also known as the maximal " +"tag depth. It depends on the abilities of the SCSI adapter." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:181 +msgid "Finally we register the SCSI buses associated with our SCSI adapter:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:188 +#, no-wrap +msgid "" +" if (xpt_bus_register(sim, softc, bus_number) != CAM_SUCCESS) {\n" +" cam_sim_free(sim, /*free_devq*/ TRUE);\n" +" error; /* some code to handle the error */\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:192 +msgid "" +"If there is one `devq` structure per SCSI bus (i.e., we consider a card with " +"multiple buses as multiple cards with one bus each) then the bus number will " +"always be 0, otherwise each bus on the SCSI card should be get a distinct " +"number. Each bus needs its own separate structure cam_sim." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:195 +msgid "" +"After that our controller is completely hooked to the CAM system. The value " +"of `devq` can be discarded now: sim will be passed as an argument in all " +"further calls from CAM and devq can be derived from it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:199 +msgid "" +"CAM provides the framework for such asynchronous events. Some events " +"originate from the lower levels (the SIM drivers), some events originate " +"from the peripheral drivers, some events originate from the CAM subsystem " +"itself. Any driver can register callbacks for some types of the " +"asynchronous events, so that it would be notified if these events occur." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:207 +msgid "" +"A typical example of such an event is a device reset. Each transaction and " +"event identifies the devices to which it applies by the means of \"path\". " +"The target-specific events normally occur during a transaction with this " +"device. So the path from that transaction may be re-used to report this " +"event (this is safe because the event path is copied in the event reporting " +"routine but not deallocated nor passed anywhere further). Also it is safe " +"to allocate paths dynamically at any time including the interrupt routines, " +"although that incurs certain overhead, and a possible problem with this " +"approach is that there may be no free memory at that time. For a bus reset " +"event we need to define a wildcard path including all devices on the bus. " +"So we can create the path for the future bus reset events in advance and " +"avoid problems with the future memory shortage:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:211 +#, no-wrap +msgid " struct cam_path *path;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:219 +#, no-wrap +msgid "" +" if (xpt_create_path(&path, /*periph*/NULL,\n" +" cam_sim_path(sim), CAM_TARGET_WILDCARD,\n" +" CAM_LUN_WILDCARD) != CAM_REQ_CMP) {\n" +" xpt_bus_deregister(cam_sim_path(sim));\n" +" cam_sim_free(sim, /*free_devq*/TRUE);\n" +" error; /* some code to handle the error */\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:222 +#, no-wrap +msgid "" +" softc->wpath = path;\n" +" softc->sim = sim;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:225 +msgid "As you can see the path includes:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:227 +msgid "ID of the peripheral driver (NULL here because we have none)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:228 +msgid "ID of the SIM driver (`cam_sim_path(sim)`)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:229 +msgid "" +"SCSI target number of the device (CAM_TARGET_WILDCARD means \"all devices\")" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:230 +msgid "SCSI LUN number of the subdevice (CAM_LUN_WILDCARD means \"all LUNs\")" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:232 +msgid "" +"If the driver can not allocate this path it will not be able to work " +"normally, so in that case we dismantle that SCSI bus." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:235 +msgid "" +"And we save the path pointer in the `softc` structure for future use. After " +"that we save the value of sim (or we can also discard it on the exit from " +"`xxx_probe()` if we wish)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:238 +msgid "" +"That is all for a minimalistic initialization. To do things right there is " +"one more issue left." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:243 +msgid "" +"For a SIM driver there is one particularly interesting event: when a target " +"device is considered lost. In this case resetting the SCSI negotiations " +"with this device may be a good idea. So we register a callback for this " +"event with CAM. The request is passed to CAM by requesting CAM action on a " +"CAM control block for this type of request:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:247 +#, no-wrap +msgid " struct ccb_setasync csa;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:254 +#, no-wrap +msgid "" +" xpt_setup_ccb(&csa.ccb_h, path, /*priority*/5);\n" +" csa.ccb_h.func_code = XPT_SASYNC_CB;\n" +" csa.event_enable = AC_LOST_DEVICE;\n" +" csa.callback = xxx_async;\n" +" csa.callback_arg = sim;\n" +" xpt_action((union ccb *)&csa);\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:256 +#, no-wrap +msgid "Processing CAM messages: xxx_action" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:261 +#, no-wrap +msgid "static void xxx_action(struct cam_sim *sim, union ccb *ccb);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:268 +msgid "" +"Do some action on request of the CAM subsystem. Sim describes the SIM for " +"the request, CCB is the request itself. CCB stands for \"CAM Control " +"Block\". It is a union of many specific instances, each describing " +"arguments for some type of transactions. All of these instances share the " +"CCB header where the common part of arguments is stored." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:271 +msgid "" +"CAM supports the SCSI controllers working in both initiator (\"normal\") " +"mode and target (simulating a SCSI device) mode. Here we only consider the " +"part relevant to the initiator mode." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:273 +msgid "" +"There are a few function and macros (in other words, methods) defined to " +"access the public data in the struct sim:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:275 +msgid "`cam_sim_path(sim)` - the path ID (see above)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:276 +msgid "`cam_sim_name(sim)` - the name of the sim" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:277 +msgid "" +"`cam_sim_softc(sim)` - the pointer to the softc (driver private data) " +"structure" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:278 +msgid "`cam_sim_unit(sim)` - the unit number" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:279 +msgid "`cam_sim_bus(sim)` - the bus ID" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:281 +msgid "" +"To identify the device, `xxx_action()` can get the unit number and pointer " +"to its structure softc using these functions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:284 +msgid "" +"The type of request is stored in `ccb->ccb_h.func_code`. So generally " +"`xxx_action()` consists of a big switch:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:291 +#, no-wrap +msgid "" +" struct xxx_softc *softc = (struct xxx_softc *) cam_sim_softc(sim);\n" +" struct ccb_hdr *ccb_h = &ccb->ccb_h;\n" +" int unit = cam_sim_unit(sim);\n" +" int bus = cam_sim_bus(sim);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:300 +#, no-wrap +msgid "" +" switch (ccb_h->func_code) {\n" +" case ...:\n" +" ...\n" +" default:\n" +" ccb_h->status = CAM_REQ_INVALID;\n" +" xpt_done(ccb);\n" +" break;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:303 +msgid "" +"As can be seen from the default case (if an unknown command was received) " +"the return code of the command is set into `ccb->ccb_h.status` and the " +"completed CCB is returned back to CAM by calling `xpt_done(ccb)`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:306 +msgid "" +"`xpt_done()` does not have to be called from `xxx_action()`: For example an " +"I/O request may be enqueued inside the SIM driver and/or its SCSI " +"controller. Then when the device would post an interrupt signaling that the " +"processing of this request is complete `xpt_done()` may be called from the " +"interrupt handling routine." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:314 +msgid "" +"Actually, the CCB status is not only assigned as a return code but a CCB has " +"some status all the time. Before CCB is passed to the `xxx_action()` " +"routine it gets the status CCB_REQ_INPROG meaning that it is in progress. " +"There are a surprising number of status values defined in [.filename]#/sys/" +"cam/cam.h# which should be able to represent the status of a request in " +"great detail. More interesting yet, the status is in fact a \"bitwise or\" " +"of an enumerated status value (the lower 6 bits) and possible additional " +"flag-like bits (the upper bits). The enumerated values will be discussed " +"later in more detail. The summary of them can be found in the Errors " +"Summary section. The possible status flags are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:317 +msgid "" +"_CAM_DEV_QFRZN_ - if the SIM driver gets a serious error (for example, the " +"device does not respond to the selection or breaks the SCSI protocol) when " +"processing a CCB it should freeze the request queue by calling " +"`xpt_freeze_simq()`, return the other enqueued but not processed yet CCBs " +"for this device back to the CAM queue, then set this flag for the " +"troublesome CCB and call `xpt_done()`. This flag causes the CAM subsystem " +"to unfreeze the queue after it handles the error." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:319 +msgid "" +"_CAM_AUTOSNS_VALID_ - if the device returned an error condition and the flag " +"CAM_DIS_AUTOSENSE is not set in CCB the SIM driver must execute the REQUEST " +"SENSE command automatically to extract the sense (extended error " +"information) data from the device. If this attempt was successful the sense " +"data should be saved in the CCB and this flag set." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:322 +msgid "" +"_CAM_RELEASE_SIMQ_ - like CAM_DEV_QFRZN but used in case there is some " +"problem (or resource shortage) with the SCSI controller itself. Then all " +"the future requests to the controller should be stopped by " +"`xpt_freeze_simq()`. The controller queue will be restarted after the SIM " +"driver overcomes the shortage and informs CAM by returning some CCB with " +"this flag set." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:324 +msgid "" +"_CAM_SIM_QUEUED_ - when SIM puts a CCB into its request queue this flag " +"should be set (and removed when this CCB gets dequeued before being returned " +"back to CAM). This flag is not used anywhere in the CAM code now, so its " +"purpose is purely diagnostic." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:325 +msgid "_CAM_QOS_VALID_ - The QOS data is now valid." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:328 +msgid "" +"The function `xxx_action()` is not allowed to sleep, so all the " +"synchronization for resource access must be done using SIM or device queue " +"freezing. Besides the aforementioned flags the CAM subsystem provides " +"functions `xpt_release_simq()` and `xpt_release_devq()` to unfreeze the " +"queues directly, without passing a CCB to CAM." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:330 +msgid "The CCB header contains the following fields:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:332 +msgid "_path_ - path ID for the request" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:333 +msgid "_target_id_ - target device ID for the request" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:334 +msgid "_target_lun_ - LUN ID of the target device" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:335 +msgid "_timeout_ - timeout interval for this command, in milliseconds" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:336 +msgid "" +"_timeout_ch_ - a convenience place for the SIM driver to store the timeout " +"handle (the CAM subsystem itself does not make any assumptions about it)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:337 +msgid "" +"_flags_ - various bits of information about the request spriv_ptr0, " +"spriv_ptr1 - fields reserved for private use by the SIM driver (such as " +"linking to the SIM queues or SIM private control blocks); actually, they " +"exist as unions: spriv_ptr0 and spriv_ptr1 have the type (void *), " +"spriv_field0 and spriv_field1 have the type unsigned long, " +"sim_priv.entries[0].bytes and sim_priv.entries[1].bytes are byte arrays of " +"the size consistent with the other incarnations of the union and " +"sim_priv.bytes is one array, twice bigger." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:339 +msgid "" +"The recommended way of using the SIM private fields of CCB is to define some " +"meaningful names for them and use these meaningful names in the driver, like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:344 +#, no-wrap +msgid "" +"#define ccb_some_meaningful_name sim_priv.entries[0].bytes\n" +"#define ccb_hcb spriv_ptr1 /* for hardware control block */\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:347 +msgid "The most common initiator mode requests are:" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:348 +#, no-wrap +msgid "_XPT_SCSI_IO_ - execute an I/O transaction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:352 +msgid "" +"The instance \"struct ccb_scsiio csio\" of the union ccb is used to transfer " +"the arguments. They are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:354 +msgid "_cdb_io_ - pointer to the SCSI command buffer or the buffer itself" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:355 +msgid "_cdb_len_ - SCSI command length" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:356 +msgid "" +"_data_ptr_ - pointer to the data buffer (gets a bit complicated if scatter/" +"gather is used)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:357 +msgid "_dxfer_len_ - length of the data to transfer" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:358 +msgid "_sglist_cnt_ - counter of the scatter/gather segments" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:359 +msgid "_scsi_status_ - place to return the SCSI status" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:360 +msgid "" +"_sense_data_ - buffer for the SCSI sense information if the command returns " +"an error (the SIM driver is supposed to run the REQUEST SENSE command " +"automatically in this case if the CCB flag CAM_DIS_AUTOSENSE is not set)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:361 +msgid "" +"_sense_len_ - the length of that buffer (if it happens to be higher than " +"size of sense_data the SIM driver must silently assume the smaller value)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:364 +msgid "" +"_resid_, _sense_resid_ - if the transfer of data or SCSI sense returned an " +"error these are the returned counters of the residual (not transferred) " +"data. They do not seem to be especially meaningful, so in a case when they " +"are difficult to compute (say, counting bytes in the SCSI controller's FIFO " +"buffer) an approximate value will do as well. For a successfully completed " +"transfer they must be set to zero." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:365 +msgid "_tag_action_ - the kind of tag to use:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:366 +msgid "CAM_TAG_ACTION_NONE - do not use tags for this transaction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:367 +msgid "" +"MSG_SIMPLE_Q_TAG, MSG_HEAD_OF_Q_TAG, MSG_ORDERED_Q_TAG - value equal to the " +"appropriate tag message (see /sys/cam/scsi/scsi_message.h); this gives only " +"the tag type, the SIM driver must assign the tag value itself" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:369 +msgid "The general logic of handling this request is the following:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:371 +msgid "" +"The first thing to do is to check for possible races, to make sure that the " +"command did not get aborted when it was sitting in the queue:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:375 +#, no-wrap +msgid " struct ccb_scsiio *csio = &ccb->csio;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:380 +#, no-wrap +msgid "" +" if ((ccb_h->status & CAM_STATUS_MASK) != CAM_REQ_INPROG) {\n" +" xpt_done(ccb);\n" +" return;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:383 +msgid "Also we check that the device is supported at all by our controller:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:397 +#, no-wrap +msgid "" +" if (ccb_h->target_id > OUR_MAX_SUPPORTED_TARGET_ID\n" +" || cch_h->target_id == OUR_SCSI_CONTROLLERS_OWN_ID) {\n" +" ccb_h->status = CAM_TID_INVALID;\n" +" xpt_done(ccb);\n" +" return;\n" +" }\n" +" if (ccb_h->target_lun > OUR_MAX_SUPPORTED_LUN) {\n" +" ccb_h->status = CAM_LUN_INVALID;\n" +" xpt_done(ccb);\n" +" return;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:403 +msgid "" +"Then allocate whatever data structures (such as card-dependent hardware " +"control block) we need to process this request. If we can not then freeze " +"the SIM queue and remember that we have a pending operation, return the CCB " +"back and ask CAM to re-queue it. Later when the resources become available " +"the SIM queue must be unfrozen by returning a ccb with the " +"`CAM_SIMQ_RELEASE` bit set in its status. Otherwise, if all went well, link " +"the CCB with the hardware control block (HCB) and mark it as queued." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:407 +#, no-wrap +msgid " struct xxx_hcb *hcb = allocate_hcb(softc, unit, bus);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:415 +#, no-wrap +msgid "" +" if (hcb == NULL) {\n" +" softc->flags |= RESOURCE_SHORTAGE;\n" +" xpt_freeze_simq(sim, /*count*/1);\n" +" ccb_h->status = CAM_REQUEUE_REQ;\n" +" xpt_done(ccb);\n" +" return;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:418 +#, no-wrap +msgid "" +" hcb->ccb = ccb; ccb_h->ccb_hcb = (void *)hcb;\n" +" ccb_h->status |= CAM_SIM_QUEUED;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:423 +msgid "" +"Extract the target data from CCB into the hardware control block. Check if " +"we are asked to assign a tag and if yes then generate an unique tag and " +"build the SCSI tag messages. The SIM driver is also responsible for " +"negotiations with the devices to set the maximal mutually supported bus " +"width, synchronous rate and offset." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:432 +#, no-wrap +msgid "" +" hcb->target = ccb_h->target_id; hcb->lun = ccb_h->target_lun;\n" +" generate_identify_message(hcb);\n" +" if (ccb_h->tag_action != CAM_TAG_ACTION_NONE)\n" +" generate_unique_tag_message(hcb, ccb_h->tag_action);\n" +" if (!target_negotiated(hcb))\n" +" generate_negotiation_messages(hcb);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:438 +msgid "" +"Then set up the SCSI command. The command storage may be specified in the " +"CCB in many interesting ways, specified by the CCB flags. The command " +"buffer can be contained in CCB or pointed to, in the latter case the pointer " +"may be physical or virtual. Since the hardware commonly needs physical " +"address we always convert the address to the physical one, typically using " +"the busdma API." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:441 +msgid "" +"In case if a physical address is requested it is OK to return the CCB with " +"the status `CAM_REQ_INVALID`, the current drivers do that. If necessary a " +"physical address can be also converted or mapped back to a virtual address " +"but with big pain, so we do not do that." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:458 +#, no-wrap +msgid "" +" if (ccb_h->flags & CAM_CDB_POINTER) {\n" +" /* CDB is a pointer */\n" +" if (!(ccb_h->flags & CAM_CDB_PHYS)) {\n" +" /* CDB pointer is virtual */\n" +" hcb->cmd = vtobus(csio->cdb_io.cdb_ptr);\n" +" } else {\n" +" /* CDB pointer is physical */\n" +" hcb->cmd = csio->cdb_io.cdb_ptr ;\n" +" }\n" +" } else {\n" +" /* CDB is in the ccb (buffer) */\n" +" hcb->cmd = vtobus(csio->cdb_io.cdb_bytes);\n" +" }\n" +" hcb->cmdlen = csio->cdb_len;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:464 +msgid "" +"Now it is time to set up the data. Again, the data storage may be specified " +"in the CCB in many interesting ways, specified by the CCB flags. First we " +"get the direction of the data transfer. The simplest case is if there is no " +"data to transfer:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:468 +#, no-wrap +msgid " int dir = (ccb_h->flags & CAM_DIR_MASK);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:471 +#, no-wrap +msgid "" +" if (dir == CAM_DIR_NONE)\n" +" goto end_data;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:482 +msgid "" +"Then we check if the data is in one chunk or in a scatter-gather list, and " +"the addresses are physical or virtual. The SCSI controller may be able to " +"handle only a limited number of chunks of limited length. If the request " +"hits this limitation we return an error. We use a special function to " +"return the CCB to handle in one place the HCB resource shortages. The " +"functions to add chunks are driver-dependent, and here we leave them without " +"detailed implementation. See description of the SCSI command (CDB) handling " +"for the details on the address-translation issues. If some variation is too " +"difficult or impossible to implement with a particular card it is OK to " +"return the status `CAM_REQ_INVALID`. Actually, it seems like the scatter-" +"gather ability is not used anywhere in the CAM code now. But at least the " +"case for a single non-scattered virtual buffer must be implemented, it is " +"actively used by CAM." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:486 +#, no-wrap +msgid " int rv;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:488 +#, no-wrap +msgid " initialize_hcb_for_data(hcb);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:501 +#, no-wrap +msgid "" +" if ((!(ccb_h->flags & CAM_SCATTER_VALID)) {\n" +" /* single buffer */\n" +" if (!(ccb_h->flags & CAM_DATA_PHYS)) {\n" +" rv = add_virtual_chunk(hcb, csio->data_ptr, csio->dxfer_len, dir);\n" +" }\n" +" } else {\n" +" rv = add_physical_chunk(hcb, csio->data_ptr, csio->dxfer_len, dir);\n" +" }\n" +" } else {\n" +" int i;\n" +" struct bus_dma_segment *segs;\n" +" segs = (struct bus_dma_segment *)csio->data_ptr;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:533 +#, no-wrap +msgid "" +" if ((ccb_h->flags & CAM_SG_LIST_PHYS) != 0) {\n" +" /* The SG list pointer is physical */\n" +" rv = setup_hcb_for_physical_sg_list(hcb, segs, csio->sglist_cnt);\n" +" } else if (!(ccb_h->flags & CAM_DATA_PHYS)) {\n" +" /* SG buffer pointers are virtual */\n" +" for (i = 0; i < csio->sglist_cnt; i++) {\n" +" rv = add_virtual_chunk(hcb, segs[i].ds_addr,\n" +" segs[i].ds_len, dir);\n" +" if (rv != CAM_REQ_CMP)\n" +" break;\n" +" }\n" +" } else {\n" +" /* SG buffer pointers are physical */\n" +" for (i = 0; i < csio->sglist_cnt; i++) {\n" +" rv = add_physical_chunk(hcb, segs[i].ds_addr,\n" +" segs[i].ds_len, dir);\n" +" if (rv != CAM_REQ_CMP)\n" +" break;\n" +" }\n" +" }\n" +" }\n" +" if (rv != CAM_REQ_CMP) {\n" +" /* we expect that add_*_chunk() functions return CAM_REQ_CMP\n" +" * if they added a chunk successfully, CAM_REQ_TOO_BIG if\n" +" * the request is too big (too many bytes or too many chunks),\n" +" * CAM_REQ_INVALID in case of other troubles\n" +" */\n" +" free_hcb_and_ccb_done(hcb, ccb, rv);\n" +" return;\n" +" }\n" +" end_data:\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:536 +msgid "" +"If disconnection is disabled for this CCB we pass this information to the " +"hcb:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:541 +#, no-wrap +msgid "" +" if (ccb_h->flags & CAM_DIS_DISCONNECT)\n" +" hcb_disable_disconnect(hcb);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:544 +msgid "" +"If the controller is able to run REQUEST SENSE command all by itself then " +"the value of the flag CAM_DIS_AUTOSENSE should also be passed to it, to " +"prevent automatic REQUEST SENSE if the CAM subsystem does not want it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:546 +msgid "" +"The only thing left is to set up the timeout, pass our hcb to the hardware " +"and return, the rest will be done by the interrupt handler (or timeout " +"handler)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:553 +#, no-wrap +msgid "" +" ccb_h->timeout_ch = timeout(xxx_timeout, (caddr_t) hcb,\n" +" (ccb_h->timeout * hz) / 1000); /* convert milliseconds to ticks */\n" +" put_hcb_into_hardware_queue(hcb);\n" +" return;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:556 +msgid "And here is a possible implementation of the function returning CCB:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:563 +#, no-wrap +msgid "" +" static void\n" +" free_hcb_and_ccb_done(struct xxx_hcb *hcb, union ccb *ccb, u_int32_t status)\n" +" {\n" +" struct xxx_softc *softc = hcb->softc;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:578 +#, no-wrap +msgid "" +" ccb->ccb_h.ccb_hcb = 0;\n" +" if (hcb != NULL) {\n" +" untimeout(xxx_timeout, (caddr_t) hcb, ccb->ccb_h.timeout_ch);\n" +" /* we're about to free a hcb, so the shortage has ended */\n" +" if (softc->flags & RESOURCE_SHORTAGE) {\n" +" softc->flags &= ~RESOURCE_SHORTAGE;\n" +" status |= CAM_RELEASE_SIMQ;\n" +" }\n" +" free_hcb(hcb); /* also removes hcb from any internal lists */\n" +" }\n" +" ccb->ccb_h.status = status |\n" +" (ccb->ccb_h.status & ~(CAM_STATUS_MASK|CAM_SIM_QUEUED));\n" +" xpt_done(ccb);\n" +" }\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:580 +#, no-wrap +msgid "_XPT_RESET_DEV_ - send the SCSI \"BUS DEVICE RESET\" message to a device" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:585 +msgid "" +"There is no data transferred in CCB except the header and the most " +"interesting argument of it is target_id. Depending on the controller " +"hardware a hardware control block just like for the XPT_SCSI_IO request may " +"be constructed (see XPT_SCSI_IO request description) and sent to the " +"controller or the SCSI controller may be immediately programmed to send this " +"RESET message to the device or this request may be just not supported (and " +"return the status `CAM_REQ_INVALID`). Also on completion of the request all " +"the disconnected transactions for this target must be aborted (probably in " +"the interrupt routine)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:588 +msgid "" +"Also all the current negotiations for the target are lost on reset, so they " +"might be cleaned too. Or they clearing may be deferred, because anyway the " +"target would request re-negotiation on the next transaction." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:589 +#, no-wrap +msgid "_XPT_RESET_BUS_ - send the RESET signal to the SCSI bus" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:592 +msgid "" +"No arguments are passed in the CCB, the only interesting argument is the " +"SCSI bus indicated by the struct sim pointer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:594 +msgid "" +"A minimalistic implementation would forget the SCSI negotiations for all the " +"devices on the bus and return the status CAM_REQ_CMP." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:597 +msgid "" +"The proper implementation would in addition actually reset the SCSI bus " +"(possible also reset the SCSI controller) and mark all the CCBs being " +"processed, both those in the hardware queue and those being disconnected, as " +"done with the status CAM_SCSI_BUS_RESET. Like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:603 +#, no-wrap +msgid "" +" int targ, lun;\n" +" struct xxx_hcb *h, *hh;\n" +" struct ccb_trans_settings neg;\n" +" struct cam_path *path;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:609 +#, no-wrap +msgid "" +" /* The SCSI bus reset may take a long time, in this case its completion\n" +" * should be checked by interrupt or timeout. But for simplicity\n" +" * we assume here that it is really fast.\n" +" */\n" +" reset_scsi_bus(softc);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:615 +#, no-wrap +msgid "" +" /* drop all enqueued CCBs */\n" +" for (h = softc->first_queued_hcb; h != NULL; h = hh) {\n" +" hh = h->next;\n" +" free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:621 +#, no-wrap +msgid "" +" /* the clean values of negotiations to report */\n" +" neg.bus_width = 8;\n" +" neg.sync_period = neg.sync_offset = 0;\n" +" neg.valid = (CCB_TRANS_BUS_WIDTH_VALID\n" +" | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:625 +#, no-wrap +msgid "" +" /* drop all disconnected CCBs and clean negotiations */\n" +" for (targ=0; targ <= OUR_MAX_SUPPORTED_TARGET; targ++) {\n" +" clean_negotiations(softc, targ);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:633 +#, no-wrap +msgid "" +" /* report the event if possible */\n" +" if (xpt_create_path(&path, /*periph*/NULL,\n" +" cam_sim_path(sim), targ,\n" +" CAM_LUN_WILDCARD) == CAM_REQ_CMP) {\n" +" xpt_async(AC_TRANSFER_NEG, path, &neg);\n" +" xpt_free_path(path);\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:640 +#, no-wrap +msgid "" +" for (lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++)\n" +" for (h = softc->first_discon_hcb[targ][lun]; h != NULL; h = hh) {\n" +" hh=h->next;\n" +" free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);\n" +" }\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:643 +#, no-wrap +msgid "" +" ccb->ccb_h.status = CAM_REQ_CMP;\n" +" xpt_done(ccb);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:647 +#, no-wrap +msgid "" +" /* report the event */\n" +" xpt_async(AC_BUS_RESET, softc->wpath, NULL);\n" +" return;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:650 +msgid "" +"Implementing the SCSI bus reset as a function may be a good idea because it " +"would be re-used by the timeout function as a last resort if the things go " +"wrong." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:651 +#, no-wrap +msgid "_XPT_ABORT_ - abort the specified CCB" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:655 +msgid "" +"The arguments are transferred in the instance \"struct ccb_abort cab\" of " +"the union ccb. The only argument field in it is:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:657 +msgid "_abort_ccb_ - pointer to the CCB to be aborted" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:660 +msgid "" +"If the abort is not supported just return the status CAM_UA_ABORT. This is " +"also the easy way to minimally implement this call, return CAM_UA_ABORT in " +"any case." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:663 +msgid "" +"The hard way is to implement this request honestly. First check that abort " +"applies to a SCSI transaction:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:668 +#, no-wrap +msgid "" +" struct ccb *abort_ccb;\n" +" abort_ccb = ccb->cab.abort_ccb;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:674 +#, no-wrap +msgid "" +" if (abort_ccb->ccb_h.func_code != XPT_SCSI_IO) {\n" +" ccb->ccb_h.status = CAM_UA_ABORT;\n" +" xpt_done(ccb);\n" +" return;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:678 +msgid "" +"Then it is necessary to find this CCB in our queue. This can be done by " +"walking the list of all our hardware control blocks in search for one " +"associated with this CCB:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:682 +#, no-wrap +msgid " struct xxx_hcb *hcb, *h;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:684 +#, no-wrap +msgid " hcb = NULL;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:695 +#, no-wrap +msgid "" +" /* We assume that softc->first_hcb is the head of the list of all\n" +" * HCBs associated with this bus, including those enqueued for\n" +" * processing, being processed by hardware and disconnected ones.\n" +" */\n" +" for (h = softc->first_hcb; h != NULL; h = h->next) {\n" +" if (h->ccb == abort_ccb) {\n" +" hcb = h;\n" +" break;\n" +" }\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:702 +#, no-wrap +msgid "" +" if (hcb == NULL) {\n" +" /* no such CCB in our queue */\n" +" ccb->ccb_h.status = CAM_PATH_INVALID;\n" +" xpt_done(ccb);\n" +" return;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:704 +#, no-wrap +msgid " hcb=found_hcb;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:709 +msgid "" +"Now we look at the current processing status of the HCB. It may be either " +"sitting in the queue waiting to be sent to the SCSI bus, being transferred " +"right now, or disconnected and waiting for the result of the command, or " +"actually completed by hardware but not yet marked as done by software. To " +"make sure that we do not get in any races with hardware we mark the HCB as " +"being aborted, so that if this HCB is about to be sent to the SCSI bus the " +"SCSI controller will see this flag and skip it." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:713 +#, no-wrap +msgid " int hstatus;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:718 +#, no-wrap +msgid "" +" /* shown as a function, in case special action is needed to make\n" +" * this flag visible to hardware\n" +" */\n" +" set_hcb_flags(hcb, HCB_BEING_ABORTED);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:720 +#, no-wrap +msgid " abort_again:\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:730 +#, no-wrap +msgid "" +" hstatus = get_hcb_status(hcb);\n" +" switch (hstatus) {\n" +" case HCB_SITTING_IN_QUEUE:\n" +" remove_hcb_from_hardware_queue(hcb);\n" +" /* FALLTHROUGH */\n" +" case HCB_COMPLETED:\n" +" /* this is an easy case */\n" +" free_hcb_and_ccb_done(hcb, abort_ccb, CAM_REQ_ABORTED);\n" +" break;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:737 +msgid "" +"If the CCB is being transferred right now we would like to signal to the " +"SCSI controller in some hardware-dependent way that we want to abort the " +"current transfer. The SCSI controller would set the SCSI ATTENTION signal " +"and when the target responds to it send an ABORT message. We also reset the " +"timeout to make sure that the target is not sleeping forever. If the " +"command would not get aborted in some reasonable time like 10 seconds the " +"timeout routine would go ahead and reset the whole SCSI bus. Since the " +"command will be aborted in some reasonable time we can just return the abort " +"request now as successfully completed, and mark the aborted CCB as aborted " +"(but not mark it as done yet)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:753 +#, no-wrap +msgid "" +" case HCB_BEING_TRANSFERRED:\n" +" untimeout(xxx_timeout, (caddr_t) hcb, abort_ccb->ccb_h.timeout_ch);\n" +" abort_ccb->ccb_h.timeout_ch =\n" +" timeout(xxx_timeout, (caddr_t) hcb, 10 * hz);\n" +" abort_ccb->ccb_h.status = CAM_REQ_ABORTED;\n" +" /* ask the controller to abort that HCB, then generate\n" +" * an interrupt and stop\n" +" */\n" +" if (signal_hardware_to_abort_hcb_and_stop(hcb) < 0) {\n" +" /* oops, we missed the race with hardware, this transaction\n" +" * got off the bus before we aborted it, try again */\n" +" goto abort_again;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:755 +#, no-wrap +msgid " break;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:759 +msgid "" +"If the CCB is in the list of disconnected then set it up as an abort request " +"and re-queue it at the front of hardware queue. Reset the timeout and " +"report the abort request to be completed." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:773 +#, no-wrap +msgid "" +" case HCB_DISCONNECTED:\n" +" untimeout(xxx_timeout, (caddr_t) hcb, abort_ccb->ccb_h.timeout_ch);\n" +" abort_ccb->ccb_h.timeout_ch =\n" +" timeout(xxx_timeout, (caddr_t) hcb, 10 * hz);\n" +" put_abort_message_into_hcb(hcb);\n" +" put_hcb_at_the_front_of_hardware_queue(hcb);\n" +" break;\n" +" }\n" +" ccb->ccb_h.status = CAM_REQ_CMP;\n" +" xpt_done(ccb);\n" +" return;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:778 +msgid "" +"That is all for the ABORT request, although there is one more issue. As the " +"ABORT message cleans all the ongoing transactions on a LUN we have to mark " +"all the other active transactions on this LUN as aborted. That should be " +"done in the interrupt routine, after the transaction gets aborted." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:782 +msgid "" +"Implementing the CCB abort as a function may be quite a good idea, this " +"function can be re-used if an I/O transaction times out. The only " +"difference would be that the timed out transaction would return the status " +"CAM_CMD_TIMEOUT for the timed out request. Then the case XPT_ABORT would be " +"small, like that:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:788 +#, no-wrap +msgid "" +" case XPT_ABORT:\n" +" struct ccb *abort_ccb;\n" +" abort_ccb = ccb->cab.abort_ccb;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:801 +#, no-wrap +msgid "" +" if (abort_ccb->ccb_h.func_code != XPT_SCSI_IO) {\n" +" ccb->ccb_h.status = CAM_UA_ABORT;\n" +" xpt_done(ccb);\n" +" return;\n" +" }\n" +" if (xxx_abort_ccb(abort_ccb, CAM_REQ_ABORTED) < 0)\n" +" /* no such CCB in our queue */\n" +" ccb->ccb_h.status = CAM_PATH_INVALID;\n" +" else\n" +" ccb->ccb_h.status = CAM_REQ_CMP;\n" +" xpt_done(ccb);\n" +" return;\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:803 +#, no-wrap +msgid "_XPT_SET_TRAN_SETTINGS_ - explicitly set values of SCSI transfer settings" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:806 +msgid "" +"The arguments are transferred in the instance \"struct ccb_trans_setting " +"cts\" of the union ccb:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:808 +msgid "_valid_ - a bitmask showing which settings should be updated:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:809 +msgid "_CCB_TRANS_SYNC_RATE_VALID_ - synchronous transfer rate" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:810 +msgid "_CCB_TRANS_SYNC_OFFSET_VALID_ - synchronous offset" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:811 +msgid "_CCB_TRANS_BUS_WIDTH_VALID_ - bus width" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:812 +msgid "_CCB_TRANS_DISC_VALID_ - set enable/disable disconnection" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:813 +msgid "_CCB_TRANS_TQ_VALID_ - set enable/disable tagged queuing" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:815 +msgid "" +"_flags_ - consists of two parts, binary arguments and identification of sub-" +"operations. The binary arguments are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:816 +msgid "_CCB_TRANS_DISC_ENB_ - enable disconnection" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:817 +msgid "_CCB_TRANS_TAG_ENB_ - enable tagged queuing" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:818 +msgid "the sub-operations are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:819 +msgid "_CCB_TRANS_CURRENT_SETTINGS_ - change the current negotiations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:820 +msgid "" +"_CCB_TRANS_USER_SETTINGS_ - remember the desired user values sync_period, " +"sync_offset - self-explanatory, if sync_offset==0 then the asynchronous mode " +"is requested bus_width - bus width, in bits (not bytes)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:825 +msgid "" +"Two sets of negotiated parameters are supported, the user settings and the " +"current settings. The user settings are not really used much in the SIM " +"drivers, this is mostly just a piece of memory where the upper levels can " +"store (and later recall) its ideas about the parameters. Setting the user " +"parameters does not cause re-negotiation of the transfer rates. But when " +"the SCSI controller does a negotiation it must never set the values higher " +"than the user parameters, so it is essentially the top boundary." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:830 +msgid "" +"The current settings are, as the name says, current. Changing them means " +"that the parameters must be re-negotiated on the next transfer. Again, " +"these \"new current settings\" are not supposed to be forced on the device, " +"just they are used as the initial step of negotiations. Also they must be " +"limited by actual capabilities of the SCSI controller: for example, if the " +"SCSI controller has 8-bit bus and the request asks to set 16-bit wide " +"transfers this parameter must be silently truncated to 8-bit transfers " +"before sending it to the device." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:832 +msgid "" +"One caveat is that the bus width and synchronous parameters are per target " +"while the disconnection and tag enabling parameters are per lun." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:834 +msgid "" +"The recommended implementation is to keep 3 sets of negotiated (bus width " +"and synchronous transfer) parameters:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:836 +msgid "_user_ - the user set, as above" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:837 +msgid "_current_ - those actually in effect" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:838 +msgid "_goal_ - those requested by setting of the \"current\" parameters" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:840 +msgid "The code looks like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:846 +#, no-wrap +msgid "" +" struct ccb_trans_settings *cts;\n" +" int targ, lun;\n" +" int flags;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:858 +#, no-wrap +msgid "" +" cts = &ccb->cts;\n" +" targ = ccb_h->target_id;\n" +" lun = ccb_h->target_lun;\n" +" flags = cts->flags;\n" +" if (flags & CCB_TRANS_USER_SETTINGS) {\n" +" if (flags & CCB_TRANS_SYNC_RATE_VALID)\n" +" softc->user_sync_period[targ] = cts->sync_period;\n" +" if (flags & CCB_TRANS_SYNC_OFFSET_VALID)\n" +" softc->user_sync_offset[targ] = cts->sync_offset;\n" +" if (flags & CCB_TRANS_BUS_WIDTH_VALID)\n" +" softc->user_bus_width[targ] = cts->bus_width;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:877 +#, no-wrap +msgid "" +" if (flags & CCB_TRANS_DISC_VALID) {\n" +" softc->user_tflags[targ][lun] &= ~CCB_TRANS_DISC_ENB;\n" +" softc->user_tflags[targ][lun] |= flags & CCB_TRANS_DISC_ENB;\n" +" }\n" +" if (flags & CCB_TRANS_TQ_VALID) {\n" +" softc->user_tflags[targ][lun] &= ~CCB_TRANS_TQ_ENB;\n" +" softc->user_tflags[targ][lun] |= flags & CCB_TRANS_TQ_ENB;\n" +" }\n" +" }\n" +" if (flags & CCB_TRANS_CURRENT_SETTINGS) {\n" +" if (flags & CCB_TRANS_SYNC_RATE_VALID)\n" +" softc->goal_sync_period[targ] =\n" +" max(cts->sync_period, OUR_MIN_SUPPORTED_PERIOD);\n" +" if (flags & CCB_TRANS_SYNC_OFFSET_VALID)\n" +" softc->goal_sync_offset[targ] =\n" +" min(cts->sync_offset, OUR_MAX_SUPPORTED_OFFSET);\n" +" if (flags & CCB_TRANS_BUS_WIDTH_VALID)\n" +" softc->goal_bus_width[targ] = min(cts->bus_width, OUR_BUS_WIDTH);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:890 +#, no-wrap +msgid "" +" if (flags & CCB_TRANS_DISC_VALID) {\n" +" softc->current_tflags[targ][lun] &= ~CCB_TRANS_DISC_ENB;\n" +" softc->current_tflags[targ][lun] |= flags & CCB_TRANS_DISC_ENB;\n" +" }\n" +" if (flags & CCB_TRANS_TQ_VALID) {\n" +" softc->current_tflags[targ][lun] &= ~CCB_TRANS_TQ_ENB;\n" +" softc->current_tflags[targ][lun] |= flags & CCB_TRANS_TQ_ENB;\n" +" }\n" +" }\n" +" ccb->ccb_h.status = CAM_REQ_CMP;\n" +" xpt_done(ccb);\n" +" return;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:894 +msgid "" +"Then when the next I/O request will be processed it will check if it has to " +"re-negotiate, for example by calling the function target_negotiated(hcb). " +"It can be implemented like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:902 +#, no-wrap +msgid "" +" int\n" +" target_negotiated(struct xxx_hcb *hcb)\n" +" {\n" +" struct softc *softc = hcb->softc;\n" +" int targ = hcb->targ;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:910 +#, no-wrap +msgid "" +" if (softc->current_sync_period[targ] != softc->goal_sync_period[targ]\n" +" || softc->current_sync_offset[targ] != softc->goal_sync_offset[targ]\n" +" || softc->current_bus_width[targ] != softc->goal_bus_width[targ])\n" +" return 0; /* FALSE */\n" +" else\n" +" return 1; /* TRUE */\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:914 +msgid "" +"After the values are re-negotiated the resulting values must be assigned to " +"both current and goal parameters, so for future I/O transactions the current " +"and goal parameters would be the same and `target_negotiated()` would return " +"TRUE. When the card is initialized (in `xxx_attach()`) the current " +"negotiation values must be initialized to narrow asynchronous mode, the goal " +"and current values must be initialized to the maximal values supported by " +"controller." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:915 +#, no-wrap +msgid "_XPT_GET_TRAN_SETTINGS_ - get values of SCSI transfer settings" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:920 +msgid "" +"This operations is the reverse of XPT_SET_TRAN_SETTINGS. Fill up the CCB " +"instance \"struct ccb_trans_setting cts\" with data as requested by the " +"flags CCB_TRANS_CURRENT_SETTINGS or CCB_TRANS_USER_SETTINGS (if both are set " +"then the existing drivers return the current settings). Set all the bits in " +"the valid field." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:921 +#, no-wrap +msgid "_XPT_CALC_GEOMETRY_ - calculate logical (BIOS) geometry of the disk" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:924 +msgid "" +"The arguments are transferred in the instance \"struct ccb_calc_geometry " +"ccg\" of the union ccb:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:926 +msgid "_block_size_ - input, block (A.K.A sector) size in bytes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:927 +msgid "_volume_size_ - input, volume size in bytes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:928 +msgid "_cylinders_ - output, logical cylinders" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:929 +msgid "_heads_ - output, logical heads" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:930 +msgid "_secs_per_track_ - output, logical sectors per track" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:933 +msgid "" +"If the returned geometry differs much enough from what the SCSI controller " +"BIOS thinks and a disk on this SCSI controller is used as bootable the " +"system may not be able to boot. The typical calculation example taken from " +"the aic7xxx driver is:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:940 +#, no-wrap +msgid "" +" struct ccb_calc_geometry *ccg;\n" +" u_int32_t size_mb;\n" +" u_int32_t secs_per_cylinder;\n" +" int extended;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:945 +#, no-wrap +msgid "" +" ccg = &ccb->ccg;\n" +" size_mb = ccg->volume_size\n" +" / ((1024L * 1024L) / ccg->block_size);\n" +" extended = check_cards_EEPROM_for_extended_geometry(softc);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:958 +#, no-wrap +msgid "" +" if (size_mb > 1024 && extended) {\n" +" ccg->heads = 255;\n" +" ccg->secs_per_track = 63;\n" +" } else {\n" +" ccg->heads = 64;\n" +" ccg->secs_per_track = 32;\n" +" }\n" +" secs_per_cylinder = ccg->heads * ccg->secs_per_track;\n" +" ccg->cylinders = ccg->volume_size / secs_per_cylinder;\n" +" ccb->ccb_h.status = CAM_REQ_CMP;\n" +" xpt_done(ccb);\n" +" return;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:963 +msgid "" +"This gives the general idea, the exact calculation depends on the quirks of " +"the particular BIOS. If BIOS provides no way set the \"extended " +"translation\" flag in EEPROM this flag should normally be assumed equal to " +"1. Other popular geometries are:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:968 +#, no-wrap +msgid "" +" 128 heads, 63 sectors - Symbios controllers\n" +" 16 heads, 63 sectors - old controllers\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:971 +msgid "" +"Some system BIOSes and SCSI BIOSes fight with each other with variable " +"success, for example a combination of Symbios 875/895 SCSI and Phoenix BIOS " +"can give geometry 128/63 after power up and 255/63 after a hard reset or " +"soft reboot." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:972 +#, no-wrap +msgid "_XPT_PATH_INQ_ - path inquiry, in other words get the SIM driver and SCSI controller (also known as HBA - Host Bus Adapter) properties" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:975 +msgid "" +"The properties are returned in the instance \"struct ccb_pathinq cpi\" of " +"the union ccb:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:977 +msgid "version_num - the SIM driver version number, now all drivers use 1" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:978 +msgid "hba_inquiry - bitmask of features supported by the controller:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:979 +msgid "PI_MDP_ABLE - supports MDP message (something from SCSI3?)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:980 +msgid "PI_WIDE_32 - supports 32 bit wide SCSI" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:981 +msgid "PI_WIDE_16 - supports 16 bit wide SCSI" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:982 +msgid "PI_SDTR_ABLE - can negotiate synchronous transfer rate" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:983 +msgid "PI_LINKED_CDB - supports linked commands" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:984 +msgid "PI_TAG_ABLE - supports tagged commands" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:985 +msgid "" +"PI_SOFT_RST - supports soft reset alternative (hard reset and soft reset are " +"mutually exclusive within a SCSI bus)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:986 +msgid "target_sprt - flags for target mode support, 0 if unsupported" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:987 +msgid "hba_misc - miscellaneous controller features:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:988 +msgid "PIM_SCANHILO - bus scans from high ID to low ID" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:989 +msgid "PIM_NOREMOVE - removable devices not included in scan" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:990 +msgid "PIM_NOINITIATOR - initiator role not supported" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:991 +msgid "PIM_NOBUSRESET - user has disabled initial BUS RESET" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:992 +msgid "" +"hba_eng_cnt - mysterious HBA engine count, something related to compression, " +"now is always set to 0" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:993 +msgid "vuhba_flags - vendor-unique flags, unused now" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:994 +msgid "" +"max_target - maximal supported target ID (7 for 8-bit bus, 15 for 16-bit " +"bus, 127 for Fibre Channel)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:995 +msgid "" +"max_lun - maximal supported LUN ID (7 for older SCSI controllers, 63 for " +"newer ones)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:996 +msgid "async_flags - bitmask of installed Async handler, unused now" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:997 +msgid "hpath_id - highest Path ID in the subsystem, unused now" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:998 +msgid "unit_number - the controller unit number, cam_sim_unit(sim)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:999 +msgid "bus_id - the bus number, cam_sim_bus(sim)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1000 +msgid "initiator_id - the SCSI ID of the controller itself" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1001 +msgid "" +"base_transfer_speed - nominal transfer speed in KB/s for asynchronous narrow " +"transfers, equals to 3300 for SCSI" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1002 +msgid "" +"sim_vid - SIM driver's vendor id, a zero-terminated string of maximal length " +"SIM_IDLEN including the terminating zero" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1003 +msgid "" +"hba_vid - SCSI controller's vendor id, a zero-terminated string of maximal " +"length HBA_IDLEN including the terminating zero" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1004 +msgid "" +"dev_name - device driver name, a zero-terminated string of maximal length " +"DEV_IDLEN including the terminating zero, equal to cam_sim_name(sim)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1006 +msgid "" +"The recommended way of setting the string fields is using strncpy, like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1010 +#, no-wrap +msgid " strncpy(cpi->dev_name, cam_sim_name(sim), DEV_IDLEN);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1013 +msgid "" +"After setting the values set the status to CAM_REQ_CMP and mark the CCB as " +"done." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1015 +#, no-wrap +msgid "Polling xxx_poll" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1029 +msgid "" +"The poll function is used to simulate the interrupts when the interrupt " +"subsystem is not functioning (for example, when the system has crashed and " +"is creating the system dump). The CAM subsystem sets the proper interrupt " +"level before calling the poll routine. So all it needs to do is to call the " +"interrupt routine (or the other way around, the poll routine may be doing " +"the real action and the interrupt routine would just call the poll " +"routine). Why bother about a separate function then? This has to do with " +"different calling conventions. The `xxx_poll` routine gets the struct " +"cam_sim pointer as its argument while the PCI interrupt routine by common " +"convention gets pointer to the struct `xxx_softc` and the ISA interrupt " +"routine gets just the device unit number. So the poll routine would " +"normally look as:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1037 +#, no-wrap +msgid "" +"static void\n" +"xxx_poll(struct cam_sim *sim)\n" +"{\n" +" xxx_intr((struct xxx_softc *)cam_sim_softc(sim)); /* for PCI device */\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1040 +msgid "or" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1048 +#, no-wrap +msgid "" +"static void\n" +"xxx_poll(struct cam_sim *sim)\n" +"{\n" +" xxx_intr(cam_sim_unit(sim)); /* for ISA device */\n" +"}\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1051 +#, no-wrap +msgid "Asynchronous Events" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1054 +msgid "" +"If an asynchronous event callback has been set up then the callback function " +"should be defined." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1059 +#, no-wrap +msgid "" +"static void\n" +"ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1062 +msgid "callback_arg - the value supplied when registering the callback" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1063 +msgid "code - identifies the type of event" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1064 +msgid "path - identifies the devices to which the event applies" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1065 +msgid "arg - event-specific argument" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1067 +msgid "Implementation for a single type of event, AC_LOST_DEVICE, looks like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1074 +#, no-wrap +msgid "" +" struct xxx_softc *softc;\n" +" struct cam_sim *sim;\n" +" int targ;\n" +" struct ccb_trans_settings neg;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1093 +#, no-wrap +msgid "" +" sim = (struct cam_sim *)callback_arg;\n" +" softc = (struct xxx_softc *)cam_sim_softc(sim);\n" +" switch (code) {\n" +" case AC_LOST_DEVICE:\n" +" targ = xpt_path_target_id(path);\n" +" if (targ <= OUR_MAX_SUPPORTED_TARGET) {\n" +" clean_negotiations(softc, targ);\n" +" /* send indication to CAM */\n" +" neg.bus_width = 8;\n" +" neg.sync_period = neg.sync_offset = 0;\n" +" neg.valid = (CCB_TRANS_BUS_WIDTH_VALID\n" +" | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID);\n" +" xpt_async(AC_TRANSFER_NEG, path, &neg);\n" +" }\n" +" break;\n" +" default:\n" +" break;\n" +" }\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1096 +#, no-wrap +msgid "Interrupts" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1099 +msgid "" +"The exact type of the interrupt routine depends on the type of the " +"peripheral bus (PCI, ISA and so on) to which the SCSI controller is " +"connected." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1106 +msgid "" +"The interrupt routines of the SIM drivers run at the interrupt level " +"splcam. So `splcam()` should be used in the driver to synchronize activity " +"between the interrupt routine and the rest of the driver (for a " +"multiprocessor-aware driver things get yet more interesting but we ignore " +"this case here). The pseudo-code in this document happily ignores the " +"problems of synchronization. The real code must not ignore them. A simple-" +"minded approach is to set `splcam()` on the entry to the other routines and " +"reset it on return thus protecting them by one big critical section. To " +"make sure that the interrupt level will be always restored a wrapper " +"function can be defined, like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1117 +#, no-wrap +msgid "" +" static void\n" +" xxx_action(struct cam_sim *sim, union ccb *ccb)\n" +" {\n" +" int s;\n" +" s = splcam();\n" +" xxx_action1(sim, ccb);\n" +" splx(s);\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1123 +#, no-wrap +msgid "" +" static void\n" +" xxx_action1(struct cam_sim *sim, union ccb *ccb)\n" +" {\n" +" ... process the request ...\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1127 +msgid "" +"This approach is simple and robust but the problem with it is that " +"interrupts may get blocked for a relatively long time and this would " +"negatively affect the system's performance. On the other hand the functions " +"of the `spl()` family have rather high overhead, so vast amount of tiny " +"critical sections may not be good either." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1130 +msgid "" +"The conditions handled by the interrupt routine and the details depend very " +"much on the hardware. We consider the set of \"typical\" conditions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1135 +msgid "" +"First, we check if a SCSI reset was encountered on the bus (probably caused " +"by another SCSI controller on the same SCSI bus). If so we drop all the " +"enqueued and disconnected requests, report the events and re-initialize our " +"SCSI controller. It is important that during this initialization the " +"controller will not issue another reset or else two controllers on the same " +"SCSI bus could ping-pong resets forever. The case of fatal controller error/" +"hang could be handled in the same place, but it will probably need also " +"sending RESET signal to the SCSI bus to reset the status of the connections " +"with the SCSI devices." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1141 +#, no-wrap +msgid "" +" int fatal=0;\n" +" struct ccb_trans_settings neg;\n" +" struct cam_path *path;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1146 +#, no-wrap +msgid "" +" if (detected_scsi_reset(softc)\n" +" || (fatal = detected_fatal_controller_error(softc))) {\n" +" int targ, lun;\n" +" struct xxx_hcb *h, *hh;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1152 +#, no-wrap +msgid "" +" /* drop all enqueued CCBs */\n" +" for(h = softc->first_queued_hcb; h != NULL; h = hh) {\n" +" hh = h->next;\n" +" free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1158 +#, no-wrap +msgid "" +" /* the clean values of negotiations to report */\n" +" neg.bus_width = 8;\n" +" neg.sync_period = neg.sync_offset = 0;\n" +" neg.valid = (CCB_TRANS_BUS_WIDTH_VALID\n" +" | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1162 +#, no-wrap +msgid "" +" /* drop all disconnected CCBs and clean negotiations */\n" +" for (targ=0; targ <= OUR_MAX_SUPPORTED_TARGET; targ++) {\n" +" clean_negotiations(softc, targ);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1170 +#, no-wrap +msgid "" +" /* report the event if possible */\n" +" if (xpt_create_path(&path, /*periph*/NULL,\n" +" cam_sim_path(sim), targ,\n" +" CAM_LUN_WILDCARD) == CAM_REQ_CMP) {\n" +" xpt_async(AC_TRANSFER_NEG, path, &neg);\n" +" xpt_free_path(path);\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1180 +#, no-wrap +msgid "" +" for (lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++)\n" +" for (h = softc->first_discon_hcb[targ][lun]; h != NULL; h = hh) {\n" +" hh=h->next;\n" +" if (fatal)\n" +" free_hcb_and_ccb_done(h, h->ccb, CAM_UNREC_HBA_ERROR);\n" +" else\n" +" free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);\n" +" }\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1183 +#, no-wrap +msgid "" +" /* report the event */\n" +" xpt_async(AC_BUS_RESET, softc->wpath, NULL);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1197 +#, no-wrap +msgid "" +" /* re-initialization may take a lot of time, in such case\n" +" * its completion should be signaled by another interrupt or\n" +" * checked on timeout - but for simplicity we assume here that\n" +" * it is really fast\n" +" */\n" +" if (!fatal) {\n" +" reinitialize_controller_without_scsi_reset(softc);\n" +" } else {\n" +" reinitialize_controller_with_scsi_reset(softc);\n" +" }\n" +" schedule_next_hcb(softc);\n" +" return;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1202 +msgid "" +"If interrupt is not caused by a controller-wide condition then probably " +"something has happened to the current hardware control block. Depending on " +"the hardware there may be other non-HCB-related events, we just do not " +"consider them here. Then we analyze what happened to this HCB:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1210 +#, no-wrap +msgid "" +" struct xxx_hcb *hcb, *h, *hh;\n" +" int hcb_status, scsi_status;\n" +" int ccb_status;\n" +" int targ;\n" +" int lun_to_freeze;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1219 +#, no-wrap +msgid "" +" hcb = get_current_hcb(softc);\n" +" if (hcb == NULL) {\n" +" /* either stray interrupt or something went very wrong\n" +" * or this is something hardware-dependent\n" +" */\n" +" handle as necessary;\n" +" return;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1222 +#, no-wrap +msgid "" +" targ = hcb->target;\n" +" hcb_status = get_status_of_current_hcb(softc);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1225 +msgid "" +"First we check if the HCB has completed and if so we check the returned SCSI " +"status." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1230 +#, no-wrap +msgid "" +" if (hcb_status == COMPLETED) {\n" +" scsi_status = get_completion_status(hcb);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1233 +msgid "" +"Then look if this status is related to the REQUEST SENSE command and if so " +"handle it in a simple way." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1247 +#, no-wrap +msgid "" +" if (hcb->flags & DOING_AUTOSENSE) {\n" +" if (scsi_status == GOOD) { /* autosense was successful */\n" +" hcb->ccb->ccb_h.status |= CAM_AUTOSNS_VALID;\n" +" free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_SCSI_STATUS_ERROR);\n" +" } else {\n" +" autosense_failed:\n" +" free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_AUTOSENSE_FAIL);\n" +" }\n" +" schedule_next_hcb(softc);\n" +" return;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1251 +msgid "" +"Else the command itself has completed, pay more attention to details. If " +"auto-sense is not disabled for this CCB and the command has failed with " +"sense data then run REQUEST SENSE command to receive that data." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1256 +#, no-wrap +msgid "" +" hcb->ccb->csio.scsi_status = scsi_status;\n" +" calculate_residue(hcb);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1273 +#, no-wrap +msgid "" +" if ((hcb->ccb->ccb_h.flags & CAM_DIS_AUTOSENSE)==0\n" +" && (scsi_status == CHECK_CONDITION\n" +" || scsi_status == COMMAND_TERMINATED)) {\n" +" /* start auto-SENSE */\n" +" hcb->flags |= DOING_AUTOSENSE;\n" +" setup_autosense_command_in_hcb(hcb);\n" +" restart_current_hcb(softc);\n" +" return;\n" +" }\n" +" if (scsi_status == GOOD)\n" +" free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_REQ_CMP);\n" +" else\n" +" free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_SCSI_STATUS_ERROR);\n" +" schedule_next_hcb(softc);\n" +" return;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1276 +msgid "" +"One typical thing would be negotiation events: negotiation messages received " +"from a SCSI target (in answer to our negotiation attempt or by target's " +"initiative) or the target is unable to negotiate (rejects our negotiation " +"messages or does not answer them)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1292 +#, no-wrap +msgid "" +" switch (hcb_status) {\n" +" case TARGET_REJECTED_WIDE_NEG:\n" +" /* revert to 8-bit bus */\n" +" softc->current_bus_width[targ] = softc->goal_bus_width[targ] = 8;\n" +" /* report the event */\n" +" neg.bus_width = 8;\n" +" neg.valid = CCB_TRANS_BUS_WIDTH_VALID;\n" +" xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &neg);\n" +" continue_current_hcb(softc);\n" +" return;\n" +" case TARGET_ANSWERED_WIDE_NEG:\n" +" {\n" +" int wd;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1298 +#, no-wrap +msgid "" +" wd = get_target_bus_width_request(softc);\n" +" if (wd <= softc->goal_bus_width[targ]) {\n" +" /* answer is acceptable */\n" +" softc->current_bus_width[targ] =\n" +" softc->goal_bus_width[targ] = neg.bus_width = wd;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1311 +#, no-wrap +msgid "" +" /* report the event */\n" +" neg.valid = CCB_TRANS_BUS_WIDTH_VALID;\n" +" xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &neg);\n" +" } else {\n" +" prepare_reject_message(hcb);\n" +" }\n" +" }\n" +" continue_current_hcb(softc);\n" +" return;\n" +" case TARGET_REQUESTED_WIDE_NEG:\n" +" {\n" +" int wd;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1315 +#, no-wrap +msgid "" +" wd = get_target_bus_width_request(softc);\n" +" wd = min (wd, OUR_BUS_WIDTH);\n" +" wd = min (wd, softc->user_bus_width[targ]);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1320 +#, no-wrap +msgid "" +" if (wd != softc->current_bus_width[targ]) {\n" +" /* the bus width has changed */\n" +" softc->current_bus_width[targ] =\n" +" softc->goal_bus_width[targ] = neg.bus_width = wd;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1330 +#, no-wrap +msgid "" +" /* report the event */\n" +" neg.valid = CCB_TRANS_BUS_WIDTH_VALID;\n" +" xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &neg);\n" +" }\n" +" prepare_width_nego_rsponse(hcb, wd);\n" +" }\n" +" continue_current_hcb(softc);\n" +" return;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1334 +msgid "" +"Then we handle any errors that could have happened during auto-sense in the " +"same simple-minded way as before. Otherwise we look closer at the details " +"again." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1339 +#, no-wrap +msgid "" +" if (hcb->flags & DOING_AUTOSENSE)\n" +" goto autosense_failed;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1341 +#, no-wrap +msgid " switch (hcb_status) {\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1345 +msgid "" +"The next event we consider is unexpected disconnect. Which is considered " +"normal after an ABORT or BUS DEVICE RESET message and abnormal in other " +"cases." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1361 +#, no-wrap +msgid "" +" case UNEXPECTED_DISCONNECT:\n" +" if (requested_abort(hcb)) {\n" +" /* abort affects all commands on that target+LUN, so\n" +" * mark all disconnected HCBs on that target+LUN as aborted too\n" +" */\n" +" for (h = softc->first_discon_hcb[hcb->target][hcb->lun];\n" +" h != NULL; h = hh) {\n" +" hh=h->next;\n" +" free_hcb_and_ccb_done(h, h->ccb, CAM_REQ_ABORTED);\n" +" }\n" +" ccb_status = CAM_REQ_ABORTED;\n" +" } else if (requested_bus_device_reset(hcb)) {\n" +" int lun;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1365 +#, no-wrap +msgid "" +" /* reset affects all commands on that target, so\n" +" * mark all disconnected HCBs on that target+LUN as reset\n" +" */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1372 +#, no-wrap +msgid "" +" for (lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++)\n" +" for (h = softc->first_discon_hcb[hcb->target][lun];\n" +" h != NULL; h = hh) {\n" +" hh=h->next;\n" +" free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1375 +#, no-wrap +msgid "" +" /* send event */\n" +" xpt_async(AC_SENT_BDR, hcb->ccb->ccb_h.path_id, NULL);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1386 +#, no-wrap +msgid "" +" /* this was the CAM_RESET_DEV request itself, it is completed */\n" +" ccb_status = CAM_REQ_CMP;\n" +" } else {\n" +" calculate_residue(hcb);\n" +" ccb_status = CAM_UNEXP_BUSFREE;\n" +" /* request the further code to freeze the queue */\n" +" hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN;\n" +" lun_to_freeze = hcb->lun;\n" +" }\n" +" break;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1389 +msgid "" +"If the target refuses to accept tags we notify CAM about that and return " +"back all commands for this LUN:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1397 +#, no-wrap +msgid "" +" case TAGS_REJECTED:\n" +" /* report the event */\n" +" neg.flags = 0 & ~CCB_TRANS_TAG_ENB;\n" +" neg.valid = CCB_TRANS_TQ_VALID;\n" +" xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &neg);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1403 +#, no-wrap +msgid "" +" ccb_status = CAM_MSG_REJECT_REC;\n" +" /* request the further code to freeze the queue */\n" +" hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN;\n" +" lun_to_freeze = hcb->lun;\n" +" break;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1406 +msgid "" +"Then we check a number of other conditions, with processing basically " +"limited to setting the CCB status:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1430 +#, no-wrap +msgid "" +" case SELECTION_TIMEOUT:\n" +" ccb_status = CAM_SEL_TIMEOUT;\n" +" /* request the further code to freeze the queue */\n" +" hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN;\n" +" lun_to_freeze = CAM_LUN_WILDCARD;\n" +" break;\n" +" case PARITY_ERROR:\n" +" ccb_status = CAM_UNCOR_PARITY;\n" +" break;\n" +" case DATA_OVERRUN:\n" +" case ODD_WIDE_TRANSFER:\n" +" ccb_status = CAM_DATA_RUN_ERR;\n" +" break;\n" +" default:\n" +" /* all other errors are handled in a generic way */\n" +" ccb_status = CAM_REQ_CMP_ERR;\n" +" /* request the further code to freeze the queue */\n" +" hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN;\n" +" lun_to_freeze = CAM_LUN_WILDCARD;\n" +" break;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1433 +msgid "" +"Then we check if the error was serious enough to freeze the input queue " +"until it gets proceeded and do so if it is:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1439 +#, no-wrap +msgid "" +" if (hcb->ccb->ccb_h.status & CAM_DEV_QFRZN) {\n" +" /* freeze the queue */\n" +" xpt_freeze_devq(ccb->ccb_h.path, /*count*/1);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1441 +#, no-wrap +msgid " /* re-queue all commands for this target/LUN back to CAM */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1444 +#, no-wrap +msgid "" +" for (h = softc->first_queued_hcb; h != NULL; h = hh) {\n" +" hh = h->next;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1453 +#, no-wrap +msgid "" +" if (targ == h->targ\n" +" && (lun_to_freeze == CAM_LUN_WILDCARD || lun_to_freeze == h->lun))\n" +" free_hcb_and_ccb_done(h, h->ccb, CAM_REQUEUE_REQ);\n" +" }\n" +" }\n" +" free_hcb_and_ccb_done(hcb, hcb->ccb, ccb_status);\n" +" schedule_next_hcb(softc);\n" +" return;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1456 +msgid "" +"This concludes the generic interrupt handling although specific controllers " +"may require some additions." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1458 +#, no-wrap +msgid "Errors Summary" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1464 +msgid "" +"When executing an I/O request many things may go wrong. The reason of error " +"can be reported in the CCB status with great detail. Examples of use are " +"spread throughout this document. For completeness here is the summary of " +"recommended responses for the typical error conditions:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1467 +msgid "" +"_CAM_RESRC_UNAVAIL_ - some resource is temporarily unavailable and the SIM " +"driver cannot generate an event when it will become available. An example " +"of this resource would be some intra-controller hardware resource for which " +"the controller does not generate an interrupt when it becomes available." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1468 +msgid "_CAM_UNCOR_PARITY_ - unrecovered parity error occurred" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1469 +msgid "" +"_CAM_DATA_RUN_ERR_ - data overrun or unexpected data phase (going in other " +"direction than specified in CAM_DIR_MASK) or odd transfer length for wide " +"transfer" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1470 +msgid "" +"_CAM_SEL_TIMEOUT_ - selection timeout occurred (target does not respond)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1471 +msgid "_CAM_CMD_TIMEOUT_ - command timeout occurred (the timeout function ran)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1472 +msgid "_CAM_SCSI_STATUS_ERROR_ - the device returned error" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1473 +msgid "" +"_CAM_AUTOSENSE_FAIL_ - the device returned error and the REQUEST SENSE " +"COMMAND failed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1474 +msgid "_CAM_MSG_REJECT_REC_ - MESSAGE REJECT message was received" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1475 +msgid "_CAM_SCSI_BUS_RESET_ - received SCSI bus reset" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1476 +msgid "" +"_CAM_REQ_CMP_ERR_ - \"impossible\" SCSI phase occurred or something else as " +"weird or just a generic error if further detail is not available" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1477 +msgid "_CAM_UNEXP_BUSFREE_ - unexpected disconnect occurred" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1478 +msgid "_CAM_BDR_SENT_ - BUS DEVICE RESET message was sent to the target" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1479 +msgid "_CAM_UNREC_HBA_ERROR_ - unrecoverable Host Bus Adapter Error" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1480 +msgid "_CAM_REQ_TOO_BIG_ - the request was too large for this controller" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1484 +msgid "" +"_CAM_REQUEUE_REQ_ - this request should be re-queued to preserve transaction " +"ordering. This typically occurs when the SIM recognizes an error that " +"should freeze the queue and must place other queued requests for the target " +"at the sim level back into the XPT queue. Typical cases of such errors are " +"selection timeouts, command timeouts and other like conditions. In such " +"cases the troublesome command returns the status indicating the error, the " +"and the other commands which have not be sent to the bus yet get re-queued." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1485 +msgid "" +"_CAM_LUN_INVALID_ - the LUN ID in the request is not supported by the SCSI " +"controller" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1486 +msgid "" +"_CAM_TID_INVALID_ - the target ID in the request is not supported by the " +"SCSI controller" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1488 +#, no-wrap +msgid "Timeout Handling" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1496 +msgid "" +"When the timeout for an HCB expires that request should be aborted, just " +"like with an XPT_ABORT request. The only difference is that the returned " +"status of aborted request should be CAM_CMD_TIMEOUT instead of " +"CAM_REQ_ABORTED (that is why implementation of the abort better be done as a " +"function). But there is one more possible problem: what if the abort " +"request itself will get stuck? In this case the SCSI bus should be reset, " +"just like with an XPT_RESET_BUS request (and the idea about implementing it " +"as a function called from both places applies here too). Also we should " +"reset the whole SCSI bus if a device reset request got stuck. So after all " +"the timeout function would look like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1505 +#, no-wrap +msgid "" +"static void\n" +"xxx_timeout(void *arg)\n" +"{\n" +" struct xxx_hcb *hcb = (struct xxx_hcb *)arg;\n" +" struct xxx_softc *softc;\n" +" struct ccb_hdr *ccb_h;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1508 +#, no-wrap +msgid "" +" softc = hcb->softc;\n" +" ccb_h = &hcb->ccb->ccb_h;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1515 +#, no-wrap +msgid "" +" if (hcb->flags & HCB_BEING_ABORTED || ccb_h->func_code == XPT_RESET_DEV) {\n" +" xxx_reset_bus(softc);\n" +" } else {\n" +" xxx_abort_ccb(hcb->ccb, CAM_CMD_TIMEOUT);\n" +" }\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1520 +msgid "" +"When we abort a request all the other disconnected requests to the same " +"target/LUN get aborted too. So there appears a question, should we return " +"them with status CAM_REQ_ABORTED or CAM_CMD_TIMEOUT? The current drivers use " +"CAM_CMD_TIMEOUT. This seems logical because if one request got timed out " +"then probably something really bad is happening to the device, so if they " +"would not be disturbed they would time out by themselves." +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/smp/_index.adoc b/documentation/content/en/books/arch-handbook/smp/_index.adoc index 5336f5fb73..dde5aaf93d 100644 --- a/documentation/content/en/books/arch-handbook/smp/_index.adoc +++ b/documentation/content/en/books/arch-handbook/smp/_index.adoc @@ -6,7 +6,8 @@ description: SMPng Design Document tags: ["SMPng", "introduction", "locks"] showBookMenu: true weight: 9 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/smp/" --- [[smp]] @@ -54,7 +55,11 @@ This document presents the current design and implementation of the SMPng Archit This document is a work-in-progress, and will be updated to reflect on-going design and implementation activities associated with the SMPng Project. Many sections currently exist only in outline form, but will be fleshed out as work proceeds. Updates or suggestions regarding the document may be directed to the document editors. -The goal of SMPng is to allow concurrency in the kernel. The kernel is basically one rather large and complex program. To make the kernel multi-threaded we use some of the same tools used to make other programs multi-threaded. These include mutexes, shared/exclusive locks, semaphores, and condition variables. For the definitions of these and other SMP-related terms, please see the <<smp-glossary>> section of this article. +The goal of SMPng is to allow concurrency in the kernel. The kernel is basically +one rather large and complex program. To make the kernel multi-threaded we use +some of the same tools used to make other programs multi-threaded. These include +mutexes, shared/exclusive locks, semaphores, and condition variables. For the +definitions of these and other SMP-related terms, please see the crossref:smp[smp-glossary, Glossary] section of this article. [[smp-lock-fundamentals]] == Basic Tools and Locking Fundamentals diff --git a/documentation/content/en/books/arch-handbook/smp/_index.po b/documentation/content/en/books/arch-handbook/smp/_index.po new file mode 100644 index 0000000000..67dab90afb --- /dev/null +++ b/documentation/content/en/books/arch-handbook/smp/_index.po @@ -0,0 +1,1396 @@ +# 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/smp/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:14 +#, no-wrap +msgid "SMPng Design Document" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:1 +#, no-wrap +msgid "Chapter 8. SMPng Design Document" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:52 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:55 +msgid "" +"This document presents the current design and implementation of the SMPng " +"Architecture. First, the basic primitives and tools are introduced. Next, a " +"general architecture for the FreeBSD kernel's synchronization and execution " +"model is laid out. Then, locking strategies for specific subsystems are " +"discussed, documenting the approaches taken to introduce fine-grained " +"synchronization and parallelism for each subsystem. Finally, detailed " +"implementation notes are provided to motivate design choices, and make the " +"reader aware of important implications involving the use of specific " +"primitives." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:57 +msgid "" +"This document is a work-in-progress, and will be updated to reflect on-going " +"design and implementation activities associated with the SMPng Project. Many " +"sections currently exist only in outline form, but will be fleshed out as " +"work proceeds. Updates or suggestions regarding the document may be directed " +"to the document editors." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:63 +msgid "" +"The goal of SMPng is to allow concurrency in the kernel. The kernel is " +"basically one rather large and complex program. To make the kernel multi-" +"threaded we use some of the same tools used to make other programs multi-" +"threaded. These include mutexes, shared/exclusive locks, semaphores, and " +"condition variables. For the definitions of these and other SMP-related " +"terms, please see the crossref:smp[smp-glossary, Glossary] section of this " +"article." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:65 +#, no-wrap +msgid "Basic Tools and Locking Fundamentals" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:67 +#, no-wrap +msgid "Atomic Instructions and Memory Barriers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:70 +msgid "" +"There are several existing treatments of memory barriers and atomic " +"instructions, so this section will not include a lot of detail. To put it " +"simply, one can not go around reading variables without a lock if a lock is " +"used to protect writes to that variable. This becomes obvious when you " +"consider that memory barriers simply determine relative order of memory " +"operations; they do not make any guarantee about timing of memory " +"operations. That is, a memory barrier does not force the contents of a CPU's " +"local cache or store buffer to flush. Instead, the memory barrier at lock " +"release simply ensures that all writes to the protected data will be visible " +"to other CPU's or devices if the write to release the lock is visible. The " +"CPU is free to keep that data in its cache or store buffer as long as it " +"wants. However, if another CPU performs an atomic instruction on the same " +"datum, the first CPU must guarantee that the updated value is made visible " +"to the second CPU along with any other operations that memory barriers may " +"require." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:72 +msgid "" +"For example, assuming a simple model where data is considered visible when " +"it is in main memory (or a global cache), when an atomic instruction is " +"triggered on one CPU, other CPU's store buffers and caches must flush any " +"writes to that same cache line along with any pending operations behind a " +"memory barrier." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:74 +msgid "" +"This requires one to take special care when using an item protected by " +"atomic instructions. For example, in the sleep mutex implementation, we have " +"to use an `atomic_cmpset` rather than an `atomic_set` to turn on the " +"`MTX_CONTESTED` bit. The reason is that we read the value of `mtx_lock` into " +"a variable and then make a decision based on that read. However, the value " +"we read may be stale, or it may change while we are making our decision. " +"Thus, when the `atomic_set` executed, it may end up setting the bit on " +"another value than the one we made the decision on. Thus, we have to use an " +"`atomic_cmpset` to set the value only if the value we made the decision on " +"is up-to-date and valid." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:76 +msgid "" +"Finally, atomic instructions only allow one item to be updated or read. If " +"one needs to atomically update several items, then a lock must be used " +"instead. For example, if two counters must be read and have values that are " +"consistent relative to each other, then those counters must be protected by " +"a lock rather than by separate atomic instructions." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:77 +#, no-wrap +msgid "Read Locks Versus Write Locks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:80 +msgid "" +"Read locks do not need to be as strong as write locks. Both types of locks " +"need to ensure that the data they are accessing is not stale. However, only " +"write access requires exclusive access. Multiple threads can safely read a " +"value. Using different types of locks for reads and writes can be " +"implemented in a number of ways." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:82 +msgid "" +"First, sx locks can be used in this manner by using an exclusive lock when " +"writing and a shared lock when reading. This method is quite straightforward." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:84 +msgid "" +"A second method is a bit more obscure. You can protect a datum with multiple " +"locks. Then for reading that data you simply need to have a read lock of one " +"of the locks. However, to write to the data, you need to have a write lock " +"of all of the locks. This can make writing rather expensive but can be " +"useful when data is accessed in various ways. For example, the parent " +"process pointer is protected by both the `proctree_lock` sx lock and the per-" +"process mutex. Sometimes the proc lock is easier as we are just checking to " +"see who a parent of a process is that we already have locked. However, other " +"places such as `inferior` need to walk the tree of processes via parent " +"pointers and locking each process would be prohibitive as well as a pain to " +"guarantee that the condition you are checking remains valid for both the " +"check and the actions taken as a result of the check." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:85 +#, no-wrap +msgid "Locking Conditions and Results" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:88 +msgid "" +"If you need a lock to check the state of a variable so that you can take an " +"action based on the state you read, you can not just hold the lock while " +"reading the variable and then drop the lock before you act on the value you " +"read. Once you drop the lock, the variable can change rendering your " +"decision invalid. Thus, you must hold the lock both while reading the " +"variable and while performing the action as a result of the test." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:90 +#, no-wrap +msgid "General Architecture and Design" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:92 +#, no-wrap +msgid "Interrupt Handling" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:95 +msgid "" +"Following the pattern of several other multi-threaded UNIX(R) kernels, " +"FreeBSD deals with interrupt handlers by giving them their own thread " +"context. Providing a context for interrupt handlers allows them to block on " +"locks. To help avoid latency, however, interrupt threads run at real-time " +"kernel priority. Thus, interrupt handlers should not execute for very long " +"to avoid starving other kernel threads. In addition, since multiple handlers " +"may share an interrupt thread, interrupt handlers should not sleep or use a " +"sleepable lock to avoid starving another interrupt handler." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:97 +msgid "" +"The interrupt threads currently in FreeBSD are referred to as heavyweight " +"interrupt threads. They are called this because switching to an interrupt " +"thread involves a full context switch. In the initial implementation, the " +"kernel was not preemptive and thus interrupts that interrupted a kernel " +"thread would have to wait until the kernel thread blocked or returned to " +"userland before they would have an opportunity to run." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:99 +msgid "" +"To deal with the latency problems, the kernel in FreeBSD has been made " +"preemptive. Currently, we only preempt a kernel thread when we release a " +"sleep mutex or when an interrupt comes in. However, the plan is to make the " +"FreeBSD kernel fully preemptive as described below." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:101 +msgid "" +"Not all interrupt handlers execute in a thread context. Instead, some " +"handlers execute directly in primary interrupt context. These interrupt " +"handlers are currently misnamed \"fast\" interrupt handlers since the " +"`INTR_FAST` flag used in earlier versions of the kernel is used to mark " +"these handlers. The only interrupts which currently use these types of " +"interrupt handlers are clock interrupts and serial I/O device interrupts. " +"Since these handlers do not have their own context, they may not acquire " +"blocking locks and thus may only use spin mutexes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:103 +msgid "" +"Finally, there is one optional optimization that can be added in MD code " +"called lightweight context switches. Since an interrupt thread executes in a " +"kernel context, it can borrow the vmspace of any process. Thus, in a " +"lightweight context switch, the switch to the interrupt thread does not " +"switch vmspaces but borrows the vmspace of the interrupted thread. In order " +"to ensure that the vmspace of the interrupted thread does not disappear out " +"from under us, the interrupted thread is not allowed to execute until the " +"interrupt thread is no longer borrowing its vmspace. This can happen when " +"the interrupt thread either blocks or finishes. If an interrupt thread " +"blocks, then it will use its own context when it is made runnable again. " +"Thus, it can release the interrupted thread." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:105 +msgid "" +"The cons of this optimization are that they are very machine specific and " +"complex and thus only worth the effort if their is a large performance " +"improvement. At this point it is probably too early to tell, and in fact, " +"will probably hurt performance as almost all interrupt handlers will " +"immediately block on Giant and require a thread fix-up when they block. " +"Also, an alternative method of interrupt handling has been proposed by Mike " +"Smith that works like so:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:107 +msgid "" +"Each interrupt handler has two parts: a predicate which runs in primary " +"interrupt context and a handler which runs in its own thread context." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:108 +msgid "" +"If an interrupt handler has a predicate, then when an interrupt is " +"triggered, the predicate is run. If the predicate returns true then the " +"interrupt is assumed to be fully handled and the kernel returns from the " +"interrupt. If the predicate returns false or there is no predicate, then the " +"threaded handler is scheduled to run." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:110 +msgid "" +"Fitting light weight context switches into this scheme might prove rather " +"complicated. Since we may want to change to this scheme at some point in the " +"future, it is probably best to defer work on light weight context switches " +"until we have settled on the final interrupt handling architecture and " +"determined how light weight context switches might or might not fit into it." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:111 +#, no-wrap +msgid "Kernel Preemption and Critical Sections" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:113 +#, no-wrap +msgid "Kernel Preemption in a Nutshell" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:116 +msgid "" +"Kernel preemption is fairly simple. The basic idea is that a CPU should " +"always be doing the highest priority work available. Well, that is the ideal " +"at least. There are a couple of cases where the expense of achieving the " +"ideal is not worth being perfect." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:118 +msgid "" +"Implementing full kernel preemption is very straightforward: when you " +"schedule a thread to be executed by putting it on a run queue, you check to " +"see if its priority is higher than the currently executing thread. If so, " +"you initiate a context switch to that thread." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:120 +msgid "" +"While locks can protect most data in the case of a preemption, not all of " +"the kernel is preemption safe. For example, if a thread holding a spin mutex " +"preempted and the new thread attempts to grab the same spin mutex, the new " +"thread may spin forever as the interrupted thread may never get a chance to " +"execute. Also, some code such as the code to assign an address space number " +"for a process during `exec` on the Alpha needs to not be preempted as it " +"supports the actual context switch code. Preemption is disabled for these " +"code sections by using a critical section." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:121 +#, no-wrap +msgid "Critical Sections" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:124 +msgid "" +"The responsibility of the critical section API is to prevent context " +"switches inside of a critical section. With a fully preemptive kernel, every " +"`setrunqueue` of a thread other than the current thread is a preemption " +"point. One implementation is for `critical_enter` to set a per-thread flag " +"that is cleared by its counterpart. If `setrunqueue` is called with this " +"flag set, it does not preempt regardless of the priority of the new thread " +"relative to the current thread. However, since critical sections are used in " +"spin mutexes to prevent context switches and multiple spin mutexes can be " +"acquired, the critical section API must support nesting. For this reason the " +"current implementation uses a nesting count instead of a single per-thread " +"flag." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:126 +msgid "" +"In order to minimize latency, preemptions inside of a critical section are " +"deferred rather than dropped. If a thread that would normally be preempted " +"to is made runnable while the current thread is in a critical section, then " +"a per-thread flag is set to indicate that there is a pending preemption. " +"When the outermost critical section is exited, the flag is checked. If the " +"flag is set, then the current thread is preempted to allow the higher " +"priority thread to run." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:128 +msgid "" +"Interrupts pose a problem with regards to spin mutexes. If a low-level " +"interrupt handler needs a lock, it needs to not interrupt any code needing " +"that lock to avoid possible data structure corruption. Currently, providing " +"this mechanism is piggybacked onto critical section API by means of the " +"`cpu_critical_enter` and `cpu_critical_exit` functions. Currently this API " +"disables and re-enables interrupts on all of FreeBSD's current platforms. " +"This approach may not be purely optimal, but it is simple to understand and " +"simple to get right. Theoretically, this second API need only be used for " +"spin mutexes that are used in primary interrupt context. However, to make " +"the code simpler, it is used for all spin mutexes and even all critical " +"sections. It may be desirable to split out the MD API from the MI API and " +"only use it in conjunction with the MI API in the spin mutex implementation. " +"If this approach is taken, then the MD API likely would need a rename to " +"show that it is a separate API." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:129 +#, no-wrap +msgid "Design Tradeoffs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:132 +msgid "" +"As mentioned earlier, a couple of trade-offs have been made to sacrifice " +"cases where perfect preemption may not always provide the best performance." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:134 +msgid "" +"The first trade-off is that the preemption code does not take other CPUs " +"into account. Suppose we have a two CPU's A and B with the priority of A's " +"thread as 4 and the priority of B's thread as 2. If CPU B makes a thread " +"with priority 1 runnable, then in theory, we want CPU A to switch to the new " +"thread so that we will be running the two highest priority runnable threads. " +"However, the cost of determining which CPU to enforce a preemption on as " +"well as actually signaling that CPU via an IPI along with the " +"synchronization that would be required would be enormous. Thus, the current " +"code would instead force CPU B to switch to the higher priority thread. Note " +"that this still puts the system in a better position as CPU B is executing a " +"thread of priority 1 rather than a thread of priority 2." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:136 +msgid "" +"The second trade-off limits immediate kernel preemption to real-time " +"priority kernel threads. In the simple case of preemption defined above, a " +"thread is always preempted immediately (or as soon as a critical section is " +"exited) if a higher priority thread is made runnable. However, many threads " +"executing in the kernel only execute in a kernel context for a short time " +"before either blocking or returning to userland. Thus, if the kernel " +"preempts these threads to run another non-realtime kernel thread, the kernel " +"may switch out the executing thread just before it is about to sleep or " +"execute. The cache on the CPU must then adjust to the new thread. When the " +"kernel returns to the preempted thread, it must refill all the cache " +"information that was lost. In addition, two extra context switches are " +"performed that could be avoided if the kernel deferred the preemption until " +"the first thread blocked or returned to userland. Thus, by default, the " +"preemption code will only preempt immediately if the higher priority thread " +"is a real-time priority thread." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:138 +msgid "" +"Turning on full kernel preemption for all kernel threads has value as a " +"debugging aid since it exposes more race conditions. It is especially useful " +"on UP systems were many races are hard to simulate otherwise. Thus, there is " +"a kernel option `FULL_PREEMPTION` to enable preemption for all kernel " +"threads that can be used for debugging purposes." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:139 +#, no-wrap +msgid "Thread Migration" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:142 +msgid "" +"Simply put, a thread migrates when it moves from one CPU to another. In a " +"non-preemptive kernel this can only happen at well-defined points such as " +"when calling `msleep` or returning to userland. However, in the preemptive " +"kernel, an interrupt can force a preemption and possible migration at any " +"time. This can have negative affects on per-CPU data since with the " +"exception of `curthread` and `curpcb` the data can change whenever you " +"migrate. Since you can potentially migrate at any time this renders " +"unprotected per-CPU data access rather useless. Thus it is desirable to be " +"able to disable migration for sections of code that need per-CPU data to be " +"stable." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:144 +msgid "" +"Critical sections currently prevent migration since they do not allow " +"context switches. However, this may be too strong of a requirement to " +"enforce in some cases since a critical section also effectively blocks " +"interrupt threads on the current processor. As a result, another API has " +"been provided to allow the current thread to indicate that if it preempted " +"it should not migrate to another CPU." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:146 +msgid "" +"This API is known as thread pinning and is provided by the scheduler. The " +"API consists of two functions: `sched_pin` and `sched_unpin`. These " +"functions manage a per-thread nesting count `td_pinned`. A thread is pinned " +"when its nesting count is greater than zero and a thread starts off unpinned " +"with a nesting count of zero. Each scheduler implementation is required to " +"ensure that pinned threads are only executed on the CPU that they were " +"executing on when the `sched_pin` was first called. Since the nesting count " +"is only written to by the thread itself and is only read by other threads " +"when the pinned thread is not executing but while `sched_lock` is held, then " +"`td_pinned` does not need any locking. The `sched_pin` function increments " +"the nesting count and `sched_unpin` decrements the nesting count. Note that " +"these functions only operate on the current thread and bind the current " +"thread to the CPU it is executing on at the time. To bind an arbitrary " +"thread to a specific CPU, the `sched_bind` and `sched_unbind` functions " +"should be used instead." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:147 +#, no-wrap +msgid "Callouts" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:150 +msgid "" +"The `timeout` kernel facility permits kernel services to register functions " +"for execution as part of the `softclock` software interrupt. Events are " +"scheduled based on a desired number of clock ticks, and callbacks to the " +"consumer-provided function will occur at approximately the right time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:152 +msgid "" +"The global list of pending timeout events is protected by a global spin " +"mutex, `callout_lock`; all access to the timeout list must be performed with " +"this mutex held. When `softclock` is woken up, it scans the list of pending " +"timeouts for those that should fire. In order to avoid lock order reversal, " +"the `softclock` thread will release the `callout_lock` mutex when invoking " +"the provided `timeout` callback function. If the `CALLOUT_MPSAFE` flag was " +"not set during registration, then Giant will be grabbed before invoking the " +"callout, and then released afterwards. The `callout_lock` mutex will be re-" +"grabbed before proceeding. The `softclock` code is careful to leave the list " +"in a consistent state while releasing the mutex. If `DIAGNOSTIC` is enabled, " +"then the time taken to execute each function is measured, and a warning is " +"generated if it exceeds a threshold." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:154 +#, no-wrap +msgid "Specific Locking Strategies" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:156 +#, no-wrap +msgid "Credentials" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:159 +msgid "" +"`struct ucred` is the kernel's internal credential structure, and is " +"generally used as the basis for process-driven access control within the " +"kernel. BSD-derived systems use a \"copy-on-write\" model for credential " +"data: multiple references may exist for a credential structure, and when a " +"change needs to be made, the structure is duplicated, modified, and then the " +"reference replaced. Due to wide-spread caching of the credential to " +"implement access control on open, this results in substantial memory " +"savings. With a move to fine-grained SMP, this model also saves " +"substantially on locking operations by requiring that modification only " +"occur on an unshared credential, avoiding the need for explicit " +"synchronization when consuming a known-shared credential." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:161 +msgid "" +"Credential structures with a single reference are considered mutable; shared " +"credential structures must not be modified or a race condition is risked. A " +"mutex, `cr_mtxp` protects the reference count of `struct ucred` so as to " +"maintain consistency. Any use of the structure requires a valid reference " +"for the duration of the use, or the structure may be released out from under " +"the illegitimate consumer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:163 +msgid "" +"The `struct ucred` mutex is a leaf mutex and is implemented via a mutex pool " +"for performance reasons." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:165 +msgid "" +"Usually, credentials are used in a read-only manner for access control " +"decisions, and in this case `td_ucred` is generally preferred because it " +"requires no locking. When a process' credential is updated the `proc` lock " +"must be held across the check and update operations thus avoid races. The " +"process credential `p_ucred` must be used for check and update operations to " +"prevent time-of-check, time-of-use races." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:167 +msgid "" +"If system call invocations will perform access control after an update to " +"the process credential, the value of `td_ucred` must also be refreshed to " +"the current process value. This will prevent use of a stale credential " +"following a change. The kernel automatically refreshes the `td_ucred` " +"pointer in the thread structure from the process `p_ucred` whenever a " +"process enters the kernel, permitting use of a fresh credential for kernel " +"access control." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:168 +#, no-wrap +msgid "File Descriptors and File Descriptor Tables" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:171 +msgid "Details to follow." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:172 +#, no-wrap +msgid "Jail Structures" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:175 +msgid "" +"`struct prison` stores administrative details pertinent to the maintenance " +"of jails created using the man:jail[2] API. This includes the per-jail " +"hostname, IP address, and related settings. This structure is reference-" +"counted since pointers to instances of the structure are shared by many " +"credential structures. A single mutex, `pr_mtx` protects read and write " +"access to the reference count and all mutable variables inside the struct " +"jail. Some variables are set only when the jail is created, and a valid " +"reference to the `struct prison` is sufficient to read these values. The " +"precise locking of each entry is documented via comments in [.filename]#sys/" +"jail.h#." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:176 +#, no-wrap +msgid "MAC Framework" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:179 +msgid "" +"The TrustedBSD MAC Framework maintains data in a variety of kernel objects, " +"in the form of `struct label`. In general, labels in kernel objects are " +"protected by the same lock as the remainder of the kernel object. For " +"example, the `v_label` label in `struct vnode` is protected by the vnode " +"lock on the vnode." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:181 +msgid "" +"In addition to labels maintained in standard kernel objects, the MAC " +"Framework also maintains a list of registered and active policies. The " +"policy list is protected by a global mutex (`mac_policy_list_lock`) and a " +"busy count (also protected by the mutex). Since many access control checks " +"may occur in parallel, entry to the framework for a read-only access to the " +"policy list requires holding the mutex while incrementing (and later " +"decrementing) the busy count. The mutex need not be held for the duration of " +"the MAC entry operation--some operations, such as label operations on file " +"system objects--are long-lived. To modify the policy list, such as during " +"policy registration and de-registration, the mutex must be held and the " +"reference count must be zero, to prevent modification of the list while it " +"is in use." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:183 +msgid "" +"A condition variable, `mac_policy_list_not_busy`, is available to threads " +"that need to wait for the list to become unbusy, but this condition variable " +"must only be waited on if the caller is holding no other locks, or a lock " +"order violation may be possible. The busy count, in effect, acts as a form " +"of shared/exclusive lock over access to the framework: the difference is " +"that, unlike with an sx lock, consumers waiting for the list to become " +"unbusy may be starved, rather than permitting lock order problems with " +"regards to the busy count and other locks that may be held on entry to (or " +"inside) the MAC Framework." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:184 +#, no-wrap +msgid "Modules" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:187 +msgid "" +"For the module subsystem there exists a single lock that is used to protect " +"the shared data. This lock is a shared/exclusive (SX) lock and has a good " +"chance of needing to be acquired (shared or exclusively), therefore there " +"are a few macros that have been added to make access to the lock more easy. " +"These macros can be located in [.filename]#sys/module.h# and are quite basic " +"in terms of usage. The main structures protected under this lock are the " +"`module_t` structures (when shared) and the global `modulelist_t` structure, " +"modules. One should review the related source code in [.filename]#kern/" +"kern_module.c# to further understand the locking strategy." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:188 +#, no-wrap +msgid "Newbus Device Tree" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:191 +msgid "" +"The newbus system will have one sx lock. Readers will hold a shared (read) " +"lock (man:sx_slock[9]) and writers will hold an exclusive (write) lock " +"(man:sx_xlock[9]). Internal functions will not do locking at all. Externally " +"visible ones will lock as needed. Those items that do not matter if the race " +"is won or lost will not be locked, since they tend to be read all over the " +"place (e.g., man:device_get_softc[9]). There will be relatively few changes " +"to the newbus data structures, so a single lock should be sufficient and not " +"impose a performance penalty." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:192 +#, no-wrap +msgid "Pipes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:195 +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:217 +msgid "..." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:196 +#, no-wrap +msgid "Processes and Threads" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:199 +msgid "process hierarchy" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:201 +msgid "proc locks, references" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:203 +msgid "" +"thread-specific copies of proc entries to freeze during system calls, " +"including td_ucred" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:205 +msgid "inter-process operations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:207 +msgid "process groups and sessions" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:208 +#, no-wrap +msgid "Scheduler" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:211 +msgid "" +"Lots of references to `sched_lock` and notes pointing at specific primitives " +"and related magic elsewhere in the document." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:212 +#, no-wrap +msgid "Select and Poll" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:215 +msgid "" +"The `select` and `poll` functions permit threads to block waiting on events " +"on file descriptors--most frequently, whether or not the file descriptors " +"are readable or writable." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:218 +#, no-wrap +msgid "SIGIO" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:221 +msgid "" +"The SIGIO service permits processes to request the delivery of a SIGIO " +"signal to its process group when the read/write status of specified file " +"descriptors changes. At most one process or process group is permitted to " +"register for SIGIO from any given kernel object, and that process or group " +"is referred to as the owner. Each object supporting SIGIO registration " +"contains pointer field that is `NULL` if the object is not registered, or " +"points to a `struct sigio` describing the registration. This field is " +"protected by a global mutex, `sigio_lock`. Callers to SIGIO maintenance " +"functions must pass in this field \"by reference\" so that local register " +"copies of the field are not made when unprotected by the lock." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:223 +msgid "" +"One `struct sigio` is allocated for each registered object associated with " +"any process or process group, and contains back-pointers to the object, " +"owner, signal information, a credential, and the general disposition of the " +"registration. Each process or progress group contains a list of registered " +"`struct sigio` structures, `p_sigiolst` for processes, and `pg_sigiolst` for " +"process groups. These lists are protected by the process or process group " +"locks respectively. Most fields in each `struct sigio` are constant for the " +"duration of the registration, with the exception of the `sio_pgsigio` field " +"which links the `struct sigio` into the process or process group list. " +"Developers implementing new kernel objects supporting SIGIO will, in " +"general, want to avoid holding structure locks while invoking SIGIO " +"supporting functions, such as `fsetown` or `funsetown` to avoid defining a " +"lock order between structure locks and the global SIGIO lock. This is " +"generally possible through use of an elevated reference count on the " +"structure, such as reliance on a file descriptor reference to a pipe during " +"a pipe operation." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:224 +#, no-wrap +msgid "Sysctl" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:227 +msgid "" +"The `sysctl` MIB service is invoked from both within the kernel and from " +"userland applications using a system call. At least two issues are raised in " +"locking: first, the protection of the structures maintaining the namespace, " +"and second, interactions with kernel variables and functions that are " +"accessed by the sysctl interface. Since sysctl permits the direct export " +"(and modification) of kernel statistics and configuration parameters, the " +"sysctl mechanism must become aware of appropriate locking semantics for " +"those variables. Currently, sysctl makes use of a single global sx lock to " +"serialize use of `sysctl`; however, it is assumed to operate under Giant and " +"other protections are not provided. The remainder of this section speculates " +"on locking and semantic changes to sysctl." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:229 +msgid "" +"Need to change the order of operations for sysctl's that update values from " +"read old, copyin and copyout, write new to copyin, lock, read old and write " +"new, unlock, copyout. Normal sysctl's that just copyout the old value and " +"set a new value that they copyin may still be able to follow the old model. " +"However, it may be cleaner to use the second model for all of the sysctl " +"handlers to avoid lock operations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:231 +msgid "" +"To allow for the common case, a sysctl could embed a pointer to a mutex in " +"the SYSCTL_FOO macros and in the struct. This would work for most sysctl's. " +"For values protected by sx locks, spin mutexes, or other locking strategies " +"besides a single sleep mutex, SYSCTL_PROC nodes could be used to get the " +"locking right." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:232 +#, no-wrap +msgid "Taskqueue" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:235 +msgid "" +"The taskqueue's interface has two basic locks associated with it in order to " +"protect the related shared data. The `taskqueue_queues_mutex` is meant to " +"serve as a lock to protect the `taskqueue_queues` TAILQ. The other mutex " +"lock associated with this system is the one in the `struct taskqueue` data " +"structure. The use of the synchronization primitive here is to protect the " +"integrity of the data in the `struct taskqueue`. It should be noted that " +"there are no separate macros to assist the user in locking down his/her own " +"work since these locks are most likely not going to be used outside of " +"[.filename]#kern/subr_taskqueue.c#." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:237 +#, no-wrap +msgid "Implementation Notes" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:239 +#, no-wrap +msgid "Sleep Queues" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:242 +msgid "" +"A sleep queue is a structure that holds the list of threads asleep on a wait " +"channel. Each thread that is not asleep on a wait channel carries a sleep " +"queue structure around with it. When a thread blocks on a wait channel, it " +"donates its sleep queue structure to that wait channel. Sleep queues " +"associated with a wait channel are stored in a hash table." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:244 +msgid "" +"The sleep queue hash table holds sleep queues for wait channels that have at " +"least one blocked thread. Each entry in the hash table is called a " +"sleepqueue chain. The chain contains a linked list of sleep queues and a " +"spin mutex. The spin mutex protects the list of sleep queues as well as the " +"contents of the sleep queue structures on the list. Only one sleep queue is " +"associated with a given wait channel. If multiple threads block on a wait " +"channel than the sleep queues associated with all but the first thread are " +"stored on a list of free sleep queues in the master sleep queue. When a " +"thread is removed from the sleep queue it is given one of the sleep queue " +"structures from the master queue's free list if it is not the only thread " +"asleep on the queue. The last thread is given the master sleep queue when it " +"is resumed. Since threads may be removed from the sleep queue in a different " +"order than they are added, a thread may depart from a sleep queue with a " +"different sleep queue structure than the one it arrived with." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:246 +msgid "" +"The `sleepq_lock` function locks the spin mutex of the sleep queue chain " +"that maps to a specific wait channel. The `sleepq_lookup` function looks in " +"the hash table for the master sleep queue associated with a given wait " +"channel. If no master sleep queue is found, it returns `NULL`. The " +"`sleepq_release` function unlocks the spin mutex associated with a given " +"wait channel." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:248 +msgid "" +"A thread is added to a sleep queue via the `sleepq_add`. This function " +"accepts the wait channel, a pointer to the mutex that protects the wait " +"channel, a wait message description string, and a mask of flags. The sleep " +"queue chain should be locked via `sleepq_lock` before this function is " +"called. If no mutex protects the wait channel (or it is protected by Giant), " +"then the mutex pointer argument should be `NULL`. The flags argument " +"contains a type field that indicates the kind of sleep queue that the thread " +"is being added to and a flag to indicate if the sleep is interruptible " +"(`SLEEPQ_INTERRUPTIBLE`). Currently there are only two types of sleep " +"queues: traditional sleep queues managed via the `msleep` and `wakeup` " +"functions (`SLEEPQ_MSLEEP`) and condition variable sleep queues " +"(`SLEEPQ_CONDVAR`). The sleep queue type and lock pointer argument are used " +"solely for internal assertion checking. Code that calls `sleepq_add` should " +"explicitly unlock any interlock protecting the wait channel after the " +"associated sleepqueue chain has been locked via `sleepq_lock` and before " +"blocking on the sleep queue via one of the waiting functions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:250 +msgid "" +"A timeout for a sleep is set by invoking `sleepq_set_timeout`. The function " +"accepts the wait channel and the timeout time as a relative tick count as " +"its arguments. If a sleep should be interrupted by arriving signals, the " +"`sleepq_catch_signals` function should be called as well. This function " +"accepts the wait channel as its only parameter. If there is already a signal " +"pending for this thread, then `sleepq_catch_signals` will return a signal " +"number; otherwise, it will return 0." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:252 +msgid "" +"Once a thread has been added to a sleep queue, it blocks using one of the " +"`sleepq_wait` functions. There are four wait functions depending on whether " +"or not the caller wishes to use a timeout or have the sleep aborted by " +"caught signals or an interrupt from the userland thread scheduler. The " +"`sleepq_wait` function simply waits until the current thread is explicitly " +"resumed by one of the wakeup functions. The `sleepq_timedwait` function " +"waits until either the thread is explicitly resumed or the timeout set by an " +"earlier call to `sleepq_set_timeout` expires. The `sleepq_wait_sig` function " +"waits until either the thread is explicitly resumed or its sleep is aborted. " +"The `sleepq_timedwait_sig` function waits until either the thread is " +"explicitly resumed, the timeout set by an earlier call to " +"`sleepq_set_timeout` expires, or the thread's sleep is aborted. All of the " +"wait functions accept the wait channel as their first parameter. In " +"addition, the `sleepq_timedwait_sig` function accepts a second boolean " +"parameter to indicate if the earlier call to `sleepq_catch_signals` found a " +"pending signal." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:254 +msgid "" +"If the thread is explicitly resumed or is aborted by a signal, then a value " +"of zero is returned by the wait function to indicate a successful sleep. If " +"the thread is resumed by either a timeout or an interrupt from the userland " +"thread scheduler then an appropriate errno value is returned instead. Note " +"that since `sleepq_wait` can only return 0 it does not return anything and " +"the caller should assume a successful sleep. Also, if a thread's sleep times " +"out and is aborted simultaneously then `sleepq_timedwait_sig` will return an " +"error indicating that a timeout occurred. If an error value of 0 is returned " +"and either `sleepq_wait_sig` or `sleepq_timedwait_sig` was used to block, " +"then the function `sleepq_calc_signal_retval` should be called to check for " +"any pending signals and calculate an appropriate return value if any are " +"found. The signal number returned by the earlier call to " +"`sleepq_catch_signals` should be passed as the sole argument to " +"`sleepq_calc_signal_retval`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:256 +msgid "" +"Threads asleep on a wait channel are explicitly resumed by the " +"`sleepq_broadcast` and `sleepq_signal` functions. Both functions accept the " +"wait channel from which to resume threads, a priority to raise resumed " +"threads to, and a flags argument to indicate which type of sleep queue is " +"being resumed. The priority argument is treated as a minimum priority. If a " +"thread being resumed already has a higher priority (numerically lower) than " +"the priority argument then its priority is not adjusted. The flags argument " +"is used for internal assertions to ensure that sleep queues are not being " +"treated as the wrong type. For example, the condition variable functions " +"should not resume threads on a traditional sleep queue. The " +"`sleepq_broadcast` function resumes all threads that are blocked on the " +"specified wait channel while `sleepq_signal` only resumes the highest " +"priority thread blocked on the wait channel. The sleep queue chain should " +"first be locked via the `sleepq_lock` function before calling these " +"functions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:258 +msgid "" +"A sleeping thread may have its sleep interrupted by calling the " +"`sleepq_abort` function. This function must be called with `sched_lock` held " +"and the thread must be queued on a sleep queue. A thread may also be removed " +"from a specific sleep queue via the `sleepq_remove` function. This function " +"accepts both a thread and a wait channel as an argument and only awakens the " +"thread if it is on the sleep queue for the specified wait channel. If the " +"thread is not on a sleep queue or it is on a sleep queue for a different " +"wait channel, then this function does nothing." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:259 +#, no-wrap +msgid "Turnstiles" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:262 +msgid "Compare/contrast with sleep queues." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:264 +msgid "Lookup/wait/release. - Describe TDF_TSNOBLOCK race." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:266 +msgid "Priority propagation." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:267 +#, no-wrap +msgid "Details of the Mutex Implementation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:270 +msgid "" +"Should we require mutexes to be owned for mtx_destroy() since we can not " +"safely assert that they are unowned by anyone else otherwise?" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:271 +#, no-wrap +msgid "Spin Mutexes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:274 +msgid "Use a critical section..." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:275 +#, no-wrap +msgid "Sleep Mutexes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:278 +msgid "Describe the races with contested mutexes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:280 +msgid "" +"Why it is safe to read mtx_lock of a contested mutex when holding the " +"turnstile chain lock." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:281 +#, no-wrap +msgid "Witness" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:284 +msgid "What does it do" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:286 +msgid "How does it work" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:288 +#, no-wrap +msgid "Miscellaneous Topics" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:290 +#, no-wrap +msgid "Interrupt Source and ICU Abstractions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:293 +msgid "struct isrc" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:295 +msgid "pic drivers" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:296 +#, no-wrap +msgid "Other Random Questions/Topics" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:299 +msgid "Should we pass an interlock into `sema_wait`?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:301 +msgid "Should we have non-sleepable sx locks?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:303 +msgid "Add some info about proper use of reference counts." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:308 +#, no-wrap +msgid "Glossary" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:311 +#, no-wrap +msgid "atomic" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:313 +msgid "" +"An operation is atomic if all of its effects are visible to other CPUs " +"together when the proper access protocol is followed. In the degenerate case " +"are atomic instructions provided directly by machine architectures. At a " +"higher level, if several members of a structure are protected by a lock, " +"then a set of operations are atomic if they are all performed while holding " +"the lock without releasing the lock in between any of the operations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:315 +msgid "See Also operation." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:316 +#, no-wrap +msgid "block" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:318 +msgid "" +"A thread is blocked when it is waiting on a lock, resource, or condition. " +"Unfortunately this term is a bit overloaded as a result." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:320 +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:357 +msgid "See Also sleep." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:321 +#, no-wrap +msgid "critical section" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:323 +msgid "" +"A section of code that is not allowed to be preempted. A critical section is " +"entered and exited using the man:critical_enter[9] API." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:324 +#, no-wrap +msgid "MD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:326 +msgid "Machine dependent." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:328 +msgid "See Also MI." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:329 +#, no-wrap +msgid "memory operation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:331 +msgid "A memory operation reads and/or writes to a memory location." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:332 +#, no-wrap +msgid "MI" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:334 +msgid "Machine independent." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:336 +msgid "See Also MD." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:337 +#, no-wrap +msgid "operation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:339 +msgid "See memory operation." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:340 +#, no-wrap +msgid "primary interrupt context" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:342 +msgid "" +"Primary interrupt context refers to the code that runs when an interrupt " +"occurs. This code can either run an interrupt handler directly or schedule " +"an asynchronous interrupt thread to execute the interrupt handlers for a " +"given interrupt source." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:343 +#, no-wrap +msgid "realtime kernel thread" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:345 +msgid "" +"A high priority kernel thread. Currently, the only realtime priority kernel " +"threads are interrupt threads." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:347 +msgid "See Also thread." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:348 +#, no-wrap +msgid "sleep" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:350 +msgid "" +"A thread is asleep when it is blocked on a condition variable or a sleep " +"queue via msleep or tsleep." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:352 +msgid "See Also block." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:353 +#, no-wrap +msgid "sleepable lock" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:355 +msgid "" +"A sleepable lock is a lock that can be held by a thread which is asleep. " +"Lockmgr locks and sx locks are currently the only sleepable locks in " +"FreeBSD. Eventually, some sx locks such as the allproc and proctree locks " +"may become non-sleepable locks." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:358 +#, no-wrap +msgid "thread" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:360 +msgid "" +"A kernel thread represented by a struct thread. Threads own locks and hold a " +"single execution context." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:361 +#, no-wrap +msgid "wait channel" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:363 +msgid "A kernel virtual address that threads may sleep on." +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/sound/_index.adoc b/documentation/content/en/books/arch-handbook/sound/_index.adoc index 98e7f618b1..395cade887 100644 --- a/documentation/content/en/books/arch-handbook/sound/_index.adoc +++ b/documentation/content/en/books/arch-handbook/sound/_index.adoc @@ -6,7 +6,8 @@ description: FreeBSD Sound Subsystem tags: ["Sound", "OSS", "pcm", "mixer"] showBookMenu: true weight: 17 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/sound/" --- [[oss]] @@ -96,9 +97,13 @@ However, sound drivers differ in some ways: .... + Most sound drivers need to store additional private information about their device. A private data structure is usually allocated in the attach routine. Its address is passed to [.filename]#pcm# by the calls to `pcm_register()` and `mixer_init()`. [.filename]#pcm# later passes back this address as a parameter in calls to the sound driver interfaces. -* The sound driver attach routine should declare its MIXER or AC97 interface to [.filename]#pcm# by calling `mixer_init()`. For a MIXER interface, this causes in turn a call to <<xxxmixer-init,`xxxmixer_init()`>>. +* The sound driver attach routine should declare its MIXER or AC97 interface to + [.filename]#pcm# by calling `mixer_init()`. For a MIXER interface, this causes + in turn a call to crossref:sound[xxxmixer-init,`xxxmixer_init()`]. * The sound driver attach routine declares its general CHANNEL configuration to [.filename]#pcm# by calling `pcm_register(dev, sc, nplay, nrec)`, where `sc` is the address for the device data structure, used in further calls from [.filename]#pcm#, and `nplay` and `nrec` are the number of play and record channels. -* The sound driver attach routine declares each of its channel objects by calls to `pcm_addchan()`. This sets up the channel glue in [.filename]#pcm# and causes in turn a call to <<xxxchannel-init,`xxxchannel_init()`>>. +* The sound driver attach routine declares each of its channel objects by calls + to `pcm_addchan()`. This sets up the channel glue in [.filename]#pcm# and + causes in turn a call to crossref:sound[xxxchannel-init,`xxxchannel_init()`]. * The sound driver detach routine should call `pcm_unregister()` before releasing its resources. There are two possible methods to handle non-PnP devices: @@ -111,7 +116,8 @@ There are two possible methods to handle non-PnP devices: [[oss-interfaces]] == Interfaces -The interface between the [.filename]#pcm# core and the sound drivers is defined in terms of <<kernel-objects,kernel objects>>. +The interface between the [.filename]#pcm# core and the sound drivers is defined +in terms of crossref:kobj[kernel-objects,kernel objects]. There are two main interfaces that a sound driver will usually provide: _CHANNEL_ and either _MIXER_ or _AC97_. @@ -137,14 +143,16 @@ The shared memory area has a size of `sndbuf_getsize()` and is divided into fixe When playing, the general transfer mechanism is as follows (reverse the idea for recording): -* [.filename]#pcm# initially fills up the buffer, then calls the sound driver's <<channel-trigger,`xxxchannel_trigger()`>> function with a parameter of PCMTRIG_START. +* [.filename]#pcm# initially fills up the buffer, then calls the sound driver's + crossref:sound[channel-trigger,`xxxchannel_trigger()`] function with a parameter of PCMTRIG_START. * The sound driver then arranges to repeatedly transfer the whole memory area (`sndbuf_getbuf()`, `sndbuf_getsize()`) to the device, in blocks of `sndbuf_getblksz()` bytes. It calls back the `chn_intr()`[.filename]#pcm# function for each transferred block (this will typically happen at interrupt time). * `chn_intr()` arranges to copy new data to the area that was transferred to the device (now free), and make appropriate updates to the `snd_dbuf` structure. [[xxxchannel-init]] ==== channel_init -`xxxchannel_init()` is called to initialize each of the play or record channels. The calls are initiated from the sound driver attach routine. (See the <<pcm-probe-and-attach,probe and attach section>>). +`xxxchannel_init()` is called to initialize each of the play or record channels. +The calls are initiated from the sound driver attach routine. (See the crossref:sound[pcm-probe-and-attach,probe and attach section). [.programlisting] .... diff --git a/documentation/content/en/books/arch-handbook/sound/_index.po b/documentation/content/en/books/arch-handbook/sound/_index.po new file mode 100644 index 0000000000..a2f6a6debf --- /dev/null +++ b/documentation/content/en/books/arch-handbook/sound/_index.po @@ -0,0 +1,857 @@ +# 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: YAML Front Matter: description +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:1 +#, no-wrap +msgid "FreeBSD Sound Subsystem" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:1 +#, no-wrap +msgid "Chapter 15. Sound Subsystem" +msgstr "" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:14 +#, no-wrap +msgid "Sound Subsystem" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:52 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:55 +msgid "" +"The FreeBSD sound subsystem cleanly separates generic sound handling issues " +"from device-specific ones. This makes it easier to add support for new " +"hardware." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:57 +msgid "" +"The man:pcm[4] framework is the central piece of the sound subsystem. It " +"mainly implements the following elements:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:59 +msgid "" +"A system call interface (read, write, ioctls) to digitized sound and mixer " +"functions. The ioctl command set is compatible with the legacy _OSS_ or " +"_Voxware_ interface, allowing common multimedia applications to be ported " +"without modification." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:60 +msgid "" +"Common code for processing sound data (format conversions, virtual channels)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:61 +msgid "" +"A uniform software interface to hardware-specific audio interface modules." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:62 +msgid "" +"Additional support for some common hardware interfaces (ac97), or shared " +"hardware-specific code (ex: ISA DMA routines)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:64 +msgid "" +"The support for specific sound cards is implemented by hardware-specific " +"drivers, which provide channel and mixer interfaces to plug into the generic " +"[.filename]#pcm# code." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:66 +msgid "" +"In this chapter, the term [.filename]#pcm# will refer to the central, common " +"part of the sound driver, as opposed to the hardware-specific modules." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:68 +msgid "" +"The prospective driver writer will of course want to start from an existing " +"module and use the code as the ultimate reference. But, while the sound code " +"is nice and clean, it is also mostly devoid of comments. This document tries " +"to give an overview of the framework interface and answer some questions " +"that may arise while adapting the existing code." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:70 +msgid "" +"As an alternative, or in addition to starting from a working example, you " +"can find a commented driver template at https://people.FreeBSD.org/~cg/" +"template.c[ https://people.FreeBSD.org/~cg/template.c]" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:72 +#, no-wrap +msgid "Files" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:75 +msgid "" +"All the relevant code lives in [.filename]#/usr/src/sys/dev/sound/#, except " +"for the public ioctl interface definitions, found in [.filename]#/usr/src/" +"sys/sys/soundcard.h#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:77 +msgid "" +"Under [.filename]#/usr/src/sys/dev/sound/#, the [.filename]#pcm/# directory " +"holds the central code, while the [.filename]#pci/#, [.filename]#isa/# and " +"[.filename]#usb/# directories have the drivers for PCI and ISA boards, and " +"for USB audio devices." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:79 +#, no-wrap +msgid "Probing, Attaching, etc." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:82 +msgid "" +"Sound drivers probe and attach in almost the same way as any hardware driver " +"module. You might want to look at the crossref:isa-driver[isa-driver,ISA] or " +"crossref:pci[pci,PCI] specific sections of the handbook for more information." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:84 +msgid "However, sound drivers differ in some ways:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:86 +msgid "" +"They declare themselves as [.filename]#pcm# class devices, with a `struct " +"snddev_info` device private structure:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:94 +#, no-wrap +msgid "" +" static driver_t xxx_driver = {\n" +" \"pcm\",\n" +" xxx_methods,\n" +" sizeof(struct snddev_info)\n" +" };\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:97 +#, no-wrap +msgid "" +" DRIVER_MODULE(snd_xxxpci, pci, xxx_driver, pcm_devclass, 0, 0);\n" +" MODULE_DEPEND(snd_xxxpci, snd_pcm, PCM_MINVER, PCM_PREFVER,PCM_MAXVER);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:100 +msgid "" +"Most sound drivers need to store additional private information about their " +"device. A private data structure is usually allocated in the attach routine. " +"Its address is passed to [.filename]#pcm# by the calls to `pcm_register()` " +"and `mixer_init()`. [.filename]#pcm# later passes back this address as a " +"parameter in calls to the sound driver interfaces." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:103 +msgid "" +"The sound driver attach routine should declare its MIXER or AC97 interface " +"to [.filename]#pcm# by calling `mixer_init()`. For a MIXER interface, this " +"causes in turn a call to crossref:sound[xxxmixer-init,`xxxmixer_init()`]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:104 +msgid "" +"The sound driver attach routine declares its general CHANNEL configuration " +"to [.filename]#pcm# by calling `pcm_register(dev, sc, nplay, nrec)`, where " +"`sc` is the address for the device data structure, used in further calls " +"from [.filename]#pcm#, and `nplay` and `nrec` are the number of play and " +"record channels." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:107 +msgid "" +"The sound driver attach routine declares each of its channel objects by " +"calls to `pcm_addchan()`. This sets up the channel glue in [.filename]#pcm# " +"and causes in turn a call to crossref:sound[xxxchannel-" +"init,`xxxchannel_init()`]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:108 +msgid "" +"The sound driver detach routine should call `pcm_unregister()` before " +"releasing its resources." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:110 +msgid "There are two possible methods to handle non-PnP devices:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:112 +msgid "" +"Use a `device_identify()` method (example: [.filename]#sound/isa/es1888.c#). " +"The `device_identify()` method probes for the hardware at known addresses " +"and, if it finds a supported device, creates a new pcm device which is then " +"passed to probe/attach." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:113 +msgid "" +"Use a custom kernel configuration with appropriate hints for pcm devices " +"(example: [.filename]#sound/isa/mss.c#)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:115 +msgid "" +"[.filename]#pcm# drivers should implement `device_suspend`, `device_resume` " +"and `device_shutdown` routines, so that power management and module " +"unloading function correctly." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:117 +#, no-wrap +msgid "Interfaces" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:121 +msgid "" +"The interface between the [.filename]#pcm# core and the sound drivers is " +"defined in terms of crossref:kobj[kernel-objects,kernel objects]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:123 +msgid "" +"There are two main interfaces that a sound driver will usually provide: " +"_CHANNEL_ and either _MIXER_ or _AC97_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:125 +msgid "" +"The _AC97_ interface is a very small hardware access (register read/write) " +"interface, implemented by drivers for hardware with an AC97 codec. In this " +"case, the actual MIXER interface is provided by the shared AC97 code in " +"[.filename]#pcm#." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:126 +#, no-wrap +msgid "The CHANNEL Interface" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:128 +#, no-wrap +msgid "Common Notes for Function Parameters" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:131 +msgid "" +"Sound drivers usually have a private data structure to describe their " +"device, and one structure for each play and record data channel that it " +"supports." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:133 +msgid "" +"For all CHANNEL interface functions, the first parameter is an opaque " +"pointer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:135 +msgid "" +"The second parameter is a pointer to the private channel data structure, " +"except for `channel_init()` which has a pointer to the private device " +"structure (and returns the channel pointer for further use by " +"[.filename]#pcm#)." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:136 +#, no-wrap +msgid "Overview of Data Transfer Operations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:139 +msgid "" +"For sound data transfers, the [.filename]#pcm# core and the sound drivers " +"communicate through a shared memory area, described by a `struct snd_dbuf`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:141 +msgid "" +"`struct snd_dbuf` is private to [.filename]#pcm#, and sound drivers obtain " +"values of interest by calls to accessor functions (`sndbuf_getxxx()`)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:143 +msgid "" +"The shared memory area has a size of `sndbuf_getsize()` and is divided into " +"fixed size blocks of `sndbuf_getblksz()` bytes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:145 +msgid "" +"When playing, the general transfer mechanism is as follows (reverse the idea " +"for recording):" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:148 +msgid "" +"[.filename]#pcm# initially fills up the buffer, then calls the sound " +"driver's crossref:sound[channel-trigger,`xxxchannel_trigger()`] function " +"with a parameter of PCMTRIG_START." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:149 +msgid "" +"The sound driver then arranges to repeatedly transfer the whole memory area " +"(`sndbuf_getbuf()`, `sndbuf_getsize()`) to the device, in blocks of " +"`sndbuf_getblksz()` bytes. It calls back the `chn_intr()`[.filename]#pcm# " +"function for each transferred block (this will typically happen at interrupt " +"time)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:150 +msgid "" +"`chn_intr()` arranges to copy new data to the area that was transferred to " +"the device (now free), and make appropriate updates to the `snd_dbuf` " +"structure." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:152 +#, no-wrap +msgid "channel_init" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:156 +msgid "" +"`xxxchannel_init()` is called to initialize each of the play or record " +"channels. The calls are initiated from the sound driver attach routine. " +"(See the crossref:sound[pcm-probe-and-attach,probe and attach section)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:168 +#, no-wrap +msgid "" +" static void *\n" +" xxxchannel_init(kobj_t obj, void *data,\n" +" struct snd_dbuf *b, struct pcm_channel *c, int dir) <.>\n" +" {\n" +" struct xxx_info *sc = data;\n" +" struct xxx_chinfo *ch;\n" +" ...\n" +" return ch; <.>\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:171 +msgid "" +"`b` is the address for the channel `struct snd_dbuf`. It should be " +"initialized in the function by calling `sndbuf_alloc()`. The buffer size to " +"use is normally a small multiple of the 'typical' unit transfer size for " +"your device.`c` is the [.filename]#pcm# channel control structure pointer. " +"This is an opaque object. The function should store it in the local channel " +"structure, to be used in later calls to [.filename]#pcm# (ie: " +"`chn_intr(c)`).`dir` indicates the channel direction (`PCMDIR_PLAY` or " +"`PCMDIR_REC`)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:173 +msgid "" +"The function should return a pointer to the private area used to control " +"this channel. This will be passed as a parameter to other channel interface " +"calls." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:174 +#, no-wrap +msgid "channel_setformat" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:177 +msgid "" +"`xxxchannel_setformat()` should set up the hardware for the specified " +"channel for the specified sound format." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:187 +#, no-wrap +msgid "" +" static int\n" +" xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format) <.>\n" +" {\n" +" struct xxx_chinfo *ch = data;\n" +" ...\n" +" return 0;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:190 +msgid "" +"`format` is specified as an `AFMT_XXX value` ([.filename]#soundcard.h#)." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:191 +#, no-wrap +msgid "channel_setspeed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:194 +msgid "" +"`xxxchannel_setspeed()` sets up the channel hardware for the specified " +"sampling speed, and returns the possibly adjusted speed." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:204 +#, no-wrap +msgid "" +" static int\n" +" xxxchannel_setspeed(kobj_t obj, void *data, u_int32_t speed)\n" +" {\n" +" struct xxx_chinfo *ch = data;\n" +" ...\n" +" return speed;\n" +" }\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:206 +#, no-wrap +msgid "channel_setblocksize" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:209 +msgid "" +"`xxxchannel_setblocksize()` sets the block size, which is the size of unit " +"transactions between [.filename]#pcm# and the sound driver, and between the " +"sound driver and the device. Typically, this would be the number of bytes " +"transferred before an interrupt occurs. During a transfer, the sound driver " +"should call [.filename]#pcm#'s `chn_intr()` every time this size has been " +"transferred." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:211 +msgid "" +"Most sound drivers only take note of the block size here, to be used when an " +"actual transfer will be started." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:221 +#, no-wrap +msgid "" +" static int\n" +" xxxchannel_setblocksize(kobj_t obj, void *data, u_int32_t blocksize)\n" +" {\n" +" struct xxx_chinfo *ch = data;\n" +" ...\n" +" return blocksize; <.>\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:224 +msgid "" +"The function returns the possibly adjusted block size. In case the block " +"size is indeed changed, `sndbuf_resize()` should be called to adjust the " +"buffer." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:226 +#, no-wrap +msgid "channel_trigger" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:229 +msgid "" +"`xxxchannel_trigger()` is called by [.filename]#pcm# to control data " +"transfer operations in the driver." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:239 +#, no-wrap +msgid "" +" static int\n" +" xxxchannel_trigger(kobj_t obj, void *data, int go) <.>\n" +" {\n" +" struct xxx_chinfo *ch = data;\n" +" ...\n" +" return 0;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:242 +msgid "`go` defines the action for the current call. The possible values are:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:246 +msgid "" +"If the driver uses ISA DMA, `sndbuf_isadma()` should be called before " +"performing actions on the device, and will take care of the DMA chip side of " +"things." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:248 +#, no-wrap +msgid "channel_getptr" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:251 +msgid "" +"`xxxchannel_getptr()` returns the current offset in the transfer buffer. " +"This will typically be called by `chn_intr()`, and this is how " +"[.filename]#pcm# knows where it can transfer new data." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:252 +#, no-wrap +msgid "channel_free" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:255 +msgid "" +"`xxxchannel_free()` is called to free up channel resources, for example when " +"the driver is unloaded, and should be implemented if the channel data " +"structures are dynamically allocated or if `sndbuf_alloc()` was not used for " +"buffer allocation." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:256 +#, no-wrap +msgid "channel_getcaps" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:265 +#, no-wrap +msgid "" +" struct pcmchan_caps *\n" +" xxxchannel_getcaps(kobj_t obj, void *data)\n" +" {\n" +" return &xxx_caps; <.>\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:268 +msgid "" +"The routine returns a pointer to a (usually statically-defined) " +"`pcmchan_caps` structure (defined in [.filename]#sound/pcm/channel.h#. The " +"structure holds the minimum and maximum sampling frequencies, and the " +"accepted sound formats. Look at any sound driver for an example." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:269 +#, no-wrap +msgid "More Functions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:272 +msgid "" +"`channel_reset()`, `channel_resetdone()`, and `channel_notify()` are for " +"special purposes and should not be implemented in a driver without " +"discussing it on the {freebsd-multimedia}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:274 +msgid "`channel_setdir()` is deprecated." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:275 +#, no-wrap +msgid "The MIXER Interface" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:278 +#, no-wrap +msgid "mixer_init" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:281 +msgid "" +"`xxxmixer_init()` initializes the hardware and tells [.filename]#pcm# what " +"mixer devices are available for playing and recording" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:289 +#, no-wrap +msgid "" +" static int\n" +" xxxmixer_init(struct snd_mixer *m)\n" +" {\n" +" struct xxx_info *sc = mix_getdevinfo(m);\n" +" u_int32_t v;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:291 +#, no-wrap +msgid " [Initialize hardware]\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:296 +#, no-wrap +msgid "" +" [Set appropriate bits in v for play mixers] <.>\n" +" mix_setdevs(m, v);\n" +" [Set appropriate bits in v for record mixers]\n" +" mix_setrecdevs(m, v)\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:299 +#, no-wrap +msgid "" +" return 0;\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:302 +msgid "" +"Set bits in an integer value and call `mix_setdevs()` and `mix_setrecdevs()` " +"to tell [.filename]#pcm# what devices exist." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:304 +msgid "" +"Mixer bits definitions can be found in [.filename]#soundcard.h# " +"(`SOUND_MASK_XXX` values and `SOUND_MIXER_XXX` bit shifts)." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:305 +#, no-wrap +msgid "mixer_set" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:308 +msgid "`xxxmixer_set()` sets the volume level for one mixer device." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:319 +#, no-wrap +msgid "" +" static int\n" +" xxxmixer_set(struct snd_mixer *m, unsigned dev,\n" +" unsigned left, unsigned right) <.>\n" +" {\n" +" struct sc_info *sc = mix_getdevinfo(m);\n" +" [set volume level]\n" +" return left | (right << 8); <.>\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:322 +msgid "" +"The device is specified as a `SOUND_MIXER_XXX` value. The volume values are " +"specified in range [0-100]. A value of zero should mute the device." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:323 +msgid "" +"As the hardware levels probably will not match the input scale, and some " +"rounding will occur, the routine returns the actual level values (in range " +"0-100) as shown." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:324 +#, no-wrap +msgid "mixer_setrecsrc" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:327 +msgid "`xxxmixer_setrecsrc()` sets the recording source device." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:334 +#, no-wrap +msgid "" +" static int\n" +" xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src) <.>\n" +" {\n" +" struct xxx_info *sc = mix_getdevinfo(m);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:336 +#, no-wrap +msgid " [look for non zero bit(s) in src, set up hardware]\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:340 +#, no-wrap +msgid "" +" [update src to reflect actual action]\n" +" return src; <.>\n" +" }\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:343 +msgid "The desired recording devices are specified as a bit field" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:344 +msgid "" +"The actual devices set for recording are returned. Some drivers can only set " +"one device for recording. The function should return -1 if an error occurs." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:345 +#, no-wrap +msgid "mixer_uninit, mixer_reinit" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:348 +msgid "" +"`xxxmixer_uninit()` should ensure that all sound is muted and if possible " +"mixer hardware should be powered down." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:350 +msgid "" +"`xxxmixer_reinit()` should ensure that the mixer hardware is powered up and " +"any settings not controlled by `mixer_set()` or `mixer_setrecsrc()` are " +"restored." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:351 +#, no-wrap +msgid "The AC97 Interface" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:354 +msgid "" +"The _AC97_ interface is implemented by drivers with an AC97 codec. It only " +"has three methods:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:356 +msgid "`xxxac97_init()` returns the number of ac97 codecs found." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:357 +msgid "`ac97_read()` and `ac97_write()` read or write a specified register." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:358 +msgid "" +"The _AC97_ interface is used by the AC97 code in [.filename]#pcm# to perform " +"higher level operations. Look at [.filename]#sound/pci/maestro3.c# or many " +"others under [.filename]#sound/pci/# for an example." +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/sysinit/_index.adoc b/documentation/content/en/books/arch-handbook/sysinit/_index.adoc index 5d0809fda8..7948ea01e0 100644 --- a/documentation/content/en/books/arch-handbook/sysinit/_index.adoc +++ b/documentation/content/en/books/arch-handbook/sysinit/_index.adoc @@ -6,7 +6,8 @@ description: The SYSINIT Framework tags: ["SYSINIT", "framework", "Terminology"] showBookMenu: true weight: 6 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/sysinit/" --- [[sysinit]] diff --git a/documentation/content/en/books/arch-handbook/sysinit/_index.po b/documentation/content/en/books/arch-handbook/sysinit/_index.po new file mode 100644 index 0000000000..6c01ddc85d --- /dev/null +++ b/documentation/content/en/books/arch-handbook/sysinit/_index.po @@ -0,0 +1,299 @@ +# 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/sysinit/_index.adoc:1 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:14 +#, no-wrap +msgid "The SYSINIT Framework" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:1 +#, no-wrap +msgid "Chapter 5. The SYSINIT Framework" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:52 +msgid "" +"SYSINIT is the framework for a generic call sort and dispatch mechanism. " +"FreeBSD currently uses it for the dynamic initialization of the kernel. " +"SYSINIT allows FreeBSD's kernel subsystems to be reordered, and added, " +"removed, and replaced at kernel link time when the kernel or one of its " +"modules is loaded without having to edit a statically ordered initialization " +"routing and recompile the kernel. This system also allows kernel modules, " +"currently called _KLD's_, to be separately compiled, linked, and initialized " +"at boot time and loaded even later while the system is already running. This " +"is accomplished using the \"kernel linker\" and \"linker sets\"." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:54 +#, no-wrap +msgid "Terminology" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:56 +#, no-wrap +msgid "Linker Set" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:58 +msgid "" +"A linker technique in which the linker gathers statically declared data " +"throughout a program's source files into a single contiguously addressable " +"unit of data." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:60 +#, no-wrap +msgid "SYSINIT Operation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:63 +msgid "" +"SYSINIT relies on the ability of the linker to take static data declared at " +"multiple locations throughout a program's source and group it together as a " +"single contiguous chunk of data. This linker technique is called a \"linker " +"set\". SYSINIT uses two linker sets to maintain two data sets containing " +"each consumer's call order, function, and a pointer to the data to pass to " +"that function." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:65 +msgid "" +"SYSINIT uses two priorities when ordering the functions for execution. The " +"first priority is a subsystem ID giving an overall order for SYSINIT's " +"dispatch of functions. Current predeclared ID's are in [.filename]#<sys/" +"kernel.h># in the enum list `sysinit_sub_id`. The second priority used is an " +"element order within the subsystem. Current predeclared subsystem element " +"orders are in [.filename]#<sys/kernel.h># in the enum list " +"`sysinit_elem_order`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:67 +msgid "" +"There are currently two uses for SYSINIT. Function dispatch at system " +"startup and kernel module loads, and function dispatch at system shutdown " +"and kernel module unload. Kernel subsystems often use system startup " +"SYSINIT's to initialize data structures, for example the process scheduling " +"subsystem uses a SYSINIT to initialize the run queue data structure. Device " +"drivers should avoid using `SYSINIT()` directly. Instead drivers for real " +"devices that are part of a bus structure should use `DRIVER_MODULE()` to " +"provide a function that detects the device and, if it is present, " +"initializes the device. It will do a few things specific to devices and then " +"call `SYSINIT()` itself. For pseudo-devices, which are not part of a bus " +"structure, use `DEV_MODULE()`." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:69 +#, no-wrap +msgid "Using SYSINIT" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:71 +#, no-wrap +msgid "Interface" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:73 +#, no-wrap +msgid "Headers" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:78 +#, no-wrap +msgid "<sys/kernel.h>\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:80 +#, no-wrap +msgid "Macros" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:86 +#, no-wrap +msgid "" +"SYSINIT(uniquifier, subsystem, order, func, ident)\n" +"SYSUNINIT(uniquifier, subsystem, order, func, ident)\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:88 +#, no-wrap +msgid "Startup" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:91 +msgid "" +"The `SYSINIT()` macro creates the necessary SYSINIT data in SYSINIT's " +"startup data set for SYSINIT to sort and dispatch a function at system " +"startup and module load. `SYSINIT()` takes a uniquifier that SYSINIT uses to " +"identify the particular function dispatch data, the subsystem order, the " +"subsystem element order, the function to call, and the data to pass the " +"function. All functions must take a constant pointer argument." +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:92 +#, no-wrap +msgid "Example of a `SYSINIT()`" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:98 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:148 +#, no-wrap +msgid "#include <sys/kernel.h>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:104 +#, no-wrap +msgid "" +"void foo_null(void *unused)\n" +"{\n" +" foo_doo();\n" +"}\n" +"SYSINIT(foo, SI_SUB_FOO, SI_ORDER_FOO, foo_null, NULL);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:108 +#, no-wrap +msgid "" +"struct foo foo_voodoo = {\n" +" FOO_VOODOO;\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:115 +#, no-wrap +msgid "" +"void foo_arg(void *vdata)\n" +"{\n" +" struct foo *foo = (struct foo *)vdata;\n" +" foo_data(foo);\n" +"}\n" +"SYSINIT(bar, SI_SUB_FOO, SI_ORDER_FOO, foo_arg, &foo_voodoo);\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:119 +msgid "" +"Note that `SI_SUB_FOO` and `SI_ORDER_FOO` need to be in the `sysinit_sub_id` " +"and `sysinit_elem_order` enum's as mentioned above. Either use existing ones " +"or add your own to the enum's. You can also use math for fine-tuning the " +"order a SYSINIT will run in. This example shows a SYSINIT that needs to be " +"run just barely before the SYSINIT's that handle tuning kernel parameters." +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:120 +#, no-wrap +msgid "Example of Adjusting `SYSINIT()` Order" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:128 +#, no-wrap +msgid "" +"static void\n" +"mptable_register(void *dummy __unused)\n" +"{\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:131 +#, no-wrap +msgid "" +"\tapic_register_enumerator(&mptable_enumerator);\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:134 +#, no-wrap +msgid "" +"SYSINIT(mptable_register, SI_SUB_TUNABLES - 1, SI_ORDER_FIRST,\n" +" mptable_register, NULL);\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:138 +#, no-wrap +msgid "Shutdown" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:141 +msgid "" +"The `SYSUNINIT()` macro behaves similarly to the `SYSINIT()` macro except " +"that it adds the SYSINIT data to SYSINIT's shutdown data set." +msgstr "" + +#. type: Block title +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:142 +#, no-wrap +msgid "Example of a `SYSUNINIT()`" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:154 +#, no-wrap +msgid "" +"void foo_cleanup(void *unused)\n" +"{\n" +" foo_kill();\n" +"}\n" +"SYSUNINIT(foobar, SI_SUB_FOO, SI_ORDER_FOO, foo_cleanup, NULL);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:158 +#, no-wrap +msgid "" +"struct foo_stack foo_stack = {\n" +" FOO_STACK_VOODOO;\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:163 +#, no-wrap +msgid "" +"void foo_flush(void *vdata)\n" +"{\n" +"}\n" +"SYSUNINIT(barfoo, SI_SUB_FOO, SI_ORDER_FOO, foo_flush, &foo_stack);\n" +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/usb/_index.adoc b/documentation/content/en/books/arch-handbook/usb/_index.adoc index f88db60bc8..94a22e850b 100644 --- a/documentation/content/en/books/arch-handbook/usb/_index.adoc +++ b/documentation/content/en/books/arch-handbook/usb/_index.adoc @@ -6,7 +6,8 @@ description: USB Devices in FreeBSD tags: ["USB", "Structure", "UHCI", "OHCI"] showBookMenu: true weight: 15 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/usb/" --- [[usb]] @@ -93,7 +94,7 @@ The UHCI host controller maintains a framelist with 1024 pointers to per frame d Each transfer consists of one or more packets. The UHCI driver splits large transfers into multiple packets. For every transfer, apart from isochronous transfers, a QH is allocated. For every type of transfer these QHs are collected at a QH for that type. Isochronous transfers have to be executed first because of the fixed latency requirement and are directly referred to by the pointer in the framelist. The last isochronous TD refers to the QH for interrupt transfers for that frame. All QHs for interrupt transfers point at the QH for control transfers, which in turn points at the QH for bulk transfers. The following diagram gives a graphical overview of this: -This results in the following schedule being run in each frame. After fetching the pointer for the current frame from the framelist the controller first executes the TDs for all the isochronous packets in that frame. The last of these TDs refers to the QH for the interrupt transfers for thatframe. The host controller will then descend from that QH to the QHs for the individual interrupt transfers. After finishing that queue, the QH for the interrupt transfers will refer the controller to the QH for all control transfers. It will execute all the subqueues scheduled there, followed by all the transfers queued at the bulk QH. To facilitate the handling of finished or failed transfers different types of interrupts are generated by the hardware at the end of each frame. In the last TD for a transfer the Interrupt-On Completion bit is set by the HC driver to flag an interrupt when the transfer has completed. An error interrupt is flagged if a TD reaches its maximum error count. If the short packet detect bit is set in a TD and less than the set packet length is transferred this interrupt is flagged to notify the controller driver of the completed transfer. It is the host controller driver's task to find out which transfer has completed or produced an error. When called the interrupt service routine will locate all the finished transfers and call their callbacks. +This results in the following schedule being run in each frame. After fetching the pointer for the current frame from the framelist the controller first executes the TDs for all the isochronous packets in that frame. The last of these TDs refers to the QH for the interrupt transfers for that frame. The host controller will then descend from that QH to the QHs for the individual interrupt transfers. After finishing that queue, the QH for the interrupt transfers will refer the controller to the QH for all control transfers. It will execute all the subqueues scheduled there, followed by all the transfers queued at the bulk QH. To facilitate the handling of finished or failed transfers different types of interrupts are generated by the hardware at the end of each frame. In the last TD for a transfer the Interrupt-On Completion bit is set by the HC driver to flag an interrupt when the transfer has completed. An error interrupt is flagged if a TD reaches its maximum error count. If the short packet detect bit is set in a TD and less than the set packet length is transferred this interrupt is flagged to notify the controller driver of the completed transfer. It is the host controller driver's task to find out which transfer has completed or produced an error. When called the interrupt service routine will locate all the finished transfers and call their callbacks. Refer to the UHCI Specification for a more elaborate description. diff --git a/documentation/content/en/books/arch-handbook/usb/_index.po b/documentation/content/en/books/arch-handbook/usb/_index.po new file mode 100644 index 0000000000..b86f26017f --- /dev/null +++ b/documentation/content/en/books/arch-handbook/usb/_index.po @@ -0,0 +1,797 @@ +# 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: YAML Front Matter: description +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:1 +#, no-wrap +msgid "USB Devices in FreeBSD" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:1 +#, no-wrap +msgid "Chapter 13. USB Devices" +msgstr "" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:14 +#, no-wrap +msgid "USB Devices" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:52 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:55 +msgid "" +"The Universal Serial Bus (USB) is a new way of attaching devices to personal " +"computers. The bus architecture features two-way communication and has been " +"developed as a response to devices becoming smarter and requiring more " +"interaction with the host. USB support is included in all current PC " +"chipsets and is therefore available in all recently built PCs. Apple's " +"introduction of the USB-only iMac has been a major incentive for hardware " +"manufacturers to produce USB versions of their devices. The future PC " +"specifications specify that all legacy connectors on PCs should be replaced " +"by one or more USB connectors, providing generic plug and play capabilities. " +"Support for USB hardware was available at a very early stage in NetBSD and " +"was developed by Lennart Augustsson for the NetBSD project. The code has " +"been ported to FreeBSD and we are currently maintaining a shared code base. " +"For the implementation of the USB subsystem a number of features of USB are " +"important." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:57 +msgid "" +"_Lennart Augustsson has done most of the implementation of the USB support " +"for the NetBSD project. Many thanks for this incredible amount of work. Many " +"thanks also to Ardy and Dirk for their comments and proofreading of this " +"paper._" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:59 +msgid "" +"Devices connect to ports on the computer directly or on devices called hubs, " +"forming a treelike device structure." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:60 +msgid "The devices can be connected and disconnected at run time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:61 +msgid "Devices can suspend themselves and trigger resumes of the host system" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:62 +msgid "" +"As the devices can be powered from the bus, the host software has to keep " +"track of power budgets for each hub." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:63 +msgid "" +"Different quality of service requirements by the different device types " +"together with the maximum of 126 devices that can be connected to the same " +"bus, require proper scheduling of transfers on the shared bus to take full " +"advantage of the 12Mbps bandwidth available. (over 400Mbps with USB 2.0)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:64 +msgid "" +"Devices are intelligent and contain easily accessible information about " +"themselves" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:66 +msgid "" +"The development of drivers for the USB subsystem and devices connected to it " +"is supported by the specifications that have been developed and will be " +"developed. These specifications are publicly available from the USB home " +"pages. Apple has been very strong in pushing for standards based drivers, by " +"making drivers for the generic classes available in their operating system " +"MacOS and discouraging the use of separate drivers for each new device. This " +"chapter tries to collate essential information for a basic understanding of " +"the USB 2.0 implementation stack in FreeBSD/NetBSD. It is recommended " +"however to read it together with the relevant 2.0 specifications and other " +"developer resources:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:68 +msgid "" +"USB 2.0 Specification (http://www.usb.org/developers/docs/usb20_docs/[http://" +"www.usb.org/developers/docs/usb20_docs/])" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:69 +msgid "" +"Universal Host Controller Interface (UHCI) Specification (link:ftp://" +"ftp.netbsd.org/pub/NetBSD/misc/blymn/uhci11d.pdf[ftp://ftp.netbsd.org/pub/" +"NetBSD/misc/blymn/uhci11d.pdf)]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:70 +msgid "" +"Open Host Controller Interface (OHCI) Specification(link:ftp://" +"ftp.compaq.com/pub/supportinformation/papers/hcir1_0a.pdf[ftp://" +"ftp.compaq.com/pub/supportinformation/papers/hcir1_0a.pdf])" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:71 +msgid "" +"Developer section of USB home page (http://www.usb.org/developers/[http://" +"www.usb.org/developers/])" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:72 +#, no-wrap +msgid "Structure of the USB Stack" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:75 +msgid "" +"The USB support in FreeBSD can be split into three layers. The lowest layer " +"contains the host controller driver, providing a generic interface to the " +"hardware and its scheduling facilities. It supports initialisation of the " +"hardware, scheduling of transfers and handling of completed and/or failed " +"transfers. Each host controller driver implements a virtual hub providing " +"hardware independent access to the registers controlling the root ports on " +"the back of the machine." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:77 +msgid "" +"The middle layer handles the device connection and disconnection, basic " +"initialisation of the device, driver selection, the communication channels " +"(pipes) and does resource management. This services layer also controls the " +"default pipes and the device requests transferred over them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:79 +msgid "" +"The top layer contains the individual drivers supporting specific (classes " +"of) devices. These drivers implement the protocol that is used over the " +"pipes other than the default pipe. They also implement additional " +"functionality to make the device available to other parts of the kernel or " +"userland. They use the USB driver interface (USBDI) exposed by the services " +"layer." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:81 +#, no-wrap +msgid "Host Controllers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:84 +msgid "" +"The host controller (HC) controls the transmission of packets on the bus. " +"Frames of 1 millisecond are used. At the start of each frame the host " +"controller generates a Start of Frame (SOF) packet." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:86 +msgid "" +"The SOF packet is used to synchronise to the start of the frame and to keep " +"track of the frame number. Within each frame packets are transferred, either " +"from host to device (out) or from device to host (in). Transfers are always " +"initiated by the host (polled transfers). Therefore there can only be one " +"host per USB bus. Each transfer of a packet has a status stage in which the " +"recipient of the data can return either ACK (acknowledge reception), NAK " +"(retry), STALL (error condition) or nothing (garbled data stage, device not " +"available or disconnected). Section 8.5 of the USB 2.0 Specification " +"explains the details of packets in more detail. Four different types of " +"transfers can occur on a USB bus: control, bulk, interrupt and isochronous. " +"The types of transfers and their characteristics are described below." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:88 +msgid "" +"Large transfers between the device on the USB bus and the device driver are " +"split up into multiple packets by the host controller or the HC driver." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:90 +msgid "" +"Device requests (control transfers) to the default endpoints are special. " +"They consist of two or three phases: SETUP, DATA (optional) and STATUS. The " +"set-up packet is sent to the device. If there is a data phase, the direction " +"of the data packet(s) is given in the set-up packet. The direction in the " +"status phase is the opposite of the direction during the data phase, or IN " +"if there was no data phase. The host controller hardware also provides " +"registers with the current status of the root ports and the changes that " +"have occurred since the last reset of the status change register. Access to " +"these registers is provided through a virtualised hub as suggested in the " +"USB specification. The virtual hub must comply with the hub device class " +"given in chapter 11 of that specification. It must provide a default pipe " +"through which device requests can be sent to it. It returns the standard " +"andhub class specific set of descriptors. It should also provide an " +"interrupt pipe that reports changes happening at its ports. There are " +"currently two specifications for host controllers available: Universal Host " +"Controller Interface (UHCI) from Intel and Open Host Controller Interface " +"(OHCI) from Compaq, Microsoft, and National Semiconductor. The UHCI " +"specification has been designed to reduce hardware complexity by requiring " +"the host controller driver to supply a complete schedule of the transfers " +"for each frame. OHCI type controllers are much more independent by providing " +"a more abstract interface doing a lot of work themselves." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:91 +#, no-wrap +msgid "UHCI" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:94 +msgid "" +"The UHCI host controller maintains a framelist with 1024 pointers to per " +"frame data structures. It understands two different data types: transfer " +"descriptors (TD) and queue heads (QH). Each TD represents a packet to be " +"communicated to or from a device endpoint. QHs are a means to groupTDs (and " +"QHs) together." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:96 +msgid "" +"Each transfer consists of one or more packets. The UHCI driver splits large " +"transfers into multiple packets. For every transfer, apart from isochronous " +"transfers, a QH is allocated. For every type of transfer these QHs are " +"collected at a QH for that type. Isochronous transfers have to be executed " +"first because of the fixed latency requirement and are directly referred to " +"by the pointer in the framelist. The last isochronous TD refers to the QH " +"for interrupt transfers for that frame. All QHs for interrupt transfers " +"point at the QH for control transfers, which in turn points at the QH for " +"bulk transfers. The following diagram gives a graphical overview of this:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:98 +msgid "" +"This results in the following schedule being run in each frame. After " +"fetching the pointer for the current frame from the framelist the controller " +"first executes the TDs for all the isochronous packets in that frame. The " +"last of these TDs refers to the QH for the interrupt transfers for that " +"frame. The host controller will then descend from that QH to the QHs for the " +"individual interrupt transfers. After finishing that queue, the QH for the " +"interrupt transfers will refer the controller to the QH for all control " +"transfers. It will execute all the subqueues scheduled there, followed by " +"all the transfers queued at the bulk QH. To facilitate the handling of " +"finished or failed transfers different types of interrupts are generated by " +"the hardware at the end of each frame. In the last TD for a transfer the " +"Interrupt-On Completion bit is set by the HC driver to flag an interrupt " +"when the transfer has completed. An error interrupt is flagged if a TD " +"reaches its maximum error count. If the short packet detect bit is set in a " +"TD and less than the set packet length is transferred this interrupt is " +"flagged to notify the controller driver of the completed transfer. It is the " +"host controller driver's task to find out which transfer has completed or " +"produced an error. When called the interrupt service routine will locate all " +"the finished transfers and call their callbacks." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:100 +msgid "Refer to the UHCI Specification for a more elaborate description." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:101 +#, no-wrap +msgid "OHCI" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:104 +msgid "" +"Programming an OHCI host controller is much simpler. The controller assumes " +"that a set of endpoints is available, and is aware of scheduling priorities " +"and the ordering of the types of transfers in a frame. The main data " +"structure used by the host controller is the endpoint descriptor (ED) to " +"which a queue of transfer descriptors (TDs) is attached. The ED contains the " +"maximum packet size allowed for an endpoint and the controller hardware does " +"the splitting into packets. The pointers to the data buffers are updated " +"after each transfer and when the start and end pointer are equal, the TD is " +"retired to the done-queue. The four types of endpoints (interrupt, " +"isochronous, control, and bulk) have their own queues. Control and bulk " +"endpoints are queued each at their own queue. Interrupt EDs are queued in a " +"tree, with the level in the tree defining the frequency at which they run." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:106 +msgid "" +"The schedule being run by the host controller in each frame looks as " +"follows. The controller will first run the non-periodic control and bulk " +"queues, up to a time limit set by the HC driver. Then the interrupt " +"transfers for that frame number are run, by using the lower five bits of the " +"frame number as an index into level 0 of the tree of interrupts EDs. At the " +"end of this tree the isochronous EDs are connected and these are traversed " +"subsequently. The isochronous TDs contain the frame number of the first " +"frame the transfer should be run in. After all the periodic transfers have " +"been run, the control and bulk queues are traversed again. Periodically the " +"interrupt service routine is called to process the done queue and call the " +"callbacks for each transfer and reschedule interrupt and isochronous " +"endpoints." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:108 +msgid "" +"See the UHCI Specification for a more elaborate description. The middle " +"layer provides access to the device in a controlled way and maintains " +"resources in use by the different drivers and the services layer. The layer " +"takes care of the following aspects:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:110 +msgid "The device configuration information" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:111 +msgid "The pipes to communicate with a device" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:112 +msgid "Probing and attaching and detaching form a device." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:114 +#, no-wrap +msgid "USB Device Information" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:116 +#, no-wrap +msgid "Device Configuration Information" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:119 +msgid "" +"Each device provides different levels of configuration information. Each " +"device has one or more configurations, of which one is selected during probe/" +"attach. A configuration provides power and bandwidth requirements. Within " +"each configuration there can be multiple interfaces. A device interface is a " +"collection of endpoints. For example USB speakers can have an interface for " +"the audio data (Audio Class) and an interface for the knobs, dials and " +"buttons (HID Class). All interfaces in a configuration are active at the " +"same time and can be attached to by different drivers. Each interface can " +"have alternates, providing different quality of service parameters. In for " +"example cameras this is used to provide different frame sizes and numbers of " +"frames per second." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:121 +msgid "" +"Within each interface, 0 or more endpoints can be specified. Endpoints are " +"the unidirectional access points for communicating with a device. They " +"provide buffers to temporarily store incoming or outgoing data from the " +"device. Each endpoint has a unique address within a configuration, the " +"endpoint's number plus its direction. The default endpoint, endpoint 0, is " +"not part of any interface and available in all configurations. It is managed " +"by the services layer and not directly available to device drivers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:123 +msgid "" +"This hierarchical configuration information is described in the device by a " +"standard set of descriptors (see section 9.6 of the USB specification). They " +"can be requested through the Get Descriptor Request. The services layer " +"caches these descriptors to avoid unnecessary transfers on the USB bus. " +"Access to the descriptors is provided through function calls." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:125 +msgid "" +"Device descriptors: General information about the device, like Vendor, " +"Product and Revision Id, supported device class, subclass and protocol if " +"applicable, maximum packet size for the default endpoint, etc." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:126 +msgid "" +"Configuration descriptors: The number of interfaces in this configuration, " +"suspend and resume functionality supported and power requirements." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:127 +msgid "" +"Interface descriptors: interface class, subclass and protocol if applicable, " +"number of alternate settings for the interface and the number of endpoints." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:128 +msgid "" +"Endpoint descriptors: Endpoint address, direction and type, maximum packet " +"size supported and polling frequency if type is interrupt endpoint. There is " +"no descriptor for the default endpoint (endpoint 0) and it is never counted " +"in an interface descriptor." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:129 +msgid "" +"String descriptors: In the other descriptors string indices are supplied for " +"some fields.These can be used to retrieve descriptive strings, possibly in " +"multiple languages." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:131 +msgid "" +"Class specifications can add their own descriptor types that are available " +"through the GetDescriptor Request." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:133 +msgid "" +"Pipes Communication to end points on a device flows through so-called pipes. " +"Drivers submit transfers to endpoints to a pipe and provide a callback to be " +"called on completion or failure of the transfer (asynchronous transfers) or " +"wait for completion (synchronous transfer). Transfers to an endpoint are " +"serialised in the pipe. A transfer can either complete, fail or time-out (if " +"a time-out has been set). There are two types of time-outs for transfers. " +"Time-outs can happen due to time-out on the USBbus (milliseconds). These " +"time-outs are seen as failures and can be due to disconnection of the " +"device. A second form of time-out is implemented in software and is " +"triggered when a transfer does not complete within a specified amount of " +"time (seconds). These are caused by a device acknowledging negatively (NAK) " +"the transferred packets. The cause for this is the device not being ready to " +"receive data, buffer under- or overrun or protocol errors." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:135 +msgid "" +"If a transfer over a pipe is larger than the maximum packet size specified " +"in the associated endpoint descriptor, the host controller (OHCI) or the HC " +"driver (UHCI) will split the transfer into packets of maximum packet size, " +"with the last packet possibly smaller than the maximum packet size." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:137 +msgid "" +"Sometimes it is not a problem for a device to return less data than " +"requested. For example abulk-in-transfer to a modem might request 200 bytes " +"of data, but the modem has only 5 bytes available at that time. The driver " +"can set the short packet (SPD) flag. It allows the host controller to accept " +"a packet even if the amount of data transferred is less than requested. This " +"flag is only valid for in-transfers, as the amount of data to be sent to a " +"device is always known beforehand. If an unrecoverable error occurs in a " +"device during a transfer the pipe is stalled. Before any more data is " +"accepted or sent the driver needs to resolve the cause of the stall and " +"clear the endpoint stall condition through send the clear endpoint halt " +"device request over the default pipe. The default endpoint should never " +"stall." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:139 +msgid "" +"There are four different types of endpoints and corresponding pipes: - " +"Control pipe / default pipe: There is one control pipe per device, connected " +"to the default endpoint (endpoint 0). The pipe carries the device requests " +"and associated data. The difference between transfers over the default pipe " +"and other pipes is that the protocol for the transfers is described in the " +"USB specification. These requests are used to reset and configure the " +"device. A basic set of commands that must be supported by each device is " +"provided in chapter 9 of the USB specification. The commands supported on " +"this pipe can be extended by a device class specification to support " +"additional functionality." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:141 +msgid "Bulk pipe: This is the USB equivalent to a raw transmission medium." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:142 +msgid "" +"Interrupt pipe: The host sends a request for data to the device and if the " +"device has nothing to send, it will NAK the data packet. Interrupt transfers " +"are scheduled at a frequency specified when creating the pipe." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:143 +msgid "" +"Isochronous pipe: These pipes are intended for isochronous data, for example " +"video or audio streams, with fixed latency, but no guaranteed delivery. Some " +"support for pipes of this type is available in the current implementation. " +"Packets in control, bulk and interrupt transfers are retried if an error " +"occurs during transmission or the device acknowledges the packet negatively " +"(NAK) due to for example lack of buffer space to store the incoming data. " +"Isochronous packets are however not retried in case of failed delivery or " +"NAK of a packet as this might violate the timing constraints." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:145 +msgid "" +"The availability of the necessary bandwidth is calculated during the " +"creation of the pipe. Transfers are scheduled within frames of 1 " +"millisecond. The bandwidth allocation within a frame is prescribed by the " +"USB specification, section 5.6 [ 2]. Isochronous and interrupt transfers are " +"allowed to consume up to 90% of the bandwidth within a frame. Packets for " +"control and bulk transfers are scheduled after all isochronous and interrupt " +"packets and will consume all the remaining bandwidth." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:147 +msgid "" +"More information on scheduling of transfers and bandwidth reclamation can be " +"found in chapter 5 of the USB specification, section 1.3 of the UHCI " +"specification, and section 3.4.2 of the OHCI specification." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:149 +#, no-wrap +msgid "Device Probe and Attach" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:152 +msgid "" +"After the notification by the hub that a new device has been connected, the " +"service layer switches on the port, providing the device with 100 mA of " +"current. At this point the device is in its default state and listening to " +"device address 0. The services layer will proceed to retrieve the various " +"descriptors through the default pipe. After that it will send a Set Address " +"request to move the device away from the default device address (address 0). " +"Multiple device drivers might be able to support the device. For example a " +"modem driver might be able to support an ISDN TA through the AT " +"compatibility interface. A driver for that specific model of the ISDN " +"adapter might however be able to provide much better support for this " +"device. To support this flexibility, the probes return priorities indicating " +"their level of support. Support for a specific revision of a product ranks " +"the highest and the generic driver the lowest priority. It might also be " +"that multiple drivers could attach to one device if there are multiple " +"interfaces within one configuration. Each driver only needs to support a " +"subset of the interfaces." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:154 +msgid "" +"The probing for a driver for a newly attached device checks first for device " +"specific drivers. If not found, the probe code iterates over all supported " +"configurations until a driver attaches in a configuration. To support " +"devices with multiple drivers on different interfaces, the probe iterates " +"over all interfaces in a configuration that have not yet been claimed by a " +"driver. Configurations that exceed the power budget for the hub are ignored. " +"During attach the driver should initialise the device to its proper state, " +"but not reset it, as this will make the device disconnect itself from the " +"bus and restart the probing process for it. To avoid consuming unnecessary " +"bandwidth should not claim the interrupt pipe at attach time, but should " +"postpone allocating the pipe until the file is opened and the data is " +"actually used. When the file is closed the pipe should be closed again, even " +"though the device might still be attached." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:155 +#, no-wrap +msgid "Device Disconnect and Detach" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:158 +msgid "" +"A device driver should expect to receive errors during any transaction with " +"the device. The design of USB supports and encourages the disconnection of " +"devices at any point in time. Drivers should make sure that they do the " +"right thing when the device disappears." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:160 +msgid "" +"Furthermore a device that has been disconnected and reconnected will not be " +"reattached at the same device instance. This might change in the future when " +"more devices support serial numbers (see the device descriptor) or other " +"means of defining an identity for a device have been developed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:162 +msgid "" +"The disconnection of a device is signaled by a hub in the interrupt packet " +"delivered to the hub driver. The status change information indicates which " +"port has seen a connection change. The device detach method for all device " +"drivers for the device connected on that port are called and the structures " +"cleaned up. If the port status indicates that in the mean time a device has " +"been connected to that port, the procedure for probing and attaching the " +"device will be started. A device reset will produce a disconnect-connect " +"sequence on the hub and will be handled as described above." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:164 +#, no-wrap +msgid "USB Drivers Protocol Information" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:167 +msgid "" +"The protocol used over pipes other than the default pipe is undefined by the " +"USB specification. Information on this can be found from various sources. " +"The most accurate source is the developer's section on the USB home pages. " +"From these pages, a growing number of deviceclass specifications are " +"available. These specifications specify what a compliant device should look " +"like from a driver perspective, basic functionality it needs to provide and " +"the protocol that is to be used over the communication channels. The USB " +"specification includes the description of the Hub Class. A class " +"specification for Human Interface Devices (HID) has been created to cater " +"for keyboards, tablets, bar-code readers, buttons, knobs, switches, etc. A " +"third example is the class specification for mass storage devices. For a " +"full list of device classes see the developers section on the USB home pages." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:169 +msgid "" +"For many devices the protocol information has not yet been published " +"however. Information on the protocol being used might be available from the " +"company making the device. Some companies will require you to sign a Non " +"-Disclosure Agreement (NDA) before giving you the specifications. This in " +"most cases precludes making the driver open source." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:171 +msgid "" +"Another good source of information is the Linux driver sources, as a number " +"of companies have started to provide drivers for Linux for their devices. It " +"is always a good idea to contact the authors of those drivers for their " +"source of information." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:173 +msgid "" +"Example: Human Interface Devices The specification for the Human Interface " +"Devices like keyboards, mice, tablets, buttons, dials,etc. is referred to in " +"other device class specifications and is used in many devices." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:175 +msgid "" +"For example audio speakers provide endpoints to the digital to analogue " +"converters and possibly an extra pipe for a microphone. They also provide a " +"HID endpoint in a separate interface for the buttons and dials on the front " +"of the device. The same is true for the monitor control class. It is " +"straightforward to build support for these interfaces through the available " +"kernel and userland libraries together with the HID class driver or the " +"generic driver. Another device that serves as an example for interfaces " +"within one configuration driven by different device drivers is a cheap " +"keyboard with built-in legacy mouse port. To avoid having the cost of " +"including the hardware for a USB hub in the device, manufacturers combined " +"the mouse data received from the PS/2 port on the back of the keyboard and " +"the key presses from the keyboard into two separate interfaces in the same " +"configuration. The mouse and keyboard drivers each attach to the appropriate " +"interface and allocate the pipes to the two independent endpoints." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:177 +msgid "" +"Example: Firmware download Many devices that have been developed are based " +"on a general purpose processor with an additional USB core added to it. " +"Since the development of drivers and firmware for USB devices is still very " +"new, many devices require the downloading of the firmware after they have " +"been connected." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:179 +msgid "" +"The procedure followed is straightforward. The device identifies itself " +"through a vendor and product Id. The first driver probes and attaches to it " +"and downloads the firmware into it. After that the device soft resets itself " +"and the driver is detached. After a short pause the device announces its " +"presence on the bus. The device will have changed its vendor/product/" +"revision Id to reflect the fact that it has been supplied with firmware and " +"as a consequence a second driver will probe it and attach to it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:181 +msgid "" +"An example of these types of devices is the ActiveWire I/O board, based on " +"the EZ-USB chip. For this chip a generic firmware downloader is available. " +"The firmware downloaded into the ActiveWire board changes the revision Id. " +"It will then perform a soft reset of the USB part of the EZ-USB chip to " +"disconnect from the USB bus and again reconnect." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:183 +msgid "" +"Example: Mass Storage Devices Support for mass storage devices is mainly " +"built around existing protocols. The Iomega USB Zipdrive is based on the " +"SCSI version of their drive. The SCSI commands and status messages are " +"wrapped in blocks and transferred over the bulk pipes to and from the " +"device, emulating a SCSI controller over the USB wire. ATAPI and UFI " +"commands are supported in a similar fashion." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:185 +msgid "" +"The Mass Storage Specification supports 2 different types of wrapping of the " +"command block.The initial attempt was based on sending the command and " +"status through the default pipe and using bulk transfers for the data to be " +"moved between the host and the device. Based on experience a second approach " +"was designed that was based on wrapping the command and status blocks and " +"sending them over the bulk out and in endpoint. The specification specifies " +"exactly what has to happen when and what has to be done in case an error " +"condition is encountered. The biggest challenge when writing drivers for " +"these devices is to fit USB based protocol into the existing support for " +"mass storage devices. CAM provides hooks to do this in a fairly straight " +"forward way. ATAPI is less simple as historically the IDE interface has " +"never had many different appearances." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:186 +msgid "" +"The support for the USB floppy from Y-E Data is again less straightforward " +"as a new command set has been designed." +msgstr "" diff --git a/documentation/content/en/books/arch-handbook/vm/_index.adoc b/documentation/content/en/books/arch-handbook/vm/_index.adoc index 31a24a33b2..d35b0e0916 100644 --- a/documentation/content/en/books/arch-handbook/vm/_index.adoc +++ b/documentation/content/en/books/arch-handbook/vm/_index.adoc @@ -6,7 +6,8 @@ description: Virtual Memory System in FreeBSD tags: ["Virtual memory", "vm_page_t", "vm_object_t", "I/O", "KVM"] showBookMenu: true weight: 8 -path: "/books/arch-handbook/" +params: + path: "/books/arch-handbook/vm/" --- [[vm]] diff --git a/documentation/content/en/books/arch-handbook/vm/_index.po b/documentation/content/en/books/arch-handbook/vm/_index.po new file mode 100644 index 0000000000..bc33ddf698 --- /dev/null +++ b/documentation/content/en/books/arch-handbook/vm/_index.po @@ -0,0 +1,366 @@ +# 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: YAML Front Matter: description +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:1 +#, no-wrap +msgid "Virtual Memory System in FreeBSD" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:1 +#, no-wrap +msgid "Chapter 7. Virtual Memory System" +msgstr "" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:14 +#, no-wrap +msgid "Virtual Memory System" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:52 +#, no-wrap +msgid "Management of Physical Memory `vm_page_t`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:55 +msgid "" +"Physical memory is managed on a page-by-page basis through the `vm_page_t` " +"structure. Pages of physical memory are categorized through the placement of " +"their respective `vm_page_t` structures on one of several paging queues." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:57 +msgid "" +"A page can be in a wired, active, inactive, cache, or free state. Except for " +"the wired state, the page is typically placed in a doubly link list queue " +"representing the state that it is in. Wired pages are not placed on any " +"queue." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:59 +msgid "" +"FreeBSD implements a more involved paging queue for cached and free pages in " +"order to implement page coloring. Each of these states involves multiple " +"queues arranged according to the size of the processor's L1 and L2 caches. " +"When a new page needs to be allocated, FreeBSD attempts to obtain one that " +"is reasonably well aligned from the point of view of the L1 and L2 caches " +"relative to the VM object the page is being allocated for." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:61 +msgid "" +"Additionally, a page may be held with a reference count or locked with a " +"busy count. The VM system also implements an \"ultimate locked\" state for a " +"page using the PG_BUSY bit in the page's flags." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:63 +msgid "" +"In general terms, each of the paging queues operates in a LRU fashion. A " +"page is typically placed in a wired or active state initially. When wired, " +"the page is usually associated with a page table somewhere. The VM system " +"ages the page by scanning pages in a more active paging queue (LRU) in order " +"to move them to a less-active paging queue. Pages that get moved into the " +"cache are still associated with a VM object but are candidates for immediate " +"reuse. Pages in the free queue are truly free. FreeBSD attempts to minimize " +"the number of pages in the free queue, but a certain minimum number of truly " +"free pages must be maintained in order to accommodate page allocation at " +"interrupt time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:65 +msgid "" +"If a process attempts to access a page that does not exist in its page table " +"but does exist in one of the paging queues (such as the inactive or cache " +"queues), a relatively inexpensive page reactivation fault occurs which " +"causes the page to be reactivated. If the page does not exist in system " +"memory at all, the process must block while the page is brought in from disk." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:67 +msgid "" +"FreeBSD dynamically tunes its paging queues and attempts to maintain " +"reasonable ratios of pages in the various queues as well as attempts to " +"maintain a reasonable breakdown of clean versus dirty pages. The amount of " +"rebalancing that occurs depends on the system's memory load. This " +"rebalancing is implemented by the pageout daemon and involves laundering " +"dirty pages (syncing them with their backing store), noticing when pages are " +"activity referenced (resetting their position in the LRU queues or moving " +"them between queues), migrating pages between queues when the queues are out " +"of balance, and so forth. FreeBSD's VM system is willing to take a " +"reasonable number of reactivation page faults to determine how active or how " +"idle a page actually is. This leads to better decisions being made as to " +"when to launder or swap-out a page." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:69 +#, no-wrap +msgid "The Unified Buffer Cache `vm_object_t`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:72 +msgid "" +"FreeBSD implements the idea of a generic \"VM object\". VM objects can be " +"associated with backing store of various typesunbacked, swap-backed, " +"physical device-backed, or file-backed storage. Since the filesystem uses " +"the same VM objects to manage in-core data relating to files, the result is " +"a unified buffer cache." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:74 +msgid "" +"VM objects can be _shadowed_. That is, they can be stacked on top of each " +"other. For example, you might have a swap-backed VM object stacked on top of " +"a file-backed VM object in order to implement a MAP_PRIVATE mmap()ing. This " +"stacking is also used to implement various sharing properties, including " +"copy-on-write, for forked address spaces." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:76 +msgid "" +"It should be noted that a `vm_page_t` can only be associated with one VM " +"object at a time. The VM object shadowing implements the perceived sharing " +"of the same page across multiple instances." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:78 +#, no-wrap +msgid "Filesystem I/O `struct buf`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:81 +msgid "" +"vnode-backed VM objects, such as file-backed objects, generally need to " +"maintain their own clean/dirty info independent from the VM system's idea of " +"clean/dirty. For example, when the VM system decides to synchronize a " +"physical page to its backing store, the VM system needs to mark the page " +"clean before the page is actually written to its backing store. " +"Additionally, filesystems need to be able to map portions of a file or file " +"metadata into KVM in order to operate on it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:83 +msgid "" +"The entities used to manage this are known as filesystem buffers, ``struct " +"buf``'s, or ``bp``'s. When a filesystem needs to operate on a portion of a " +"VM object, it typically maps part of the object into a struct buf and then " +"maps the pages in the struct buf into KVM. In the same manner, disk I/O is " +"typically issued by mapping portions of objects into buffer structures and " +"then issuing the I/O on the buffer structures. The underlying vm_page_t's " +"are typically busied for the duration of the I/O. Filesystem buffers also " +"have their own notion of being busy, which is useful to filesystem driver " +"code which would rather operate on filesystem buffers instead of hard VM " +"pages." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:85 +msgid "" +"FreeBSD reserves a limited amount of KVM to hold mappings from struct bufs, " +"but it should be made clear that this KVM is used solely to hold mappings " +"and does not limit the ability to cache data. Physical data caching is " +"strictly a function of ``vm_page_t``'s, not filesystem buffers. However, " +"since filesystem buffers are used to placehold I/O, they do inherently limit " +"the amount of concurrent I/O possible. However, as there are usually a few " +"thousand filesystem buffers available, this is not usually a problem." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:87 +#, no-wrap +msgid "Mapping Page Tables `vm_map_t, vm_entry_t`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:90 +msgid "" +"FreeBSD separates the physical page table topology from the VM system. All " +"hard per-process page tables can be reconstructed on the fly and are usually " +"considered throwaway. Special page tables such as those managing KVM are " +"typically permanently preallocated. These page tables are not throwaway." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:92 +msgid "" +"FreeBSD associates portions of vm_objects with address ranges in virtual " +"memory through `vm_map_t` and `vm_entry_t` structures. Page tables are " +"directly synthesized from the `vm_map_t`/`vm_entry_t`/ `vm_object_t` " +"hierarchy. Recall that I mentioned that physical pages are only directly " +"associated with a `vm_object`; that is not quite true. ``vm_page_t``'s are " +"also linked into page tables that they are actively associated with. One " +"`vm_page_t` can be linked into several _pmaps_, as page tables are called. " +"However, the hierarchical association holds, so all references to the same " +"page in the same object reference the same `vm_page_t` and thus give us " +"buffer cache unification across the board." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:94 +#, no-wrap +msgid "KVM Memory Mapping" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:97 +msgid "" +"FreeBSD uses KVM to hold various kernel structures. The single largest " +"entity held in KVM is the filesystem buffer cache. That is, mappings " +"relating to `struct buf` entities." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:99 +msgid "" +"Unlike Linux, FreeBSD does _not_ map all of physical memory into KVM. This " +"means that FreeBSD can handle memory configurations up to 4G on 32 bit " +"platforms. In fact, if the mmu were capable of it, FreeBSD could " +"theoretically handle memory configurations up to 8TB on a 32 bit platform. " +"However, since most 32 bit platforms are only capable of mapping 4GB of ram, " +"this is a moot point." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:101 +msgid "" +"KVM is managed through several mechanisms. The main mechanism used to manage " +"KVM is the _zone allocator_. The zone allocator takes a chunk of KVM and " +"splits it up into constant-sized blocks of memory in order to allocate a " +"specific type of structure. You can use `vmstat -m` to get an overview of " +"current KVM utilization broken down by zone." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:103 +#, no-wrap +msgid "Tuning the FreeBSD VM System" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:106 +msgid "" +"A concerted effort has been made to make the FreeBSD kernel dynamically tune " +"itself. Typically you do not need to mess with anything beyond the " +"`maxusers` and `NMBCLUSTERS` kernel config options. That is, kernel " +"compilation options specified in (typically) [.filename]#/usr/src/sys/i386/" +"conf/CONFIG_FILE#. A description of all available kernel configuration " +"options can be found in [.filename]#/usr/src/sys/i386/conf/LINT#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:108 +msgid "" +"In a large system configuration you may wish to increase `maxusers`. Values " +"typically range from 10 to 128. Note that raising `maxusers` too high can " +"cause the system to overflow available KVM resulting in unpredictable " +"operation. It is better to leave `maxusers` at some reasonable number and " +"add other options, such as `NMBCLUSTERS`, to increase specific resources." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:110 +msgid "" +"If your system is going to use the network heavily, you may want to increase " +"`NMBCLUSTERS`. Typical values range from 1024 to 4096." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:112 +msgid "" +"The `NBUF` parameter is also traditionally used to scale the system. This " +"parameter determines the amount of KVA the system can use to map filesystem " +"buffers for I/O. Note that this parameter has nothing whatsoever to do with " +"the unified buffer cache! This parameter is dynamically tuned in 3.0-CURRENT " +"and later kernels and should generally not be adjusted manually. We " +"recommend that you _not_ try to specify an `NBUF` parameter. Let the system " +"pick it. Too small a value can result in extremely inefficient filesystem " +"operation while too large a value can starve the page queues by causing too " +"many pages to become wired down." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:114 +msgid "" +"By default, FreeBSD kernels are not optimized. You can set debugging and " +"optimization flags with the `makeoptions` directive in the kernel " +"configuration. Note that you should not use `-g` unless you can accommodate " +"the large (typically 7 MB+) kernels that result." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:119 +#, no-wrap +msgid "" +"makeoptions DEBUG=\"-g\"\n" +"makeoptions COPTFLAGS=\"-O -pipe\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:122 +msgid "" +"Sysctl provides a way to tune kernel parameters at run-time. You typically " +"do not need to mess with any of the sysctl variables, especially the VM " +"related ones." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:124 +msgid "" +"Run time VM and system tuning is relatively straightforward. First, use Soft " +"Updates on your UFS/FFS filesystems whenever possible. [.filename]#/usr/src/" +"sys/ufs/ffs/README.softupdates# contains instructions (and restrictions) on " +"how to configure it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:126 +msgid "" +"Second, configure sufficient swap. You should have a swap partition " +"configured on each physical disk, up to four, even on your \"work\" disks. " +"You should have at least 2x the swap space as you have main memory, and " +"possibly even more if you do not have a lot of memory. You should also size " +"your swap partition based on the maximum memory configuration you ever " +"intend to put on the machine so you do not have to repartition your disks " +"later on. If you want to be able to accommodate a crash dump, your first " +"swap partition must be at least as large as main memory and [.filename]#/var/" +"crash# must have sufficient free space to hold the dump." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:127 +msgid "" +"NFS-based swap is perfectly acceptable on 4.X or later systems, but you must " +"be aware that the NFS server will take the brunt of the paging load." +msgstr "" |