diff --git a/documentation/content/ru/books/arch-handbook/_index.adoc b/documentation/content/ru/books/arch-handbook/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/_index.adoc @@ -0,0 +1,57 @@ +--- +add_single_page_link: true +authors: + - + author: 'The FreeBSD Documentation Project' +bookOrder: 50 +copyright: '2000-2006, 2012-2023 The FreeBSD Documentation Project' +description: 'Для разработчиков систем FreeBSD. В этой книге рассматриваются архитектурные особенности многих важных подсистем ядра FreeBSD' +next: books/arch-handbook/parti +params: + path: /books/arch-handbook/ +showBookMenu: true +tags: ["Arch Handbook", "FreeBSD"] +title: 'Руководство по архитектуре FreeBSD' +trademarks: ["freebsd", "apple", "microsoft", "unix", "general"] +weight: 0 +--- + += Руководство по архитектуре FreeBSD +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[.abstract-title] +Аннотация + +Добро пожаловать в Руководство по архитектуре FreeBSD. Это руководство находится _в стадии разработки_ и создаётся усилиями многих участников. Многие разделы пока не написаны, а существующие могут требовать обновления. Если вы хотите помочь в работе над этим проектом, напишите на электронную почту списка рассылки {freebsd-doc}. + +Актуальная версия этого документа всегда доступна на https://www.FreeBSD.org/[официальном веб-сервере FreeBSD]. Его также можно загрузить в различных форматах и с разными вариантами сжатия с https://download.freebsd.org/doc/[сервера загрузок FreeBSD] или одного из многочисленных зеркал extref:{handbook}mirrors/[mirror sites, mirrors]. + +''' diff --git a/documentation/content/ru/books/arch-handbook/_index.po b/documentation/content/ru/books/arch-handbook/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/_index.po @@ -0,0 +1,71 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-08-16 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\n" + +#. type: Yaml Front Matter Hash Value: 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 "Для разработчиков систем FreeBSD. В этой книге рассматриваются архитектурные особенности многих важных подсистем ядра FreeBSD" + +#. 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 "Руководство по архитектуре FreeBSD" + +#. 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 "" +"Добро пожаловать в Руководство по архитектуре FreeBSD. Это руководство " +"находится _в стадии разработки_ и создаётся усилиями многих участников. " +"Многие разделы пока не написаны, а существующие могут требовать обновления. " +"Если вы хотите помочь в работе над этим проектом, напишите на электронную " +"почту списка рассылки {freebsd-doc}." + +#. 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 "" +"Актуальная версия этого документа всегда доступна на https://www.FreeBSD.org/" +"[официальном веб-сервере FreeBSD]. Его также можно загрузить в различных " +"форматах и с разными вариантами сжатия с https://download.freebsd.org/doc/" +"[сервера загрузок FreeBSD] или одного из многочисленных зеркал extref:" +"{handbook}mirrors/[mirror sites, mirrors]." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/_index.adoc:56 +msgid "'''" +msgstr "'''" diff --git a/documentation/content/ru/books/arch-handbook/bibliography/_index.adoc b/documentation/content/ru/books/arch-handbook/bibliography/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/bibliography/_index.adoc @@ -0,0 +1,51 @@ +--- +description: 'Библиография Руководства по архитектуре FreeBSD' +params: + path: /books/arch-handbook/bibliography/ +prev: books/arch-handbook/partiii +showBookMenu: true +tags: ["bibliography", "Arch Handbook", "FreeBSD"] +title: Библиография +weight: 20 +--- + +[appendix] +[[bibliography]] += Библиография +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: A +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[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. diff --git a/documentation/content/ru/books/arch-handbook/bibliography/_index.po b/documentation/content/ru/books/arch-handbook/bibliography/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/bibliography/_index.po @@ -0,0 +1,45 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-12 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\n" + +#. type: Yaml Front Matter Hash Value: description +#: documentation/content/en/books/arch-handbook/bibliography/_index.adoc:1 +#, no-wrap +msgid "Bibliography of the FreeBSD Architecture Handbook" +msgstr "Библиография Руководства по архитектуре FreeBSD" + +#. 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 "" +"[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." diff --git a/documentation/content/ru/books/arch-handbook/book.adoc b/documentation/content/ru/books/arch-handbook/book.adoc --- a/documentation/content/ru/books/arch-handbook/book.adoc +++ b/documentation/content/ru/books/arch-handbook/book.adoc @@ -1,14 +1,16 @@ --- -title: FreeBSD Architecture Handbook -authors: - - author: The FreeBSD Documentation Project -copyright: 2000-2006, 2012-2013 The FreeBSD Documentation Project -description: FreeBSD Architecture Handbook -trademarks: ["freebsd", "apple", "microsoft", "unix", "general"] +add_split_page_link: true +authors: + - + author: 'The FreeBSD Documentation Project' +copyright: '2000-2006, 2012-2023 The FreeBSD Documentation Project' +description: 'Для разработчиков систем FreeBSD. В этой книге рассматриваются архитектурные особенности многих важных подсистем ядра FreeBSD' tags: ["Arch Handbook", "FreeBSD"] +title: 'Руководство по архитектуре FreeBSD' +trademarks: ["freebsd", "apple", "microsoft", "unix", "general"] --- -= FreeBSD Architecture Handbook += Руководство по архитектуре FreeBSD :doctype: book :toc: macro :toclevels: 2 @@ -20,7 +22,6 @@ :experimental: :book: true :pdf: false -:images-path: books/arch-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] @@ -44,15 +45,39 @@ include::../../../../../shared/asciidoctor.adoc[] endif::[] +[.abstract-title] +Аннотация + +Добро пожаловать в Руководство по архитектуре FreeBSD. Это руководство находится _в стадии разработки_ и создаётся усилиями многих участников. Многие разделы пока не написаны, а существующие могут требовать обновления. Если вы хотите помочь в работе над этим проектом, напишите на электронную почту списка рассылки {freebsd-doc}. + +Актуальная версия этого документа всегда доступна на https://www.FreeBSD.org/[официальном веб-сервере FreeBSD]. Его также можно загрузить в различных форматах и с разными вариантами сжатия с https://download.freebsd.org/doc/[сервера загрузок FreeBSD] или одного из многочисленных зеркал extref:{handbook}mirrors/[mirror sites, mirrors]. + ''' toc::[] // Section one - -include::{chapters-path}locking/chapter.adoc[leveloffset=+1] +include::{chapters-path}parti.adoc[] +include::{chapters-path}boot/_index.adoc[leveloffset=+1] +include::{chapters-path}locking/_index.adoc[leveloffset=+1] +include::{chapters-path}kobj/_index.adoc[leveloffset=+1] +include::{chapters-path}jail/_index.adoc[leveloffset=+1] +include::{chapters-path}sysinit/_index.adoc[leveloffset=+1]] +include::{chapters-path}mac/_index.adoc[leveloffset=+1] +include::{chapters-path}vm/_index.adoc[leveloffset=+1] +include::{chapters-path}smp/_index.adoc[leveloffset=+1] // Section two +include::{chapters-path}partii.adoc[] +include::{chapters-path}driverbasics/_index.adoc[leveloffset=+1] +include::{chapters-path}isa/_index.adoc[leveloffset=+1] +include::{chapters-path}pci/_index.adoc[leveloffset=+1] +include::{chapters-path}scsi/_index.adoc[leveloffset=+1] +include::{chapters-path}usb/_index.adoc[leveloffset=+1] +include::{chapters-path}newbus/_index.adoc[leveloffset=+1] +include::{chapters-path}sound/_index.adoc[leveloffset=+1] +include::{chapters-path}pccard/_index.adoc[leveloffset=+1] -include::{chapters-path}driverbasics/chapter.adoc[leveloffset=+1] -include::{chapters-path}sound/chapter.adoc[leveloffset=+1] +// Section three +include::{chapters-path}partiii.adoc[] +include::{chapters-path}bibliography/_index.adoc[leveloffset=+1] diff --git a/documentation/content/ru/books/arch-handbook/book.po b/documentation/content/ru/books/arch-handbook/book.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/book.po @@ -0,0 +1,71 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-08-16 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\n" + +#. type: Yaml Front Matter Hash Value: 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 "Для разработчиков систем FreeBSD. В этой книге рассматриваются архитектурные особенности многих важных подсистем ядра FreeBSD" + +#. 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 "Руководство по архитектуре FreeBSD" + +#. 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 "" +"Добро пожаловать в Руководство по архитектуре FreeBSD. Это руководство " +"находится _в стадии разработки_ и создаётся усилиями многих участников. " +"Многие разделы пока не написаны, а существующие могут требовать обновления. " +"Если вы хотите помочь в работе над этим проектом, напишите на электронную " +"почту списка рассылки {freebsd-doc}." + +#. 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 "" +"Актуальная версия этого документа всегда доступна на https://www.FreeBSD.org/" +"[официальном веб-сервере FreeBSD]. Его также можно загрузить в различных " +"форматах и с разными вариантами сжатия с https://download.freebsd.org/doc/" +"[сервера загрузок FreeBSD] или одного из многочисленных зеркал extref:" +"{handbook}mirrors/[mirror sites, mirrors]." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/book.adoc:55 +msgid "'''" +msgstr "'''" diff --git a/documentation/content/ru/books/arch-handbook/boot/_index.adoc b/documentation/content/ru/books/arch-handbook/boot/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/boot/_index.adoc @@ -0,0 +1,1351 @@ +--- +description: 'Начальная загрузка и инициализация ядра' +next: books/arch-handbook/locking +params: + path: /books/arch-handbook/boot/ +prev: books/arch-handbook/parti +showBookMenu: true +tags: ["boot", "BIOS", "kernel", "MBR", "FreeBSD"] +title: 'Глава 1. Начальная загрузка и инициализация ядра' +weight: 2 +--- + +[[boot]] += Начальная загрузка и инициализация ядра +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 1 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[boot-synopsis]] +== Обзор + +Эта глава представляет собой обзор процессов загрузки и инициализации системы, начиная с POST в BIOS (микропрограмме) и заканчивая созданием первого пользовательского процесса. Поскольку начальные этапы загрузки системы сильно зависят от архитектуры, в качестве примера используется архитектура IA-32. Однако архитектуры AMD64 и ARM64 гораздо важнее и интереснее, и их следует рассмотреть в ближайшем будущем в соответствии с темой этого документа. + +Процесс загрузки FreeBSD может быть удивительно сложным. После передачи управления от BIOS необходимо выполнить значительный объем низкоуровневой настройки перед загрузкой и выполнением ядра. Эта настройка должна быть выполнена простым и гибким способом, предоставляя пользователю широкие возможности для настройки и адаптации. + +[[boot-overview]] +== Обзор + +Процесс загрузки — это операция, крайне зависимая от оборудования. Не только для каждой архитектуры компьютера должен быть написан код, но также могут существовать различные типы загрузки в рамках одной архитектуры. Например, список файлов в каталоге [.filename]#stand# показывает большое количество кода, зависящего от архитектуры. Для каждой из поддерживаемых архитектур существует отдельный каталог. FreeBSD поддерживает стандарт загрузки CSM (Compatibility Support Module). Таким образом, CSM поддерживается (как с GPT, так и с MBR разметкой), а также загрузка через UEFI (GPT полностью поддерживается, MBR — в основном). Также поддерживается загрузка файлов с ext2fs, MSDOS, UFS и ZFS. FreeBSD поддерживает функцию загрузочного окружения ZFS, которая позволяет основной ОС передавать детали о том, что загружать, выходящие за рамки простого раздела, как это было возможно ранее. Однако в наши дни UEFI более актуален, чем CSM. В следующем примере показана загрузка компьютера x86 с жёсткого диска с MBR-разметкой, где используется мультизагрузчик FreeBSD [.filename]#boot0#, сохранённый в самом первом секторе. Этот загрузочный код запускает трёхэтапный процесс загрузки FreeBSD. + +Ключ к пониманию этого процесса заключается в том, что он состоит из последовательных стадий возрастающей сложности. Эти стадии — [.filename]#boot1#, [.filename]#boot2# и [.filename]#loader# (подробнее см. man:boot[8]). Система загрузки выполняет каждую стадию последовательно. Последняя стадия, [.filename]#loader#, отвечает за загрузку ядра FreeBSD. Каждая стадия рассматривается в следующих разделах. + +Вот пример вывода, сгенерированного на различных этапах загрузки. Фактический вывод может отличаться в зависимости от машины: + +[.informaltable] +[cols="20%,80%", frame="none"] +|=== + +|*Компонент FreeBSD* +|*Вывод (может отличаться)* + +|`boot0` +a| + +[source,bash] +.... +F1 FreeBSD +F2 BSD +F5 Disk 2 +.... + +|`boot2` footnote:[Это приглашение появится, если пользователь нажмет клавишу сразу после выбора ОС для загрузки на этапе boot0.] +a| + +[source,bash] +.... +>>FreeBSD/x86 BOOT +Default: 0:ad(0p4)/boot/loader +boot: +.... + +|[.filename]#loader# +a| + +[source,bash] +.... +BTX loader 1.00 BTX version is 1.02 +Consoles: internal video/keyboard +BIOS drive C: is disk0 +BIOS 639kB/2096064kB available memory + +FreeBSD/x86 bootstrap loader, Revision 1.1 +Console internal video/keyboard +(root@releng1.nyi.freebsd.org, Fri Apr 9 04:04:45 UTC 2021) +Loading /boot/defaults/loader.conf +/boot/kernel/kernel text=0xed9008 data=0x117d28+0x176650 syms=[0x8+0x137988+0x8+0x1515f8] +.... + +|ядро системы +a| + +[source,bash] +.... +Copyright (c) 1992-2021 The FreeBSD Project. +Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994 + The Regents of the University of California. All rights reserved. +FreeBSD is a registered trademark of The FreeBSD Foundation. +FreeBSD 13.0-RELEASE 0 releng/13.0-n244733-ea31abc261f: Fri Apr 9 04:04:45 UTC 2021 + root@releng1.nyi.freebsd.org:/usr/obj/usr/src/i386.i386/sys/GENERIC i386 +FreeBSD clang version 11.0.1 (git@github.com:llvm/llvm-project.git llvmorg-11.0.1-0-g43ff75f2c3fe) +.... + +|=== + +[[boot-bios]] +== BIOS + +При включении компьютера регистры процессора устанавливаются в некоторые предопределённые значения. Один из регистров — это регистр _указателя команд_, и его значение после включения питания чётко определено: это 32-битное значение `0xfffffff0`. Регистр указателя команд (также известный как Счётчик Команд) указывает на код, который должен быть выполнен процессором. Ещё один важный регистр — это 32-битный управляющий регистр `cr0`, и его значение сразу после перезагрузки равно `0`. Один из битов ``cr0``, бит PE (Protection Enabled, Защита Включена), указывает, работает ли процессор в 32-битном защищённом режиме или 16-битном реальном режиме. Поскольку этот бит сброшен при загрузке, процессор запускается в 16-битном реальном режиме. Реальный режим означает, среди прочего, что линейные и физические адреса идентичны. Причина, по которой процессор не запускается сразу в 32-битном защищённом режиме, — это обратная совместимость. В частности, процесс загрузки зависит от услуг, предоставляемых BIOS, а сам BIOS работает в устаревшем 16-битном коде. + +Значение `0xfffffff0` немного меньше 4 ГБ, поэтому, если в машине нет 4 ГБ физической памяти, оно не может указывать на действительный адрес памяти. Аппаратное обеспечение компьютера преобразует этот адрес так, чтобы он указывал на блок памяти BIOS. + +BIOS (Basic Input Output System) — это микросхема на материнской плате, которая содержит относительно небольшой объем памяти только для чтения (ROM). Эта память включает различные низкоуровневые процедуры, специфичные для оборудования, поставляемого с материнской платой. Процессор сначала переходит по адресу 0xfffffff0, который фактически находится в памяти BIOS. Обычно по этому адресу содержится инструкция перехода к процедурам POST BIOS. + +POST (Power On Self Test) — это набор процедур, включающих проверку памяти, проверку системной шины и другую низкоуровневую инициализацию, чтобы процессор мог правильно настроить компьютер. Важным этапом на этой стадии является определение загрузочного устройства. Современные реализации BIOS позволяют выбирать загрузочное устройство, обеспечивая загрузку с дискеты, CD-ROM, жесткого диска или других устройств. + +Самым последним действием в POST является инструкция `INT 0x19`. Обработчик `INT 0x19` считывает 512 байт из первого сектора загрузочного устройства в память по адресу `0x7c00`. Термин _первый сектор_ происходит из архитектуры жёстких дисков, где магнитная пластина разделена на множество цилиндрических дорожек. Дорожки нумеруются, и каждая дорожка разделена на несколько (обычно 64) секторов. Нумерация дорожек начинается с 0, но нумерация секторов начинается с 1. Дорожка 0 находится на внешней стороне магнитной пластины, а сектор 1, первый сектор, имеет особое назначение. Он также называется MBR (Master Boot Record) или Главная Загрузочная Запись. Остальные секторы на первой дорожке не используются. + +Этот сектор является нашей точкой входа в последовательность загрузки. Как мы увидим, этот сектор содержит копию нашей программы [.filename]#boot0#. BIOS выполняет переход по адресу `0x7c00`, и она начинает выполняться. + +[[boot-boot0]] +== Главная загрузочная запись (`boot0`) + +После получения управления от BIOS по адресу памяти `0x7c00` начинает выполняться [.filename]#boot0#. Это первый код, который управляется FreeBSD. Задача [.filename]#boot0# довольно проста: просканировать таблицу разделов и позволить пользователю выбрать, с какого раздела загружаться. Таблица разделов — это специальная стандартная структура данных, встроенная в MBR (а значит, и в [.filename]#boot0#), которая описывает четыре стандартных PC-раздела. [.filename]#boot0# находится в файловой системе как [.filename]#/boot/boot0#. Это небольшой файл размером 512 байт, и именно его процедура установки FreeBSD записывает в MBR жёсткого диска, если во время установки была выбрана опция "bootmanager". Действительно, [.filename]#boot0# _и есть_ MBR. + +Как упоминалось ранее, мы вызываем прерывание BIOS `INT 0x19` для загрузки MBR ([.filename]#boot0#) в память по адресу `0x7c00`. Исходный файл для [.filename]#boot0# можно найти в [.filename]#stand/i386/boot0/boot0.S# — это впечатляющий фрагмент кода, написанный Робертом Нордье. + +Особая структура, начинающаяся со смещения `0x1be` в MBR, называется _таблицей разделов_. Она содержит четыре записи по 16 байт каждая, называемые _записями разделов_, которые определяют, как разделён жёсткий диск, или, в терминологии FreeBSD, нарезан. Один из этих 16 байт указывает, является ли раздел (срез) загрузочным или нет. Ровно одна запись должна быть с этом установленным флагом, иначе код [.filename]#boot0# откажется продолжать работу. + +Запись о разделе содержит следующие поля: + +* 1-байтовый тип файловой системы +* 1-байтовый флаг загрузки (`bootable`) +* 6-байтовый дескриптор в формате CHS +* 8-байтовый дескриптор в формате LBA + +Дескриптор записи раздела содержит информацию о том, где именно раздел расположен на диске. Оба дескриптора, LBA и CHS, описывают одну и ту же информацию, но разными способами: LBA (Logical Block Addressing) содержит начальный сектор раздела и его длину, тогда как CHS (Cylinder Head Sector) содержит координаты первого и последнего секторов раздела. Таблица разделов завершается специальной сигнатурой `0xaa55`. + +MBR должен помещаться в 512 байт, один сектор диска. Эта программа использует низкоуровневые «трюки», такие как использование побочных эффектов определённых инструкций и повторное использование значений регистров из предыдущих операций, чтобы максимально эффективно использовать минимально возможное количество инструкций. Также необходимо соблюдать осторожность при работе с таблицей разделов, которая встроена в сам MBR. По этим причинам будьте очень внимательны при изменении [.filename]#boot0.S#. + +Обратите внимание, что исходный файл [.filename]#boot0.S# ассемблируется "как есть": инструкции переводятся одна за одной в бинарный код без дополнительной информации (например, без формата файла ELF). Такой низкоуровневый контроль достигается на этапе компоновки с помощью специальных флагов, передаваемых компоновщику. Например, текстовая секция программы располагается по адресу `0x600`. На практике это означает, что [.filename]#boot0# должен быть загружен в память по адресу `0x600` для корректной работы. + +Стоит взглянуть на [.filename]#Makefile# для [.filename]#boot0# ([.filename]#stand/i386/boot0/Makefile#), так как он определяет некоторые аспекты поведения [.filename]#boot0# во время выполнения. Например, если для ввода-вывода используется терминал, подключённый к последовательному порту (COM1), необходимо определить макрос `SIO` (`-DSIO`). `-DPXE` включает загрузку через PXE при нажатии kbd:[F6]. Кроме того, программа определяет набор _флагов_, которые позволяют дополнительно настроить её поведение. Всё это проиллюстрировано в [.filename]#Makefile#. Например, обратите внимание на директивы компоновщика, которые предписывают ему начинать секцию текста с адреса `0x600` и создавать выходной файл "как есть" (удаляя любое форматирование файла): + +[.programlisting] +.... + BOOT_BOOT0_ORG?=0x600 + ORG=${BOOT_BOOT0_ORG} +.... + +.[.filename]#stand/i386/boot0/Makefile# [[boot-boot0-makefile-as-is]] +Приступим к изучению MBR, или [.filename]#boot0#, начиная с точки входа. + +[NOTE] +==== +В некоторые инструкции были внесены изменения для лучшего изложения. Например, некоторые макросы раскрыты, а некоторые проверки макросов опущены, когда результат проверки известен. Это относится ко всем приведённым примерам кода. +==== + +[.programlisting] +.... +start: + cld # String ops inc + xorw %ax,%ax # Zero + movw %ax,%es # Address + movw %ax,%ds # data + movw %ax,%ss # Set up + movw $LOAD,%sp # stack +.... + +.[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-entrypoint]] +Этот первый блок кода является точкой входа программы. Именно сюда BIOS передаёт управление. Сначала он гарантирует, что строковые операции автоматически увеличивают указатели операндов (инструкция `cld`) footnote:[В случае сомнений мы отсылаем читателя к официальным руководствам Intel, где описана точная семантика каждой инструкции: .]. Затем, не делая предположений о состоянии сегментных регистров, он их инициализирует. Наконец, он устанавливает регистр указателя стека (`%sp`) в ($LOAD = адрес `0x7c00`), чтобы обеспечить работоспособный стек. + +Следующий блок отвечает за перемещение и последующий переход к перемещенному коду. + +[.programlisting] +.... + movw %sp,%si # Source + movw $start,%di # Destination + movw $0x100,%cx # Word count + rep # Relocate + movsw # code + movw %di,%bp # Address variables + movb $0x8,%cl # Words to clear + rep # Zero + stosw # them + incb -0xe(%di) # Set the S field to 1 + jmp main-LOAD+ORIGIN # Jump to relocated code +.... + +.[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-relocation]] +Так как [.filename]#boot0# загружается BIOS по адресу `0x7C00`, он копирует себя по адресу `0x600` и передаёт управление туда (напомним, что он был слинкован для выполнения по адресу `0x600`). Исходный адрес, `0x7c00`, копируется в регистр `%si`. Конечный адрес, `0x600`, — в регистр `%di`. Количество слов для копирования, `256` (размер программы = 512 байт), копируется в регистр `%cx`. Далее инструкция `rep` повторяет следующую за ней инструкцию, то есть `movsw`, количество раз, указанное в регистре `%cx`. Инструкция `movsw` копирует слово, на которое указывает `%si`, по адресу, на который указывает `%di`. Это повторяется ещё 255 раз. При каждом повторении оба регистра, исходный и конечный, `%si` и `%di`, увеличиваются на единицу. Таким образом, по завершении копирования 256 слов (512 байт), `%di` имеет значение `0x600`+`512`= `0x800`, а `%si` — значение `0x7c00`+`512`= `0x7e00`; таким образом, мы завершили _перемещение_ кода. С момента последнего обновления этого документа инструкции копирования в коде изменились, поэтому вместо movsb и stosb были введены movsw и stosw, которые копируют 2 байта (1 слово) за одну итерацию. + +Затем регистр назначения `%di` копируется в `%bp`. `%bp` получает значение `0x800`. Значение `8` копируется в `%cl` для подготовки новой строковой операции (как в предыдущей `movsw`). Теперь `stosw` выполняется 8 раз. Эта инструкция копирует значение `0` по адресу, на который указывает регистр назначения (`%di`, то есть `0x800`), и увеличивает его. Это повторяется ещё 7 раз, так что `%di` в итоге получает значение `0x810`. Фактически это очищает диапазон адресов `0x800`-`0x80f`. Этот диапазон используется как (фиктивная) таблица разделов для записи MBR обратно на диск. Наконец, полю сектора для CHS-адресации этого фиктивного раздела присваивается значение 1, и выполняется переход к основной функции из перемещённого кода. Обратите внимание, что до этого перехода к перемещённому коду любые ссылки на абсолютные адреса избегались. + +Следующий блок кода проверяет, следует ли использовать номер диска, предоставленный BIOS, или тот, что хранится в [.filename]#boot0#. + +[.programlisting] +.... +main: + testb $SETDRV,_FLAGS(%bp) # Set drive number? +#ifndef CHECK_DRIVE /* disable drive checks */ + jz save_curdrive # no, use the default +#else + jnz disable_update # Yes + testb %dl,%dl # Drive number valid? + js save_curdrive # Possibly (0x80 set) +#endif +.... + +.[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-drivenumber]] +Этот код проверяет бит `SETDRV` (`0x20`) в переменной _flags_. Напомним, что регистр `%bp` указывает на адрес `0x800`, поэтому проверка выполняется для переменной _flags_ по адресу `0x800`-`69`= `0x7bb`. Это пример типа изменений, которые можно внести в [.filename]#boot0#. Флаг `SETDRV` не установлен по умолчанию, но его можно задать в [.filename]#Makefile#. Если он установлен, используется номер диска, сохранённый в MBR, вместо предоставленного BIOS. Мы предполагаем значения по умолчанию и то, что BIOS предоставил корректный номер диска, поэтому переходим к `save_curdrive`. + +Следующий блок сохраняет номер диска, предоставленный BIOS, и вызывает `putn` для вывода новой строки на экран. + +[.programlisting] +.... +save_curdrive: + movb %dl, (%bp) # Save drive number + pushw %dx # Also in the stack +#ifdef TEST /* test code, print internal bios drive */ + rolb $1, %dl + movw $drive, %si + call putkey +#endif + callw putn # Print a newline +.... + +.[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-savedrivenumber]] +Обратите внимание, что мы предполагаем, что `TEST` не определён, поэтому условный код в нём не собирается и не появится в нашем исполняемом файле [.filename]#boot0#. + +Следующий блок реализует фактическое сканирование таблицы разделов. Он выводит на экран тип раздела для каждой из четырёх записей в таблице разделов. Каждый тип сравнивается со списком известных файловых систем операционных систем. Примерами распознаваемых типов разделов являются NTFS (Windows(R), ID 0x7), `ext2fs` (Linux(R), ID 0x83) и, конечно же, `ffs`/`ufs2` (FreeBSD, ID 0xa5). Реализация довольно проста. + +[.programlisting] +.... + movw $(partbl+0x4),%bx # Partition table (+4) + xorw %dx,%dx # Item number + +read_entry: + movb %ch,-0x4(%bx) # Zero active flag (ch == 0) + btw %dx,_FLAGS(%bp) # Entry enabled? + jnc next_entry # No + movb (%bx),%al # Load type + test %al, %al # skip empty partition + jz next_entry + movw $bootable_ids,%di # Lookup tables + movb $(TLEN+1),%cl # Number of entries + repne # Locate + scasb # type + addw $(TLEN-1), %di # Adjust + movb (%di),%cl # Partition + addw %cx,%di # description + callw putx # Display it + +next_entry: + incw %dx # Next item + addb $0x10,%bl # Next entry + jnc read_entry # Till done +.... + +.[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-partition-scan]] +Важно отметить, что флаг активности для каждой записи сбрасывается, поэтому после сканирования _ни одна_ запись о разделе не активна в нашей копии [.filename]#boot0# в памяти. Позже флаг активности будет установлен для выбранного раздела. Это гарантирует, что только один активный раздел существует, если пользователь решит записать изменения обратно на диск. + +Следующий блок проверяет наличие других дисков. При запуске BIOS записывает количество дисков, присутствующих в компьютере, по адресу `0x475`. Если есть другие диски, [.filename]#boot0# выводит текущий диск на экран. Пользователь может позже дать команду [.filename]#boot0# просканировать разделы на другом диске. + +[.programlisting] +.... + popw %ax # Drive number + subb $0x80-0x1,%al # Does next + cmpb NHRDRV,%al # drive exist? (from BIOS?) + jb print_drive # Yes + decw %ax # Already drive 0? + jz print_prompt # Yes +.... + +.[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-test-drives]] +Мы предполагаем, что присутствует только один диск, поэтому переход к `print_drive` не выполняется. Также мы предполагаем, что ничего необычного не произошло, поэтому переходим к `print_prompt`. + +Следующий блок просто выводит приглашение с последующим вариантом по умолчанию: + +[.programlisting] +.... +print_prompt: + movw $prompt,%si # Display + callw putstr # prompt + movb _OPT(%bp),%dl # Display + decw %si # default + callw putkey # key + jmp start_input # Skip beep +.... + +.[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-prompt]] +Наконец, выполняется переход к `start_input`, где используются сервисы BIOS для запуска таймера и чтения пользовательского ввода с клавиатуры; если таймер истекает, будет выбран вариант по умолчанию: + +[.programlisting] +.... +start_input: + xorb %ah,%ah # BIOS: Get + int $0x1a # system time + movw %dx,%di # Ticks when + addw _TICKS(%bp),%di # timeout +read_key: + movb $0x1,%ah # BIOS: Check + int $0x16 # for keypress + jnz got_key # Have input + xorb %ah,%ah # BIOS: int 0x1a, 00 + int $0x1a # get system time + cmpw %di,%dx # Timeout? + jb read_key # No +.... + +.[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-start-input]] +Прерывание запрашивается с номером `0x1a` и аргументом `0` в регистре `%ah`. BIOS имеет предопределённый набор сервисов, запрашиваемых приложениями как программно-генерируемые прерывания через инструкцию `int`, с получением аргументов в регистрах (в данном случае, `%ah`). Здесь, в частности, запрашивается количество тиков часов с момента последней полуночи; это значение вычисляется BIOS через RTC (Real Time Clock). Эти часы могут быть настроены на работу с частотой от 2 Гц до 8192 Гц. BIOS устанавливает их на 18,2 Гц при запуске. Когда запрос выполнен, 32-битный результат возвращается BIOS в регистрах `%cx` и `%dx` (младшие байты в `%dx`). Этот результат (часть `%dx`) копируется в регистр `%di`, и к `%di` добавляется значение переменной `TICKS`. Эта переменная находится в [.filename]#boot0# по смещению `_TICKS` (отрицательное значение) от регистра `%bp` (который, напомним, указывает на `0x800`). Значение этой переменной по умолчанию — `0xb6` (182 в десятичной системе). Идея заключается в том, что [.filename]#boot0# постоянно запрашивает время у BIOS, и когда значение, возвращённое в регистре `%dx`, становится больше значения, хранящегося в `%di`, время истекает и будет сделан выбор по умолчанию. Поскольку RTC тикает 18,2 раза в секунду, это условие выполнится через 10 секунд (это поведение по умолчанию можно изменить в [.filename]#Makefile#). До истечения этого времени [.filename]#boot0# непрерывно опрашивает BIOS на предмет ввода пользователя; это делается через `int 0x16`, аргумент `1` в `%ah`. + +Была нажата клавиша или истекло время, последующий код проверяет выбор. В зависимости от выбора, регистр `%si` устанавливается так, чтобы указывать на соответствующую запись раздела в таблице разделов. Этот новый выбор переопределяет предыдущий выбор по умолчанию. Действительно, он становится новым значением по умолчанию. Наконец, устанавливается флаг ACTIVE выбранного раздела. Если это было разрешено при компиляции, версия [.filename]#boot0# в памяти с этими изменёнными значениями записывается обратно в MBR на диске. Мы оставляем детали этой реализации читателю. + +Мы завершаем наше изучение последним блоком кода из программы [.filename]#boot0#: + +[.programlisting] +.... + movw $LOAD,%bx # Address for read + movb $0x2,%ah # Read sector + callw intx13 # from disk + jc beep # If error + cmpw $MAGIC,0x1fe(%bx) # Bootable? + jne beep # No + pushw %si # Save ptr to selected part. + callw putn # Leave some space + popw %si # Restore, next stage uses it + jmp *%bx # Invoke bootstrap +.... + +.[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-check-bootable]] +Вспомним, что `%si` указывает на выбранную запись раздела. Эта запись сообщает нам, где начинается раздел на диске. Мы предполагаем, конечно, что выбранный раздел действительно является срезом FreeBSD. + +[NOTE] +==== +Отныне мы будем отдавать предпочтение использованию технически более точного термина "слайс" вместо "раздел". +==== + +Буфер передачи установлен в `0x7c00` (регистр `%bx`), и запрос на чтение первого сектора слайса FreeBSD выполняется вызовом `intx13`. Мы предполагаем, что всё прошло успешно, поэтому переход к `beep` не выполняется. В частности, новый прочитанный сектор должен заканчиваться магической последовательностью `0xaa55`. Наконец, значение в `%si` (указатель на выбранную таблицу разделов) сохраняется для использования на следующем этапе, и выполняется переход по адресу `0x7c00`, где начинается выполнение нашего следующего этапа (только что прочитанного блока). + +[[boot-boot1]] +== Этап `boot1` + +До сих пор мы прошли следующую последовательность: + +* BIOS выполнил первоначальную инициализацию оборудования, включая POST. MBR ([.filename]#boot0#) был загружен по адресу `0x7c00` из абсолютного сектора один с диска. Управление выполнением было передано по этому адресу. +* [.filename]#boot0# переместил себя по адресу, по которому он был скомпонован для выполнения (`0x600`), после чего выполнил переход для продолжения выполнения в соответствующем месте. В завершение, [.filename]#boot0# загрузил первый сектор диска из раздела FreeBSD по адресу `0x7c00`. Управление выполнением было передано по этому адресу. + +[.filename]#boot1# — это следующий шаг в последовательности загрузки. Это первая из трех стадий загрузки. Обратите внимание, что до сих пор мы работали исключительно с секторами диска. Действительно, BIOS загружает самый первый сектор, а [.filename]#boot0# загружает первый сектор раздела FreeBSD. Обе загрузки происходят по адресу `0x7c00`. Мы можем концептуально представлять эти секторы диска как содержащие файлы [.filename]#boot0# и [.filename]#boot1#, соответственно, но на самом деле это не совсем верно для [.filename]#boot1#. Строго говоря, в отличие от [.filename]#boot0#, [.filename]#boot1# не является частью загрузочных блоков footnote:[Файл /boot/boot1 существует, но он не записывается в начало раздела FreeBSD. Вместо этого он объединяется с boot2, формируя файл boot, который записывается в начало раздела FreeBSD и считывается во время загрузки.]. Вместо этого, единый полноценный файл [.filename]#boot# ([.filename]#/boot/boot#) в итоге записывается на диск. Этот файл представляет собой комбинацию [.filename]#boot1#, [.filename]#boot2# и `Boot Extender` (или BTX). Этот единый файл превышает размер одного сектора (больше 512 байт). К счастью, [.filename]#boot1# занимает _ровно_ первые 512 байт этого файла, поэтому, когда [.filename]#boot0# загружает первый сектор раздела FreeBSD (512 байт), он фактически загружает [.filename]#boot1# и передает ему управление. + +Основная задача [.filename]#boot1# — загрузить следующий этап загрузки. Этот следующий этап несколько сложнее. Он состоит из сервера под названием "Boot Extender" (BTX) и клиента под названием [.filename]#boot2#. Как мы увидим, последний этап загрузки, [.filename]#loader#, также является клиентом сервера BTX. + +Давайте теперь подробно рассмотрим, что именно делает [.filename]#boot1#, начиная, как мы это делали для [.filename]#boot0#, с точки входа: + +[.programlisting] +.... +start: + jmp main +.... + +.[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-entry]] +Точка входа `start` просто переходит через специальную область данных к метке `main`, которая, в свою очередь, выглядит следующим образом: + +[.programlisting] +.... +main: + cld # String ops inc + xor %cx,%cx # Zero + mov %cx,%es # Address + mov %cx,%ds # data + mov %cx,%ss # Set up + mov $start,%sp # stack + mov %sp,%si # Source + mov $MEM_REL,%di # Destination + incb %ch # Word count + rep # Copy + movsw # code +.... + +.[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-main]] +Как и [.filename]#boot0#, этот код перемещает [.filename]#boot1#, на этот раз по адресу `0x700`. Однако, в отличие от [.filename]#boot0#, он не переходит туда. [.filename]#boot1# скомпонован для выполнения по адресу `0x7c00`, фактически там, куда он был изначально загружен. Причина этого перемещения будет рассмотрена далее. + +Далее идет цикл, который ищет слайс FreeBSD. Хотя [.filename]#boot0# загрузил [.filename]#boot1# из слайса FreeBSD, ему не была передана информация об этом footnote:[На самом деле мы передали указатель на адрес слайса в регистре %si. Однако boot1 не предполагает, что он был загружен boot0 (возможно, его загрузил другой MBR и не передал эту информацию), поэтому он ничего не предполагает.], поэтому [.filename]#boot1# должен повторно просканировать таблицу разделов, чтобы найти начало слайса FreeBSD. Для этого он перечитывает MBR: + +[.programlisting] +.... + mov $part4,%si # Partition + cmpb $0x80,%dl # Hard drive? + jb main.4 # No + movb $0x1,%dh # Block count + callw nread # Read MBR +.... + +.[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-find-freebsd]] +В приведённом выше коде регистр `%dl` содержит информацию о загрузочном устройстве. Эти данные передаются BIOS и сохраняются MBR. Числа `0x80` и выше указывают на то, что мы имеем дело с жёстким диском, поэтому вызывается `nread`, где считывается MBR. Аргументы для `nread` передаются через `%si` и `%dh`. Адрес памяти по метке `part4` копируется в `%si`. Этот адрес памяти содержит "фальшивый раздел", который будет использован `nread`. Ниже приведены данные фальшивого раздела: + +[.programlisting] +.... + part4: + .byte 0x80, 0x00, 0x01, 0x00 + .byte 0xa5, 0xfe, 0xff, 0xff + .byte 0x00, 0x00, 0x00, 0x00 + .byte 0x50, 0xc3, 0x00, 0x00 +.... + +.[.filename]#stand/i386/boot2/boot1.S# [[boot-boot2-make-fake-partition]] +В частности, LBA для этой фиктивной раздела жестко закодирован как ноль. Это используется как аргумент для BIOS при чтении абсолютного сектора один с жесткого диска. Альтернативно, может использоваться адресация CHS. В этом случае, фиктивный раздел содержит цилиндр 0, головку 0 и сектор 1, что эквивалентно абсолютному сектору один. + +Продолжим, рассмотрев `nread`: + +[.programlisting] +.... +nread: + mov $MEM_BUF,%bx # Transfer buffer + mov 0x8(%si),%ax # Get + mov 0xa(%si),%cx # LBA + push %cs # Read from + callw xread.1 # disk + jnc return # If success, return +.... + +.[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-nread]] +Напомним, что `%si` указывает на поддельный раздел. Слово footnote:[В контексте 16-битного реального режима слово — это 2 байта.] по смещению `0x8` копируется в регистр `%ax`, а слово по смещению `0xa` — в `%cx`. BIOS интерпретирует их как младшее 4-байтовое значение, обозначающее LBA для чтения (старшие четыре байта предполагаются нулевыми). Регистр `%bx` содержит адрес памяти, куда будет загружен MBR. Инструкция, помещающая `%cs` в стек, очень интересна. В данном контексте она ничего не делает. Однако, как мы скоро увидим, [.filename]#boot2# в сочетании с сервером BTX также использует `xread.1`. Этот механизм будет рассмотрен в следующем разделе. + +Код в `xread.1` далее вызывает функцию `read`, которая фактически обращается к BIOS с запросом на чтение сектора диска: + +[.programlisting] +.... +xread.1: + pushl $0x0 # absolute + push %cx # block + push %ax # number + push %es # Address of + push %bx # transfer buffer + xor %ax,%ax # Number of + movb %dh,%al # blocks to + push %ax # transfer + push $0x10 # Size of packet + mov %sp,%bp # Packet pointer + callw read # Read from disk + lea 0x10(%bp),%sp # Clear stack + lret # To far caller +.... + +.[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-xread1]] +Обратите внимание на длинную инструкцию возврата в конце этого блока. Эта инструкция извлекает регистр `%cs`, помещённый в стек `nread`, и возвращает управление. В конце `nread` также возвращает управление. + +С загрузкой MBR в память начинается фактический цикл поиска слайса FreeBSD: + +[.programlisting] +.... + mov $0x1,%cx # Two passes +main.1: + mov $MEM_BUF+PRT_OFF,%si # Partition table + movb $0x1,%dh # Partition +main.2: + cmpb $PRT_BSD,0x4(%si) # Our partition type? + jne main.3 # No + jcxz main.5 # If second pass + testb $0x80,(%si) # Active? + jnz main.5 # Yes +main.3: + add $0x10,%si # Next entry + incb %dh # Partition + cmpb $0x1+PRT_NUM,%dh # In table? + jb main.2 # Yes + dec %cx # Do two + jcxz main.1 # passes +.... + +.[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-find-part]] +Если обнаружен слайс FreeBSD, выполнение продолжается на метке `main.5`. Обратите внимание, что при обнаружении слайса FreeBSD `%si` указывает на соответствующую запись в таблице разделов, а `%dh` содержит номер раздела. Мы предполагаем, что слайс FreeBSD найден, поэтому продолжаем выполнение на метке `main.5`: + +[.programlisting] +.... +main.5: + mov %dx,MEM_ARG # Save args + movb $NSECT,%dh # Sector count + callw nread # Read disk + mov $MEM_BTX,%bx # BTX + mov 0xa(%bx),%si # Get BTX length and set + add %bx,%si # %si to start of boot2.bin + mov $MEM_USR+SIZ_PAG*2,%di # Client page 2 + mov $MEM_BTX+(NSECT-1)*SIZ_SEC,%cx # Byte + sub %si,%cx # count + rep # Relocate + movsb # client +.... + +.[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-main5]] +Напомним, что в данный момент регистр `%si` указывает на запись среза FreeBSD в таблице разделов MBR, поэтому вызов `nread` фактически прочитает секторы в начале этого раздела. Аргумент, переданный в регистре `%dh`, указывает `nread` прочитать 16 секторов диска. Напомним, что первые 512 байт, или первый сектор слайса FreeBSD, совпадает с программой [.filename]#boot1#. Также напомним, что файл, записанный в начало слайса FreeBSD, это не [.filename]#/boot/boot1#, а [.filename]#/boot/boot#. Давайте посмотрим на размер этих файлов в файловой системе: + +[source, bash] +.... +-r--r--r-- 1 root wheel 512B Jan 8 00:15 /boot/boot0 +-r--r--r-- 1 root wheel 512B Jan 8 00:15 /boot/boot1 +-r--r--r-- 1 root wheel 7.5K Jan 8 00:15 /boot/boot2 +-r--r--r-- 1 root wheel 8.0K Jan 8 00:15 /boot/boot +.... + +Оба файла [.filename]#boot0# и [.filename]#boot1# имеют размер 512 байт каждый, поэтому они занимают _ровно_ один сектор диска. [.filename]#boot2# значительно больше, так как содержит как сервер BTX, так и клиент [.filename]#boot2#. Наконец, файл под названием просто [.filename]#boot# на 512 байт больше, чем [.filename]#boot2#. Этот файл представляет собой объединение [.filename]#boot1# и [.filename]#boot2#. Как уже отмечалось, [.filename]#boot0# записывается в самый первый сектор диска (MBR), а [.filename]#boot# записывается в первый сектор раздела FreeBSD; [.filename]#boot1# и [.filename]#boot2# _не_ записываются на диск. Команда, используемая для объединения [.filename]#boot1# и [.filename]#boot2# в единый файл [.filename]#boot#, выглядит просто как `cat boot1 boot2 > boot`. + +Итак, [.filename]#boot1# занимает ровно первые 512 байт [.filename]#boot#, и, поскольку [.filename]#boot# записывается в первый сектор слайса FreeBSD, [.filename]#boot1# полностью помещается в этот первый сектор. Когда `nread` читает первые 16 секторов слайса FreeBSD, он фактически читает весь файл [.filename]#boot# footnote:[512*16=8192 байта, ровно размер boot]. Более подробно о том, как [.filename]#boot# формируется из [.filename]#boot1# и [.filename]#boot2#, мы увидим в следующем разделе. + +Напомним, что `nread` использует адрес памяти `0x8c00` в качестве буфера передачи для хранения прочитанных секторов. Этот адрес выбран не случайно. Действительно, поскольку [.filename]#boot1# принадлежит первым 512 байтам, он оказывается в диапазоне адресов `0x8c00`-`0x8dff`. Следующие 512 байт (диапазон `0x8e00`-`0x8fff`) используются для хранения _bsdlabel_ footnote:[Исторически известной как disklabel. Если вам когда-либо было интересно, где FreeBSD хранит эту информацию, она находится в этой области — см. man:bsdlabel[8]]. + +Начиная с адреса `0x9000` находится начало сервера BTX, и сразу за ним следует клиент [.filename]#boot2#. Сервер BTX действует как ядро и выполняется в защищённом режиме с наивысшим уровнем привилегий. В отличие от этого, клиенты BTX (например, [.filename]#boot2#) выполняются в пользовательском режиме. Мы увидим, как это реализовано, в следующем разделе. Код после вызова `nread` находит начало [.filename]#boot2# в буфере памяти и копирует его по адресу `0xc000`. Это связано с тем, что сервер BTX размещает [.filename]#boot2# для выполнения в сегменте, начинающемся с `0xa000`. Мы подробно рассмотрим это в следующем разделе. + +Последний блок кода в [.filename]#boot1# разрешает доступ к памяти выше 1MB footnote:[Это необходимо по историческим причинам. Заинтересованные читатели могут обратиться к .] и завершается переходом к начальной точке сервера BTX: + +[.programlisting] +.... +seta20: + cli # Disable interrupts +seta20.1: + dec %cx # Timeout? + jz seta20.3 # Yes + + inb $0x64,%al # Get status + testb $0x2,%al # Busy? + jnz seta20.1 # Yes + movb $0xd1,%al # Command: Write + outb %al,$0x64 # output port +seta20.2: + inb $0x64,%al # Get status + testb $0x2,%al # Busy? + jnz seta20.2 # Yes + movb $0xdf,%al # Enable + outb %al,$0x60 # A20 +seta20.3: + sti # Enable interrupts + jmp 0x9010 # Start BTX +.... + +.[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-seta20]] +Обратите внимание, что непосредственно перед переходом прерывания включаются. + +[[btx-server]] +== Сервер BTX + +Далее в нашей последовательности загрузки идёт сервер BTX. Давайте быстро вспомним, как мы сюда попали: + +* BIOS загружает абсолютный сектор один (MBR или [.filename]#boot0#) по адресу `0x7c00` и переходит туда. +* [.filename]#boot0# перемещает себя по адресу `0x600`, по которому он был слинкован для выполнения, и переходит туда. Затем он читает первый сектор среза FreeBSD (который содержит [.filename]#boot1#) в адрес `0x7c00` и переходит туда. +* [.filename]#boot1# загружает первые 16 секторов среза FreeBSD по адресу `0x8c00`. Эти 16 секторов, или 8192 байта, представляют собой весь файл [.filename]#boot#. Файл является объединением [.filename]#boot1# и [.filename]#boot2#. [.filename]#boot2#, в свою очередь, содержит сервер BTX и клиент [.filename]#boot2#. Наконец, выполняется переход по адресу `0x9010`, точке входа сервера BTX. + +Прежде чем изучать сервер BTX подробно, давайте рассмотрим, как создается единый, всеобъемлющий файл [.filename]#boot#. Способ сборки [.filename]#boot# определен в его [.filename]#Makefile# ([.filename]#stand/i386/boot2/Makefile#). Рассмотрим правило, которое создает файл [.filename]#boot#: + +[.programlisting] +.... + boot: boot1 boot2 + cat boot1 boot2 > boot +.... + +.[.filename]#stand/i386/boot2/Makefile# [[boot-boot1-make-boot]] +Это говорит нам, что [.filename]#boot1# и [.filename]#boot2# необходимы, и правило просто объединяет их для создания одного файла с именем [.filename]#boot#. Правила для создания [.filename]#boot1# также довольно просты: + +[.programlisting] +.... + boot1: boot1.out + ${OBJCOPY} -S -O binary boot1.out ${.TARGET} + + boot1.out: boot1.o + ${LD} ${LD_FLAGS} -e start --defsym ORG=${ORG1} -T ${LDSCRIPT} -o ${.TARGET} boot1.o +.... + +.[.filename]#stand/i386/boot2/Makefile# [[boot-boot1-make-boot1]] +Для применения правила создания [.filename]#boot1# необходимо собрать [.filename]#boot1.out#. Это, в свою очередь, зависит от наличия [.filename]#boot1.o#. Последний файл является результатом ассемблирования нашего знакомого [.filename]#boot1.S# без компоновки. Теперь применяется правило создания [.filename]#boot1.out#. Оно указывает, что [.filename]#boot1.o# должен быть скомпонован с точкой входа `start` и начальным адресом `0x7c00`. Наконец, [.filename]#boot1# создается из [.filename]#boot1.out# применением соответствующего правила. Это команда [.filename]#objcopy#, применяемая к [.filename]#boot1.out#. Обратите внимание на флаги, передаваемые [.filename]#objcopy#: `-S` указывает на удаление всей информации о перемещении и символов; `-O binary` указывает формат вывода, то есть простой, неформатированный двоичный файл. + +Имея [.filename]#boot1#, давайте посмотрим, как устроен [.filename]#boot2#: + +[.programlisting] +.... + boot2: boot2.ld + @set -- `ls -l ${.ALLSRC}`; x=$$((${BOOT2SIZE}-$$5)); \ + echo "$$x bytes available"; test $$x -ge 0 + ${DD} if=${.ALLSRC} of=${.TARGET} bs=${BOOT2SIZE} conv=sync + + boot2.ld: boot2.ldr boot2.bin ${BTXKERN} + btxld -v -E ${ORG2} -f bin -b ${BTXKERN} -l boot2.ldr \ + -o ${.TARGET} -P 1 boot2.bin + + boot2.ldr: + ${DD} if=/dev/zero of=${.TARGET} bs=512 count=1 + + boot2.bin: boot2.out + ${OBJCOPY} -S -O binary boot2.out ${.TARGET} + + boot2.out: ${BTXCRT} boot2.o sio.o ashldi3.o + ${LD} ${LD_FLAGS} --defsym ORG=${ORG2} -T ${LDSCRIPT} -o ${.TARGET} ${.ALLSRC} + + boot2.h: boot1.out + ${NM} -t d ${.ALLSRC} | awk '/([0-9])+ T xread/ \ + { x = $$1 - ORG1; \ + printf("#define XREADORG %#x\n", REL1 + x) }' \ + ORG1=`printf "%d" ${ORG1}` \ + REL1=`printf "%d" ${REL1}` > ${.TARGET} +.... + +.[.filename]#stand/i386/boot2/Makefile# [[boot-boot1-make-boot2]] +Механизм сборки [.filename]#boot2# гораздо сложнее. Отметим наиболее важные моменты. Список зависимостей выглядит следующим образом: + +[.programlisting] +.... + boot2: boot2.ld + boot2.ld: boot2.ldr boot2.bin ${BTXDIR} + boot2.bin: boot2.out + boot2.out: ${BTXDIR} boot2.o sio.o ashldi3.o + boot2.h: boot1.out +.... + +.[.filename]#stand/i386/boot2/Makefile# [[boot-boot1-make-boot2-more]] +Отметим, что изначально файл заголовка [.filename]#boot2.h# отсутствует, но его создание зависит от [.filename]#boot1.out#, который у нас уже есть. Правило его создания немного лаконично, но важно то, что результат, [.filename]#boot2.h#, выглядит примерно так: + +[.programlisting] +.... +#define XREADORG 0x725 +.... + +.[.filename]#stand/i386/boot2/boot2.h# [[boot-boot1-make-boot2h]] +Напомним, что [.filename]#boot1# был перемещён (т.е. скопирован из `0x7c00` в `0x700`). Это перемещение теперь обретает смысл, потому что, как мы увидим, сервер BTX освобождает часть памяти, включая область, куда [.filename]#boot1# был изначально загружен. Однако серверу BTX необходим доступ к функции `xread` из [.filename]#boot1#; согласно выводу [.filename]#boot2.h#, эта функция находится по адресу `0x725`. Действительно, сервер BTX использует функцию `xread` из перемещённого кода [.filename]#boot1#. Теперь эта функция доступна из клиента [.filename]#boot2#. + +Следующее правило указывает компоновщику на необходимость связать различные файлы ([.filename]#ashldi3.o#, [.filename]#boot2.o# и [.filename]#sio.o#). Обратите внимание, что выходной файл [.filename]#boot2.out# компонуется для выполнения по адресу `0x2000` (${ORG2}). Напомним, что [.filename]#boot2# будет выполняться в пользовательском режиме внутри специального пользовательского сегмента, созданного сервером BTX. Этот сегмент начинается с адреса `0xa000`. Также помните, что часть [.filename]#boot2# в [.filename]#boot# была скопирована по адресу `0xc000`, то есть со смещением `0x2000` от начала пользовательского сегмента, поэтому [.filename]#boot2# будет работать корректно при передаче управления на него. Далее, [.filename]#boot2.bin# создается из [.filename]#boot2.out# путем удаления символов и информации о формате; boot2.bin представляет собой _сырой_ бинарный файл. Теперь обратите внимание, что файл [.filename]#boot2.ldr# создается как 512-байтный файл, заполненный нулями. Это пространство зарезервировано для bsdlabel. + +Теперь, когда у нас есть файлы [.filename]#boot1#, [.filename]#boot2.bin# и [.filename]#boot2.ldr#, осталось только добавить сервер BTX перед созданием универсального файла [.filename]#boot#. Сервер BTX находится в [.filename]#stand/i386/btx/btx#; у него есть собственный [.filename]#Makefile# со своим набором правил для сборки. Важно отметить, что он также компилируется как _сырой_ бинарный файл и линкуется для выполнения по адресу `0x9000`. Подробности можно найти в [.filename]#stand/i386/btx/btx/Makefile#. + +Имея файлы, составляющие программу [.filename]#boot#, последним шагом является их _объединение_. Это выполняется специальной программой под названием [.filename]#btxld# (исходный код расположен в [.filename]#/usr/src/usr.sbin/btxld#). Некоторые аргументы этой программы включают имя выходного файла ([.filename]#boot#), его точку входа (`0x2000`) и формат файла (бинарный). Различные файлы окончательно объединяются этой утилитой в файл [.filename]#boot#, который состоит из [.filename]#boot1#, [.filename]#boot2#, `bsdlabel` и сервера BTX. Этот файл, занимающий ровно 16 секторов или 8192 байта, записывается в начало раздела FreeBSD во время установки. Теперь перейдем к изучению программы сервера BTX. + +Сервер BTX подготавливает простое окружение и переключается из 16-битного реального режима в 32-битный защищённый режим, непосредственно перед передачей управления клиенту. Это включает инициализацию и обновление следующих структур данных: + +* Изменяет `Таблицу Векторов Прерываний (IVT)`. IVT предоставляет обработчики исключений и прерываний для кода в Реальном Режиме. +* Создается `Таблица дескрипторов прерываний (IDT)`. В ней предусмотрены записи для исключений процессора, аппаратных прерываний, двух системных вызовов и интерфейса V86. IDT предоставляет обработчики исключений и прерываний для кода в защищенном режиме. +* Создается `Сегмент состояния задачи (TSS)`. Это необходимо, потому что процессор работает на _наименее_ привилегированном уровне при выполнении клиента ([.filename]#boot2#), но на _наиболее_ привилегированном уровне при выполнении сервера BTX. +* Устанавливается GDT (Глобальная Таблица Дескрипторов). Создаются записи (дескрипторы) для кода и данных супервизора, кода и данных пользователя, а также кода и данных реального режима. footnote:[Код и данные реального режима необходимы при переключении обратно в реальный режим из защищённого режима, как указано в руководствах Intel.] + +Приступим к изучению фактической реализации. Напомним, что [.filename]#boot1# выполнил переход на адрес `0x9010` — точку входа сервера BTX. Прежде чем изучать выполнение программы там, обратите внимание, что сервер BTX имеет специальный заголовок в диапазоне адресов `0x9000-0x900f`, непосредственно перед точкой входа. Этот заголовок определён следующим образом: + +[.programlisting] +.... +start: # Start of code +/* + * BTX header. + */ +btx_hdr: .byte 0xeb # Machine ID + .byte 0xe # Header size + .ascii "BTX" # Magic + .byte 0x1 # Major version + .byte 0x2 # Minor version + .byte BTX_FLAGS # Flags + .word PAG_CNT-MEM_ORG>>0xc # Paging control + .word break-start # Text size + .long 0x0 # Entry address +.... + +.[.filename]#stand/i386/btx/btx/btx.S# [[btx-header]] +Обратите внимание, что первые два байта — это `0xeb` и `0xe`. В архитектуре IA-32 эти два байта интерпретируются как относительный переход за заголовок к точке входа, поэтому теоретически [.filename]#boot1# мог бы перейти сюда (адрес `0x9000`) вместо адреса `0x9010`. Обратите внимание, что последнее поле в заголовке BTX — это указатель на точку входа клиента ([.filename]#boot2#)b2. Это поле исправляется во время компоновки. + +Сразу после заголовка следует точка входа сервера BTX: + +[.programlisting] +.... +/* + * Initialization routine. + */ +init: cli # Disable interrupts + xor %ax,%ax # Zero/segment + mov %ax,%ss # Set up + mov $MEM_ESP0,%sp # stack + mov %ax,%es # Address + mov %ax,%ds # data + pushl $0x2 # Clear + popfl # flags +.... + +.[.filename]#stand/i386/btx/btx/btx.S# [[btx-init]] +Этот код отключает прерывания, устанавливает рабочий стек (начиная с адреса `0x1800`) и очищает флаги в регистре EFLAGS. Обратите внимание, что инструкция `popfl` извлекает двойное слово (4 байта) из стека и помещает его в регистр EFLAGS. Поскольку извлекаемое значение фактически равно `2`, регистр EFLAGS эффективно очищается (IA-32 требует, чтобы бит 2 регистра EFLAGS всегда был равен 1). + +Следующий блок кода очищает (устанавливает в `0`) диапазон памяти `0x5e00-0x8fff`. В этом диапазоне будут созданы различные структуры данных: + +[.programlisting] +.... +/* + * Initialize memory. + */ + mov $MEM_IDT,%di # Memory to initialize + mov $(MEM_ORG-MEM_IDT)/2,%cx # Words to zero + rep # Zero-fill + stosw # memory +.... + +.[.filename]#stand/i386/btx/btx/btx.S# [[btx-clear-mem]] +Напомним, что [.filename]#boot1# изначально загружался по адресу `0x7c00`, поэтому при такой инициализации памяти эта копия фактически исчезла. Однако также напомним, что [.filename]#boot1# был перемещён на адрес `0x700`, поэтому _эта_ копия всё ещё находится в памяти, и сервер BTX будет её использовать. + +Далее обновляется таблица векторов прерываний (IVT) в реальном режиме. IVT представляет собой массив пар сегмент/смещение для обработчиков исключений и прерываний. BIOS обычно сопоставляет аппаратные прерывания с векторами прерываний `0x8`–`0xf` и `0x70`–`0x77`, но, как будет показано, программируемый контроллер прерываний 8259A, микросхема, управляющая фактическим сопоставлением аппаратных прерываний с векторами прерываний, программируется для переназначения этих векторов прерываний с `0x8`–`0xf` на `0x20`–`0x27` и с `0x70`–`0x77` на `0x28`–`0x2f`. Таким образом, обработчики прерываний предоставляются для векторов прерываний `0x20`–`0x2f`. Причина, по которой обработчики, предоставляемые BIOS, не используются напрямую, заключается в том, что они работают в 16-битном реальном режиме, но не в 32-битном защищённом режиме. Вскоре будет выполнен переход в 32-битный защищённый режим. Однако сервер BTX настраивает механизм для эффективного использования обработчиков, предоставляемых BIOS: + +[.programlisting] +.... +/* + * Update real mode IDT for reflecting hardware interrupts. + */ + mov $intr20,%bx # Address first handler + mov $0x10,%cx # Number of handlers + mov $0x20*4,%di # First real mode IDT entry +init.0: mov %bx,(%di) # Store IP + inc %di # Address next + inc %di # entry + stosw # Store CS + add $4,%bx # Next handler + loop init.0 # Next IRQ +.... + +.[.filename]#stand/i386/btx/btx/btx.S# [[btx-ivt]] +Следующий блок создает IDT (таблицу дескрипторов прерываний). IDT в защищенном режиме аналогична IVT в реальном режиме. То есть, IDT описывает различные обработчики исключений и прерываний, используемые, когда процессор работает в защищенном режиме. По сути, она также состоит из массива пар сегмент/смещение, хотя структура несколько сложнее, поскольку сегменты в защищенном режиме отличаются от реального режима, и применяются различные механизмы защиты: + +[.programlisting] +.... +/* + * Create IDT. + */ + mov $MEM_IDT,%di # IDT's address + mov $idtctl,%si # Control string +init.1: lodsb # Get entry + cbw # count + xchg %ax,%cx # as word + jcxz init.4 # If done + lodsb # Get segment + xchg %ax,%dx # P:DPL:type + lodsw # Get control + xchg %ax,%bx # set + lodsw # Get handler offset + mov $SEL_SCODE,%dh # Segment selector +init.2: shr %bx # Handle this int? + jnc init.3 # No + mov %ax,(%di) # Set handler offset + mov %dh,0x2(%di) # and selector + mov %dl,0x5(%di) # Set P:DPL:type + add $0x4,%ax # Next handler +init.3: lea 0x8(%di),%di # Next entry + loop init.2 # Till set done + jmp init.1 # Continue +.... + +.[.filename]#stand/i386/btx/btx/btx.S# [[btx-idt]] +Каждая запись в `IDT` имеет длину 8 байт. Помимо информации о сегменте/смещении, они также описывают тип сегмента, уровень привилегий и присутствует ли сегмент в памяти. Структура организована так, что векторы прерываний от `0` до `0xf` (исключения) обрабатываются функцией `intx00`; вектор `0x10` (также исключение) обрабатывается `intx10`; аппаратные прерывания, которые позже настраиваются начиная с вектора `0x20` и до вектора `0x2f`, обрабатываются функцией `intx20`. Наконец, вектор прерывания `0x30`, используемый для системных вызовов, обрабатывается `intx30`, а векторы `0x31` и `0x32` обрабатываются `intx31`. Необходимо отметить, что только дескрипторы для векторов прерываний `0x30`, `0x31` и `0x32` имеют уровень привилегий 3, такой же, как у клиента [.filename]#boot2#, что означает, что клиент может выполнить программно-генерируемое прерывание к этим векторам через инструкцию `int` без ошибки (это способ, которым [.filename]#boot2# использует сервисы, предоставляемые сервером BTX). Также обратите внимание, что _только_ программно-генерируемые прерывания защищены от кода, выполняющегося на более низких уровнях привилегий. Аппаратно-генерируемые прерывания и исключения, генерируемые процессором, _всегда_ обрабатываются корректно, независимо от фактических привилегий. + +Следующий шаг — инициализация TSS (сегмента состояния задачи). TSS — это аппаратная функция, которая помогает операционной системе или исполнительному ПО реализовать многозадачность через абстракцию процессов. Архитектура IA-32 требует создания и использования _как минимум_ одного TSS, если используются механизмы многозадачности или определены различные уровни привилегий. Поскольку клиент [.filename]#boot2# выполняется на уровне привилегий 3, а сервер BTX работает на уровне привилегий 0, необходимо определить TSS: + +[.programlisting] +.... +/* + * Initialize TSS. + */ +init.4: movb $_ESP0H,TSS_ESP0+1(%di) # Set ESP0 + movb $SEL_SDATA,TSS_SS0(%di) # Set SS0 + movb $_TSSIO,TSS_MAP(%di) # Set I/O bit map base +.... + +.[.filename]#stand/i386/btx/btx/btx.S# [[btx-tss]] +Обратите внимание, что в TSS указано значение для указателя стека и сегмента стека уровня привилегий 0. Это необходимо, потому что если прерывание или исключение получено во время выполнения [.filename]#boot2# на уровне привилегий 3, процессор автоматически переключается на уровень привилегий 0, поэтому требуется новый рабочий стек. Наконец, полю базового адреса карты ввода-вывода TSS присваивается значение, которое представляет собой 16-битное смещение от начала TSS до битовой карты разрешений ввода-вывода и битовой карты перенаправления прерываний. + +После создания IDT и TSS процессор готов к переходу в защищённый режим. Это выполняется в следующем блоке: + +[.programlisting] +.... +/* + * Bring up the system. + */ + mov $0x2820,%bx # Set protected mode + callw setpic # IRQ offsets + lidt idtdesc # Set IDT + lgdt gdtdesc # Set GDT + mov %cr0,%eax # Switch to protected + inc %ax # mode + mov %eax,%cr0 # + ljmp $SEL_SCODE,$init.8 # To 32-bit code + .code32 +init.8: xorl %ecx,%ecx # Zero + movb $SEL_SDATA,%cl # To 32-bit + movw %cx,%ss # stack +.... + +.[.filename]#stand/i386/btx/btx/btx.S# [[btx-prot]] +Сначала вызывается `setpic` для программирования 8259A PIC (программируемого контроллера прерываний). Этот чип подключен к нескольким источникам аппаратных прерываний. При получении прерывания от устройства он сигнализирует процессору соответствующим вектором прерывания. Это можно настроить так, чтобы определенные прерывания были связаны с конкретными векторами прерываний, как объяснялось ранее. Затем регистры IDTR (Interrupt Descriptor Table Register) и GDTR (Global Descriptor Table Register) загружаются инструкциями `lidt` и `lgdt` соответственно. Эти регистры загружаются базовым адресом и предельным адресом для IDT и GDT. Следующие три инструкции устанавливают бит Protection Enable (PE) в регистре `%cr0`. Это фактически переключает процессор в 32-битный защищенный режим. Затем выполняется дальний переход на `init.8` с использованием селектора сегмента SEL_SCODE, который выбирает сегмент кода супервизора (Supervisor Code Segment). После этого перехода процессор фактически работает на уровне CPL 0 — наиболее привилегированном уровне. Наконец, для стека выбирается сегмент данных супервизора (Supervisor Data Segment) путем присвоения селектора сегмента SEL_SDATA регистру `%ss`. Этот сегмент данных также имеет уровень привилегий `0`. + +Наш последний блок кода отвечает за загрузку TR (Регистра Задач) с селектором сегмента для TSS, который мы создали ранее, и настройку окружения пользовательского режима перед передачей управления исполнения клиенту [.filename]#boot2#. + +[.programlisting] +.... +/* + * Launch user task. + */ + movb $SEL_TSS,%cl # Set task + ltr %cx # register + movl $MEM_USR,%edx # User base address + movzwl %ss:BDA_MEM,%eax # Get free memory + shll $0xa,%eax # To bytes + subl $ARGSPACE,%eax # Less arg space + subl %edx,%eax # Less base + movb $SEL_UDATA,%cl # User data selector + pushl %ecx # Set SS + pushl %eax # Set ESP + push $0x202 # Set flags (IF set) + push $SEL_UCODE # Set CS + pushl btx_hdr+0xc # Set EIP + pushl %ecx # Set GS + pushl %ecx # Set FS + pushl %ecx # Set DS + pushl %ecx # Set ES + pushl %edx # Set EAX + movb $0x7,%cl # Set remaining +init.9: push $0x0 # general + loop init.9 # registers +#ifdef BTX_SERIAL + call sio_init # setup the serial console +#endif + popa # and initialize + popl %es # Initialize + popl %ds # user + popl %fs # segment + popl %gs # registers + iret # To user mode +.... + +.[.filename]#stand/i386/btx/btx/btx.S# [[btx-end]] +Обратите внимание, что среда клиента включает селектор сегмента стека и указатель стека (регистры `%ss` и `%esp`). Действительно, как только TR загружается соответствующим селектором сегмента стека (инструкция `ltr`), указатель стека вычисляется и помещается в стек вместе с селектором сегмента стека. Затем значение `0x202` помещается в стек; это значение, которое EFLAGS получит при передаче управления клиенту. Также в стек помещаются селектор сегмента кода пользовательского режима и точка входа клиента. Напомним, что эта точка входа прописывается в заголовке BTX во время компоновки. Наконец, селекторы сегментов (хранящиеся в регистре `%ecx`) для регистров сегментов `%gs, %fs, %ds и %es` помещаются в стек вместе со значением из `%edx` (`0xa000`). Примите во внимание эти значения, помещенные в стек (они скоро будут извлечены). Затем значения для оставшихся регистров общего назначения также помещаются в стек (обратите внимание на цикл `loop`, который помещает значение `0` семь раз). Теперь начнётся извлечение значений из стека. Сначала инструкция `popa` извлекает из стека последние семь помещённых значений. Они сохраняются в регистрах общего назначения в порядке `%edi, %esi, %ebp, %ebx, %edx, %ecx, %eax`. Затем различные селекторы сегментов, помещённые в стек, извлекаются в соответствующие регистры сегментов. В стеке остаются ещё пять значений. Они извлекаются при выполнении инструкции `iret`. Эта инструкция сначала извлекает значение, которое было помещено из заголовка BTX. Это значение является указателем на точку входа [.filename]#boot2#. Оно помещается в регистр `%eip` — регистр указателя инструкций. Затем селектор сегмента кода пользователя извлекается и копируется в регистр `%cs`. Помните, что уровень привилегий этого сегмента — 3, наименее привилегированный уровень. Это означает, что мы должны предоставить значения для стека этого уровня привилегий. Именно поэтому процессор, помимо дальнейшего извлечения значения для регистра EFLAGS, выполняет ещё два извлечения из стека. Эти значения попадают в указатель стека (`%esp`) и сегмент стека (`%ss`). Теперь выполнение продолжается с точки входа ``boot0``. + +Важно отметить, как определяется сегмент пользовательского кода. _Базовый адрес_ этого сегмента установлен на `0xa000`. Это означает, что адреса памяти кода являются _относительными_ к адресу 0xa000; если код, который выполняется, извлекается из адреса `0x2000`, _фактический_ адрес в памяти будет `0xa000+0x2000=0xc000`. + +[[boot2]] +== Этап загрузки boot2 + +`boot2` определяет важную структуру, `struct bootinfo`. Эта структура инициализируется `boot2` и передается загрузчику, а затем ядру. Некоторые узлы этой структуры устанавливаются `boot2`, остальные — загрузчиком. Эта структура, среди прочей информации, содержит имя файла ядра, геометрию жесткого диска в BIOS, номер диска в BIOS для загрузочного устройства, доступную физическую память, указатель `envp` и т.д. Ее определение выглядит так: + +[.programlisting] +.... +/usr/include/machine/bootinfo.h: +struct bootinfo { + u_int32_t bi_version; + u_int32_t bi_kernelname; /* represents a char * */ + u_int32_t bi_nfs_diskless; /* struct nfs_diskless * */ + /* End of fields that are always present. */ +#define bi_endcommon bi_n_bios_used + u_int32_t bi_n_bios_used; + u_int32_t bi_bios_geom[N_BIOS_GEOM]; + u_int32_t bi_size; + u_int8_t bi_memsizes_valid; + u_int8_t bi_bios_dev; /* bootdev BIOS unit number */ + u_int8_t bi_pad[2]; + u_int32_t bi_basemem; + u_int32_t bi_extmem; + u_int32_t bi_symtab; /* struct symtab * */ + u_int32_t bi_esymtab; /* struct symtab * */ + /* Items below only from advanced bootloader */ + u_int32_t bi_kernend; /* end of kernel space */ + u_int32_t bi_envp; /* environment */ + u_int32_t bi_modulep; /* preloaded modules */ +}; +.... + +`boot2` входит в бесконечный цикл, ожидая ввода пользователя, затем вызывает `load()`. Если пользователь ничего не нажимает, цикл прерывается по таймауту, и `load()` загружает файл по умолчанию ([.filename]#/boot/loader#). Функции `ino_t lookup(char *filename)` и `int xfsread(ino_t inode, void *buf, size_t nbyte)` используются для чтения содержимого файла в память. [.filename]#/boot/loader# — это ELF-бинарный файл, но с заголовком ELF, перед которым добавлена структура `struct exec` из [.filename]#a.out#. `load()` анализирует ELF-заголовок загрузчика, загружает содержимое [.filename]#/boot/loader# в память и передаёт управление на точку входа загрузчика: + +[.programlisting] +.... +stand/i386/boot2/boot2.c: + __exec((caddr_t)addr, RB_BOOTINFO | (opts & RBX_MASK), + MAKEBOOTDEV(dev_maj[dsk.type], dsk.slice, dsk.unit, dsk.part), + 0, 0, 0, VTOP(&bootinfo)); +.... + +[[boot-loader]] +== Этап загрузчика (loader) + +Загрузчик также является клиентом BTX. Я не буду подробно описывать его здесь, существует исчерпывающая man-страница, написанная Майком Смитом: man:loader[8]. Основные механизмы и BTX были рассмотрены выше. + +Основная задача загрузчика — загрузить ядро. Когда ядро загружено в память, загрузчик вызывает его: + +[.programlisting] +.... +stand/common/boot.c: + /* Call the exec handler from the loader matching the kernel */ + file_formats[fp->f_loader]->l_exec(fp); +.... + +[[boot-kernel]] +== Инициализация ядра + +Давайте рассмотрим команду, которая компонует ядро. Это поможет определить точное местоположение, где загрузчик передает выполнение ядру. Это местоположение является фактической точкой входа ядра. Данная команда теперь исключена из [.filename]#sys/conf/Makefile.i386#. Интересующее нас содержимое можно найти в [.filename]#/usr/obj/usr/src/i386.i386/sys/GENERIC/#. + +[.programlisting] +.... +/usr/obj/usr/src/i386.i386/sys/GENERIC/kernel.meta: +ld -m elf_i386_fbsd -Bdynamic -T /usr/src/sys/conf/ldscript.i386 --build-id=sha1 --no-warn-mismatch \ +--warn-common --export-dynamic --dynamic-linker /red/herring -X -o kernel locore.o + +.... + +Вот несколько интересных наблюдений. Во-первых, ядро представляет собой динамически связанный бинарный файл ELF, но динамический компоновщик для ядра — это [.filename]#/red/herring#, что явно является фиктивным файлом. Во-вторых, взглянув на файл [.filename]#sys/conf/ldscript.i386#, можно понять, какие параметры ld используются при компиляции ядра. Читая первые несколько строк, видим, что строка + +[.programlisting] +.... +sys/conf/ldscript.i386: +ENTRY(btext) +.... + +говорит, что точка входа ядра — это символ `btext`. Этот символ определён в [.filename]#locore.s#: + +[.programlisting] +.... +sys/i386/i386/locore.s: + .text +/********************************************************************** + * + * This is where the bootblocks start us, set the ball rolling... + * + */ +NON_GPROF_ENTRY(btext) +.... + +Сначала регистр EFLAGS устанавливается в предопределённое значение 0x00000002. Затем инициализируются все сегментные регистры: + +[.programlisting] +.... +sys/i386/i386/locore.s: +/* Don't trust what the BIOS gives for eflags. */ + pushl $PSL_KERNEL + popfl + +/* + * Don't trust what the BIOS gives for %fs and %gs. Trust the bootstrap + * to set %cs, %ds, %es and %ss. + */ + mov %ds, %ax + mov %ax, %fs + mov %ax, %gs +.... + +btext вызывает подпрограммы `recover_bootinfo()` и `identify_cpu()`, которые также определены в [.filename]#locore.s#. Вот описание их функций: + +[.informaltable] +[cols="1,1", frame="none"] +|=== + +|`recover_bootinfo` +|Эта процедура разбирает параметры, переданные ядру при загрузке. +Ядро могло быть загружено тремя способами: загрузчиком (как описано выше), старыми загрузочными блоками диска или по старой процедуре загрузки без диска. +Эта функция определяет метод загрузки и сохраняет структуру `struct bootinfo` в памяти ядра. + +|`identify_cpu` +|Эта функция пытается определить, на каком процессоре она выполняется, сохраняя найденное значение в переменной `_cpu`. +|=== + +Следующие шаги включают активацию VME, если процессор поддерживает эту функцию: + +[.programlisting] +.... +sys/i386/i386/mpboot.s: + testl $CPUID_VME,%edx + jz 3f + orl $CR4_VME,%eax +3: movl %eax,%cr4 +.... + +Затем, включение подкачки: + +[.programlisting] +.... +sys/i386/i386/mpboot.s: +/* Now enable paging */ + movl IdlePTD_nopae, %eax + movl %eax,%cr3 /* load ptd addr into mmu */ + movl %cr0,%eax /* get control word */ + orl $CR0_PE|CR0_PG,%eax /* enable paging */ + movl %eax,%cr0 /* and let's page NOW! */ +.... + +Следующие три строки кода необходимы, потому что была установлена подкачка, поэтому требуется переход для продолжения выполнения в виртуализированном адресном пространстве: + +[.programlisting] +.... +sys/i386/i386/mpboot.s: + pushl $mp_begin /* jump to high mem */ + ret + +/* now running relocated at KERNBASE where the system is linked to run */ +mp_begin: /* now running relocated at KERNBASE */ +.... + +Функция `init386()` вызывается с указателем на первую свободную физическую страницу, после чего следует вызов `mi_startup()`. `init386` — это архитектурно-зависимая функция инициализации, а `mi_startup()` — архитектурно-независимая (префикс 'mi_' означает Machine Independent, то есть «независимая от машины»). Ядро никогда не возвращается из `mi_startup()`, и, вызывая её, завершает загрузку: + +[.programlisting] +.... +sys/i386/i386/locore.s: + pushl physfree /* value of first for init386(first) */ + call init386 /* wire 386 chip for unix operation */ + addl $4,%esp + movl %eax,%esp /* Switch to true top of stack. */ + call mi_startup /* autoconfiguration, mountroot etc */ + /* NOTREACHED */ +.... + +=== `init386()` + +`init386()` определена в [.filename]#sys/i386/i386/machdep.c# и выполняет низкоуровневую инициализацию, специфичную для чипа i386. Переход в защищённый режим был выполнен загрузчиком. Загрузчик создал самую первую задачу, в которой ядро продолжает работать. Прежде чем рассматривать код, рассмотрим задачи, которые процессор должен выполнить для инициализации выполнения в защищённом режиме: + +* Инициализировать настраиваемые параметры ядра, переданные из загрузочной программы. +* Подготовить GDT. +* Подготовить IDT. +* Инициализировать системную консоль. +* Инициализировать DDB, если он скомпилирован в ядро. +* Инициализировать TSS. +* Подготовить LDT. +* Настройка pcb для thread0. + +`init386()` инициализирует настраиваемые параметры, переданные из bootstrap, устанавливая указатель окружения (envp) и вызывая `init_param1()`. Указатель envp был передан из loader в структуре `bootinfo`: + +[.programlisting] +.... +sys/i386/i386/machdep.c: + /* Init basic tunables, hz etc */ + init_param1(); +.... + +`init_param1()` определена в [.filename]#sys/kern/subr_param.c#. Этот файл содержит ряд sysctl, а также две функции, `init_param1()` и `init_param2()`, которые вызываются из `init386()`: + +[.programlisting] +.... +sys/kern/subr_param.c: + hz = -1; + TUNABLE_INT_FETCH("kern.hz", &hz); + if (hz == -1) + hz = vm_guest > VM_GUEST_NO ? HZ_VM : HZ; +.... + +`TUNABLE__FETCH` используется для получения значения из окружения: + +[.programlisting] +.... +/usr/src/sys/sys/kernel.h: +#define TUNABLE_INT_FETCH(path, var) getenv_int((path), (var)) +.... + +Sysctl `kern.hz` представляет собой такт системных часов. Кроме того, эти параметры sysctl устанавливаются функцией `init_param1()`: `kern.maxswzone, kern.maxbcache, kern.maxtsiz, kern.dfldsiz, kern.maxdsiz, kern.dflssiz, kern.maxssiz, kern.sgrowsiz`. + +Затем `init386()` подготавливает Глобальную Таблицу Дескрипторов +(GDT). Каждая задача на x86 выполняется в своем собственном виртуальном +адресном пространстве, и это пространство адресуется парой +сегмент:смещение. Например, если текущая инструкция, которую должен +выполнить процессор, находится по адресу CS:EIP, то линейный виртуальный +адрес этой инструкции будет "виртуальный адрес кодового сегмента CS" + +EIP. Для удобства сегменты начинаются с виртуального адреса 0 и +заканчиваются на границе 4 ГБ. Таким образом, линейный виртуальный адрес +инструкции в данном примере будет просто значением EIP. Сегментные регистры, +такие как CS, DS и другие, являются селекторами, то есть индексами в GDT +(если быть более точным, индекс — это не сам селектор, а поле INDEX в +селекторе). GDT в FreeBSD содержит дескрипторы для 15 селекторов на каждый +CPU: + +[.programlisting] +.... +sys/i386/i386/machdep.c: +union descriptor gdt0[NGDT]; /* initial global descriptor table */ +union descriptor *gdt = gdt0; /* global descriptor table */ + +sys/x86/include/segments.h: +/* + * Entries in the Global Descriptor Table (GDT) + */ +#define GNULL_SEL 0 /* Null Descriptor */ +#define GPRIV_SEL 1 /* SMP Per-Processor Private Data */ +#define GUFS_SEL 2 /* User %fs Descriptor (order critical: 1) */ +#define GUGS_SEL 3 /* User %gs Descriptor (order critical: 2) */ +#define GCODE_SEL 4 /* Kernel Code Descriptor (order critical: 1) */ +#define GDATA_SEL 5 /* Kernel Data Descriptor (order critical: 2) */ +#define GUCODE_SEL 6 /* User Code Descriptor (order critical: 3) */ +#define GUDATA_SEL 7 /* User Data Descriptor (order critical: 4) */ +#define GBIOSLOWMEM_SEL 8 /* BIOS low memory access (must be entry 8) */ +#define GPROC0_SEL 9 /* Task state process slot zero and up */ +#define GLDT_SEL 10 /* Default User LDT */ +#define GUSERLDT_SEL 11 /* User LDT */ +#define GPANIC_SEL 12 /* Task state to consider panic from */ +#define GBIOSCODE32_SEL 13 /* BIOS interface (32bit Code) */ +#define GBIOSCODE16_SEL 14 /* BIOS interface (16bit Code) */ +#define GBIOSDATA_SEL 15 /* BIOS interface (Data) */ +#define GBIOSUTIL_SEL 16 /* BIOS interface (Utility) */ +#define GBIOSARGS_SEL 17 /* BIOS interface (Arguments) */ +#define GNDIS_SEL 18 /* For the NDIS layer */ +#define NGDT 19 +.... + +Обратите внимание, что эти `#defines` не являются самими селекторами, а лишь полем `INDEX` селектора, поэтому они точно соответствуют индексам GDT. Например, реальный селектор для кода ядра (`GCODE_SEL`) имеет значение `0x20`. + +Следующий шаг — инициализация таблицы дескрипторов прерываний (IDT). Эта таблица используется процессором при возникновении программного или аппаратного прерывания. Например, чтобы выполнить системный вызов, пользовательское приложение использует инструкцию `INT 0x80`. Это программное прерывание, поэтому аппаратное обеспечение процессора ищет запись с индексом 0x80 в IDT. Эта запись указывает на процедуру обработки данного прерывания, в данном конкретном случае это будет шлюз системных вызовов ядра. IDT может содержать максимум 256 (0x100) записей. Ядро выделяет NIDT записей для IDT, где NIDT — это максимум (256): + +[.programlisting] +.... +sys/i386/i386/machdep.c: +static struct gate_descriptor idt0[NIDT]; +struct gate_descriptor *idt = &idt0[0]; /* interrupt descriptor table */ +.... + +Для каждого прерывания устанавливается соответствующий обработчик. Также настраивается шлюз системного вызова для `INT 0x80`: + +[.programlisting] +.... +sys/i386/i386/machdep.c: + setidt(IDT_SYSCALL, &IDTVEC(int0x80_syscall), + SDT_SYS386IGT, SEL_UPL, GSEL(GCODE_SEL, SEL_KPL)); +.... + +Итак, когда пользовательское приложение выполняет инструкцию `INT 0x80`, управление передаётся функции `_Xint0x80_syscall`, которая находится в сегменте кода ядра и будет выполнена с привилегиями супервизора. + +Консоль и DDB инициализируются: + +[.programlisting] +.... +sys/i386/i386/machdep.c: + cninit(); +/* skipped */ + kdb_init(); +#ifdef KDB + if (boothowto & RB_KDB) + kdb_enter(KDB_WHY_BOOTFLAGS, "Boot flags requested debugger"); +#endif +.... + +Сегмент состояния задачи (TSS) — это еще одна структура защищенного режима x86, используемая оборудованием для хранения информации о задаче при переключении задач. + +Локальная таблица дескрипторов (LDT) используется для ссылки на код и данные пользовательского пространства. Определено несколько селекторов, указывающих на LDT, включая шлюзы системных вызовов, а также селекторы кода и данных пользователя: + +[.programlisting] +.... +sys/x86/include/segments.h: +#define LSYS5CALLS_SEL 0 /* forced by intel BCS */ +#define LSYS5SIGR_SEL 1 +#define LUCODE_SEL 3 +#define LUDATA_SEL 5 +#define NLDT (LUDATA_SEL + 1) +.... + +Далее инициализируется структура Блока Управления Процессом (`struct pcb`) для proc0. proc0 — это структура `struct proc`, описывающая процесс ядра. Она всегда присутствует во время работы ядра, поэтому связана с thread0: + +[.programlisting] +.... +sys/i386/i386/machdep.c: +register_t +init386(int first) +{ + /* ... skipped ... */ + + proc_linkup0(&proc0, &thread0); + /* ... skipped ... */ +} +.... + +Структура `struct pcb` является частью структуры proc. Она определена в [.filename]#/usr/include/machine/pcb.h# и содержит информацию процесса, специфичную для архитектуры i386, такую как значения регистров. + +=== `mi_startup()` + +Эта функция выполняет сортировку пузырьком всех объектов инициализации системы, а затем вызывает вход каждого объекта по очереди: + +[.programlisting] +.... +sys/kern/init_main.c: + for (sipp = sysinit; sipp < sysinit_end; sipp++) { + + /* ... skipped ... */ + + /* Call function */ + (*((*sipp)->func))((*sipp)->udata); + /* ... skipped ... */ + } +.... + +Хотя фреймворк sysinit описан в link:/books/developers-handbook[Руководстве разработчика], я рассмотрю его внутреннее устройство. + +Каждый объект инициализации системы (объект sysinit) создается путем вызова макроса SYSINIT(). Возьмем, к примеру, объект sysinit `announce`. Этот объект выводит сообщение об авторских правах: + +[.programlisting] +.... +sys/kern/init_main.c: +static void +print_caddr_t(void *data __unused) +{ + printf("%s", (char *)data); +} +/* ... skipped ... */ +SYSINIT(announce, SI_SUB_COPYRIGHT, SI_ORDER_FIRST, print_caddr_t, copyright); +.... + +Идентификатор подсистемы для этого объекта — SI_SUB_COPYRIGHT (0x0800001). Таким образом, сообщение об авторских правах будет выведено первым, сразу после инициализации консоли. + +Давайте рассмотрим, что именно делает макрос `SYSINIT()`. Он раскрывается в макрос `C_SYSINIT()`. Макрос `C_SYSINIT()` затем раскрывается в статическое объявление структуры `struct sysinit` с вызовом другого макроса `DATA_SET`: + +[.programlisting] +.... +/usr/include/sys/kernel.h: + #define C_SYSINIT(uniquifier, subsystem, order, func, ident) \ + static struct sysinit uniquifier ## _sys_init = { \ subsystem, \ + order, \ func, \ (ident) \ }; \ DATA_WSET(sysinit_set,uniquifier ## + _sys_init); + +#define SYSINIT(uniquifier, subsystem, order, func, ident) \ + C_SYSINIT(uniquifier, subsystem, order, \ + (sysinit_cfunc_t)(sysinit_nfunc_t)func, (void *)(ident)) +.... + +Макрос `DATA_SET()` раскрывается в `_MAKE_SET()`, и именно в этом макросе скрыта вся магия инициализации системы: + +[.programlisting] +.... +/usr/include/linker_set.h: +#define TEXT_SET(set, sym) _MAKE_SET(set, sym) +#define DATA_SET(set, sym) _MAKE_SET(set, sym) +.... + +После выполнения этих макросов в ядре были созданы различные разделы, включая `set.sysinit_set`. Запустив objdump для бинарного файла ядра, можно заметить наличие таких небольших разделов: + +[source, bash] +.... +% llvm-objdump -h /kernel +Sections: +Idx Name Size VMA Type + 10 set_sysctl_set 000021d4 01827078 DATA + 16 set_kbddriver_set 00000010 0182a4d0 DATA + 20 set_scterm_set 0000000c 0182c75c DATA + 21 set_cons_set 00000014 0182c768 DATA + 33 set_scrndr_set 00000024 0182c828 DATA + 41 set_sysinit_set 000014d8 018fabb0 DATA +.... + +Это содержимое экрана показывает, что размер раздела set.sysinit_set составляет 0x14d8 байт, поэтому `0x14d8/sizeof(void *)` объектов sysinit скомпилировано в ядро. Другие разделы, такие как `set.sysctl_set`, представляют другие наборы компоновщика. + +Определяя переменную типа `struct sysinit`, содержимое раздела `set.sysinit_set` будет "собрано" в эту переменную: + +[.programlisting] +.... +sys/kern/init_main.c: + SET_DECLARE(sysinit_set, struct sysinit); +.... + +`struct sysinit` определена следующим образом: + +[.programlisting] +.... +sys/sys/kernel.h: + struct sysinit { + enum sysinit_sub_id subsystem; /* subsystem identifier*/ + enum sysinit_elem_order order; /* init order within subsystem*/ + sysinit_cfunc_t func; /* function */ + const void *udata; /* multiplexer/argument */ +}; +.... + +Возвращаясь к обсуждению `mi_startup()`, теперь должно быть понятно, как организованы объекты sysinit. Функция `mi_startup()` сортирует их и вызывает каждый. Самый последний объект — это системный планировщик: + +[.programlisting] +.... +/usr/include/sys/kernel.h: +enum sysinit_sub_id { + SI_SUB_DUMMY = 0x0000000, /* not executed; for linker*/ + SI_SUB_DONE = 0x0000001, /* processed*/ + SI_SUB_TUNABLES = 0x0700000, /* establish tunable values */ + SI_SUB_COPYRIGHT = 0x0800001, /* first use of console*/ +... + SI_SUB_LAST = 0xfffffff /* final initialization */ +}; +.... + +Системный планировщик sysinit определен в файле [.filename]#sys/vm/vm_glue.c#, а точка входа для этого объекта — `scheduler()`. Эта функция фактически представляет собой бесконечный цикл и описывает процесс с PID 0, известный как процесс swapper. Структура thread0, упомянутая ранее, используется для его описания. + +Первый пользовательский процесс, называемый _init_, создаётся объектом sysinit `init`: + +[.programlisting] +.... +sys/kern/init_main.c: +static void +create_init(const void *udata __unused) +{ + struct fork_req fr; + struct ucred *newcred, *oldcred; + struct thread *td; + int error; + + bzero(&fr, sizeof(fr)); + fr.fr_flags = RFFDG | RFPROC | RFSTOPPED; + fr.fr_procp = &initproc; + error = fork1(&thread0, &fr); + if (error) + panic("cannot fork init: %d\n", error); + KASSERT(initproc->p_pid == 1, ("create_init: initproc->p_pid != 1")); + /* divorce init's credentials from the kernel's */ + newcred = crget(); + sx_xlock(&proctree_lock); + PROC_LOCK(initproc); + initproc->p_flag |= P_SYSTEM | P_INMEM; + initproc->p_treeflag |= P_TREE_REAPER; + oldcred = initproc->p_ucred; + crcopy(newcred, oldcred); +#ifdef MAC + mac_cred_create_init(newcred); +#endif +#ifdef AUDIT + audit_cred_proc1(newcred); +#endif + proc_set_cred(initproc, newcred); + td = FIRST_THREAD_IN_PROC(initproc); + crcowfree(td); + td->td_realucred = crcowget(initproc->p_ucred); + td->td_ucred = td->td_realucred; + PROC_UNLOCK(initproc); + sx_xunlock(&proctree_lock); + crfree(oldcred); + cpu_fork_kthread_handler(FIRST_THREAD_IN_PROC(initproc), start_init, NULL); +} +SYSINIT(init, SI_SUB_CREATE_INIT, SI_ORDER_FIRST, create_init, NULL); +.... + +Функция `create_init()` выделяет новый процесс, вызывая `fork1()`, но не помечает его как готовый к выполнению. Когда этот новый процесс будет запланирован для выполнения планировщиком, будет вызвана функция `start_init()`. Эта функция определена в [.filename]#init_main.c#. Она пытается загрузить и выполнить бинарный файл [.filename]#init#, сначала проверяя [.filename]#/sbin/init#, затем [.filename]#/sbin/oinit#, [.filename]#/sbin/init.bak# и, наконец, [.filename]#/rescue/init#: + +[.programlisting] +.... +sys/kern/init_main.c: +static char init_path[MAXPATHLEN] = +#ifdef INIT_PATH + __XSTRING(INIT_PATH); +#else + "/sbin/init:/sbin/oinit:/sbin/init.bak:/rescue/init"; +#endif +.... diff --git a/documentation/content/ru/books/arch-handbook/boot/_index.po b/documentation/content/ru/books/arch-handbook/boot/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/boot/_index.po @@ -0,0 +1,4415 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-02 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 Hash Value: title +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1 +#, no-wrap +msgid "Chapter 1. Bootstrapping and Kernel Initialization" +msgstr "Глава 1. Начальная загрузка и инициализация ядра" + +#. 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 "" +"Эта глава представляет собой обзор процессов загрузки и инициализации " +"системы, начиная с POST в BIOS (микропрограмме) и заканчивая созданием " +"первого пользовательского процесса. Поскольку начальные этапы загрузки " +"системы сильно зависят от архитектуры, в качестве примера используется " +"архитектура IA-32. Однако архитектуры AMD64 и ARM64 гораздо важнее и " +"интереснее, и их следует рассмотреть в ближайшем будущем в соответствии с " +"темой этого документа." + +#. 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 "" +"Процесс загрузки FreeBSD может быть удивительно сложным. После передачи " +"управления от BIOS необходимо выполнить значительный объем низкоуровневой " +"настройки перед загрузкой и выполнением ядра. Эта настройка должна быть " +"выполнена простым и гибким способом, предоставляя пользователю широкие " +"возможности для настройки и адаптации." + +#. 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 "" +"Процесс загрузки — это операция, крайне зависимая от оборудования. Не только " +"для каждой архитектуры компьютера должен быть написан код, но также могут " +"существовать различные типы загрузки в рамках одной архитектуры. Например, " +"список файлов в каталоге [.filename]#stand# показывает большое количество " +"кода, зависящего от архитектуры. Для каждой из поддерживаемых архитектур " +"существует отдельный каталог. FreeBSD поддерживает стандарт загрузки CSM " +"(Compatibility Support Module). Таким образом, CSM поддерживается (как с " +"GPT, так и с MBR разметкой), а также загрузка через UEFI (GPT полностью " +"поддерживается, MBR — в основном). Также поддерживается загрузка файлов с " +"ext2fs, MSDOS, UFS и ZFS. FreeBSD поддерживает функцию загрузочного " +"окружения ZFS, которая позволяет основной ОС передавать детали о том, что " +"загружать, выходящие за рамки простого раздела, как это было возможно ранее. " +"Однако в наши дни UEFI более актуален, чем CSM. В следующем примере показана " +"загрузка компьютера x86 с жёсткого диска с MBR-разметкой, где используется " +"мультизагрузчик FreeBSD [.filename]#boot0#, сохранённый в самом первом " +"секторе. Этот загрузочный код запускает трёхэтапный процесс загрузки FreeBSD." + +#. 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 "" +"Ключ к пониманию этого процесса заключается в том, что он состоит из " +"последовательных стадий возрастающей сложности. Эти стадии — " +"[.filename]#boot1#, [.filename]#boot2# и [.filename]#loader# (подробнее см. " +"man:boot[8]). Система загрузки выполняет каждую стадию последовательно. " +"Последняя стадия, [.filename]#loader#, отвечает за загрузку ядра FreeBSD. " +"Каждая стадия рассматривается в следующих разделах." + +#. 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 "*Компонент FreeBSD*" + +#. 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 "`boot0`" + +#. 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 "" +"[source,bash]\n" +"....\n" +"F1 FreeBSD\n" +"F2 BSD\n" +"F5 Disk 2\n" +"...." + +#. 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 "`boot2` footnote:[Это приглашение появится, если пользователь нажмет клавишу сразу после выбора ОС для загрузки на этапе boot0.]" + +#. 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 "" +"[source,bash]\n" +"....\n" +">>FreeBSD/x86 BOOT\n" +"Default: 0:ad(0p4)/boot/loader\n" +"boot:\n" +"...." + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:114 +#, no-wrap +msgid "[.filename]#loader#" +msgstr "[.filename]#loader#" + +#. 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 "" +"[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" +"...." + +#. 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 "" +"[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" +"...." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:147 +#, no-wrap +msgid "The BIOS" +msgstr "BIOS" + +#. 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 "" +"При включении компьютера регистры процессора устанавливаются в некоторые " +"предопределённые значения. Один из регистров — это регистр _указателя " +"команд_, и его значение после включения питания чётко определено: это 32-" +"битное значение `0xfffffff0`. Регистр указателя команд (также известный как " +"Счётчик Команд) указывает на код, который должен быть выполнен процессором. " +"Ещё один важный регистр — это 32-битный управляющий регистр `cr0`, и его " +"значение сразу после перезагрузки равно `0`. Один из битов ``cr0``, бит PE " +"(Protection Enabled, Защита Включена), указывает, работает ли процессор в 32-" +"битном защищённом режиме или 16-битном реальном режиме. Поскольку этот бит " +"сброшен при загрузке, процессор запускается в 16-битном реальном режиме. " +"Реальный режим означает, среди прочего, что линейные и физические адреса " +"идентичны. Причина, по которой процессор не запускается сразу в 32-битном " +"защищённом режиме, — это обратная совместимость. В частности, процесс " +"загрузки зависит от услуг, предоставляемых BIOS, а сам BIOS работает в " +"устаревшем 16-битном коде." + +#. 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 "" +"Значение `0xfffffff0` немного меньше 4 ГБ, поэтому, если в машине нет 4 ГБ " +"физической памяти, оно не может указывать на действительный адрес памяти. " +"Аппаратное обеспечение компьютера преобразует этот адрес так, чтобы он " +"указывал на блок памяти BIOS." + +#. 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 "" +"BIOS (Basic Input Output System) — это микросхема на материнской плате, " +"которая содержит относительно небольшой объем памяти только для чтения " +"(ROM). Эта память включает различные низкоуровневые процедуры, специфичные " +"для оборудования, поставляемого с материнской платой. Процессор сначала " +"переходит по адресу 0xfffffff0, который фактически находится в памяти BIOS. " +"Обычно по этому адресу содержится инструкция перехода к процедурам POST BIOS." + +#. 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 "" +"POST (Power On Self Test) — это набор процедур, включающих проверку памяти, " +"проверку системной шины и другую низкоуровневую инициализацию, чтобы " +"процессор мог правильно настроить компьютер. Важным этапом на этой стадии " +"является определение загрузочного устройства. Современные реализации BIOS " +"позволяют выбирать загрузочное устройство, обеспечивая загрузку с дискеты, " +"CD-ROM, жесткого диска или других устройств." + +#. 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 "" +"Самым последним действием в POST является инструкция `INT 0x19`. Обработчик " +"`INT 0x19` считывает 512 байт из первого сектора загрузочного устройства в " +"память по адресу `0x7c00`. Термин _первый сектор_ происходит из архитектуры " +"жёстких дисков, где магнитная пластина разделена на множество цилиндрических " +"дорожек. Дорожки нумеруются, и каждая дорожка разделена на несколько (обычно " +"64) секторов. Нумерация дорожек начинается с 0, но нумерация секторов " +"начинается с 1. Дорожка 0 находится на внешней стороне магнитной пластины, а " +"сектор 1, первый сектор, имеет особое назначение. Он также называется MBR " +"(Master Boot Record) или Главная Загрузочная Запись. Остальные секторы на " +"первой дорожке не используются." + +#. 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 "" +"Этот сектор является нашей точкой входа в последовательность загрузки. Как " +"мы увидим, этот сектор содержит копию нашей программы [.filename]#boot0#. " +"BIOS выполняет переход по адресу `0x7c00`, и она начинает выполняться." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:185 +#, no-wrap +msgid "The Master Boot Record (`boot0`)" +msgstr "Главная загрузочная запись (`boot0`)" + +#. 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 "" +"После получения управления от BIOS по адресу памяти `0x7c00` начинает " +"выполняться [.filename]#boot0#. Это первый код, который управляется FreeBSD. " +"Задача [.filename]#boot0# довольно проста: просканировать таблицу разделов и " +"позволить пользователю выбрать, с какого раздела загружаться. Таблица " +"разделов — это специальная стандартная структура данных, встроенная в MBR (а " +"значит, и в [.filename]#boot0#), которая описывает четыре стандартных PC-" +"раздела. [.filename]#boot0# находится в файловой системе как [.filename]#/" +"boot/boot0#. Это небольшой файл размером 512 байт, и именно его процедура " +"установки FreeBSD записывает в MBR жёсткого диска, если во время установки " +"была выбрана опция \"bootmanager\". Действительно, [.filename]#boot0# _и " +"есть_ MBR." + +#. 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 "" +"Как упоминалось ранее, мы вызываем прерывание BIOS `INT 0x19` для загрузки " +"MBR ([.filename]#boot0#) в память по адресу `0x7c00`. Исходный файл для " +"[.filename]#boot0# можно найти в [.filename]#stand/i386/boot0/boot0.S# — это " +"впечатляющий фрагмент кода, написанный Робертом Нордье." + +#. 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 "" +"Особая структура, начинающаяся со смещения `0x1be` в MBR, называется " +"_таблицей разделов_. Она содержит четыре записи по 16 байт каждая, " +"называемые _записями разделов_, которые определяют, как разделён жёсткий " +"диск, или, в терминологии FreeBSD, нарезан. Один из этих 16 байт указывает, " +"является ли раздел (срез) загрузочным или нет. Ровно одна запись должна быть " +"с этом установленным флагом, иначе код [.filename]#boot0# откажется " +"продолжать работу." + +#. 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 "1-байтовый тип файловой системы" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:207 +msgid "the 1-byte bootable flag" +msgstr "1-байтовый флаг загрузки (`bootable`)" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:208 +msgid "the 6 byte descriptor in CHS format" +msgstr "6-байтовый дескриптор в формате CHS" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:209 +msgid "the 8 byte descriptor in LBA format" +msgstr "8-байтовый дескриптор в формате LBA" + +#. 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 "" +"Дескриптор записи раздела содержит информацию о том, где именно раздел " +"расположен на диске. Оба дескриптора, LBA и CHS, описывают одну и ту же " +"информацию, но разными способами: LBA (Logical Block Addressing) содержит " +"начальный сектор раздела и его длину, тогда как CHS (Cylinder Head Sector) " +"содержит координаты первого и последнего секторов раздела. Таблица разделов " +"завершается специальной сигнатурой `0xaa55`." + +#. 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 "" +"MBR должен помещаться в 512 байт, один сектор диска. Эта программа " +"использует низкоуровневые «трюки», такие как использование побочных эффектов " +"определённых инструкций и повторное использование значений регистров из " +"предыдущих операций, чтобы максимально эффективно использовать минимально " +"возможное количество инструкций. Также необходимо соблюдать осторожность при " +"работе с таблицей разделов, которая встроена в сам MBR. По этим причинам " +"будьте очень внимательны при изменении [.filename]#boot0.S#." + +#. 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 "" +"Обратите внимание, что исходный файл [.filename]#boot0.S# ассемблируется " +"\"как есть\": инструкции переводятся одна за одной в бинарный код без " +"дополнительной информации (например, без формата файла ELF). Такой " +"низкоуровневый контроль достигается на этапе компоновки с помощью " +"специальных флагов, передаваемых компоновщику. Например, текстовая секция " +"программы располагается по адресу `0x600`. На практике это означает, что " +"[.filename]#boot0# должен быть загружен в память по адресу `0x600` для " +"корректной работы." + +#. 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 "" +"Стоит взглянуть на [.filename]#Makefile# для [.filename]#boot0# " +"([.filename]#stand/i386/boot0/Makefile#), так как он определяет некоторые " +"аспекты поведения [.filename]#boot0# во время выполнения. Например, если для " +"ввода-вывода используется терминал, подключённый к последовательному порту " +"(COM1), необходимо определить макрос `SIO` (`-DSIO`). `-DPXE` включает " +"загрузку через PXE при нажатии kbd:[F6]. Кроме того, программа определяет " +"набор _флагов_, которые позволяют дополнительно настроить её поведение. Всё " +"это проиллюстрировано в [.filename]#Makefile#. Например, обратите внимание " +"на директивы компоновщика, которые предписывают ему начинать секцию текста с " +"адреса `0x600` и создавать выходной файл \"как есть\" (удаляя любое " +"форматирование файла):" + +#. 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 "" +" BOOT_BOOT0_ORG?=0x600\n" +" ORG=${BOOT_BOOT0_ORG}\n" + +#. 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 "[.filename]#stand/i386/boot0/Makefile# [[boot-boot0-makefile-as-is]]" + +#. 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 "" +"Приступим к изучению MBR, или [.filename]#boot0#, начиная с точки входа." + +#. 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 "" +"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" + +#. 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 "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-entrypoint]]" + +#. 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 "" +"Этот первый блок кода является точкой входа программы. Именно сюда BIOS " +"передаёт управление. Сначала он гарантирует, что строковые операции " +"автоматически увеличивают указатели операндов (инструкция `cld`) footnote:[В " +"случае сомнений мы отсылаем читателя к официальным руководствам Intel, где " +"описана точная семантика каждой инструкции: .]. Затем, не делая " +"предположений о состоянии сегментных регистров, он их инициализирует. " +"Наконец, он устанавливает регистр указателя стека (`%sp`) в ($LOAD = адрес " +"`0x7c00`), чтобы обеспечить работоспособный стек." + +#. 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 "" +" 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" + +#. 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 "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-relocation]]" + +#. 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 "" +"Так как [.filename]#boot0# загружается BIOS по адресу `0x7C00`, он копирует " +"себя по адресу `0x600` и передаёт управление туда (напомним, что он был " +"слинкован для выполнения по адресу `0x600`). Исходный адрес, `0x7c00`, " +"копируется в регистр `%si`. Конечный адрес, `0x600`, — в регистр `%di`. " +"Количество слов для копирования, `256` (размер программы = 512 байт), " +"копируется в регистр `%cx`. Далее инструкция `rep` повторяет следующую за " +"ней инструкцию, то есть `movsw`, количество раз, указанное в регистре `%cx`. " +"Инструкция `movsw` копирует слово, на которое указывает `%si`, по адресу, на " +"который указывает `%di`. Это повторяется ещё 255 раз. При каждом повторении " +"оба регистра, исходный и конечный, `%si` и `%di`, увеличиваются на единицу. " +"Таким образом, по завершении копирования 256 слов (512 байт), `%di` имеет " +"значение `0x600`+`512`= `0x800`, а `%si` — значение `0x7c00`+`512`= " +"`0x7e00`; таким образом, мы завершили _перемещение_ кода. С момента " +"последнего обновления этого документа инструкции копирования в коде " +"изменились, поэтому вместо movsb и stosb были введены movsw и stosw, которые " +"копируют 2 байта (1 слово) за одну итерацию." + +#. 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 "" +"Затем регистр назначения `%di` копируется в `%bp`. `%bp` получает значение " +"`0x800`. Значение `8` копируется в `%cl` для подготовки новой строковой " +"операции (как в предыдущей `movsw`). Теперь `stosw` выполняется 8 раз. Эта " +"инструкция копирует значение `0` по адресу, на который указывает регистр " +"назначения (`%di`, то есть `0x800`), и увеличивает его. Это повторяется ещё " +"7 раз, так что `%di` в итоге получает значение `0x810`. Фактически это " +"очищает диапазон адресов `0x800`-`0x80f`. Этот диапазон используется как " +"(фиктивная) таблица разделов для записи MBR обратно на диск. Наконец, полю " +"сектора для CHS-адресации этого фиктивного раздела присваивается значение 1, " +"и выполняется переход к основной функции из перемещённого кода. Обратите " +"внимание, что до этого перехода к перемещённому коду любые ссылки на " +"абсолютные адреса избегались." + +#. 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 "" +"Следующий блок кода проверяет, следует ли использовать номер диска, " +"предоставленный BIOS, или тот, что хранится в [.filename]#boot0#." + +#. 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 "" +"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" + +#. 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 "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-drivenumber]]" + +#. 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 "" +"Этот код проверяет бит `SETDRV` (`0x20`) в переменной _flags_. Напомним, что " +"регистр `%bp` указывает на адрес `0x800`, поэтому проверка выполняется для " +"переменной _flags_ по адресу `0x800`-`69`= `0x7bb`. Это пример типа " +"изменений, которые можно внести в [.filename]#boot0#. Флаг `SETDRV` не " +"установлен по умолчанию, но его можно задать в [.filename]#Makefile#. Если " +"он установлен, используется номер диска, сохранённый в MBR, вместо " +"предоставленного BIOS. Мы предполагаем значения по умолчанию и то, что BIOS " +"предоставил корректный номер диска, поэтому переходим к `save_curdrive`." + +#. 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 "" +"Следующий блок сохраняет номер диска, предоставленный BIOS, и вызывает " +"`putn` для вывода новой строки на экран." + +#. 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 "" +"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" + +#. 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 "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-savedrivenumber]]" + +#. 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 "" +"Обратите внимание, что мы предполагаем, что `TEST` не определён, поэтому " +"условный код в нём не собирается и не появится в нашем исполняемом файле " +"[.filename]#boot0#." + +#. 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 "" +"Следующий блок реализует фактическое сканирование таблицы разделов. Он " +"выводит на экран тип раздела для каждой из четырёх записей в таблице " +"разделов. Каждый тип сравнивается со списком известных файловых систем " +"операционных систем. Примерами распознаваемых типов разделов являются NTFS " +"(Windows(R), ID 0x7), `ext2fs` (Linux(R), ID 0x83) и, конечно же, `ffs`/" +"`ufs2` (FreeBSD, ID 0xa5). Реализация довольно проста." + +#. 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 "" +" movw $(partbl+0x4),%bx\t# Partition table (+4)\n" +" xorw %dx,%dx\t\t# Item number\n" + +#. 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 "" +"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" + +#. 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 "" +"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" + +#. 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 "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-partition-scan]]" + +#. 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 "" +"Важно отметить, что флаг активности для каждой записи сбрасывается, поэтому " +"после сканирования _ни одна_ запись о разделе не активна в нашей копии " +"[.filename]#boot0# в памяти. Позже флаг активности будет установлен для " +"выбранного раздела. Это гарантирует, что только один активный раздел " +"существует, если пользователь решит записать изменения обратно на диск." + +#. 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 "" +"Следующий блок проверяет наличие других дисков. При запуске BIOS записывает " +"количество дисков, присутствующих в компьютере, по адресу `0x475`. Если есть " +"другие диски, [.filename]#boot0# выводит текущий диск на экран. Пользователь " +"может позже дать команду [.filename]#boot0# просканировать разделы на другом " +"диске." + +#. 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 "" +" 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" + +#. 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 "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-test-drives]]" + +#. 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 "" +"Мы предполагаем, что присутствует только один диск, поэтому переход к " +"`print_drive` не выполняется. Также мы предполагаем, что ничего необычного " +"не произошло, поэтому переходим к `print_prompt`." + +#. 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 "" +"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" + +#. 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 "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-prompt]]" + +#. 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 "" +"Наконец, выполняется переход к `start_input`, где используются сервисы BIOS " +"для запуска таймера и чтения пользовательского ввода с клавиатуры; если " +"таймер истекает, будет выбран вариант по умолчанию:" + +#. 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 "" +"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" + +#. 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 "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-start-input]]" + +#. 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 "" +"Прерывание запрашивается с номером `0x1a` и аргументом `0` в регистре `%ah`. " +"BIOS имеет предопределённый набор сервисов, запрашиваемых приложениями как " +"программно-генерируемые прерывания через инструкцию `int`, с получением " +"аргументов в регистрах (в данном случае, `%ah`). Здесь, в частности, " +"запрашивается количество тиков часов с момента последней полуночи; это " +"значение вычисляется BIOS через RTC (Real Time Clock). Эти часы могут быть " +"настроены на работу с частотой от 2 Гц до 8192 Гц. BIOS устанавливает их на " +"18,2 Гц при запуске. Когда запрос выполнен, 32-битный результат возвращается " +"BIOS в регистрах `%cx` и `%dx` (младшие байты в `%dx`). Этот результат " +"(часть `%dx`) копируется в регистр `%di`, и к `%di` добавляется значение " +"переменной `TICKS`. Эта переменная находится в [.filename]#boot0# по " +"смещению `_TICKS` (отрицательное значение) от регистра `%bp` (который, " +"напомним, указывает на `0x800`). Значение этой переменной по умолчанию — " +"`0xb6` (182 в десятичной системе). Идея заключается в том, что " +"[.filename]#boot0# постоянно запрашивает время у BIOS, и когда значение, " +"возвращённое в регистре `%dx`, становится больше значения, хранящегося в " +"`%di`, время истекает и будет сделан выбор по умолчанию. Поскольку RTC " +"тикает 18,2 раза в секунду, это условие выполнится через 10 секунд (это " +"поведение по умолчанию можно изменить в [.filename]#Makefile#). До истечения " +"этого времени [.filename]#boot0# непрерывно опрашивает BIOS на предмет ввода " +"пользователя; это делается через `int 0x16`, аргумент `1` в `%ah`." + +#. 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 "" +"Была нажата клавиша или истекло время, последующий код проверяет выбор. В " +"зависимости от выбора, регистр `%si` устанавливается так, чтобы указывать на " +"соответствующую запись раздела в таблице разделов. Этот новый выбор " +"переопределяет предыдущий выбор по умолчанию. Действительно, он становится " +"новым значением по умолчанию. Наконец, устанавливается флаг ACTIVE " +"выбранного раздела. Если это было разрешено при компиляции, версия " +"[.filename]#boot0# в памяти с этими изменёнными значениями записывается " +"обратно в MBR на диске. Мы оставляем детали этой реализации читателю." + +#. 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 "" +"Мы завершаем наше изучение последним блоком кода из программы " +"[.filename]#boot0#:" + +#. 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 "" +" 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" + +#. 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 "[.filename]#stand/i386/boot0/boot0.S# [[boot-boot0-check-bootable]]" + +#. 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 "" +"Вспомним, что `%si` указывает на выбранную запись раздела. Эта запись " +"сообщает нам, где начинается раздел на диске. Мы предполагаем, конечно, что " +"выбранный раздел действительно является срезом FreeBSD." + +#. 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 "" +"Буфер передачи установлен в `0x7c00` (регистр `%bx`), и запрос на чтение " +"первого сектора слайса FreeBSD выполняется вызовом `intx13`. Мы " +"предполагаем, что всё прошло успешно, поэтому переход к `beep` не " +"выполняется. В частности, новый прочитанный сектор должен заканчиваться " +"магической последовательностью `0xaa55`. Наконец, значение в `%si` " +"(указатель на выбранную таблицу разделов) сохраняется для использования на " +"следующем этапе, и выполняется переход по адресу `0x7c00`, где начинается " +"выполнение нашего следующего этапа (только что прочитанного блока)." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:490 +#, no-wrap +msgid "`boot1` Stage" +msgstr "Этап `boot1`" + +#. 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 "" +"BIOS выполнил первоначальную инициализацию оборудования, включая POST. MBR " +"([.filename]#boot0#) был загружен по адресу `0x7c00` из абсолютного сектора " +"один с диска. Управление выполнением было передано по этому адресу." + +#. 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 "" +"[.filename]#boot0# переместил себя по адресу, по которому он был скомпонован " +"для выполнения (`0x600`), после чего выполнил переход для продолжения " +"выполнения в соответствующем месте. В завершение, [.filename]#boot0# " +"загрузил первый сектор диска из раздела FreeBSD по адресу `0x7c00`. " +"Управление выполнением было передано по этому адресу." + +#. 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 "" +"[.filename]#boot1# — это следующий шаг в последовательности загрузки. Это " +"первая из трех стадий загрузки. Обратите внимание, что до сих пор мы " +"работали исключительно с секторами диска. Действительно, BIOS загружает " +"самый первый сектор, а [.filename]#boot0# загружает первый сектор раздела " +"FreeBSD. Обе загрузки происходят по адресу `0x7c00`. Мы можем концептуально " +"представлять эти секторы диска как содержащие файлы [.filename]#boot0# и " +"[.filename]#boot1#, соответственно, но на самом деле это не совсем верно для " +"[.filename]#boot1#. Строго говоря, в отличие от [.filename]#boot0#, " +"[.filename]#boot1# не является частью загрузочных блоков footnote:[Файл /" +"boot/boot1 существует, но он не записывается в начало раздела FreeBSD. " +"Вместо этого он объединяется с boot2, формируя файл boot, который " +"записывается в начало раздела FreeBSD и считывается во время загрузки.]. " +"Вместо этого, единый полноценный файл [.filename]#boot# ([.filename]#/boot/" +"boot#) в итоге записывается на диск. Этот файл представляет собой комбинацию " +"[.filename]#boot1#, [.filename]#boot2# и `Boot Extender` (или BTX). Этот " +"единый файл превышает размер одного сектора (больше 512 байт). К счастью, " +"[.filename]#boot1# занимает _ровно_ первые 512 байт этого файла, поэтому, " +"когда [.filename]#boot0# загружает первый сектор раздела FreeBSD (512 байт), " +"он фактически загружает [.filename]#boot1# и передает ему управление." + +#. 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 "" +"Основная задача [.filename]#boot1# — загрузить следующий этап загрузки. Этот " +"следующий этап несколько сложнее. Он состоит из сервера под названием \"Boot " +"Extender\" (BTX) и клиента под названием [.filename]#boot2#. Как мы увидим, " +"последний этап загрузки, [.filename]#loader#, также является клиентом " +"сервера BTX." + +#. 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 "" +"Давайте теперь подробно рассмотрим, что именно делает [.filename]#boot1#, " +"начиная, как мы это делали для [.filename]#boot0#, с точки входа:" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:525 +#, no-wrap +msgid "" +"start:\n" +"\tjmp main\n" +msgstr "" +"start:\n" +"\tjmp main\n" + +#. 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 "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-entry]]" + +#. 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 "" +"Точка входа `start` просто переходит через специальную область данных к " +"метке `main`, которая, в свою очередь, выглядит следующим образом:" + +#. 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 "" +"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" + +#. 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 "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-main]]" + +#. 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 "" +"Как и [.filename]#boot0#, этот код перемещает [.filename]#boot1#, на этот " +"раз по адресу `0x700`. Однако, в отличие от [.filename]#boot0#, он не " +"переходит туда. [.filename]#boot1# скомпонован для выполнения по адресу " +"`0x7c00`, фактически там, куда он был изначально загружен. Причина этого " +"перемещения будет рассмотрена далее." + +#. 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 "" +"Далее идет цикл, который ищет слайс FreeBSD. Хотя [.filename]#boot0# " +"загрузил [.filename]#boot1# из слайса FreeBSD, ему не была передана " +"информация об этом footnote:[На самом деле мы передали указатель на адрес " +"слайса в регистре %si. Однако boot1 не предполагает, что он был загружен " +"boot0 (возможно, его загрузил другой MBR и не передал эту информацию), " +"поэтому он ничего не предполагает.], поэтому [.filename]#boot1# должен " +"повторно просканировать таблицу разделов, чтобы найти начало слайса FreeBSD. " +"Для этого он перечитывает MBR:" + +#. 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 "" +" 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" + +#. 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 "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-find-freebsd]]" + +#. 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 "" +"В приведённом выше коде регистр `%dl` содержит информацию о загрузочном " +"устройстве. Эти данные передаются BIOS и сохраняются MBR. Числа `0x80` и " +"выше указывают на то, что мы имеем дело с жёстким диском, поэтому вызывается " +"`nread`, где считывается MBR. Аргументы для `nread` передаются через `%si` " +"и `%dh`. Адрес памяти по метке `part4` копируется в `%si`. Этот адрес " +"памяти содержит \"фальшивый раздел\", который будет использован `nread`. " +"Ниже приведены данные фальшивого раздела:" + +#. 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 "" +" 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" + +#. 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 "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot2-make-fake-partition]]" + +#. 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 "" +"В частности, LBA для этой фиктивной раздела жестко закодирован как ноль. Это " +"используется как аргумент для BIOS при чтении абсолютного сектора один с " +"жесткого диска. Альтернативно, может использоваться адресация CHS. В этом " +"случае, фиктивный раздел содержит цилиндр 0, головку 0 и сектор 1, что " +"эквивалентно абсолютному сектору один." + +#. 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 "Продолжим, рассмотрев `nread`:" + +#. 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 "" +"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" + +#. 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 "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-nread]]" + +#. 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 "" +"Напомним, что `%si` указывает на поддельный раздел. Слово footnote:[В " +"контексте 16-битного реального режима слово — это 2 байта.] по смещению " +"`0x8` копируется в регистр `%ax`, а слово по смещению `0xa` — в `%cx`. BIOS " +"интерпретирует их как младшее 4-байтовое значение, обозначающее LBA для " +"чтения (старшие четыре байта предполагаются нулевыми). Регистр `%bx` " +"содержит адрес памяти, куда будет загружен MBR. Инструкция, помещающая `%cs` " +"в стек, очень интересна. В данном контексте она ничего не делает. Однако, " +"как мы скоро увидим, [.filename]#boot2# в сочетании с сервером BTX также " +"использует `xread.1`. Этот механизм будет рассмотрен в следующем разделе." + +#. 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 "" +"Код в `xread.1` далее вызывает функцию `read`, которая фактически обращается " +"к BIOS с запросом на чтение сектора диска:" + +#. 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 "" +"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" + +#. 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 "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-xread1]]" + +#. 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 "" +"Обратите внимание на длинную инструкцию возврата в конце этого блока. Эта " +"инструкция извлекает регистр `%cs`, помещённый в стек `nread`, и возвращает " +"управление. В конце `nread` также возвращает управление." + +#. 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 "" +"С загрузкой MBR в память начинается фактический цикл поиска слайса FreeBSD:" + +#. 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 "" +"\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" + +#. 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 "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-find-part]]" + +#. 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 "" +"Если обнаружен слайс FreeBSD, выполнение продолжается на метке `main.5`. " +"Обратите внимание, что при обнаружении слайса FreeBSD `%si` указывает на " +"соответствующую запись в таблице разделов, а `%dh` содержит номер раздела. " +"Мы предполагаем, что слайс FreeBSD найден, поэтому продолжаем выполнение на " +"метке `main.5`:" + +#. 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 "" +"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" + +#. 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 "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-main5]]" + +#. 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 "" +"Напомним, что в данный момент регистр `%si` указывает на запись среза " +"FreeBSD в таблице разделов MBR, поэтому вызов `nread` фактически прочитает " +"секторы в начале этого раздела. Аргумент, переданный в регистре `%dh`, " +"указывает `nread` прочитать 16 секторов диска. Напомним, что первые 512 " +"байт, или первый сектор слайса FreeBSD, совпадает с программой " +"[.filename]#boot1#. Также напомним, что файл, записанный в начало слайса " +"FreeBSD, это не [.filename]#/boot/boot1#, а [.filename]#/boot/boot#. Давайте " +"посмотрим на размер этих файлов в файловой системе:" + +#. 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 "" +"-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" + +#. 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 "" +"Оба файла [.filename]#boot0# и [.filename]#boot1# имеют размер 512 байт " +"каждый, поэтому они занимают _ровно_ один сектор диска. [.filename]#boot2# " +"значительно больше, так как содержит как сервер BTX, так и клиент " +"[.filename]#boot2#. Наконец, файл под названием просто [.filename]#boot# на " +"512 байт больше, чем [.filename]#boot2#. Этот файл представляет собой " +"объединение [.filename]#boot1# и [.filename]#boot2#. Как уже отмечалось, " +"[.filename]#boot0# записывается в самый первый сектор диска (MBR), а " +"[.filename]#boot# записывается в первый сектор раздела FreeBSD; " +"[.filename]#boot1# и [.filename]#boot2# _не_ записываются на диск. Команда, " +"используемая для объединения [.filename]#boot1# и [.filename]#boot2# в " +"единый файл [.filename]#boot#, выглядит просто как `cat boot1 boot2 > boot`." + +#. 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 "" +"Итак, [.filename]#boot1# занимает ровно первые 512 байт [.filename]#boot#, " +"и, поскольку [.filename]#boot# записывается в первый сектор слайса FreeBSD, " +"[.filename]#boot1# полностью помещается в этот первый сектор. Когда `nread` " +"читает первые 16 секторов слайса FreeBSD, он фактически читает весь файл " +"[.filename]#boot# footnote:[512*16=8192 байта, ровно размер boot]. Более " +"подробно о том, как [.filename]#boot# формируется из [.filename]#boot1# и " +"[.filename]#boot2#, мы увидим в следующем разделе." + +#. 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 "" +"Напомним, что `nread` использует адрес памяти `0x8c00` в качестве буфера " +"передачи для хранения прочитанных секторов. Этот адрес выбран не случайно. " +"Действительно, поскольку [.filename]#boot1# принадлежит первым 512 байтам, " +"он оказывается в диапазоне адресов `0x8c00`-`0x8dff`. Следующие 512 байт " +"(диапазон `0x8e00`-`0x8fff`) используются для хранения _bsdlabel_ footnote:" +"[Исторически известной как disklabel. Если вам когда-либо было интересно, " +"где FreeBSD хранит эту информацию, она находится в этой области — см. " +"man:bsdlabel[8]]." + +#. 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 "" +"Начиная с адреса `0x9000` находится начало сервера BTX, и сразу за ним " +"следует клиент [.filename]#boot2#. Сервер BTX действует как ядро и " +"выполняется в защищённом режиме с наивысшим уровнем привилегий. В отличие от " +"этого, клиенты BTX (например, [.filename]#boot2#) выполняются в " +"пользовательском режиме. Мы увидим, как это реализовано, в следующем " +"разделе. Код после вызова `nread` находит начало [.filename]#boot2# в буфере " +"памяти и копирует его по адресу `0xc000`. Это связано с тем, что сервер BTX " +"размещает [.filename]#boot2# для выполнения в сегменте, начинающемся с " +"`0xa000`. Мы подробно рассмотрим это в следующем разделе." + +#. 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 "" +"Последний блок кода в [.filename]#boot1# разрешает доступ к памяти выше 1MB " +"footnote:[Это необходимо по историческим причинам. Заинтересованные читатели " +"могут обратиться к .] и завершается переходом к начальной точке сервера BTX:" + +#. 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 "" +"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" + +#. 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 "" +"\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" + +#. 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 "[.filename]#stand/i386/boot2/boot1.S# [[boot-boot1-seta20]]" + +#. 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 "Сервер BTX" + +#. 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 "" +"Далее в нашей последовательности загрузки идёт сервер BTX. Давайте быстро " +"вспомним, как мы сюда попали:" + +#. 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 "" +"BIOS загружает абсолютный сектор один (MBR или [.filename]#boot0#) по адресу " +"`0x7c00` и переходит туда." + +#. 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 "" +"[.filename]#boot0# перемещает себя по адресу `0x600`, по которому он был " +"слинкован для выполнения, и переходит туда. Затем он читает первый сектор " +"среза FreeBSD (который содержит [.filename]#boot1#) в адрес `0x7c00` и " +"переходит туда." + +#. 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 "" +"[.filename]#boot1# загружает первые 16 секторов среза FreeBSD по адресу " +"`0x8c00`. Эти 16 секторов, или 8192 байта, представляют собой весь файл " +"[.filename]#boot#. Файл является объединением [.filename]#boot1# и " +"[.filename]#boot2#. [.filename]#boot2#, в свою очередь, содержит сервер BTX " +"и клиент [.filename]#boot2#. Наконец, выполняется переход по адресу " +"`0x9010`, точке входа сервера BTX." + +#. 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 "" +"Прежде чем изучать сервер BTX подробно, давайте рассмотрим, как создается " +"единый, всеобъемлющий файл [.filename]#boot#. Способ сборки " +"[.filename]#boot# определен в его [.filename]#Makefile# ([.filename]#stand/" +"i386/boot2/Makefile#). Рассмотрим правило, которое создает файл " +"[.filename]#boot#:" + +#. 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 "" +" boot: boot1 boot2\n" +"\tcat boot1 boot2 > boot\n" + +#. 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 "[.filename]#stand/i386/boot2/Makefile# [[boot-boot1-make-boot]]" + +#. 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 "" +"Это говорит нам, что [.filename]#boot1# и [.filename]#boot2# необходимы, и " +"правило просто объединяет их для создания одного файла с именем " +"[.filename]#boot#. Правила для создания [.filename]#boot1# также довольно " +"просты:" + +#. 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 "" +" boot1: boot1.out\n" +"\t${OBJCOPY} -S -O binary boot1.out ${.TARGET}\n" + +#. 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 "" +" boot1.out: boot1.o\n" +"\t${LD} ${LD_FLAGS} -e start --defsym ORG=${ORG1} -T ${LDSCRIPT} -o ${.TARGET} boot1.o\n" + +#. 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 "[.filename]#stand/i386/boot2/Makefile# [[boot-boot1-make-boot1]]" + +#. 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 "" +"Для применения правила создания [.filename]#boot1# необходимо собрать " +"[.filename]#boot1.out#. Это, в свою очередь, зависит от наличия " +"[.filename]#boot1.o#. Последний файл является результатом ассемблирования " +"нашего знакомого [.filename]#boot1.S# без компоновки. Теперь применяется " +"правило создания [.filename]#boot1.out#. Оно указывает, что " +"[.filename]#boot1.o# должен быть скомпонован с точкой входа `start` и " +"начальным адресом `0x7c00`. Наконец, [.filename]#boot1# создается из " +"[.filename]#boot1.out# применением соответствующего правила. Это команда " +"[.filename]#objcopy#, применяемая к [.filename]#boot1.out#. Обратите " +"внимание на флаги, передаваемые [.filename]#objcopy#: `-S` указывает на " +"удаление всей информации о перемещении и символов; `-O binary` указывает " +"формат вывода, то есть простой, неформатированный двоичный файл." + +#. 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 "" +"Имея [.filename]#boot1#, давайте посмотрим, как устроен [.filename]#boot2#:" + +#. 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 "" +" 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" + +#. 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 "" +" 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" + +#. 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 "" +" boot2.ldr:\n" +"\t${DD} if=/dev/zero of=${.TARGET} bs=512 count=1\n" + +#. 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 "" +" boot2.bin: boot2.out\n" +"\t${OBJCOPY} -S -O binary boot2.out ${.TARGET}\n" + +#. 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 "" +" boot2.out: ${BTXCRT} boot2.o sio.o ashldi3.o\n" +"\t${LD} ${LD_FLAGS} --defsym ORG=${ORG2} -T ${LDSCRIPT} -o ${.TARGET} ${.ALLSRC}\n" + +#. 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 "" +" 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" + +#. 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 "[.filename]#stand/i386/boot2/Makefile# [[boot-boot1-make-boot2]]" + +#. 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 "" +"Механизм сборки [.filename]#boot2# гораздо сложнее. Отметим наиболее важные " +"моменты. Список зависимостей выглядит следующим образом:" + +#. 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 "" +" 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" + +#. 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 "[.filename]#stand/i386/boot2/Makefile# [[boot-boot1-make-boot2-more]]" + +#. 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 "" +"Отметим, что изначально файл заголовка [.filename]#boot2.h# отсутствует, но " +"его создание зависит от [.filename]#boot1.out#, который у нас уже есть. " +"Правило его создания немного лаконично, но важно то, что результат, " +"[.filename]#boot2.h#, выглядит примерно так:" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:851 +#, no-wrap +msgid "#define XREADORG 0x725\n" +msgstr "#define XREADORG 0x725\n" + +#. 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 "[.filename]#stand/i386/boot2/boot2.h# [[boot-boot1-make-boot2h]]" + +#. 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 "" +"Напомним, что [.filename]#boot1# был перемещён (т.е. скопирован из `0x7c00` " +"в `0x700`). Это перемещение теперь обретает смысл, потому что, как мы " +"увидим, сервер BTX освобождает часть памяти, включая область, куда " +"[.filename]#boot1# был изначально загружен. Однако серверу BTX необходим " +"доступ к функции `xread` из [.filename]#boot1#; согласно выводу " +"[.filename]#boot2.h#, эта функция находится по адресу `0x725`. " +"Действительно, сервер BTX использует функцию `xread` из перемещённого кода " +"[.filename]#boot1#. Теперь эта функция доступна из клиента " +"[.filename]#boot2#." + +#. 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 "" +"Следующее правило указывает компоновщику на необходимость связать различные " +"файлы ([.filename]#ashldi3.o#, [.filename]#boot2.o# и [.filename]#sio.o#). " +"Обратите внимание, что выходной файл [.filename]#boot2.out# компонуется для " +"выполнения по адресу `0x2000` (${ORG2}). Напомним, что [.filename]#boot2# " +"будет выполняться в пользовательском режиме внутри специального " +"пользовательского сегмента, созданного сервером BTX. Этот сегмент начинается " +"с адреса `0xa000`. Также помните, что часть [.filename]#boot2# в " +"[.filename]#boot# была скопирована по адресу `0xc000`, то есть со смещением " +"`0x2000` от начала пользовательского сегмента, поэтому [.filename]#boot2# " +"будет работать корректно при передаче управления на него. Далее, " +"[.filename]#boot2.bin# создается из [.filename]#boot2.out# путем удаления " +"символов и информации о формате; boot2.bin представляет собой _сырой_ " +"бинарный файл. Теперь обратите внимание, что файл [.filename]#boot2.ldr# " +"создается как 512-байтный файл, заполненный нулями. Это пространство " +"зарезервировано для bsdlabel." + +#. 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 "" +"Теперь, когда у нас есть файлы [.filename]#boot1#, [.filename]#boot2.bin# и " +"[.filename]#boot2.ldr#, осталось только добавить сервер BTX перед созданием " +"универсального файла [.filename]#boot#. Сервер BTX находится в " +"[.filename]#stand/i386/btx/btx#; у него есть собственный " +"[.filename]#Makefile# со своим набором правил для сборки. Важно отметить, " +"что он также компилируется как _сырой_ бинарный файл и линкуется для " +"выполнения по адресу `0x9000`. Подробности можно найти в [.filename]#stand/" +"i386/btx/btx/Makefile#." + +#. 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 "" +"Имея файлы, составляющие программу [.filename]#boot#, последним шагом " +"является их _объединение_. Это выполняется специальной программой под " +"названием [.filename]#btxld# (исходный код расположен в [.filename]#/usr/src/" +"usr.sbin/btxld#). Некоторые аргументы этой программы включают имя выходного " +"файла ([.filename]#boot#), его точку входа (`0x2000`) и формат файла " +"(бинарный). Различные файлы окончательно объединяются этой утилитой в файл " +"[.filename]#boot#, который состоит из [.filename]#boot1#, " +"[.filename]#boot2#, `bsdlabel` и сервера BTX. Этот файл, занимающий ровно 16 " +"секторов или 8192 байта, записывается в начало раздела FreeBSD во время " +"установки. Теперь перейдем к изучению программы сервера BTX." + +#. 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 "" +"Сервер BTX подготавливает простое окружение и переключается из 16-битного " +"реального режима в 32-битный защищённый режим, непосредственно перед " +"передачей управления клиенту. Это включает инициализацию и обновление " +"следующих структур данных:" + +#. 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 "" +"Изменяет `Таблицу Векторов Прерываний (IVT)`. IVT предоставляет обработчики " +"исключений и прерываний для кода в Реальном Режиме." + +#. 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 "" +"Создается `Таблица дескрипторов прерываний (IDT)`. В ней предусмотрены " +"записи для исключений процессора, аппаратных прерываний, двух системных " +"вызовов и интерфейса V86. IDT предоставляет обработчики исключений и " +"прерываний для кода в защищенном режиме." + +#. 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 "" +"Создается `Сегмент состояния задачи (TSS)`. Это необходимо, потому что " +"процессор работает на _наименее_ привилегированном уровне при выполнении " +"клиента ([.filename]#boot2#), но на _наиболее_ привилегированном уровне при " +"выполнении сервера BTX." + +#. 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 "" +"Устанавливается GDT (Глобальная Таблица Дескрипторов). Создаются записи " +"(дескрипторы) для кода и данных супервизора, кода и данных пользователя, а " +"также кода и данных реального режима. footnote:[Код и данные реального " +"режима необходимы при переключении обратно в реальный режим из защищённого " +"режима, как указано в руководствах Intel.]" + +#. 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 "" +"Приступим к изучению фактической реализации. Напомним, что " +"[.filename]#boot1# выполнил переход на адрес `0x9010` — точку входа сервера " +"BTX. Прежде чем изучать выполнение программы там, обратите внимание, что " +"сервер BTX имеет специальный заголовок в диапазоне адресов `0x9000-0x900f`, " +"непосредственно перед точкой входа. Этот заголовок определён следующим " +"образом:" + +#. 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 "" +"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" + +#. 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 "[.filename]#stand/i386/btx/btx/btx.S# [[btx-header]]" + +#. 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 "" +"Обратите внимание, что первые два байта — это `0xeb` и `0xe`. В архитектуре " +"IA-32 эти два байта интерпретируются как относительный переход за заголовок " +"к точке входа, поэтому теоретически [.filename]#boot1# мог бы перейти сюда " +"(адрес `0x9000`) вместо адреса `0x9010`. Обратите внимание, что последнее " +"поле в заголовке BTX — это указатель на точку входа клиента " +"([.filename]#boot2#)b2. Это поле исправляется во время компоновки." + +#. 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 "Сразу после заголовка следует точка входа сервера BTX:" + +#. 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 "" +"/*\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" + +#. 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 "[.filename]#stand/i386/btx/btx/btx.S# [[btx-init]]" + +#. 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 "" +"Этот код отключает прерывания, устанавливает рабочий стек (начиная с адреса " +"`0x1800`) и очищает флаги в регистре EFLAGS. Обратите внимание, что " +"инструкция `popfl` извлекает двойное слово (4 байта) из стека и помещает его " +"в регистр EFLAGS. Поскольку извлекаемое значение фактически равно `2`, " +"регистр EFLAGS эффективно очищается (IA-32 требует, чтобы бит 2 регистра " +"EFLAGS всегда был равен 1)." + +#. 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 "" +"Следующий блок кода очищает (устанавливает в `0`) диапазон памяти " +"`0x5e00-0x8fff`. В этом диапазоне будут созданы различные структуры данных:" + +#. 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 "" +"/*\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" + +#. 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 "[.filename]#stand/i386/btx/btx/btx.S# [[btx-clear-mem]]" + +#. 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 "" +"Напомним, что [.filename]#boot1# изначально загружался по адресу `0x7c00`, " +"поэтому при такой инициализации памяти эта копия фактически исчезла. Однако " +"также напомним, что [.filename]#boot1# был перемещён на адрес `0x700`, " +"поэтому _эта_ копия всё ещё находится в памяти, и сервер BTX будет её " +"использовать." + +#. 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 "" +"Далее обновляется таблица векторов прерываний (IVT) в реальном режиме. IVT " +"представляет собой массив пар сегмент/смещение для обработчиков исключений и " +"прерываний. BIOS обычно сопоставляет аппаратные прерывания с векторами " +"прерываний `0x8`–`0xf` и `0x70`–`0x77`, но, как будет показано, " +"программируемый контроллер прерываний 8259A, микросхема, управляющая " +"фактическим сопоставлением аппаратных прерываний с векторами прерываний, " +"программируется для переназначения этих векторов прерываний с `0x8`–`0xf` на " +"`0x20`–`0x27` и с `0x70`–`0x77` на `0x28`–`0x2f`. Таким образом, обработчики " +"прерываний предоставляются для векторов прерываний `0x20`–`0x2f`. Причина, " +"по которой обработчики, предоставляемые BIOS, не используются напрямую, " +"заключается в том, что они работают в 16-битном реальном режиме, но не в 32-" +"битном защищённом режиме. Вскоре будет выполнен переход в 32-битный " +"защищённый режим. Однако сервер BTX настраивает механизм для эффективного " +"использования обработчиков, предоставляемых BIOS:" + +#. 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 "" +"/*\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" + +#. 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 "[.filename]#stand/i386/btx/btx/btx.S# [[btx-ivt]]" + +#. 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 "" +"Следующий блок создает IDT (таблицу дескрипторов прерываний). IDT в " +"защищенном режиме аналогична IVT в реальном режиме. То есть, IDT описывает " +"различные обработчики исключений и прерываний, используемые, когда процессор " +"работает в защищенном режиме. По сути, она также состоит из массива пар " +"сегмент/смещение, хотя структура несколько сложнее, поскольку сегменты в " +"защищенном режиме отличаются от реального режима, и применяются различные " +"механизмы защиты:" + +#. 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 "" +"/*\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" + +#. 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 "[.filename]#stand/i386/btx/btx/btx.S# [[btx-idt]]" + +#. 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 "" +"Каждая запись в `IDT` имеет длину 8 байт. Помимо информации о сегменте/" +"смещении, они также описывают тип сегмента, уровень привилегий и " +"присутствует ли сегмент в памяти. Структура организована так, что векторы " +"прерываний от `0` до `0xf` (исключения) обрабатываются функцией `intx00`; " +"вектор `0x10` (также исключение) обрабатывается `intx10`; аппаратные " +"прерывания, которые позже настраиваются начиная с вектора `0x20` и до " +"вектора `0x2f`, обрабатываются функцией `intx20`. Наконец, вектор прерывания " +"`0x30`, используемый для системных вызовов, обрабатывается `intx30`, а " +"векторы `0x31` и `0x32` обрабатываются `intx31`. Необходимо отметить, что " +"только дескрипторы для векторов прерываний `0x30`, `0x31` и `0x32` имеют " +"уровень привилегий 3, такой же, как у клиента [.filename]#boot2#, что " +"означает, что клиент может выполнить программно-генерируемое прерывание к " +"этим векторам через инструкцию `int` без ошибки (это способ, которым " +"[.filename]#boot2# использует сервисы, предоставляемые сервером BTX). Также " +"обратите внимание, что _только_ программно-генерируемые прерывания защищены " +"от кода, выполняющегося на более низких уровнях привилегий. Аппаратно-" +"генерируемые прерывания и исключения, генерируемые процессором, _всегда_ " +"обрабатываются корректно, независимо от фактических привилегий." + +#. 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 "" +"Следующий шаг — инициализация TSS (сегмента состояния задачи). TSS — это " +"аппаратная функция, которая помогает операционной системе или " +"исполнительному ПО реализовать многозадачность через абстракцию процессов. " +"Архитектура IA-32 требует создания и использования _как минимум_ одного TSS, " +"если используются механизмы многозадачности или определены различные уровни " +"привилегий. Поскольку клиент [.filename]#boot2# выполняется на уровне " +"привилегий 3, а сервер BTX работает на уровне привилегий 0, необходимо " +"определить TSS:" + +#. 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 "" +"/*\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" + +#. 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 "[.filename]#stand/i386/btx/btx/btx.S# [[btx-tss]]" + +#. 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 "" +"Обратите внимание, что в TSS указано значение для указателя стека и сегмента " +"стека уровня привилегий 0. Это необходимо, потому что если прерывание или " +"исключение получено во время выполнения [.filename]#boot2# на уровне " +"привилегий 3, процессор автоматически переключается на уровень привилегий 0, " +"поэтому требуется новый рабочий стек. Наконец, полю базового адреса карты " +"ввода-вывода TSS присваивается значение, которое представляет собой 16-" +"битное смещение от начала TSS до битовой карты разрешений ввода-вывода и " +"битовой карты перенаправления прерываний." + +#. 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 "" +"После создания IDT и TSS процессор готов к переходу в защищённый режим. Это " +"выполняется в следующем блоке:" + +#. 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 "" +"/*\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" + +#. 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 "[.filename]#stand/i386/btx/btx/btx.S# [[btx-prot]]" + +#. 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 "" +"Сначала вызывается `setpic` для программирования 8259A PIC (программируемого " +"контроллера прерываний). Этот чип подключен к нескольким источникам " +"аппаратных прерываний. При получении прерывания от устройства он " +"сигнализирует процессору соответствующим вектором прерывания. Это можно " +"настроить так, чтобы определенные прерывания были связаны с конкретными " +"векторами прерываний, как объяснялось ранее. Затем регистры IDTR (Interrupt " +"Descriptor Table Register) и GDTR (Global Descriptor Table Register) " +"загружаются инструкциями `lidt` и `lgdt` соответственно. Эти регистры " +"загружаются базовым адресом и предельным адресом для IDT и GDT. Следующие " +"три инструкции устанавливают бит Protection Enable (PE) в регистре `%cr0`. " +"Это фактически переключает процессор в 32-битный защищенный режим. Затем " +"выполняется дальний переход на `init.8` с использованием селектора сегмента " +"SEL_SCODE, который выбирает сегмент кода супервизора (Supervisor Code " +"Segment). После этого перехода процессор фактически работает на уровне CPL 0 " +"— наиболее привилегированном уровне. Наконец, для стека выбирается сегмент " +"данных супервизора (Supervisor Data Segment) путем присвоения селектора " +"сегмента SEL_SDATA регистру `%ss`. Этот сегмент данных также имеет уровень " +"привилегий `0`." + +#. 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 "" +"Наш последний блок кода отвечает за загрузку TR (Регистра Задач) с " +"селектором сегмента для TSS, который мы создали ранее, и настройку окружения " +"пользовательского режима перед передачей управления исполнения клиенту " +"[.filename]#boot2#." + +#. 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 "" +"/*\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" + +#. 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 "[.filename]#stand/i386/btx/btx/btx.S# [[btx-end]]" + +#. 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 "" +"Обратите внимание, что среда клиента включает селектор сегмента стека и " +"указатель стека (регистры `%ss` и `%esp`). Действительно, как только TR " +"загружается соответствующим селектором сегмента стека (инструкция `ltr`), " +"указатель стека вычисляется и помещается в стек вместе с селектором сегмента " +"стека. Затем значение `0x202` помещается в стек; это значение, которое " +"EFLAGS получит при передаче управления клиенту. Также в стек помещаются " +"селектор сегмента кода пользовательского режима и точка входа клиента. " +"Напомним, что эта точка входа прописывается в заголовке BTX во время " +"компоновки. Наконец, селекторы сегментов (хранящиеся в регистре `%ecx`) для " +"регистров сегментов `%gs, %fs, %ds и %es` помещаются в стек вместе со " +"значением из `%edx` (`0xa000`). Примите во внимание эти значения, помещенные " +"в стек (они скоро будут извлечены). Затем значения для оставшихся регистров " +"общего назначения также помещаются в стек (обратите внимание на цикл `loop`, " +"который помещает значение `0` семь раз). Теперь начнётся извлечение значений " +"из стека. Сначала инструкция `popa` извлекает из стека последние семь " +"помещённых значений. Они сохраняются в регистрах общего назначения в порядке " +"`%edi, %esi, %ebp, %ebx, %edx, %ecx, %eax`. Затем различные селекторы " +"сегментов, помещённые в стек, извлекаются в соответствующие регистры " +"сегментов. В стеке остаются ещё пять значений. Они извлекаются при " +"выполнении инструкции `iret`. Эта инструкция сначала извлекает значение, " +"которое было помещено из заголовка BTX. Это значение является указателем на " +"точку входа [.filename]#boot2#. Оно помещается в регистр `%eip` — регистр " +"указателя инструкций. Затем селектор сегмента кода пользователя извлекается " +"и копируется в регистр `%cs`. Помните, что уровень привилегий этого сегмента " +"— 3, наименее привилегированный уровень. Это означает, что мы должны " +"предоставить значения для стека этого уровня привилегий. Именно поэтому " +"процессор, помимо дальнейшего извлечения значения для регистра EFLAGS, " +"выполняет ещё два извлечения из стека. Эти значения попадают в указатель " +"стека (`%esp`) и сегмент стека (`%ss`). Теперь выполнение продолжается с " +"точки входа ``boot0``." + +#. 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 "" +"Важно отметить, как определяется сегмент пользовательского кода. _Базовый " +"адрес_ этого сегмента установлен на `0xa000`. Это означает, что адреса " +"памяти кода являются _относительными_ к адресу 0xa000; если код, который " +"выполняется, извлекается из адреса `0x2000`, _фактический_ адрес в памяти " +"будет `0xa000+0x2000=0xc000`." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1155 +#, no-wrap +msgid "boot2 Stage" +msgstr "Этап загрузки boot2" + +#. 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 "" +"`boot2` определяет важную структуру, `struct bootinfo`. Эта структура " +"инициализируется `boot2` и передается загрузчику, а затем ядру. Некоторые " +"узлы этой структуры устанавливаются `boot2`, остальные — загрузчиком. Эта " +"структура, среди прочей информации, содержит имя файла ядра, геометрию " +"жесткого диска в BIOS, номер диска в BIOS для загрузочного устройства, " +"доступную физическую память, указатель `envp` и т.д. Ее определение выглядит " +"так:" + +#. 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 "" +"/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" + +#. 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 "" +"`boot2` входит в бесконечный цикл, ожидая ввода пользователя, затем вызывает " +"`load()`. Если пользователь ничего не нажимает, цикл прерывается по " +"таймауту, и `load()` загружает файл по умолчанию ([.filename]#/boot/" +"loader#). Функции `ino_t lookup(char *filename)` и `int xfsread(ino_t inode, " +"void *buf, size_t nbyte)` используются для чтения содержимого файла в " +"память. [.filename]#/boot/loader# — это ELF-бинарный файл, но с заголовком " +"ELF, перед которым добавлена структура `struct exec` из [.filename]#a.out#. " +"`load()` анализирует ELF-заголовок загрузчика, загружает содержимое " +"[.filename]#/boot/loader# в память и передаёт управление на точку входа " +"загрузчика:" + +#. 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 "" +"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" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1204 +#, no-wrap +msgid "loader Stage" +msgstr "Этап загрузчика (loader)" + +#. 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 "" +"Загрузчик также является клиентом BTX. Я не буду подробно описывать его " +"здесь, существует исчерпывающая man-страница, написанная Майком Смитом: " +"man:loader[8]. Основные механизмы и BTX были рассмотрены выше." + +#. 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 "" +"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" + +#. 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 "" +"Давайте рассмотрим команду, которая компонует ядро. Это поможет определить " +"точное местоположение, где загрузчик передает выполнение ядру. Это " +"местоположение является фактической точкой входа ядра. Данная команда теперь " +"исключена из [.filename]#sys/conf/Makefile.i386#. Интересующее нас " +"содержимое можно найти в [.filename]#/usr/obj/usr/src/i386.i386/sys/GENERIC/" +"#." + +#. 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" +"\n" +msgstr "" +"/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" +"\n" + +#. 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 "" +"Вот несколько интересных наблюдений. Во-первых, ядро представляет собой " +"динамически связанный бинарный файл ELF, но динамический компоновщик для " +"ядра — это [.filename]#/red/herring#, что явно является фиктивным файлом. Во-" +"вторых, взглянув на файл [.filename]#sys/conf/ldscript.i386#, можно понять, " +"какие параметры ld используются при компиляции ядра. Читая первые несколько " +"строк, видим, что строка" + +#. 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 "" +"sys/conf/ldscript.i386:\n" +"ENTRY(btext)\n" + +#. 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 "" +"говорит, что точка входа ядра — это символ `btext`. Этот символ определён в " +"[.filename]#locore.s#:" + +#. 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 "" +"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" + +#. 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 "" +"Сначала регистр EFLAGS устанавливается в предопределённое значение " +"0x00000002. Затем инициализируются все сегментные регистры:" + +#. 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 "" +"sys/i386/i386/locore.s:\n" +"/* Don't trust what the BIOS gives for eflags. */\n" +"\tpushl\t$PSL_KERNEL\n" +"\tpopfl\n" + +#. 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 "" +"/*\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" + +#. 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 "" +"btext вызывает подпрограммы `recover_bootinfo()` и `identify_cpu()`, которые " +"также определены в [.filename]#locore.s#. Вот описание их функций:" + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1290 +#, no-wrap +msgid "`recover_bootinfo`" +msgstr "`recover_bootinfo`" + +#. 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 "" +"Эта процедура разбирает параметры, переданные ядру при загрузке.\n" +"Ядро могло быть загружено тремя способами: загрузчиком (как описано выше), старыми загрузочными блоками диска или по старой процедуре загрузки без диска.\n" +"Эта функция определяет метод загрузки и сохраняет структуру `struct bootinfo` в памяти ядра." + +#. type: Table +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1295 +#, no-wrap +msgid "`identify_cpu`" +msgstr "`identify_cpu`" + +#. 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 "Эта функция пытается определить, на каком процессоре она выполняется, сохраняя найденное значение в переменной `_cpu`." + +#. 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 "" +"Следующие шаги включают активацию VME, если процессор поддерживает эту " +"функцию:" + +#. 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 "" +"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" + +#. 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 "" +"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" + +#. 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 "" +"sys/i386/i386/mpboot.s:\n" +"\tpushl\t$mp_begin\t\t\t\t/* jump to high mem */\n" +"\tret\n" + +#. 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 "" +"/* now running relocated at KERNBASE where the system is linked to run */\n" +"mp_begin:\t/* now running relocated at KERNBASE */\n" + +#. 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 "" +"Функция `init386()` вызывается с указателем на первую свободную физическую " +"страницу, после чего следует вызов `mi_startup()`. `init386` — это " +"архитектурно-зависимая функция инициализации, а `mi_startup()` — " +"архитектурно-независимая (префикс 'mi_' означает Machine Independent, то " +"есть «независимая от машины»). Ядро никогда не возвращается из " +"`mi_startup()`, и, вызывая её, завершает загрузку:" + +#. 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 "" +"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" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1349 +#, no-wrap +msgid "`init386()`" +msgstr "`init386()`" + +#. 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 "" +"`init386()` определена в [.filename]#sys/i386/i386/machdep.c# и выполняет " +"низкоуровневую инициализацию, специфичную для чипа i386. Переход в " +"защищённый режим был выполнен загрузчиком. Загрузчик создал самую первую " +"задачу, в которой ядро продолжает работать. Прежде чем рассматривать код, " +"рассмотрим задачи, которые процессор должен выполнить для инициализации " +"выполнения в защищённом режиме:" + +#. 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 "Подготовить GDT." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1358 +msgid "Prepare the IDT." +msgstr "Подготовить IDT." + +#. 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 "Инициализировать DDB, если он скомпилирован в ядро." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1361 +msgid "Initialize the TSS." +msgstr "Инициализировать TSS." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1362 +msgid "Prepare the LDT." +msgstr "Подготовить LDT." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1363 +msgid "Set up thread0's pcb." +msgstr "Настройка pcb для thread0." + +#. 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 "" +"`init386()` инициализирует настраиваемые параметры, переданные из bootstrap, " +"устанавливая указатель окружения (envp) и вызывая `init_param1()`. Указатель " +"envp был передан из loader в структуре `bootinfo`:" + +#. 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 "" +"sys/i386/i386/machdep.c:\n" +"\t/* Init basic tunables, hz etc */\n" +"\tinit_param1();\n" + +#. 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 "" +"`init_param1()` определена в [.filename]#sys/kern/subr_param.c#. Этот файл " +"содержит ряд sysctl, а также две функции, `init_param1()` и `init_param2()`, " +"которые вызываются из `init386()`:" + +#. 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 "" +"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" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1387 +msgid "" +"TUNABLE__FETCH is used to fetch the value from the environment:" +msgstr "" +"`TUNABLE__FETCH` используется для получения значения из окружения:" + +#. 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 "" +"/usr/src/sys/sys/kernel.h:\n" +"#define\tTUNABLE_INT_FETCH(path, var)\tgetenv_int((path), (var))\n" + +#. 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 "" +"Sysctl `kern.hz` представляет собой такт системных часов. Кроме того, эти " +"параметры sysctl устанавливаются функцией `init_param1()`: `kern.maxswzone, " +"kern.maxbcache, kern.maxtsiz, kern.dfldsiz, kern.maxdsiz, kern.dflssiz, " +"kern.maxssiz, kern.sgrowsiz`." + +#. 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 "" +"Затем `init386()` подготавливает Глобальную Таблицу Дескрипторов (GDT). " +"Каждая задача на x86 выполняется в своем собственном виртуальном адресном " +"пространстве, и это пространство адресуется парой сегмент:смещение. " +"Например, если текущая инструкция, которую должен выполнить процессор, " +"находится по адресу CS:EIP, то линейный виртуальный адрес этой инструкции " +"будет \"виртуальный адрес кодового сегмента CS\" + EIP. Для удобства " +"сегменты начинаются с виртуального адреса 0 и заканчиваются на границе 4 ГБ. " +"Таким образом, линейный виртуальный адрес инструкции в данном примере будет " +"просто значением EIP. Сегментные регистры, такие как CS, DS и другие, " +"являются селекторами, то есть индексами в GDT (если быть более точным, " +"индекс — это не сам селектор, а поле INDEX в селекторе). GDT в FreeBSD " +"содержит дескрипторы для 15 селекторов на каждый CPU:" + +#. 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 "" +"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" + +#. 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 "" +"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" + +#. 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 "" +"Обратите внимание, что эти `#defines` не являются самими селекторами, а лишь " +"полем `INDEX` селектора, поэтому они точно соответствуют индексам GDT. " +"Например, реальный селектор для кода ядра (`GCODE_SEL`) имеет значение " +"`0x20`." + +#. 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 "" +"Следующий шаг — инициализация таблицы дескрипторов прерываний (IDT). Эта " +"таблица используется процессором при возникновении программного или " +"аппаратного прерывания. Например, чтобы выполнить системный вызов, " +"пользовательское приложение использует инструкцию `INT 0x80`. Это " +"программное прерывание, поэтому аппаратное обеспечение процессора ищет " +"запись с индексом 0x80 в IDT. Эта запись указывает на процедуру обработки " +"данного прерывания, в данном конкретном случае это будет шлюз системных " +"вызовов ядра. IDT может содержать максимум 256 (0x100) записей. Ядро " +"выделяет NIDT записей для IDT, где NIDT — это максимум (256):" + +#. 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 "" +"sys/i386/i386/machdep.c:\n" +"static struct gate_descriptor idt0[NIDT];\n" +"struct gate_descriptor *idt = &idt0[0];\t/* interrupt descriptor table */\n" + +#. 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 "" +"Для каждого прерывания устанавливается соответствующий обработчик. Также " +"настраивается шлюз системного вызова для `INT 0x80`:" + +#. 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 "" +"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" + +#. 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 "" +"Итак, когда пользовательское приложение выполняет инструкцию `INT 0x80`, " +"управление передаётся функции `_Xint0x80_syscall`, которая находится в " +"сегменте кода ядра и будет выполнена с привилегиями супервизора." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1468 +msgid "Console and DDB are then initialized:" +msgstr "Консоль и DDB инициализируются:" + +#. 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 "" +"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" + +#. 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 "" +"Сегмент состояния задачи (TSS) — это еще одна структура защищенного режима " +"x86, используемая оборудованием для хранения информации о задаче при " +"переключении задач." + +#. 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 "" +"Локальная таблица дескрипторов (LDT) используется для ссылки на код и данные " +"пользовательского пространства. Определено несколько селекторов, указывающих " +"на LDT, включая шлюзы системных вызовов, а также селекторы кода и данных " +"пользователя:" + +#. 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 "" +"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" + +#. 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 "" +"Далее инициализируется структура Блока Управления Процессом (`struct pcb`) " +"для proc0. proc0 — это структура `struct proc`, описывающая процесс ядра. " +"Она всегда присутствует во время работы ядра, поэтому связана с thread0:" + +#. 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 "" +"sys/i386/i386/machdep.c:\n" +"register_t\n" +"init386(int first)\n" +"{\n" +" /* ... skipped ... */\n" + +#. 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 "" +" proc_linkup0(&proc0, &thread0);\n" +" /* ... skipped ... */\n" +"}\n" + +#. 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 "" +"Структура `struct pcb` является частью структуры proc. Она определена в " +"[.filename]#/usr/include/machine/pcb.h# и содержит информацию процесса, " +"специфичную для архитектуры i386, такую как значения регистров." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1516 +#, no-wrap +msgid "`mi_startup()`" +msgstr "`mi_startup()`" + +#. 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 "" +"sys/kern/init_main.c:\n" +"\tfor (sipp = sysinit; sipp < sysinit_end; sipp++) {\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1526 +#, no-wrap +msgid "\t\t/* ... skipped ... */\n" +msgstr "\t\t/* ... skipped ... */\n" + +#. 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 "" +"\t\t/* Call function */\n" +"\t\t(*((*sipp)->func))((*sipp)->udata);\n" +"\t\t/* ... skipped ... */\n" +"\t}\n" + +#. 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 "" +"Хотя фреймворк sysinit описан в link:/books/developers-handbook[Руководстве " +"разработчика], я рассмотрю его внутреннее устройство." + +#. 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 "" +"Каждый объект инициализации системы (объект sysinit) создается путем вызова " +"макроса SYSINIT(). Возьмем, к примеру, объект sysinit `announce`. Этот " +"объект выводит сообщение об авторских правах:" + +#. 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 "" +"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" + +#. 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 "" +"Идентификатор подсистемы для этого объекта — SI_SUB_COPYRIGHT (0x0800001). " +"Таким образом, сообщение об авторских правах будет выведено первым, сразу " +"после инициализации консоли." + +#. 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 "" +"Давайте рассмотрим, что именно делает макрос `SYSINIT()`. Он раскрывается в " +"макрос `C_SYSINIT()`. Макрос `C_SYSINIT()` затем раскрывается в статическое " +"объявление структуры `struct sysinit` с вызовом другого макроса `DATA_SET`:" + +#. 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 "" +"/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" + +#. 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 "" +"#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" + +#. 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 "" +"Макрос `DATA_SET()` раскрывается в `_MAKE_SET()`, и именно в этом макросе " +"скрыта вся магия инициализации системы:" + +#. 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 "" +"/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" + +#. 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 "" +"После выполнения этих макросов в ядре были созданы различные разделы, " +"включая `set.sysinit_set`. Запустив objdump для бинарного файла ядра, можно " +"заметить наличие таких небольших разделов:" + +#. 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 "" +"% 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" + +#. 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 "" +"Это содержимое экрана показывает, что размер раздела set.sysinit_set " +"составляет 0x14d8 байт, поэтому `0x14d8/sizeof(void *)` объектов sysinit " +"скомпилировано в ядро. Другие разделы, такие как `set.sysctl_set`, " +"представляют другие наборы компоновщика." + +#. 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 "" +"Определяя переменную типа `struct sysinit`, содержимое раздела " +"`set.sysinit_set` будет \"собрано\" в эту переменную:" + +#. 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 "" +"sys/kern/init_main.c:\n" +" SET_DECLARE(sysinit_set, struct sysinit);\n" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/boot/_index.adoc:1608 +msgid "The `struct sysinit` is defined as follows:" +msgstr "`struct sysinit` определена следующим образом:" + +#. 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 "" +"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" + +#. 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 "" +"Возвращаясь к обсуждению `mi_startup()`, теперь должно быть понятно, как " +"организованы объекты sysinit. Функция `mi_startup()` сортирует их и вызывает " +"каждый. Самый последний объект — это системный планировщик:" + +#. 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 "" +"/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" + +#. 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 "" +"Системный планировщик sysinit определен в файле [.filename]#sys/vm/" +"vm_glue.c#, а точка входа для этого объекта — `scheduler()`. Эта функция " +"фактически представляет собой бесконечный цикл и описывает процесс с PID 0, " +"известный как процесс swapper. Структура thread0, упомянутая ранее, " +"используется для его описания." + +#. 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 "" +"Первый пользовательский процесс, называемый _init_, создаётся объектом " +"sysinit `init`:" + +#. 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 "" +"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" + +#. 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 "" +"\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" + +#. 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 "" +"Функция `create_init()` выделяет новый процесс, вызывая `fork1()`, но не " +"помечает его как готовый к выполнению. Когда этот новый процесс будет " +"запланирован для выполнения планировщиком, будет вызвана функция " +"`start_init()`. Эта функция определена в [.filename]#init_main.c#. Она " +"пытается загрузить и выполнить бинарный файл [.filename]#init#, сначала " +"проверяя [.filename]#/sbin/init#, затем [.filename]#/sbin/oinit#, " +"[.filename]#/sbin/init.bak# и, наконец, [.filename]#/rescue/init#:" + +#. 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 "" +"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" diff --git a/documentation/content/ru/books/arch-handbook/driverbasics/_index.adoc b/documentation/content/ru/books/arch-handbook/driverbasics/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/driverbasics/_index.adoc @@ -0,0 +1,347 @@ +--- +description: 'Написание драйверов устройств для FreeBSD' +next: books/arch-handbook/isa +params: + path: /books/arch-handbook/driverbasics/ +prev: books/arch-handbook/partii +showBookMenu: true +tags: ["writing", "device drivers", "KLD", "FreeBSD"] +title: 'Глава 9. Написание драйверов устройств для FreeBSD' +weight: 11 +--- + +[[driverbasics]] += Написание драйверов устройств для FreeBSD +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 9 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[driverbasics-intro]] +== Введение + +В этой главе представлено краткое введение в написание драйверов устройств для FreeBSD. Устройство в данном контексте — это термин, используемый в основном для аппаратных компонентов системы, таких как диски, принтеры или графический дисплей с клавиатурой. Драйвер устройства — это программный компонент операционной системы, который управляет конкретным устройством. Также существуют так называемые псевдоустройства, где драйвер эмулирует поведение устройства программно, без использования какого-либо конкретного аппаратного обеспечения. Драйверы устройств могут быть статически скомпилированы в систему или загружены по требованию через механизм динамической загрузки модулей ядра `kld`. + +Большинство устройств в операционной системе, подобной UNIX(R), доступны через специальные файлы устройств, также называемые узлами устройств. Эти файлы обычно расположены в каталоге [.filename]#/dev# в иерархии файловой системы. + +Драйверы устройств можно условно разделить на две категории: символьные драйверы и драйверы сетевых устройств. + +[[driverbasics-kld]] +== Динамический загрузчик модулей ядра - KLD + +Интерфейс kld позволяет системным администраторам динамически добавлять и удалять функциональность в работающей системе. Это позволяет разработчикам драйверов устройств загружать свои новые изменения в работающее ядро без постоянной перезагрузки для проверки изменений. + +Интерфейс kld используется с помощью следующих команд: + +* `kldload` - загружает новый модуль ядра +* `kldunload` — выгружает модуль ядра +* `kldstat` — выводит список загруженных модулей + +Каркасная структура модуля ядра + +[.programlisting] +.... +/* + * KLD Skeleton + * Inspired by Andrew Reiter's Daemonnews article + */ + +#include +#include /* uprintf */ +#include +#include /* defines used in kernel.h */ +#include +#include /* types used in module initialization */ + +/* + * Load handler that deals with the loading and unloading of a KLD. + */ + +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); +} + +/* Declare this module to the rest of the kernel */ + +static moduledata_t skel_mod = { + "skel", + skel_loader, + NULL +}; + +DECLARE_MODULE(skeleton, skel_mod, SI_SUB_KLD, SI_ORDER_ANY); +.... + +=== Makefile + +FreeBSD предоставляет системный makefile для упрощения компиляции модуля ядра. + +[.programlisting] +.... +SRCS=skeleton.c +KMOD=skeleton + +.include +.... + +Запуск `make` с этим makefile создаст файл [.filename]#skeleton.ko#, который можно загрузить в ядро, набрав: + +[source, bash] +.... +# kldload -v ./skeleton.ko +.... + +[[driverbasics-char]] +== Символьные устройства + +Драйвер символьного устройства — это драйвер, который передает данные напрямую между устройством и пользовательским процессом. Это наиболее распространенный тип драйвера устройств, и в дереве исходного кода есть множество простых примеров. + +Этот простой пример псевдоустройства запоминает все значения, записанные в него, и может затем воспроизводить их при чтении. + +.Пример образца драйвера псевдоустройства Echo для FreeBSD 10.X - 12.X +[example] +==== +[.programlisting] +.... +/* + * Simple Echo pseudo-device KLD + * + * Murray Stokely + * Søren (Xride) Straarup + * Eitan Adler + */ + +#include +#include /* uprintf */ +#include /* defines used in kernel.h */ +#include +#include /* types used in module initialization */ +#include /* cdevsw struct */ +#include /* uio struct */ +#include + +#define BUFFERSIZE 255 + +/* Function prototypes */ +static d_open_t echo_open; +static d_close_t echo_close; +static d_read_t echo_read; +static d_write_t echo_write; + +/* Character device entry points */ +static struct cdevsw echo_cdevsw = { + .d_version = D_VERSION, + .d_open = echo_open, + .d_close = echo_close, + .d_read = echo_read, + .d_write = echo_write, + .d_name = "echo", +}; + +struct s_echo { + char msg[BUFFERSIZE + 1]; + int len; +}; + +/* vars */ +static struct cdev *echo_dev; +static struct s_echo *echomsg; + +MALLOC_DECLARE(M_ECHOBUF); +MALLOC_DEFINE(M_ECHOBUF, "echobuffer", "buffer for echo module"); + +/* + * This function is called by the kld[un]load(2) system calls to + * determine what actions to take when a module is loaded or unloaded. + */ +static int +echo_loader(struct module *m __unused, int what, void *arg __unused) +{ + int error = 0; + + switch (what) { + case MOD_LOAD: /* kldload */ + error = make_dev_p(MAKEDEV_CHECKNAME | MAKEDEV_WAITOK, + &echo_dev, + &echo_cdevsw, + 0, + UID_ROOT, + GID_WHEEL, + 0600, + "echo"); + if (error != 0) + break; + + echomsg = malloc(sizeof(*echomsg), M_ECHOBUF, M_WAITOK | + M_ZERO); + printf("Echo device loaded.\n"); + break; + case MOD_UNLOAD: + destroy_dev(echo_dev); + free(echomsg, M_ECHOBUF); + printf("Echo device unloaded.\n"); + break; + default: + error = EOPNOTSUPP; + break; + } + return (error); +} + +static int +echo_open(struct cdev *dev __unused, int oflags __unused, int devtype __unused, + struct thread *td __unused) +{ + int error = 0; + + uprintf("Opened device \"echo\" successfully.\n"); + return (error); +} + +static int +echo_close(struct cdev *dev __unused, int fflag __unused, int devtype __unused, + struct thread *td __unused) +{ + + uprintf("Closing device \"echo\".\n"); + return (0); +} + +/* + * The read function just takes the buf that was saved via + * echo_write() and returns it to userland for accessing. + * uio(9) + */ +static int +echo_read(struct cdev *dev __unused, struct uio *uio, int ioflag __unused) +{ + size_t amt; + int error; + + /* + * How big is this read operation? Either as big as the user wants, + * or as big as the remaining data. Note that the 'len' does not + * include the trailing null character. + */ + amt = MIN(uio->uio_resid, uio->uio_offset >= echomsg->len + 1 ? 0 : + echomsg->len + 1 - uio->uio_offset); + + if ((error = uiomove(echomsg->msg, amt, uio)) != 0) + uprintf("uiomove failed!\n"); + + return (error); +} + +/* + * echo_write takes in a character string and saves it + * to buf for later accessing. + */ +static int +echo_write(struct cdev *dev __unused, struct uio *uio, int ioflag __unused) +{ + size_t amt; + int error; + + /* + * We either write from the beginning or are appending -- do + * not allow random access. + */ + if (uio->uio_offset != 0 && (uio->uio_offset != echomsg->len)) + return (EINVAL); + + /* This is a new message, reset length */ + if (uio->uio_offset == 0) + echomsg->len = 0; + + /* Copy the string in from user memory to kernel memory */ + amt = MIN(uio->uio_resid, (BUFFERSIZE - echomsg->len)); + + error = uiomove(echomsg->msg + uio->uio_offset, amt, uio); + + /* Now we need to null terminate and record the length */ + echomsg->len = uio->uio_offset; + echomsg->msg[echomsg->len] = 0; + + if (error != 0) + uprintf("Write failed: bad address!\n"); + return (error); +} + +DEV_MODULE(echo, echo_loader, NULL); +.... +==== + +Загрузив этот драйвер, попробуйте: + +[source, bash] +.... +# echo -n "Test Data" > /dev/echo +# cat /dev/echo +Opened device "echo" successfully. +Test Data +Closing device "echo". +.... + +Реальные аппаратные устройства описаны в следующей главе. + +[[driverbasics-block]] +== Блочные устройства (удалены) + +Другие системы UNIX(R) могут поддерживать второй тип дисковых устройств, известный как блочные устройства. Блочные устройства — это дисковые устройства, для которых ядро предоставляет кэширование. Это кэширование делает блочные устройства практически непригодными или, по крайней мере, опасно ненадёжными. Кэширование изменяет порядок операций записи, лишая приложение возможности точно знать содержимое диска в любой момент времени. + +Это делает невозможным предсказуемое и надежное восстановление после сбоев для структур данных на диске (файловых систем, баз данных и т. д.). Поскольку операции записи могут быть отложены, ядро не может сообщить приложению, какая именно операция записи столкнулась с ошибкой, что усугубляет проблему согласованности. + +По этой причине ни одно серьезное приложение не полагается на блочные устройства, и фактически почти все приложения, которые обращаются к дискам напрямую, прилагают значительные усилия, чтобы указать, что следует всегда использовать символьные (или "сырые") устройства. Поскольку реализация псевдонимов для каждого диска (раздела) в виде двух устройств с разной семантикой значительно усложняла соответствующий код ядра, FreeBSD отказалась от поддержки кэшируемых дисковых устройств в рамках модернизации инфраструктуры ввода-вывода для дисков. + +[[driverbasics-net]] +== Драйверы сетевых устройств + +Драйверы сетевых устройств не используют узлы устройств для доступа. Их выбор основан на других решениях, принимаемых внутри ядра, и вместо вызова open() использование сетевого устройства обычно осуществляется через системный вызов socket(2). + +Для получения дополнительной информации см. ifnet(9), исходный текст устройства loopback. diff --git a/documentation/content/ru/books/arch-handbook/driverbasics/_index.po b/documentation/content/ru/books/arch-handbook/driverbasics/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/driverbasics/_index.po @@ -0,0 +1,867 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-03 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 "Написание драйверов устройств для FreeBSD" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:1 +#, no-wrap +msgid "Chapter 9. Writing FreeBSD Device Drivers" +msgstr "Глава 9. Написание драйверов устройств для FreeBSD" + +#. 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 "" +"В этой главе представлено краткое введение в написание драйверов устройств " +"для FreeBSD. Устройство в данном контексте — это термин, используемый в " +"основном для аппаратных компонентов системы, таких как диски, принтеры или " +"графический дисплей с клавиатурой. Драйвер устройства — это программный " +"компонент операционной системы, который управляет конкретным устройством. " +"Также существуют так называемые псевдоустройства, где драйвер эмулирует " +"поведение устройства программно, без использования какого-либо конкретного " +"аппаратного обеспечения. Драйверы устройств могут быть статически " +"скомпилированы в систему или загружены по требованию через механизм " +"динамической загрузки модулей ядра `kld`." + +#. 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 "" +"Большинство устройств в операционной системе, подобной UNIX(R), доступны " +"через специальные файлы устройств, также называемые узлами устройств. Эти " +"файлы обычно расположены в каталоге [.filename]#/dev# в иерархии файловой " +"системы." + +#. 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 "Динамический загрузчик модулей ядра - KLD" + +#. 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 "" +"Интерфейс kld позволяет системным администраторам динамически добавлять и " +"удалять функциональность в работающей системе. Это позволяет разработчикам " +"драйверов устройств загружать свои новые изменения в работающее ядро без " +"постоянной перезагрузки для проверки изменений." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:66 +msgid "The kld interface is used through:" +msgstr "Интерфейс kld используется с помощью следующих команд:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:68 +msgid "`kldload` - loads a new kernel module" +msgstr "`kldload` - загружает новый модуль ядра" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:69 +msgid "`kldunload` - unloads a kernel module" +msgstr "`kldunload` — выгружает модуль ядра" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:70 +msgid "`kldstat` - lists loaded modules" +msgstr "`kldstat` — выводит список загруженных модулей" + +#. 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 "" +"/*\n" +" * KLD Skeleton\n" +" * Inspired by Andrew Reiter's Daemonnews article\n" +" */\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:86 +#, no-wrap +msgid "" +"#include \n" +"#include /* uprintf */\n" +"#include \n" +"#include /* defines used in kernel.h */\n" +"#include \n" +"#include /* types used in module initialization */\n" +msgstr "" +"#include \n" +"#include /* uprintf */\n" +"#include \n" +"#include /* defines used in kernel.h */\n" +"#include \n" +"#include /* types used in module initialization */\n" + +#. 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 "" +"/*\n" +" * Load handler that deals with the loading and unloading of a KLD.\n" +" */\n" + +#. 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 "" +"static int\n" +"skel_loader(struct module *m, int what, void *arg)\n" +"{\n" +"\tint err = 0;\n" + +#. 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 "" +"\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" + +#. 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 "/* Declare this module to the rest of the kernel */\n" + +#. 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 "" +"static moduledata_t skel_mod = {\n" +"\t\"skel\",\n" +"\tskel_loader,\n" +"\tNULL\n" +"};\n" + +#. 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 "DECLARE_MODULE(skeleton, skel_mod, SI_SUB_KLD, SI_ORDER_ANY);\n" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:121 +#, no-wrap +msgid "Makefile" +msgstr "Makefile" + +#. 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 "" +"FreeBSD предоставляет системный makefile для упрощения компиляции модуля " +"ядра." + +#. 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 "" +"SRCS=skeleton.c\n" +"KMOD=skeleton\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:131 +#, no-wrap +msgid ".include \n" +msgstr ".include \n" + +#. 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 "" +"Запуск `make` с этим makefile создаст файл [.filename]#skeleton.ko#, который " +"можно загрузить в ядро, набрав:" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:138 +#, no-wrap +msgid "# kldload -v ./skeleton.ko\n" +msgstr "# kldload -v ./skeleton.ko\n" + +#. 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 "Пример образца драйвера псевдоустройства Echo для FreeBSD 10.X - 12.X" + +#. 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 "" +"/*\n" +" * Simple Echo pseudo-device KLD\n" +" *\n" +" * Murray Stokely\n" +" * Søren (Xride) Straarup\n" +" * Eitan Adler\n" +" */\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:168 +#, no-wrap +msgid "" +"#include \n" +"#include /* uprintf */\n" +"#include /* defines used in kernel.h */\n" +"#include \n" +"#include /* types used in module initialization */\n" +"#include /* cdevsw struct */\n" +"#include /* uio struct */\n" +"#include \n" +msgstr "" +"#include \n" +"#include /* uprintf */\n" +"#include /* defines used in kernel.h */\n" +"#include \n" +"#include /* types used in module initialization */\n" +"#include /* cdevsw struct */\n" +"#include /* uio struct */\n" +"#include \n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:170 +#, no-wrap +msgid "#define BUFFERSIZE 255\n" +msgstr "#define BUFFERSIZE 255\n" + +#. 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 "" +"/* 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" + +#. 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 "" +"/* 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" + +#. 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 "" +"struct s_echo {\n" +"\tchar msg[BUFFERSIZE + 1];\n" +"\tint len;\n" +"};\n" + +#. 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 "" +"/* vars */\n" +"static struct cdev *echo_dev;\n" +"static struct s_echo *echomsg;\n" + +#. 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 "" +"MALLOC_DECLARE(M_ECHOBUF);\n" +"MALLOC_DEFINE(M_ECHOBUF, \"echobuffer\", \"buffer for echo module\");\n" + +#. 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 "" +"/*\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" + +#. 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 "" +"\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" + +#. 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 "" +"\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" + +#. 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 "" +"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" + +#. 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 "" +"\tuprintf(\"Opened device \\\"echo\\\" successfully.\\n\");\n" +"\treturn (error);\n" +"}\n" + +#. 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 "" +"static int\n" +"echo_close(struct cdev *dev __unused, int fflag __unused, int devtype __unused,\n" +" struct thread *td __unused)\n" +"{\n" + +#. 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 "" +"\tuprintf(\"Closing device \\\"echo\\\".\\n\");\n" +"\treturn (0);\n" +"}\n" + +#. 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 "" +"/*\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" + +#. 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 "" +"\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" + +#. 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 "" +"\tif ((error = uiomove(echomsg->msg, amt, uio)) != 0)\n" +"\t\tuprintf(\"uiomove failed!\\n\");\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/driverbasics/_index.adoc:280 +#, no-wrap +msgid "" +"\treturn (error);\n" +"}\n" +msgstr "" +"\treturn (error);\n" +"}\n" + +#. 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 "" +"/*\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" + +#. 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 "" +"\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" + +#. 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 "" +"\t/* This is a new message, reset length */\n" +"\tif (uio->uio_offset == 0)\n" +"\t\techomsg->len = 0;\n" + +#. 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 "" +"\t/* Copy the string in from user memory to kernel memory */\n" +"\tamt = MIN(uio->uio_resid, (BUFFERSIZE - echomsg->len));\n" + +#. 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 "\terror = uiomove(echomsg->msg + uio->uio_offset, amt, uio);\n" + +#. 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 "" +"\t/* Now we need to null terminate and record the length */\n" +"\techomsg->len = uio->uio_offset;\n" +"\techomsg->msg[echomsg->len] = 0;\n" + +#. 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 "" +"\tif (error != 0)\n" +"\t\tuprintf(\"Write failed: bad address!\\n\");\n" +"\treturn (error);\n" +"}\n" + +#. 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 "DEV_MODULE(echo, echo_loader, NULL);\n" + +#. 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 "" +"# echo -n \"Test Data\" > /dev/echo\n" +"# cat /dev/echo\n" +"Opened device \"echo\" successfully.\n" +"Test Data\n" +"Closing device \"echo\".\n" + +#. 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 "" +"Другие системы UNIX(R) могут поддерживать второй тип дисковых устройств, " +"известный как блочные устройства. Блочные устройства — это дисковые " +"устройства, для которых ядро предоставляет кэширование. Это кэширование " +"делает блочные устройства практически непригодными или, по крайней мере, " +"опасно ненадёжными. Кэширование изменяет порядок операций записи, лишая " +"приложение возможности точно знать содержимое диска в любой момент времени." + +#. 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 "" +"По этой причине ни одно серьезное приложение не полагается на блочные " +"устройства, и фактически почти все приложения, которые обращаются к дискам " +"напрямую, прилагают значительные усилия, чтобы указать, что следует всегда " +"использовать символьные (или \"сырые\") устройства. Поскольку реализация " +"псевдонимов для каждого диска (раздела) в виде двух устройств с разной " +"семантикой значительно усложняла соответствующий код ядра, FreeBSD " +"отказалась от поддержки кэшируемых дисковых устройств в рамках модернизации " +"инфраструктуры ввода-вывода для дисков." + +#. 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 "" +"Драйверы сетевых устройств не используют узлы устройств для доступа. Их " +"выбор основан на других решениях, принимаемых внутри ядра, и вместо вызова " +"open() использование сетевого устройства обычно осуществляется через " +"системный вызов socket(2)." + +#. 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 "" +"Для получения дополнительной информации см. ifnet(9), исходный текст " +"устройства loopback." diff --git a/documentation/content/ru/books/arch-handbook/isa/_index.adoc b/documentation/content/ru/books/arch-handbook/isa/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/isa/_index.adoc @@ -0,0 +1,1121 @@ +--- +description: 'Драйверы устройств ISA' +next: books/arch-handbook/pci +params: + path: /books/arch-handbook/isa/ +prev: books/arch-handbook/driverbasics +showBookMenu: true +tags: ["ISA", "device drivers", "FreeBSD"] +title: 'Глава 10. Драйверы устройств ISA' +weight: 12 +--- + +[[isa-driver]] += Драйверы устройств ISA +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 10 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[isa-driver-synopsis]] +== Обзор + +Эта глава знакомит с вопросами, относящимся к написанию драйвера устройства ISA. Представленный здесь псевдокод довольно детализирован и напоминает реальный код, но всё же остаётся псевдокодом. Он избегает деталей, не относящихся к теме обсуждения. Реальные примеры можно найти в исходном коде настоящих драйверов. В частности, драйверы `ep` и `aha` являются хорошими источниками информации. + +[[isa-driver-basics]] +== Основная информация + +Типичному драйверу ISA могут потребоваться следующие включаемые файлы: + +[.programlisting] +.... +#include +#include +#include +#include +#include + +#include +#include +.... + +Они описывают особенности, специфичные для подсистемы ISA и обобщенной шины. + +Подсистема шины реализована в объектно-ориентированном стиле, её основные структуры доступны через методы, связанные с объектами. + +Список методов шины, реализуемых драйвером ISA, аналогичен списку для любой другой шины. Для гипотетического драйвера с именем "xxx" они будут: + +* `static void xxx_isa_identify (driver_t *, device_t);` Обычно используется для драйверов шины, а не для драйверов устройств. Однако для устройств ISA этот метод может иметь особое применение: если устройство предоставляет специфический (не PnP) способ автоматического обнаружения устройств, эта процедура может его реализовывать. +* `static int xxx_isa_probe (device_t dev);` Проверка наличия устройства в известном (или PnP) расположении. Эта процедура также может учитывать автоопределение параметров, специфичных для устройства, в случае частично настроенных устройств. +* `static int xxx_isa_attach (device_t dev);` Подключение и инициализация устройства. +* `static int xxx_isa_detach (device_t dev);` Отсоединение устройства перед выгрузкой модуля драйвера. +* `static int xxx_isa_shutdown (device_t dev);` Выполняет завершение работы устройства перед выключением системы. +* `static int xxx_isa_suspend (device_t dev);` Приостанавливает устройство перед переходом системы в энергосберегающий режим. Также может прервать переход в энергосберегающий режим. +* `static int xxx_isa_resume (device_t dev);` Возобновляет активность устройства после возврата из энергосберегающего состояния. + +`xxx_isa_probe()` и `xxx_isa_attach()` являются обязательными, остальные процедуры опциональны и зависят от потребностей устройства. + +Драйвер связан с системой следующим набором описаний. + +[.programlisting] +.... + /* table of supported bus methods */ + static device_method_t xxx_isa_methods[] = { + /* list all the bus method functions supported by the driver */ + /* omit the unsupported methods */ + DEVMETHOD(device_identify, xxx_isa_identify), + DEVMETHOD(device_probe, xxx_isa_probe), + DEVMETHOD(device_attach, xxx_isa_attach), + DEVMETHOD(device_detach, xxx_isa_detach), + DEVMETHOD(device_shutdown, xxx_isa_shutdown), + DEVMETHOD(device_suspend, xxx_isa_suspend), + DEVMETHOD(device_resume, xxx_isa_resume), + + DEVMETHOD_END + }; + + static driver_t xxx_isa_driver = { + "xxx", + xxx_isa_methods, + sizeof(struct xxx_softc), + }; + + static devclass_t xxx_devclass; + + DRIVER_MODULE(xxx, isa, xxx_isa_driver, xxx_devclass, + load_function, load_argument); +.... + +Здесь структура `xxx_softc` — это специфичная для устройства структура, которая содержит приватные данные драйвера и дескрипторы ресурсов драйвера. Код шины автоматически выделяет один дескриптор softc для каждого устройства по мере необходимости. + +Если драйвер реализован в виде загружаемого модуля, то `load_function()` вызывается для выполнения специфичной для драйвера инициализации или очистки при загрузке или выгрузке драйвера, а `load_argument` передаётся в качестве одного из её аргументов. Если драйвер не поддерживает динамическую загрузку (другими словами, он всегда должен быть связан с ядром), то эти значения должны быть установлены в 0, и последнее определение будет выглядеть следующим образом: + +[.programlisting] +.... + DRIVER_MODULE(xxx, isa, xxx_isa_driver, + xxx_devclass, 0, 0); +.... + +Если драйвер предназначен для устройства с поддержкой PnP, то должна быть определена таблица поддерживаемых PnP ID. Таблица состоит из списка PnP ID, поддерживаемых этим драйвером, и удобочитаемых описаний типов аппаратного обеспечения и моделей, имеющих эти ID. Это выглядит следующим образом: + +[.programlisting] +.... + static struct isa_pnp_id xxx_pnp_ids[] = { + /* a line for each supported PnP ID */ + { 0x12345678, "Our device model 1234A" }, + { 0x12345679, "Our device model 1234B" }, + { 0, NULL }, /* end of table */ + }; +.... + +Если драйвер не поддерживает устройства PnP, ему все равно нужна пустая таблица идентификаторов PnP, например: + +[.programlisting] +.... + static struct isa_pnp_id xxx_pnp_ids[] = { + { 0, NULL }, /* end of table */ + }; +.... + +[[isa-driver-device-t]] +== Указатель `device_t` + +`device_t` — это тип указателя на структуру устройства. Здесь мы рассматриваем только методы, представляющие интерес с точки зрения разработчика драйверов устройств. Методы для работы со значениями в структуре устройства следующие: + +* `device_t device_get_parent(dev)` Получить родительскую шину устройства. +* `driver_t device_get_driver(dev)` Получить указатель на структуру его драйвера. +* `char *device_get_name(dev)` Получить имя драйвера, например `"xxx"` в нашем примере. +* `int device_get_unit(dev)` Получить номер устройства (устройства нумеруются с 0 для устройств, связанных с каждым драйвером). +* `char *device_get_nameunit(dev)` Получить имя устройства, включая номер юнита, например, "xxx0", "xxx1" и так далее. +* `char *device_get_desc(dev)` Получить описание устройства. Обычно оно описывает точную модель устройства в удобочитаемом виде. +* `device_set_desc(dev, desc)` Установить описание. Это заставляет описание устройства указывать на строку desc, которая не может быть освобождена или изменена после этого. +* `device_set_desc_copy(dev, desc)` Устанавить описание. Описание копируется во внутренний динамически выделяемый буфер, поэтому строка desc может быть изменена впоследствии без негативных последствий. +* `void *device_get_softc(dev)` Получить указатель на дескриптор устройства (структура `xxx_softc`), связанный с данным устройством. +* `u_int32_t device_get_flags(dev)` Получить флаги, указанные для устройства в файле конфигурации. + +Функция для удобства `device_printf(dev, fmt, ...)` может использоваться для вывода сообщений из драйвера устройства. Она автоматически добавляет имя устройства и двоеточие перед сообщением. + +Методы device_t реализованы в файле [.filename]#kern/bus_subr.c#. + +[[isa-driver-config]] +== Файл конфигурации и порядок определения и проверки при автоматической настройке + +Устройства ISA описываются в файле конфигурации ядра следующим образом: + +[.programlisting] +.... +device xxx0 at isa? port 0x300 irq 10 drq 5 + iomem 0xd0000 flags 0x1 sensitive +.... + +Значения порта, IRQ и т. д. преобразуются в ресурсы, связанные с устройством. Они являются необязательными, в зависимости от потребностей устройства и его способностей к автонастройке. Например, некоторым устройствам вообще не нужен DRQ, а некоторые позволяют драйверу читать настройку IRQ из портов конфигурации устройства. Если в машине несколько шин ISA, точная шина может быть указана в строке конфигурации, например `isa0` или `isa1`, иначе устройство будет искаться на всех шинах ISA. + +`sensitive` — это ресурс, указывающий, что данное устройство должно быть проверено перед всеми нечувствительными устройствами. Он поддерживается, но, похоже, не используется ни в одном текущем драйвере. + +Для устаревших устройств ISA во многих случаях драйверы всё ещё могут определять параметры конфигурации. Однако каждое устройство, которое необходимо настроить в системе, должно иметь строку конфигурации. Если в системе установлено два устройства одного типа, но для соответствующего драйвера есть только одна строка конфигурации, например: +[.programlisting] +.... +device xxx0 at isa? +.... + тогда будет настроено только одно устройство. + +Однако для устройств, поддерживающих автоматическую идентификацию с помощью Plug-n-Play или какого-либо проприетарного протокола, достаточно одной строки конфигурации для настройки всех устройств в системе, как в примере выше или просто: + +[.programlisting] +.... +device xxx at isa? +.... + +Если драйвер поддерживает как автоматически определяемые, так и устаревшие устройства, и оба типа установлены одновременно в одной машине, то достаточно описать в конфигурационном файле только устаревшие устройства. Автоматически определяемые устройства будут добавлены автоматически. + +При автоматической настройке шины ISA события происходят в следующем порядке: + +Все процедуры идентификации драйверов (включая процедуру идентификации PnP, которая определяет все устройства PnP) вызываются в случайном порядке. Когда они идентифицируют устройства, они добавляют их в список на шине ISA. Обычно процедуры идентификации драйверов связывают свои драйверы с новыми устройствами. Процедура идентификации PnP пока не знает о других драйверах, поэтому не связывает ни один из них с новыми устройствами, которые она добавляет. + +Устройства PnP переводятся в режим сна с использованием протокола PnP, чтобы предотвратить их обнаружение как устаревших устройств. + +Вызываются процедуры обнаружения для устройств, не поддерживающих PnP, помеченных как `sensitive`. Если процедура обнаружения для устройства завершилась успешно, вызывается процедура присоединения для него. + +Вызов процедур обнаружения и присоединения всех устройств, не поддерживающих PNP, выполняется аналогичным образом. + +Устройства PnP выводятся из состояния сна и получают запрошенные ресурсы: диапазоны адресов ввода-вывода и памяти, IRQ и DRQ, причем все они не конфликтуют с подключенными устаревшими устройствами. + +Затем для каждого устройства PnP вызываются процедуры обнаружения всех присутствующих драйверов ISA. Первый драйвер, который заявит о поддержке устройства, будет присоединен. Возможна ситуация, когда несколько драйверов заявят о поддержке устройства с разным приоритетом; в этом случае побеждает драйвер с наивысшим приоритетом. Процедуры обнаружения должны вызывать `ISA_PNP_PROBE()` для сравнения фактического PnP ID со списком ID, поддерживаемых драйвером, и если ID отсутствует в таблице, возвращать ошибку. Это означает, что абсолютно каждый драйвер, даже те, которые не поддерживают никакие PnP устройства, должны вызывать `ISA_PNP_PROBE()`, хотя бы с пустой таблицей PnP ID, чтобы возвращать ошибку для неизвестных PnP устройств. + +Процедура обнаружения возвращает положительное значение (код ошибки) в случае ошибки, ноль или отрицательное значение в случае успеха. + +Отрицательные возвращаемые значения используются, когда устройство PnP поддерживает несколько интерфейсов. Например, старый совместимый интерфейс и новый расширенный интерфейс, которые поддерживаются разными драйверами. В этом случае оба драйвера обнаружат устройство. Драйвер, возвращающий большее значение в процедуре обнаружения, получает приоритет (другими словами, драйвер, возвращающий 0, имеет наивысший приоритет, возвращающий -1 — следующий, возвращающий -2 — за ним и так далее). В результате устройства, поддерживающие только старый интерфейс, будут обрабатываться старым драйвером (который должен возвращать -1 из процедуры обнаружения), тогда как устройства, поддерживающие также новый интерфейс, будут обрабатываться новым драйвером (который должен возвращать 0 из процедуры обнаружения). Если несколько драйверов возвращают одинаковое значение, побеждает тот, который был вызван первым. Таким образом, если драйвер возвращает значение 0, он может быть уверен, что выиграл арбитраж приоритетов. + +Процедуры идентификации, специфичные для устройства, также могут назначать устройству не драйвер, а класс драйверов. Затем все драйверы в этом классе проверяются на совместимость с устройством, как в случае с PnP. Эта возможность не реализована ни в одном существующем драйвере и далее в этом документе не рассматривается. + +Поскольку устройства PnP отключены при проверке устаревших устройств, они не будут присоединены дважды (один раз как устаревшие и один раз как PnP). Однако в случае процедур идентификации, зависящих от устройства, ответственность за то, чтобы одно и то же устройство не было присоединено драйвером дважды (один раз как настроенное пользователем устаревшее и один раз как автоматически идентифицированное), лежит на драйвере. + +Еще одно практическое следствие для автоматически определяемых устройств (как PnP, так и специфичных для устройства) заключается в том, что флаги не могут быть переданы им из файла конфигурации ядра. Поэтому они либо не должны использовать флаги вообще, либо использовать флаги из устройства unit 0 для всех автоматически определяемых устройств, либо использовать интерфейс sysctl вместо флагов. + +Другие нестандартные конфигурации могут быть реализованы путем прямого доступа к ресурсам конфигурации с использованием функций семейств `resource_query_*()` и `resource_*_value()`. Их реализации находятся в [.filename]#kern/subr_bus.c#. Примеры такого использования есть в старом драйвере диска IDE [.filename]#i386/isa/wd.c#. Однако стандартные методы конфигурации всегда должны быть предпочтительны. Оставьте разбор ресурсов конфигурации коду настройки шины. + +[[isa-driver-resources]] +== Ресурсы + +Информация, которую пользователь вводит в файл конфигурации ядра, обрабатывается и передаётся ядру в виде ресурсов конфигурации. Эта информация анализируется кодом конфигурации шины и преобразуется в значение структуры `device_t` и связанные с ней ресурсы шины. Драйверы могут напрямую обращаться к ресурсам конфигурации, используя функции `resource_*` для более сложных случаев конфигурации. Однако, как правило, в этом нет необходимости, и это не рекомендуется, поэтому данный вопрос далее не рассматривается. + +Ресурсы шины связаны с каждым устройством. Они идентифицируются по типу и номеру внутри типа. Для шины ISA определены следующие типы: + +* _SYS_RES_IRQ_ - номер прерывания +* _SYS_RES_DRQ_ - номер канала ISA DMA +* _SYS_RES_MEMORY_ - диапазон памяти устройства, отображенный в системное адресное пространство +* _SYS_RES_IOPORT_ - диапазон регистров ввода-вывода устройства + +Перечисление внутри типов начинается с 0, поэтому если устройство имеет две области памяти, оно будет иметь ресурсы типа `SYS_RES_MEMORY` с номерами 0 и 1. Тип ресурса не связан с типом языка C, все значения ресурсов имеют тип `unsigned long` в языке C и должны быть приведены по мере необходимости. Номера ресурсов не обязательно должны быть последовательными, хотя для ISA они обычно таковыми являются. Допустимые номера ресурсов для устройств ISA: + +[.programlisting] +.... + IRQ: 0-1 + DRQ: 0-1 + MEMORY: 0-3 + IOPORT: 0-7 +.... + +Все ресурсы представлены в виде диапазонов с начальным значением и количеством. Для ресурсов IRQ и DRQ количество обычно равно 1. Значения для памяти относятся к физическим адресам. + +Три типа действий могут выполняться над ресурсами: + +* Установка — set/get +* Выделение — allocate/release +* Активация — activate/deactivate + +Установка задает диапазон, используемый ресурсом. Выделение резервирует запрошенный диапазон, чтобы никакой другой драйвер не смог его зарезервировать (и проверяет, что никакой другой драйвер уже не зарезервировал этот диапазон). Активация делает ресурс доступным для драйвера, выполняя все необходимые для этого действия (например, для памяти это может быть отображение в виртуальное адресное пространство ядра). + +Функции для управления ресурсами: + +* `int bus_set_resource(device_t dev, int type, int rid, u_long start, u_long count)` ++ +Устанавливает диапазон для ресурса. Возвращает 0 при успешном выполнении, в противном случае — код ошибки. Обычно эта функция возвращает ошибку только в том случае, если одно из значений `type`, `rid`, `start` или `count` выходит за пределы допустимого диапазона. + +** dev - устройство драйвера +** тип - тип ресурса, SYS_RES_* +** rid - номер ресурса (ID) в пределах типа +** начало, количество - диапазон ресурсов + +* `int bus_get_resource(device_t dev, int type, int rid, u_long *startp, u_long *countp)` ++ +Получает диапазон ресурса. Возвращает 0 при успехе, код ошибки, если ресурс ещё не определён. +* `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)` ++ +Удобные функции для получения только начала или количества. Возвращают 0 в случае ошибки, поэтому если начало ресурса может законно содержать 0, невозможно определить, является ли значение 0 или произошла ошибка. К счастью, ни один ресурс ISA для дополнительных драйверов не может иметь начальное значение, равное 0. +* `void bus_delete_resource(device_t dev, int type, int rid)` ++ +Удаляет ресурс, делает его неопределённым. +* `struct resource * bus_alloc_resource(device_t dev, int type, int *rid, u_long start, u_long end, u_long count, u_int flags)` ++ +Выделяет ресурс как диапазон значений count, не выделенных никем другим, где-то между start и end. Увы, выравнивание не поддерживается. Если ресурс ещё не был установлен, он автоматически создаётся. Специальные значения start равное 0 и end равное ~0 (все единицы) означают, что должны использоваться фиксированные значения, ранее установленные `bus_set_resource()`: start и count как есть, а end=(start+count). В этом случае, если ресурс не был определён ранее, возвращается ошибка. Хотя rid передаётся по ссылке, он нигде не устанавливается кодом выделения ресурсов шины ISA. Другие шины могут использовать иной подход и изменять его. + +Флаги представляют собой битовую карту. Интересные для вызывающей стороны флаги: + +* _RF_ACTIVE_ - приводит к автоматической активации ресурса после его выделения. +* _RF_SHAREABLE_ - ресурс может использоваться одновременно несколькими драйверами. +* _RF_TIMESHARE_ - ресурс может разделяться по времени несколькими драйверами, т.е. выделяться одновременно многими, но активироваться только одним в любой момент времени. +* Возвращает 0 при ошибке. Выделенные значения могут быть получены из возвращённого дескриптора с использованием методов `rhand_*()`. +* `int bus_release_resource(device_t dev, int type, int rid, struct resource *r)` +* Освобождает ресурс, r — это дескриптор, возвращённый `bus_alloc_resource()`. Возвращает 0 при успехе, код ошибки в противном случае. +* `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)` +* Активирует или деактивирует ресурс. Возвращает 0 при успехе, в противном случае — код ошибки. Если ресурс разделяемый и в данный момент активирован другим драйвером, возвращается `EBUSY`. +* `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)` +* Связывает или разрывает связь обработчика прерывания с устройством. Возвращает 0 при успехе, код ошибки в противном случае. +* r - активированный обработчик ресурсов, описывающий IRQ ++ +flags - уровень приоритета прерывания, один из: + +** `INTR_TYPE_TTY` - терминалы и другие аналогичные символьные устройства. Для их маскировки используйте `spltty()`. +** `(INTR_TYPE_TTY | INTR_TYPE_FAST)` - терминальные устройства с малым буфером ввода, критичные к потере данных на входе (например, устаревшие последовательные порты). Для их маскирования используйте `spltty()`. +** `INTR_TYPE_BIO` - блочные устройства, за исключением тех, что подключены к контроллерам CAM. Для их маскирования используйте `splbio()`. +** `INTR_TYPE_CAM` - контроллеры шины CAM (Common Access Method). Для их маскирования используйте `splcam()`. +** `INTR_TYPE_NET` - контроллеры сетевых интерфейсов. Для их маскирования используйте `splimp()`. +** `INTR_TYPE_MISC` — прочие устройства. Нет другого способа их маскировки, кроме `splhigh()`, который маскирует все прерывания. + +Когда обработчик прерывания выполняется, все другие прерывания, соответствующие его уровню приоритета, будут заблокированы. Единственное исключение — уровень MISC, для которого никакие другие прерывания не блокируются и который сам не блокируется другими прерываниями. + +* _handler_ - указатель на функцию-обработчик, тип driver_intr_t определён как `void driver_intr_t(void *)` +* _arg_ - аргумент, передаваемый обработчику для идентификации конкретного устройства. Приводится обработчиком от void* к фактическому типу. Старая конвенция для обработчиков прерываний ISA предполагала использование номера устройства в качестве аргумента, новая (рекомендуемая) конвенция предполагает использование указателя на структуру softc устройства. +* _cookie[p]_ - значение, полученное из `setup()`, используется для идентификации обработчика при передаче в `teardown()` + +Определены несколько методов для работы с обработчиками ресурсов (struct resource *). Вот те из них, которые представляют интерес для разработчиков драйверов устройств: + +* `u_long rman_get_start(r) u_long rman_get_end(r)` Получают начало и конец выделенного диапазона ресурсов. +* `void *rman_get_virtual(r)` Получает виртуальный адрес активированного ресурса памяти. + +[[isa-driver-busmem]] +== Отображение памяти шины + +Во многих случаях данные передаются между драйвером и устройством через память. Возможны два варианта: + +(а) память расположена на карте устройства + +(b) память — это основная память компьютера + +В случае (a) драйвер всегда копирует данные между памятью на карте и основной памятью по мере необходимости. Для отображения памяти на карте в виртуальное адресное пространство ядра физический адрес и длина памяти на карте должны быть определены как ресурс `SYS_RES_MEMORY`. Этот ресурс может быть затем выделен и активирован, а его виртуальный адрес получен с помощью `rman_get_virtual()`. Более старые драйверы использовали для этой цели функцию `pmap_mapdev()`, которую больше не следует использовать напрямую. Теперь это один из внутренних шагов активации ресурса. + +Большинство ISA-карт имеют память, настроенную на физическое расположение в диапазоне 640 КБ–1 МБ. Некоторые ISA-карты требуют большего диапазона памяти, который должен быть размещён ниже 16 МБ (из-за 24-битного ограничения адресации на шине ISA). В таком случае, если в машине больше памяти, чем начальный адрес памяти устройства (другими словами, они пересекаются), необходимо настроить "дыру" в памяти по диапазону адресов, используемому устройствами. Многие BIOS позволяют настроить "дыру" в памяти размером 1 МБ, начиная с 14 МБ или 15 МБ. FreeBSD корректно обрабатывает "дыры" в памяти, если BIOS правильно их сообщает (эта функция может не работать в старых BIOS). + +В случае (b) только адрес данных отправляется на устройство, и устройство использует DMA для фактического доступа к данным в основной памяти. Существуют два ограничения: во-первых, карты ISA могут обращаться только к памяти ниже 16 МБ. Во-вторых, непрерывные страницы в виртуальном адресном пространстве могут не быть непрерывными в физическом адресном пространстве, поэтому устройству может потребоваться выполнять операции scatter/gather. Подсистема шины предоставляет готовые решения для некоторых из этих проблем, остальное должно быть реализовано самими драйверами. + +Для выделения памяти DMA используются две структуры: `bus_dma_tag_t` и `bus_dmamap_t`. Тег (`tag`) описывает свойства, необходимые для памяти DMA. Карта (`map`) представляет собой блок памяти, выделенный в соответствии с этими свойствами. С одним тегом может быть связано несколько карт. + +Теги организованы в иерархию в виде дерева с наследованием свойств. Дочерний тег наследует все требования родительского тега и может делать их более строгими, но никогда более мягкими. + +Обычно создается один корневой тег (без родителя) для каждого устройства. Если для каждого устройства требуется несколько областей памяти с разными требованиями, то для каждой из них может быть создан тег как дочерний по отношению к родительскому тегу. + +Теги могут быть использованы для создания карты двумя способами. + +Сначала может быть выделен (а затем освобожден) блок непрерывной памяти, соответствующий требованиям тега. Обычно это используется для выделения относительно долгоживущих областей памяти для взаимодействия с устройством. Загрузка такой памяти в карту тривиальна: она всегда рассматривается как один блок в соответствующем диапазоне физической памяти. + +Второй момент: произвольная область виртуальной памяти может быть загружена в карту. Каждая страница этой памяти будет проверяться на соответствие требованиям карты. Если она соответствует, то остается на своем исходном месте. Если нет, то выделяется новая соответствующая "отскоковая страница" (bounce page), которая используется как промежуточное хранилище. При записи данных с несоответствующих исходных страниц они сначала копируются на свои отскоковые страницы, а затем передаются с отскоковых страниц на устройство. При чтении данные поступают с устройства на отскоковые страницы, а затем копируются на свои несоответствующие исходные страницы. Процесс копирования между исходными и отскоковыми страницами называется синхронизацией. Обычно это используется для каждой передачи: буфер для каждой передачи загружается, передача выполняется, и буфер выгружается. + +Функции, работающие с памятью DMA: + +* `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)` ++ +Создать новый тег. Возвращает 0 при успехе, код ошибки в противном случае. + +** _parent_ - родительский тег, или NULL для создания тега верхнего уровня. +** _alignment_ - требуемое физическое выравнивание области памяти, которая будет выделена для этого тега. Используйте значение 1 для "без специфического выравнивания". Применяется только к будущим вызовам `bus_dmamem_alloc()`, но не `bus_dmamap_create()`. +** _boundary_ - физическая граница адреса, которую нельзя пересекать при выделении памяти. Используйте значение 0 для обозначения "нет границы". Применяется только к будущим вызовам `bus_dmamem_alloc()`, но не `bus_dmamap_create()`. Должна быть степенью 2. Если память планируется использовать в некаскадном режиме DMA (т.е. адреса DMA будут предоставляться не самим устройством, а контроллером DMA ISA), то граница не должна превышать 64 КБ (64*1024) из-за ограничений аппаратного обеспечения DMA. +** _lowaddr, highaddr_ - названия немного вводят в заблуждение; эти значения используются для ограничения допустимого диапазона физических адресов, используемых для выделения памяти. Точное значение зависит от предполагаемого будущего использования: + +*** Для `bus_dmamem_alloc()` все адреса от 0 до lowaddr-1 считаются разрешёнными, а более высокие — запрещёнными. +*** Для `bus_dmamap_create()` все адреса вне включительного диапазона [lowaddr; highaddr] считаются доступными. Адреса страниц внутри диапазона передаются в функцию-фильтр, которая определяет, доступны ли они. Если функция-фильтр не предоставлена, то весь диапазон считается недоступным. +*** Для устройств ISA обычные значения (без функции фильтрации) следующие: ++ +lowaddr = BUS_SPACE_MAXADDR_24BIT ++ +highaddr = BUS_SPACE_MAXADDR + +** _filter, filterarg_ - функция фильтра и её аргумент. Если передаётся NULL для filter, то весь диапазон [lowaddr, highaddr] считается недоступным при выполнении `bus_dmamap_create()`. В противном случае физический адрес каждой страницы в диапазоне [lowaddr; highaddr] передаётся в функцию фильтра, которая определяет, доступна ли она. Прототип функции фильтра: `int filterfunc(void *arg, bus_addr_t paddr)`. Функция должна вернуть 0, если страница доступна, и ненулевое значение в противном случае. +** _maxsize_ - максимальный размер памяти (в байтах), который может быть выделен через этот тег. Если сложно оценить или он может быть произвольно большим, для устройств ISA следует использовать значение `BUS_SPACE_MAXSIZE_24BIT`. +** _nsegments_ - максимальное количество сегментов scatter-gather, поддерживаемых устройством. Если ограничений нет, следует использовать значение `BUS_SPACE_UNRESTRICTED`. Это значение рекомендуется для родительских тегов, фактические ограничения затем будут указаны для дочерних тегов. Теги с nsegments равным `BUS_SPACE_UNRESTRICTED` не могут использоваться для фактической загрузки отображений, они могут применяться только как родительские теги. Практический предел для nsegments составляет около 250-300, более высокие значения вызовут переполнение стека ядра (аппаратное обеспечение обычно не поддерживает такое большое количество scatter-gather буферов в любом случае). +** _maxsegsz_ — максимальный размер сегмента scatter-gather, поддерживаемый устройством. Максимальное значение для устройства ISA будет `BUS_SPACE_MAXSIZE_24BIT`. +** _flags_ - битовая маска флагов. Единственный интересный флаг: + +*** _BUS_DMA_ALLOCNOW_ - запрашивает выделение всех потенциально необходимых страниц отскока при создании тега. + +** _dmat_ - указатель на хранилище для нового возвращаемого тега. + +* `int bus_dma_tag_destroy(bus_dma_tag_t dmat)` ++ +Уничтожить тег. Возвращает 0 при успехе, код ошибки в противном случае. ++ +dmat - тег, который должен быть уничтожен. +* `int bus_dmamem_alloc(bus_dma_tag_t dmat, void** vaddr, int flags, bus_dmamap_t *mapp)` ++ +Выделить область непрерывной памяти, описанную тегом. Размер выделяемой памяти соответствует maxsize тега. Возвращает 0 при успехе, иначе код ошибки. Результат всё ещё должен быть загружен с помощью `bus_dmamap_load()` перед использованием для получения физического адреса памяти. + +** _dmat_ - тег +** _vaddr_ - указатель на хранилище для возвращаемого виртуального адреса ядра выделенной области. +** flags - битовая карта флагов. Единственный интересный флаг: + +*** _BUS_DMA_NOWAIT_ - если память недоступна немедленно, вернуть ошибку. Если этот флаг не установлен, то процедуре разрешено ожидать до тех пор, пока память не станет доступной. + +** _mapp_ - указатель на хранилище для возвращаемой новой карты. + +* `void bus_dmamem_free(bus_dma_tag_t dmat, void *vaddr, bus_dmamap_t map)` ++ +Освободить память, выделенную `bus_dmamem_alloc()`. В настоящее время освобождение памяти, выделенной с ограничениями ISA, не реализовано. В связи с этим рекомендуется сохранять и повторно использовать выделенные области как можно дольше. Не следует без необходимости освобождать область и вскоре снова её выделять. Это не означает, что `bus_dmamem_free()` не следует использовать вовсе: есть надежда, что вскоре она будет реализована должным образом. + +** _dmat_ - тег +** _vaddr_ - виртуальный адрес памяти ядра +** _map_ - карта памяти (как возвращается из `bus_dmamem_alloc()`) + +* `int bus_dmamap_create(bus_dma_tag_t dmat, int flags, bus_dmamap_t *mapp)` ++ +Создать карту для тега, которая будет использоваться в `bus_dmamap_load()` позже. Возвращает 0 при успехе, в противном случае — код ошибки. + +** _dmat_ - тег +** _flags_ - теоретически, битовая карта флагов. Однако пока никакие флаги не определены, поэтому в настоящее время значение всегда будет 0. +** _mapp_ - указатель на хранилище для новой карты, которая будет возвращена + +* `int bus_dmamap_destroy(bus_dma_tag_t dmat, bus_dmamap_t map)` ++ +Уничтожить карту. Возвращает 0 при успехе, в противном случае — код ошибки. + +** dmat - тег, с которым ассоциирована карта +** map - карта, подлежащая уничтожению + +* `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)` ++ +Загрузить буфер в карту (карта должна быть предварительно создана с помощью `bus_dmamap_create()` или `bus_dmamem_alloc()`). Все страницы буфера проверяются на соответствие требованиям тега, и для несоответствующих выделяются страницы отскока. Создается массив дескрипторов физических сегментов и передается в подпрограмму обратного вызова. Ожидается, что эта подпрограмма обработает его каким-либо образом. Количество буферов отскока в системе ограничено, поэтому, если эти буферы требуются, но недоступны немедленно, запрос будет поставлен в очередь, и обратный вызов будет выполнен, когда буферы отскова станут доступны. Возвращает 0, если обратный вызов был выполнен немедленно, или `EINPROGRESS`, если запрос был поставлен в очередь для выполнения в будущем. В последнем случае синхронизация с подпрограммой обратного вызова, поставленной в очередь, является обязанностью драйвера. ++ +** _dmat_ - тег +** _map_ - карта +** _buf_ - виртуальный адрес буфера в пространстве ядра +** _buflen_ - длина буфера +** _callback_, `callback_arg` - функция обратного вызова и её аргумент ++ +Прототип функции обратного вызова: `void callback(void *arg, bus_dma_segment_t *seg, int nseg, int error)` ++ +** _arg_ - то же самое, что и callback_arg, переданный в `bus_dmamap_load()` +** _seg_ - массив дескрипторов сегментов +** _nseg_ - количество дескрипторов в массиве +** _error_ - указание на переполнение номера сегмента: если установлено значение `EFBIG`, значит буфер не поместился в максимальное количество сегментов, разрешённых тегом. В этом случае в массиве будет только разрешённое количество дескрипторов. Обработка этой ситуации зависит от драйвера: в зависимости от желаемой семантики он может либо считать это ошибкой, либо разделить буфер на две части и обработать вторую часть отдельно ++ +Каждая запись в массиве segments содержит поля: ++ +** _ds_addr_ - физический адрес шины сегмента +** _ds_len_ - длина сегмента ++ +* `void bus_dmamap_unload(bus_dma_tag_t dmat, bus_dmamap_t map)` ++ +выгрузить карту. ++ +** _dmat_ - тег +** _map_ - загруженная карта ++ +* `void bus_dmamap_sync (bus_dma_tag_t dmat, bus_dmamap_t map, bus_dmasync_op_t op)` ++ +Синхронизировать загруженный буфер с его страницами отскока до и после физической передачи на устройство или с устройства. Это функция, которая выполняет все необходимое копирование данных между исходным буфером и его отображенной версией. Буферы должны быть синхронизированы как до, так и после выполнения передачи. ++ +** _dmat_ - тег +** _map_ - загруженная карта +** _op_ - тип операции синхронизации для выполнения: ++ +** `BUS_DMASYNC_PREREAD` - перед чтением с устройства в буфер +** `BUS_DMASYNC_POSTREAD` - после чтения из устройства в буфер +** `BUS_DMASYNC_PREWRITE` - перед записью буфера в устройство +** `BUS_DMASYNC_POSTWRITE` - после записи буфера в устройство + +На данный момент PREREAD и POSTWRITE являются пустыми операциями, но это может измениться в будущем, поэтому их нельзя игнорировать в драйвере. Синхронизация не требуется для памяти, полученной из `bus_dmamem_alloc()`. + +Перед вызовом функции обратного вызова из `bus_dmamap_load()` массив сегментов сохраняется в стеке. Он предварительно выделяется для максимального количества сегментов, разрешенного тегом. В результате этого практический предел количества сегментов на архитектуре i386 составляет около 250-300 (размер стека ядра — 4 КБ минус размер структуры пользователя, размер элемента массива сегментов — 8 байт, и необходимо оставить некоторое пространство). Поскольку массив выделяется исходя из максимального числа, это значение не должно быть установлено выше, чем действительно необходимо. К счастью, для большинства оборудования максимально поддерживаемое количество сегментов значительно ниже. Но если драйвер должен обрабатывать буферы с очень большим количеством сегментов scatter-gather, он должен делать это по частям: загрузить часть буфера, передать его устройству, загрузить следующую часть буфера и так далее. + +Еще одно практическое следствие заключается в том, что количество сегментов может ограничивать размер буфера. Если все страницы в буфере окажутся физически несмежными, то максимальный поддерживаемый размер буфера для такого фрагментированного случая будет равен (nsegments * page_size). Например, если поддерживается максимальное количество сегментов, равное 10, то на i386 максимальный гарантированно поддерживаемый размер буфера составит 40K. Если требуется больший размер, то в драйвере следует использовать специальные приемы. + +Если оборудование не поддерживает scatter-gather вообще или драйвер хочет поддерживать некоторый размер буфера, даже если он сильно фрагментирован, то решение состоит в выделении непрерывного буфера в драйвере и использовании его в качестве промежуточного хранилища, если исходный буфер не подходит. + +Ниже представлены типичные последовательности вызовов при использовании карты в зависимости от её назначения. Символы -> используются для обозначения последовательности во времени. + +Для буфера, который остается практически неизменным в течение всего времени между присоединением и отсоединением устройства: + +bus_dmamem_alloc -> bus_dmamap_load -> ...use buffer... -> -> bus_dmamap_unload -> bus_dmamem_free + +Для буфера, который часто изменяется и передается извне драйвера: +[.programlisting] +.... + bus_dmamap_create -> + -> bus_dmamap_load -> bus_dmamap_sync(PRE...) -> do transfer -> + -> bus_dmamap_sync(POST...) -> bus_dmamap_unload -> + ... + -> bus_dmamap_load -> bus_dmamap_sync(PRE...) -> do transfer -> + -> bus_dmamap_sync(POST...) -> bus_dmamap_unload -> + -> bus_dmamap_destroy +.... + +При загрузке карты, созданной `bus_dmamem_alloc()`, переданные адрес и размер буфера должны быть такими же, как использованные в `bus_dmamem_alloc()`. В этом случае гарантируется, что весь буфер будет отображен как один сегмент (так что обратный вызов может основываться на этом предположении) и запрос будет выполнен немедленно (EINPROGRESS никогда не будет возвращен). Все, что нужно сделать обратному вызову в этом случае, — это сохранить физический адрес. + +Типичный пример: + +[.programlisting] +.... + static void + alloc_callback(void *arg, bus_dma_segment_t *seg, int nseg, int error) + { + *(bus_addr_t *)arg = seg[0].ds_addr; + } + + ... + int error; + struct somedata { + .... + }; + struct somedata *vsomedata; /* virtual address */ + bus_addr_t psomedata; /* physical bus-relative address */ + bus_dma_tag_t tag_somedata; + bus_dmamap_t map_somedata; + ... + + error=bus_dma_tag_create(parent_tag, alignment, + boundary, lowaddr, highaddr, /*filter*/ NULL, /*filterarg*/ NULL, + /*maxsize*/ sizeof(struct somedata), /*nsegments*/ 1, + /*maxsegsz*/ sizeof(struct somedata), /*flags*/ 0, + &tag_somedata); + if(error) + return error; + + error = bus_dmamem_alloc(tag_somedata, &vsomedata, /* flags*/ 0, + &map_somedata); + if(error) + return error; + + bus_dmamap_load(tag_somedata, map_somedata, (void *)vsomedata, + sizeof (struct somedata), alloc_callback, + (void *) &psomedata, /*flags*/0); +.... + +Выглядит немного длинно и сложно, но это правильный способ. Практическое следствие таково: если несколько областей памяти выделяются всегда вместе, было бы отличной идеей объединить их все в одну структуру и выделять как единое целое (если ограничения выравнивания и границ позволяют). + +При загрузке произвольного буфера в карту, созданную `bus_dmamap_create()`, необходимо принять специальные меры для синхронизации с обратным вызовом, если он будет задержан. Код будет выглядеть следующим образом: + +[.programlisting] +.... + { + int s; + int error; + + s = splsoftvm(); + error = bus_dmamap_load( + dmat, + dmamap, + buffer_ptr, + buffer_len, + callback, + /*callback_arg*/ buffer_descriptor, + /*flags*/0); + if (error == EINPROGRESS) { + /* + * Do whatever is needed to ensure synchronization + * with callback. Callback is guaranteed not to be started + * until we do splx() or tsleep(). + */ + } + splx(s); + } +.... + +Два возможных подхода для обработки запросов: + +1. Если запросы завершаются путём явной пометки их как выполненных (например, запросы CAM), то было бы проще поместить всю дальнейшую обработку в драйвер обратного вызова, который отмечал бы запрос по его завершении. В этом случае не потребуется много дополнительной синхронизации. По соображениям управления потоком может быть полезно заморозить очередь запросов до завершения этого запроса. + +2. Если запросы завершаются при возврате функции (например, классические запросы на чтение или запись для символьных устройств), то в дескрипторе буфера должен быть установлен флаг синхронизации и вызвана функция `tsleep()`. Позже, когда будет вызван обратный вызов, он выполнит свою обработку и проверит этот флаг синхронизации. Если флаг установлен, обратный вызов должен инициировать пробуждение. При таком подходе функция обратного вызова может либо выполнить всю необходимую обработку (как в предыдущем случае), либо просто сохранить массив сегментов в дескрипторе буфера. Затем после завершения обратного вызова вызывающая функция может использовать этот сохранённый массив сегментов и выполнить всю обработку. + +[[isa-driver-dma]] +== DMA + +Прямой доступ к памяти (DMA) реализован в шине ISA через контроллер DMA (на самом деле их два, но это несущественная деталь). Чтобы сделать ранние устройства ISA простыми и дешёвыми, логика управления шиной и генерации адресов была сосредоточена в контроллере DMA. К счастью, FreeBSD предоставляет набор функций, которые в основном скрывают раздражающие детали работы контроллера DMA от драйверов устройств. + +Самый простой случай — для достаточно интеллектуальных устройств. Например, устройства с bus mastering на PCI могут сами генерировать шинные циклы и адреса памяти. Единственное, что им действительно нужно от контроллера DMA, — это арбитраж шины. Для этой цели они притворяются каскадированными подчинёнными контроллерами DMA. И единственное, что требуется от системного контроллера DMA, — это включить каскадный режим на канале DMA, вызвав следующую функцию при присоединении драйвера: + +`void isa_dmacascade(int channel_number)` + +Все последующие действия выполняются путем программирования устройства. При отсоединении драйвера нет необходимости вызывать функции, связанные с DMA. + +Для более простых устройств всё становится сложнее. Используются следующие функции: + +* `int isa_dma_acquire(int chanel_number)` ++ +Зарезервировать канал DMA. Возвращает 0 при успехе или EBUSY, если канал уже зарезервирован этим или другим драйвером. Большинство устройств ISA не способны совместно использовать каналы DMA, поэтому обычно эта функция вызывается при присоединении устройства. Это резервирование стало избыточным с появлением современного интерфейса ресурсов шины, но всё ещё должно использоваться в дополнение к последнему. Если резервирование не использовать, то в дальнейшем другие процедуры DMA вызовут панику ядра. +* `int isa_dma_release(int chanel_number)` ++ +Освободить ранее зарезервированный канал DMA. На момент освобождения канала не должно быть активных передач (дополнительно устройство не должно пытаться инициировать передачу после освобождения канала). +* `void isa_dmainit(int chan, u_int bouncebufsize)` ++ +Выделить буфер отскока для использования с указанным каналом. Запрашиваемый размер буфера не может превышать 64 КБ. Этот буфер отскока будет автоматически использован в дальнейшем, если передаваемый буфер окажется не физически непрерывным, находится вне памяти, доступной шине ISA, или пересекает границу 64 КБ. Если передача всегда будет выполняться из буферов, соответствующих этим условиям (например, выделенных с помощью `bus_dmamem_alloc()` с соответствующими ограничениями), то вызов `isa_dmainit()` не требуется. Однако довольно удобно передавать произвольные данные с использованием контроллера DMA. Буфер отскока автоматически решит проблемы с разбросанно-собираемыми данными. ++ +** _chan_ - номер канала +** _bouncebufsize_ - размер буфера отскока в байтах ++ +* `void isa_dmastart(int flags, caddr_t addr, u_int nbytes, int chan)` ++ +Подготовка к началу передачи DMA. Эта функция должна быть вызвана для настройки контроллера DMA перед фактическим началом передачи на устройстве. Она проверяет, что буфер является непрерывным и попадает в диапазон памяти ISA, если нет, то автоматически используется буфер отскока. Если требуется буфер отскока, но он не настроен с помощью `isa_dmainit()` или слишком мал для запрошенного размера передачи, система перейдет в состояние паники. В случае запроса на запись с буфером отскока данные будут автоматически скопированы в этот буфер. +* flags - битовая маска, определяющая тип выполняемой операции. Бит направления B_READ и B_WRITE являются взаимоисключающими. ++ +** B_READ - чтение с шины ISA в память +** B_WRITE - запись из памяти на шину ISA +** B_RAW - если установлен, то контроллер DMA запомнит буфер и после завершения передачи автоматически переинициализирует себя для повторной передачи того же буфера (конечно, драйвер может изменить данные в буфере перед инициированием следующей передачи на устройстве). Если не установлен, то параметры будут работать только для одной передачи, и перед инициированием следующей передачи снова потребуется вызвать `isa_dmastart()`. Использование B_RAW имеет смысл только если буфер отскока не используется. ++ +* addr - виртуальный адрес буфера +* nbytes - длина буфера. Должна быть меньше или равна 64 КБ. Длина 0 не допускается: контроллер DMA интерпретирует это как 64 КБ, в то время как код ядра поймёт это как 0, что приведёт к непредсказуемым последствиям. Для каналов номер 4 и выше длина должна быть чётной, так как эти каналы передают по 2 байта за раз. В случае нечётной длины последний байт не будет передан. +* chan - номер канала +* `void isa_dmadone(int flags, caddr_t addr, int nbytes, int chan)` ++ +Синхронизировать память после того, как устройство сообщает о завершении передачи. Если это была операция чтения с буфером отскока, то данные будут скопированы из этого буфера в исходный буфер. Аргументы такие же, как у `isa_dmastart()`. Флаг B_RAW разрешён, но он никак не влияет на `isa_dmadone()`. +* `int isa_dmastatus(int channel_number)` ++ +Возвращает количество оставшихся для передачи байт в текущей передаче. Если флаг B_READ был установлен в `isa_dmastart()`, возвращаемое значение никогда не будет равно нулю. В конце передачи оно автоматически сбрасывается обратно к длине буфера. Обычное использование — проверка количества оставшихся байт после того, как устройство сигнализирует о завершении передачи. Если количество байт не равно 0, то, вероятно, в передаче произошла ошибка. +* `int isa_dmastop(int channel_number)` ++ +Прерывает текущую передачу и возвращает количество непереданных байтов. + +[[isa-driver-probe]] +== xxx_isa_probe + +Эта функция проверяет наличие устройства. Если драйвер поддерживает автоматическое определение некоторых параметров конфигурации устройства (таких как вектор прерывания или адрес памяти), это автоматическое определение должно выполняться в данной процедуре. + +Как и для любой другой шины, если устройство не может быть обнаружено, или обнаружено, но не прошло самопроверку, или возникла другая проблема, то возвращается положительное значение ошибки. Значение `ENXIO` должно возвращаться, если устройство отсутствует. Другие значения ошибок могут означать иные условия. Нулевые или отрицательные значения означают успех. Большинство драйверов возвращают ноль в случае успеха. + +Отрицательные возвращаемые значения используются, когда устройство PnP поддерживает несколько интерфейсов. Например, старый совместимый интерфейс и новый расширенный интерфейс, которые поддерживаются разными драйверами. В этом случае оба драйвера обнаружат устройство. Драйвер, который возвращает большее значение в процедуре обнаружения, получает приоритет (другими словами, драйвер, возвращающий 0, имеет наивысший приоритет, возвращающий -1 — следующий, возвращающий -2 — за ним и так далее). В результате устройства, поддерживающие только старый интерфейс, будут обрабатываться старым драйвером (который должен возвращать -1 из процедуры probe), а устройства, поддерживающие также новый интерфейс, будут обрабатываться новым драйвером (который должен возвращать 0 из процедуры обнаружения). + +Структура дескриптора устройства `xxx_softc` выделяется системой до вызова процедуры обнаружения. Если процедура обнаружения возвращает ошибку, дескриптор автоматически освобождается системой. Поэтому при возникновении ошибки обнаружения драйвер должен убедиться, что все ресурсы, использованные во время обнаружения, освобождены и ничто не мешает безопасному освобождению дескриптора.Если обнаружение завершается успешно, дескриптор сохраняется системой и позже передаётся в процедуру `xxx_isa_attach()`. Если драйвер возвращает отрицательное значение, он не может быть уверен, что получит наивысший приоритет и его процедура присоеднинения будет вызвана. Поэтому в этом случае он также должен освободить все ресурсы перед возвратом и, если необходимо, выделить их снова в процедуре присоединения. Когда `xxx_isa_probe()` возвращает 0, освобождение ресурсов перед возвратом также является хорошей практикой, и корректно работающий драйвер должен так поступать. Однако в случаях, когда возникают проблемы с освобождением ресурсов, драйверу разрешается сохранять ресурсы между возвратом 0 из процедуры обнаружения и выполнением процедуры присоединения. + +Типичная процедура обнаружения начинается с получения дескриптора устройства и номера устройства: + +[.programlisting] +.... + struct xxx_softc *sc = device_get_softc(dev); + int unit = device_get_unit(dev); + int pnperror; + int error = 0; + + sc->dev = dev; /* link it back */ + sc->unit = unit; +.... + +Затем проверьте устройства PnP. Проверка осуществляется с помощью таблицы, содержащей список PnP ID, поддерживаемых этим драйвером, и удобочитаемые описания моделей устройств, соответствующих этим ID. + +[.programlisting] +.... + + pnperror=ISA_PNP_PROBE(device_get_parent(dev), dev, + xxx_pnp_ids); if(pnperror == ENXIO) return ENXIO; +.... + +Логика работы `ISA_PNP_PROBE` следующая: если данная карта (устройство) не была обнаружена как PnP, то будет возвращено `ENOENT`. Если она была обнаружена как PnP, но её обнаруженный ID не совпадает ни с одним из ID в таблице, то возвращается `ENXIO`. Наконец, если устройство поддерживает PnP и его ID совпадает с одним из ID в таблице, возвращается `0`, а соответствующее описание из таблицы устанавливается с помощью `device_set_desc()`. + +Если драйвер поддерживает только устройства PnP, то условие будет выглядеть следующим образом: + +[.programlisting] +.... + if(pnperror != 0) + return pnperror; +.... + +Для драйверов, которые не поддерживают PnP, не требуется специальной обработки, так как они передают пустую таблицу идентификаторов PnP и всегда будут получать ENXIO при вызове на PnP-карте. + +Функция обнаружения обычно требует как минимум некоторый минимальный набор ресурсов, например, номер порта ввода-вывода, чтобы найти карту и проверить её. В зависимости от оборудования драйвер может автоматически обнаружить другие необходимые ресурсы. Устройства PnP имеют все ресурсы, предварительно установленные подсистемой PnP, поэтому драйверу не нужно обнаруживать их самостоятельно. + +Обычно минимальная информация, необходимая для доступа к устройству, — это номер порта ввода-вывода. Затем некоторые устройства позволяют получить остальную информацию из регистров конфигурации устройства (хотя не все устройства это поддерживают). Поэтому сначала мы пытаемся получить начальное значение порта: + +[.programlisting] +.... + sc->port0 = bus_get_resource_start(dev, + SYS_RES_IOPORT, 0 /*rid*/); if(sc->port0 == 0) return ENXIO; +.... + +Базовый адрес порта сохраняется в структуре softc для последующего использования. Если он будет использоваться очень часто, то вызов функции ресурса каждый раз будет неприемлемо медленным. Если мы не получаем порт, мы просто возвращаем ошибку. Некоторые драйверы устройств могут вместо этого быть умнее и попытаться обнаружить все возможные порты, например: + +[.programlisting] +.... + + /* table of all possible base I/O port addresses for this device */ + static struct xxx_allports { + u_short port; /* port address */ + short used; /* flag: if this port is already used by some unit */ + } xxx_allports = { + { 0x300, 0 }, + { 0x320, 0 }, + { 0x340, 0 }, + { 0, 0 } /* end of table */ + }; + + ... + int port, i; + ... + + port = bus_get_resource_start(dev, SYS_RES_IOPORT, 0 /*rid*/); + if(port !=0 ) { + for(i=0; xxx_allports[i].port!=0; i++) { + if(xxx_allports[i].used || xxx_allports[i].port != port) + continue; + + /* found it */ + xxx_allports[i].used = 1; + /* do probe on a known port */ + return xxx_really_probe(dev, port); + } + return ENXIO; /* port is unknown or already used */ + } + + /* we get here only if we need to guess the port */ + for(i=0; xxx_allports[i].port!=0; i++) { + if(xxx_allports[i].used) + continue; + + /* mark as used - even if we find nothing at this port + * at least we won't probe it in future + */ + xxx_allports[i].used = 1; + + error = xxx_really_probe(dev, xxx_allports[i].port); + if(error == 0) /* found a device at that port */ + return 0; + } + /* probed all possible addresses, none worked */ + return ENXIO; +.... + +Конечно, обычно для таких вещей следует использовать процедуру `identify()` драйвера. Однако может быть одна веская причина, почему лучше сделать это в `probe()`: если этот обнаружение может привести к сбою другого чувствительного устройства. Процедуры обнаружения упорядочены с учетом флага `sensitive`: чувствительные устройства проверяются первыми, а остальные устройства — позже. Но процедуры `identify()` вызываются до любого обнаружения, поэтому они не учитывают чувствительные устройства и могут вызвать их сбой. + +Вот, после того как мы получили начальный порт, необходимо установить количество портов (за исключением устройств PnP), так как в файле конфигурации ядра эта информация отсутствует. + +[.programlisting] +.... + + if(pnperror /* only for non-PnP devices */ + && bus_set_resource(dev, SYS_RES_IOPORT, 0, sc->port0, + XXX_PORT_COUNT)<0) + return ENXIO; +.... + +Наконец, выделите и активируйте часть адресного пространства порта (специальные значения start и end означают "используйте те, что мы установили через ``bus_set_resource()``"): + +[.programlisting] +.... + + sc->port0_rid = 0; + sc->port0_r = bus_alloc_resource(dev, SYS_RES_IOPORT, + &sc->port0_rid, + /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE); + + if(sc->port0_r == NULL) + return ENXIO; +.... + +Теперь, имея доступ к регистрам с отображением на порты, мы можем каким-либо образом взаимодействовать с устройством и проверить, реагирует ли оно так, как ожидается. Если этого не происходит, вероятно, по этому адресу находится другое устройство или его там нет вовсе. + +Обычно драйверы не настраивают обработчики прерываний до вызова процедуры присоединения. Вместо этого они выполняют проверки в режиме опроса, используя функцию `DELAY()` для таймаута. Процедура проверки никогда не должна зависать навсегда, все ожидания ответа от устройства должны выполняться с таймаутами. Если устройство не отвечает в течение заданного времени, вероятно, оно неисправно или неправильно настроено, и драйвер должен вернуть ошибку. При определении интервала таймаута следует давать устройству дополнительное время для надежности: хотя предполагается, что `DELAY()` задерживает выполнение на одинаковое время на любой машине, существует некоторая погрешность, зависящая от конкретного процессора. + +Если процедура проверки действительно хочет убедиться, что прерывания работают, она может также настроить и провести обнаружение прерываний. Однако это не рекомендуется. + +[.programlisting] +.... + + /* implemented in some very device-specific way */ + if(error = xxx_probe_ports(sc)) + goto bad; /* will deallocate the resources before returning */ +.... + +Функция `xxx_probe_ports()` также может устанавливать описание устройства в зависимости от конкретной модели обнаруженного устройства. Но если поддерживается только одна модель устройства, это можно сделать и жёстко заданным способом. Конечно, для PnP-устройств поддержка PnP автоматически устанавливает описание из таблицы. + +[.programlisting] +.... + if(pnperror) + device_set_desc(dev, "Our device model 1234"); +.... + +Затем процедура обнаружения должна либо определить диапазоны всех ресурсов, читая регистры конфигурации устройства, либо убедиться, что они были явно заданы пользователем. Мы рассмотрим это на примере встроенной памяти. Процедура обнаружения должна быть как можно менее навязчивой, поэтому выделение и проверку функциональности остальных ресурсов (кроме портов) лучше оставить для процедуры присоединения. + +Адрес памяти может быть указан в конфигурационном файле ядра, а на некоторых устройствах он может быть предварительно настроен в энергонезависимых конфигурационных регистрах. Если доступны оба источника и они различаются, какой из них следует использовать? Вероятно, если пользователь явно указал адрес в конфигурационном файле ядра, он знает, что делает, и этот адрес должен иметь приоритет. Пример реализации может выглядеть так: + +[.programlisting] +.... + + /* try to find out the config address first */ + sc->mem0_p = bus_get_resource_start(dev, SYS_RES_MEMORY, 0 /*rid*/); + if(sc->mem0_p == 0) { /* nope, not specified by user */ + sc->mem0_p = xxx_read_mem0_from_device_config(sc); + + if(sc->mem0_p == 0) + /* can't get it from device config registers either */ + goto bad; + } else { + if(xxx_set_mem0_address_on_device(sc) < 0) + goto bad; /* device does not support that address */ + } + + /* just like the port, set the memory size, + * for some devices the memory size would not be constant + * but should be read from the device configuration registers instead + * to accommodate different models of devices. Another option would + * be to let the user set the memory size as "msize" configuration + * resource which will be automatically handled by the ISA bus. + */ + if(pnperror) { /* only for non-PnP devices */ + sc->mem0_size = bus_get_resource_count(dev, SYS_RES_MEMORY, 0 /*rid*/); + if(sc->mem0_size == 0) /* not specified by user */ + sc->mem0_size = xxx_read_mem0_size_from_device_config(sc); + + if(sc->mem0_size == 0) { + /* suppose this is a very old model of device without + * auto-configuration features and the user gave no preference, + * so assume the minimalistic case + * (of course, the real value will vary with the driver) + */ + sc->mem0_size = 8*1024; + } + + if(xxx_set_mem0_size_on_device(sc) < 0) + goto bad; /* device does not support that size */ + + if(bus_set_resource(dev, SYS_RES_MEMORY, /*rid*/0, + sc->mem0_p, sc->mem0_size)<0) + goto bad; + } else { + sc->mem0_size = bus_get_resource_count(dev, SYS_RES_MEMORY, 0 /*rid*/); + } +.... + +Ресурсы для IRQ и DRQ легко проверить по аналогии. + +Если всё прошло успешно, то освободите все ресурсы и верните успешный статус. + +[.programlisting] +.... + xxx_free_resources(sc); + return 0; +.... + +Наконец, обработайте проблемные ситуации. Все ресурсы должны быть освобождены перед возвратом. Мы используем тот факт, что перед передачей нам структуры `softc` она обнуляется, поэтому мы можем определить, был ли выделен какой-либо ресурс: если его дескриптор не равен нулю. + +[.programlisting] +.... + bad: + + xxx_free_resources(sc); + if(error) + return error; + else /* exact error is unknown */ + return ENXIO; +.... + +Вот и всё для процедуры обнаружения. Освобождение ресурсов выполняется из нескольких мест, поэтому оно вынесено в функцию, которая может выглядеть так: + +[.programlisting] +.... +static void + xxx_free_resources(sc) + struct xxx_softc *sc; + { + /* check every resource and free if not zero */ + + /* interrupt handler */ + if(sc->intr_r) { + bus_teardown_intr(sc->dev, sc->intr_r, sc->intr_cookie); + bus_release_resource(sc->dev, SYS_RES_IRQ, sc->intr_rid, + sc->intr_r); + sc->intr_r = 0; + } + + /* all kinds of memory maps we could have allocated */ + if(sc->data_p) { + bus_dmamap_unload(sc->data_tag, sc->data_map); + sc->data_p = 0; + } + if(sc->data) { /* sc->data_map may be legitimately equal to 0 */ + /* the map will also be freed */ + bus_dmamem_free(sc->data_tag, sc->data, sc->data_map); + sc->data = 0; + } + if(sc->data_tag) { + bus_dma_tag_destroy(sc->data_tag); + sc->data_tag = 0; + } + + ... free other maps and tags if we have them ... + + if(sc->parent_tag) { + bus_dma_tag_destroy(sc->parent_tag); + sc->parent_tag = 0; + } + + /* release all the bus resources */ + if(sc->mem0_r) { + bus_release_resource(sc->dev, SYS_RES_MEMORY, sc->mem0_rid, + sc->mem0_r); + sc->mem0_r = 0; + } + ... + if(sc->port0_r) { + bus_release_resource(sc->dev, SYS_RES_IOPORT, sc->port0_rid, + sc->port0_r); + sc->port0_r = 0; + } + } +.... + +[[isa-driver-attach]] +== xxx_isa_attach + +Процедура присоединения фактически подключает драйвер к системе, если процедура обнаружения вернула успех и система решила подключить этот драйвер. Если процедура обнаружения вернула 0, то процедура присоединения может ожидать, что получит структуру устройства `softc` в неизменном виде, как она была установлена процедкрой обнаружения. Также, если обнаружение возвращает 0, она можно ожидать, что процедкра присоединения для этого устройства будет вызвана в какой-то момент в будущем. Если процедка обнаружения возвращает отрицательное значение, то драйвер не может делать никаких из этих предположений. + +Процедура присоединение возвращает 0 при успешном завершении или код ошибки в противном случае. + +Процедура присоединения начинается так же, как и процедура обнаружения, с помещения часто используемых данных в более доступные переменные. + +[.programlisting] +.... + struct xxx_softc *sc = device_get_softc(dev); + int unit = device_get_unit(dev); + int error = 0; +.... + +Затем выделите и активируйте все необходимые ресурсы. Обычно диапазон портов освобождается перед возвратом из обнаружения, поэтому его необходимо выделить снова. Мы предполагаем, что процедура обнаружения корректно установила все диапазоны ресурсов, а также сохранила их в структуре softc. Если процедура обнаружения оставила некоторые ресурсы выделенными, то их не нужно выделять снова (это будет считаться ошибкой). + +[.programlisting] +.... + sc->port0_rid = 0; + sc->port0_r = bus_alloc_resource(dev, SYS_RES_IOPORT, &sc->port0_rid, + /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE); + + if(sc->port0_r == NULL) + return ENXIO; + + /* on-board memory */ + sc->mem0_rid = 0; + sc->mem0_r = bus_alloc_resource(dev, SYS_RES_MEMORY, &sc->mem0_rid, + /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE); + + if(sc->mem0_r == NULL) + goto bad; + + /* get its virtual address */ + sc->mem0_v = rman_get_virtual(sc->mem0_r); +.... + +Канал запроса DMA (DRQ) выделяется аналогично. Для его инициализации используйте функции семейства `isa_dma*()`. Например: + +`isa_dmacascade(sc->drq0);` + +Строка запроса прерывания (IRQ) является особенной. Помимо выделения, обработчик прерывания драйвера должен быть связан с ней. Исторически в старых драйверах ISA аргумент, передаваемый системой обработчику прерывания, был номером устройства. Однако в современных драйверах принято передавать указатель на структуру `softc`. Важная причина этого заключается в том, что когда структуры `softc` выделяются динамически, получение номера устройства из `softc` является простым, в то время как получение `softc` из номера устройства затруднительно. Кроме того, такое соглашение делает драйверы для различных шин более однородными и позволяет им совместно использовать код: каждая шина получает свои собственные процедуры обнаружения, присоединения, отсоединения и другие специфичные для шины функции, в то время как основная часть кода драйвера может быть общей для них. + +[.programlisting] +.... + + sc->intr_rid = 0; + sc->intr_r = bus_alloc_resource(dev, SYS_RES_MEMORY, &sc->intr_rid, + /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE); + + if(sc->intr_r == NULL) + goto bad; + + /* + * XXX_INTR_TYPE is supposed to be defined depending on the type of + * the driver, for example as INTR_TYPE_CAM for a CAM driver + */ + error = bus_setup_intr(dev, sc->intr_r, XXX_INTR_TYPE, + (driver_intr_t *) xxx_intr, (void *) sc, &sc->intr_cookie); + if(error) + goto bad; +.... + +Если устройству необходимо выполнять DMA в основную память, то эта память должна быть выделена, как описано ранее: + +[.programlisting] +.... + error=bus_dma_tag_create(NULL, /*alignment*/ 4, + /*boundary*/ 0, /*lowaddr*/ BUS_SPACE_MAXADDR_24BIT, + /*highaddr*/ BUS_SPACE_MAXADDR, /*filter*/ NULL, /*filterarg*/ NULL, + /*maxsize*/ BUS_SPACE_MAXSIZE_24BIT, + /*nsegments*/ BUS_SPACE_UNRESTRICTED, + /*maxsegsz*/ BUS_SPACE_MAXSIZE_24BIT, /*flags*/ 0, + &sc->parent_tag); + if(error) + goto bad; + + /* many things get inherited from the parent tag + * sc->data is supposed to point to the structure with the shared data, + * for example for a ring buffer it could be: + * struct { + * u_short rd_pos; + * u_short wr_pos; + * char bf[XXX_RING_BUFFER_SIZE] + * } *data; + */ + error=bus_dma_tag_create(sc->parent_tag, 1, + 0, BUS_SPACE_MAXADDR, 0, /*filter*/ NULL, /*filterarg*/ NULL, + /*maxsize*/ sizeof(* sc->data), /*nsegments*/ 1, + /*maxsegsz*/ sizeof(* sc->data), /*flags*/ 0, + &sc->data_tag); + if(error) + goto bad; + + error = bus_dmamem_alloc(sc->data_tag, &sc->data, /* flags*/ 0, + &sc->data_map); + if(error) + goto bad; + + /* xxx_alloc_callback() just saves the physical address at + * the pointer passed as its argument, in this case &sc->data_p. + * See details in the section on bus memory mapping. + * It can be implemented like: + * + * static void + * xxx_alloc_callback(void *arg, bus_dma_segment_t *seg, + * int nseg, int error) + * { + * *(bus_addr_t *)arg = seg[0].ds_addr; + * } + */ + bus_dmamap_load(sc->data_tag, sc->data_map, (void *)sc->data, + sizeof (* sc->data), xxx_alloc_callback, (void *) &sc->data_p, + /*flags*/0); +.... + +После выделения всех необходимых ресурсов устройство должно быть инициализировано. Инициализация может включать проверку работоспособности всех ожидаемых функций. + +[.programlisting] +.... + if(xxx_initialize(sc) < 0) + goto bad; +.... + +Подсистема шины автоматически выводит на консоль описание устройства, установленное при проверке. Однако, если драйвер хочет вывести дополнительную информацию об устройстве, он может это сделать, например: + +[.programlisting] +.... + + device_printf(dev, "has on-card FIFO buffer of %d bytes\n", sc->fifosize); +.... + +Если в процессе выполнения инициализации возникают какие-либо проблемы, рекомендуется выводить сообщения об этих проблемах перед возвратом ошибки. + +Последним шагом процедуры присоединения является подключение устройства к его функциональной подсистеме в ядре. Конкретный способ зависит от типа драйвера: символьное устройство, блочное устройство, сетевое устройство, устройство шины CAM SCSI и так далее. + +Если всё прошло успешно, вернуть успех. + +[.programlisting] +.... + error = xxx_attach_subsystem(sc); + if(error) + goto bad; + + return 0; +.... + +Наконец, обработаем проблемные ситуации. Все ресурсы должны быть освобождены перед возвратом ошибки. Мы используем тот факт, что перед передачей структуры `softc` она обнуляется, поэтому мы можем определить, был ли выделен какой-либо ресурс: если его дескриптор ненулевой. + +[.programlisting] +.... + bad: + + xxx_free_resources(sc); + if(error) + return error; + else /* exact error is unknown */ + return ENXIO; +.... + +Вот и всё для процедуры присоединения. + +[[isa-driver-detach]] +== xxx_isa_detach + +Если эта функция присутствует в драйвере и драйвер скомпилирован как загружаемый модуль, то драйвер получает возможность быть выгруженным. Это важная функция, если оборудование поддерживает горячее подключение. Однако шина ISA не поддерживает горячее подключение, поэтому эта функция не особенно важна для устройств ISA. Возможность выгрузки драйвера может быть полезна при его отладке, но во многих случаях установка новой версии драйвера потребуется только после того, как старая версия каким-то образом заблокирует систему и перезагрузка все равно будет необходима, поэтому усилия, затраченные на написание процедуры отсоединения, могут не окупиться. Другой аргумент, что выгрузка позволит обновлять драйверы на рабочей машине, кажется в основном теоретическим. Установка новой версии драйвера — это опасная операция, которую никогда не следует выполнять на рабочей машине (и которая не разрешена, когда система работает в безопасном режиме). Тем не менее, процедура отсоединения может быть предоставлена для полноты. + +Процедура отсоединения возвращает 0, если драйвер был успешно отсоединён, или код ошибки в противном случае. + +Логика отсоединения является зеркальной по отношению к присоединению. Первое, что нужно сделать, — это отсоединить драйвер от его подсистемы ядра. Если устройство в настоящее время открыто, у драйвера есть два варианта: отказаться от отсоединения или принудительно закрыть устройство и продолжить отсоединение. Выбор зависит от возможности конкретной подсистемы ядра выполнить принудительное закрытие и от предпочтений автора драйвера. Как правило, принудительное закрытие кажется предпочтительным вариантом. + +[.programlisting] +.... + struct xxx_softc *sc = device_get_softc(dev); + int error; + + error = xxx_detach_subsystem(sc); + if(error) + return error; +.... + +Далее драйвер может сбросить аппаратное обеспечение в согласованное состояние. Это включает остановку любых текущих передач, отключение каналов DMA и прерываний, чтобы избежать повреждения памяти устройством. Для большинства драйверов это именно то, что делает процедура выключения, поэтому, если она присутствует в драйвере, мы можем просто вызвать её. + +`xxx_isa_shutdown(dev);` + +И наконец освободить все ресурсы и вернуть успех. + +[.programlisting] +.... + xxx_free_resources(sc); + return 0; +.... + +[[isa-driver-shutdown]] +== xxx_isa_shutdown + +Эта процедура вызывается, когда система собирается быть выключена. Ожидается, что она приведет оборудование в согласованное состояние. Для большинства устройств ISA не требуется никаких специальных действий, поэтому функция не является действительно необходимой, так как устройство будет переинициализировано при перезагрузке в любом случае. Однако некоторые устройства должны быть выключены с помощью специальной процедуры, чтобы убедиться, что они будут правильно обнаружены после мягкой перезагрузки (это особенно актуально для многих устройств с проприетарными протоколами идентификации). В любом случае отключение DMA и прерываний в регистрах устройства и остановка любых текущих передач — это хорошая идея. Точные действия зависят от оборудования, поэтому мы не рассматриваем их здесь подробно. + +[[isa-driver-intr]] +== xxx_intr + +Обработчик прерывания вызывается при получении прерывания, которое может быть от данного конкретного устройства. Шина ISA не поддерживает разделение прерываний (за исключением некоторых специальных случаев), поэтому на практике, если вызывается обработчик прерывания, то прерывание почти наверняка поступило от его устройства. Тем не менее, обработчик прерывания должен опросить регистры устройства и убедиться, что прерывание было сгенерировано его устройством. Если нет, он должен просто вернуть управление. + +Старая практика для драйверов ISA заключалась в получении номера устройства в качестве аргумента. Это устарело, и новые драйверы получают любой аргумент, указанный для них в процедуре присоединения при вызове `bus_setup_intr()`. Согласно новой практике, это должен быть указатель на структуру softc. Таким образом, обработчик прерываний обычно начинается так: + +[.programlisting] +.... + + static void + xxx_intr(struct xxx_softc *sc) + { +.... + +Он выполняется на уровне приоритета прерывания, указанном параметром типа прерывания в `bus_setup_intr()`. Это означает, что все остальные прерывания того же типа, а также все программные прерывания, отключены. + +Во избежание гонок это обычно записывается в виде цикла: + +[.programlisting] +.... + + while(xxx_interrupt_pending(sc)) { + xxx_process_interrupt(sc); + xxx_acknowledge_interrupt(sc); + } +.... + +Обработчик прерывания должен подтвердить прерывание только устройству, но не контроллеру прерываний, система позаботится о последнем. diff --git a/documentation/content/ru/books/arch-handbook/isa/_index.po b/documentation/content/ru/books/arch-handbook/isa/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/isa/_index.po @@ -0,0 +1,4236 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-09 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 "Драйверы устройств ISA" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1 +#, no-wrap +msgid "Chapter 10. ISA Device Drivers" +msgstr "Глава 10. Драйверы устройств ISA" + +#. 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 "" +"Эта глава знакомит с вопросами, относящимся к написанию драйвера устройства " +"ISA. Представленный здесь псевдокод довольно детализирован и напоминает " +"реальный код, но всё же остаётся псевдокодом. Он избегает деталей, не " +"относящихся к теме обсуждения. Реальные примеры можно найти в исходном коде " +"настоящих драйверов. В частности, драйверы `ep` и `aha` являются хорошими " +"источниками информации." + +#. 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 "Типичному драйверу ISA могут потребоваться следующие включаемые файлы:" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:68 +#, no-wrap +msgid "" +"#include \n" +"#include \n" +"#include \n" +"#include \n" +"#include \n" +msgstr "" +"#include \n" +"#include \n" +"#include \n" +"#include \n" +"#include \n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:71 +#, no-wrap +msgid "" +"#include \n" +"#include \n" +msgstr "" +"#include \n" +"#include \n" + +#. 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 "" +"Они описывают особенности, специфичные для подсистемы ISA и обобщенной шины." + +#. 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 "" +"Список методов шины, реализуемых драйвером ISA, аналогичен списку для любой " +"другой шины. Для гипотетического драйвера с именем \"xxx\" они будут:" + +#. 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 "" +"`static void xxx_isa_identify (driver_t *, device_t);` Обычно используется " +"для драйверов шины, а не для драйверов устройств. Однако для устройств ISA " +"этот метод может иметь особое применение: если устройство предоставляет " +"специфический (не PnP) способ автоматического обнаружения устройств, эта " +"процедура может его реализовывать." + +#. 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 "" +"`static int xxx_isa_probe (device_t dev);` Проверка наличия устройства в " +"известном (или PnP) расположении. Эта процедура также может учитывать " +"автоопределение параметров, специфичных для устройства, в случае частично " +"настроенных устройств." + +#. 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 "" +"`static int xxx_isa_attach (device_t dev);` Подключение и инициализация " +"устройства." + +#. 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 "" +"`static int xxx_isa_detach (device_t dev);` Отсоединение устройства перед " +"выгрузкой модуля драйвера." + +#. 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 "" +"`static int xxx_isa_shutdown (device_t dev);` Выполняет завершение работы " +"устройства перед выключением системы." + +#. 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 "" +"`static int xxx_isa_suspend (device_t dev);` Приостанавливает устройство " +"перед переходом системы в энергосберегающий режим. Также может прервать " +"переход в энергосберегающий режим." + +#. 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 "" +"`static int xxx_isa_resume (device_t dev);` Возобновляет активность " +"устройства после возврата из энергосберегающего состояния." + +#. 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 "" +"`xxx_isa_probe()` и `xxx_isa_attach()` являются обязательными, остальные " +"процедуры опциональны и зависят от потребностей устройства." + +#. 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 "" +" /* 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" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:107 +#, no-wrap +msgid "" +"\tDEVMETHOD_END\n" +" };\n" +msgstr "" +"\tDEVMETHOD_END\n" +" };\n" + +#. 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 "" +" static driver_t xxx_isa_driver = {\n" +" \"xxx\",\n" +" xxx_isa_methods,\n" +" sizeof(struct xxx_softc),\n" +" };\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:115 +#, no-wrap +msgid " static devclass_t xxx_devclass;\n" +msgstr " static devclass_t xxx_devclass;\n" + +#. 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 "" +" DRIVER_MODULE(xxx, isa, xxx_isa_driver, xxx_devclass,\n" +" load_function, load_argument);\n" + +#. 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 "" +"Здесь структура `xxx_softc` — это специфичная для устройства структура, " +"которая содержит приватные данные драйвера и дескрипторы ресурсов драйвера. " +"Код шины автоматически выделяет один дескриптор softc для каждого устройства " +"по мере необходимости." + +#. 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 "" +"Если драйвер реализован в виде загружаемого модуля, то `load_function()` " +"вызывается для выполнения специфичной для драйвера инициализации или очистки " +"при загрузке или выгрузке драйвера, а `load_argument` передаётся в качестве " +"одного из её аргументов. Если драйвер не поддерживает динамическую загрузку " +"(другими словами, он всегда должен быть связан с ядром), то эти значения " +"должны быть установлены в 0, и последнее определение будет выглядеть " +"следующим образом:" + +#. 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 "" +" DRIVER_MODULE(xxx, isa, xxx_isa_driver,\n" +" xxx_devclass, 0, 0);\n" + +#. 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 "" +"Если драйвер предназначен для устройства с поддержкой PnP, то должна быть " +"определена таблица поддерживаемых PnP ID. Таблица состоит из списка PnP ID, " +"поддерживаемых этим драйвером, и удобочитаемых описаний типов аппаратного " +"обеспечения и моделей, имеющих эти ID. Это выглядит следующим образом:" + +#. 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 "" +" 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" + +#. 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 "" +"Если драйвер не поддерживает устройства PnP, ему все равно нужна пустая " +"таблица идентификаторов PnP, например:" + +#. 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 "" +" static struct isa_pnp_id xxx_pnp_ids[] = {\n" +" { 0, NULL }, /* end of table */\n" +" };\n" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:152 +#, no-wrap +msgid "`device_t` Pointer" +msgstr "Указатель `device_t`" + +#. 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 "" +"`device_t` — это тип указателя на структуру устройства. Здесь мы " +"рассматриваем только методы, представляющие интерес с точки зрения " +"разработчика драйверов устройств. Методы для работы со значениями в " +"структуре устройства следующие:" + +#. 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 "" +"`device_t device_get_parent(dev)` Получить родительскую шину устройства." + +#. 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 "" +"`driver_t device_get_driver(dev)` Получить указатель на структуру его " +"драйвера." + +#. 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 "" +"`char *device_get_name(dev)` Получить имя драйвера, например `\"xxx\"` в " +"нашем примере." + +#. 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 "" +"`int device_get_unit(dev)` Получить номер устройства (устройства нумеруются " +"с 0 для устройств, связанных с каждым драйвером)." + +#. 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 "" +"`char *device_get_nameunit(dev)` Получить имя устройства, включая номер " +"юнита, например, \"xxx0\", \"xxx1\" и так далее." + +#. 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 "" +"`char *device_get_desc(dev)` Получить описание устройства. Обычно оно " +"описывает точную модель устройства в удобочитаемом виде." + +#. 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 "" +"`device_set_desc(dev, desc)` Установить описание. Это заставляет описание " +"устройства указывать на строку desc, которая не может быть освобождена или " +"изменена после этого." + +#. 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 "" +"`device_set_desc_copy(dev, desc)` Устанавить описание. Описание копируется " +"во внутренний динамически выделяемый буфер, поэтому строка desc может быть " +"изменена впоследствии без негативных последствий." + +#. 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 "" +"`void *device_get_softc(dev)` Получить указатель на дескриптор устройства " +"(структура `xxx_softc`), связанный с данным устройством." + +#. 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 "" +"`u_int32_t device_get_flags(dev)` Получить флаги, указанные для устройства в " +"файле конфигурации." + +#. 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 "" +"Функция для удобства `device_printf(dev, fmt, ...)` может использоваться для " +"вывода сообщений из драйвера устройства. Она автоматически добавляет имя " +"устройства и двоеточие перед сообщением." + +#. 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 "Методы device_t реализованы в файле [.filename]#kern/bus_subr.c#." + +#. 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 "" +"Устройства ISA описываются в файле конфигурации ядра следующим образом:" + +#. 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 "" +"device xxx0 at isa? port 0x300 irq 10 drq 5\n" +" iomem 0xd0000 flags 0x1 sensitive\n" + +#. 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 "" +"Значения порта, IRQ и т. д. преобразуются в ресурсы, связанные с " +"устройством. Они являются необязательными, в зависимости от потребностей " +"устройства и его способностей к автонастройке. Например, некоторым " +"устройствам вообще не нужен DRQ, а некоторые позволяют драйверу читать " +"настройку IRQ из портов конфигурации устройства. Если в машине несколько шин " +"ISA, точная шина может быть указана в строке конфигурации, например `isa0` " +"или `isa1`, иначе устройство будет искаться на всех шинах ISA." + +#. 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 "" +"`sensitive` — это ресурс, указывающий, что данное устройство должно быть " +"проверено перед всеми нечувствительными устройствами. Он поддерживается, но, " +"похоже, не используется ни в одном текущем драйвере." + +#. 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 "" +"Для устаревших устройств ISA во многих случаях драйверы всё ещё могут " +"определять параметры конфигурации. Однако каждое устройство, которое " +"необходимо настроить в системе, должно иметь строку конфигурации. Если в " +"системе установлено два устройства одного типа, но для соответствующего " +"драйвера есть только одна строка конфигурации, например:" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:190 +#, no-wrap +msgid "device xxx0 at isa?\n" +msgstr "device xxx0 at isa?\n" + +#. 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 " тогда будет настроено только одно устройство.\n" + +#. 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 "" +"Однако для устройств, поддерживающих автоматическую идентификацию с помощью " +"Plug-n-Play или какого-либо проприетарного протокола, достаточно одной " +"строки конфигурации для настройки всех устройств в системе, как в примере " +"выше или просто:" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:198 +#, no-wrap +msgid "device xxx at isa?\n" +msgstr "device xxx at isa?\n" + +#. 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 "" +"При автоматической настройке шины ISA события происходят в следующем порядке:" + +#. 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 "" +"Все процедуры идентификации драйверов (включая процедуру идентификации PnP, " +"которая определяет все устройства PnP) вызываются в случайном порядке. Когда " +"они идентифицируют устройства, они добавляют их в список на шине ISA. Обычно " +"процедуры идентификации драйверов связывают свои драйверы с новыми " +"устройствами. Процедура идентификации PnP пока не знает о других драйверах, " +"поэтому не связывает ни один из них с новыми устройствами, которые она " +"добавляет." + +#. 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 "" +"Устройства PnP переводятся в режим сна с использованием протокола PnP, чтобы " +"предотвратить их обнаружение как устаревших устройств." + +#. 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 "" +"Вызываются процедуры обнаружения для устройств, не поддерживающих PnP, " +"помеченных как `sensitive`. Если процедура обнаружения для устройства " +"завершилась успешно, вызывается процедура присоединения для него." + +#. 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 "" +"Вызов процедур обнаружения и присоединения всех устройств, не поддерживающих " +"PNP, выполняется аналогичным образом." + +#. 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 "" +"Устройства PnP выводятся из состояния сна и получают запрошенные ресурсы: " +"диапазоны адресов ввода-вывода и памяти, IRQ и DRQ, причем все они не " +"конфликтуют с подключенными устаревшими устройствами." + +#. 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 "" +"Затем для каждого устройства PnP вызываются процедуры обнаружения всех " +"присутствующих драйверов ISA. Первый драйвер, который заявит о поддержке " +"устройства, будет присоединен. Возможна ситуация, когда несколько драйверов " +"заявят о поддержке устройства с разным приоритетом; в этом случае побеждает " +"драйвер с наивысшим приоритетом. Процедуры обнаружения должны вызывать " +"`ISA_PNP_PROBE()` для сравнения фактического PnP ID со списком ID, " +"поддерживаемых драйвером, и если ID отсутствует в таблице, возвращать " +"ошибку. Это означает, что абсолютно каждый драйвер, даже те, которые не " +"поддерживают никакие PnP устройства, должны вызывать `ISA_PNP_PROBE()`, хотя " +"бы с пустой таблицей PnP ID, чтобы возвращать ошибку для неизвестных PnP " +"устройств." + +#. 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 "" +"Отрицательные возвращаемые значения используются, когда устройство PnP " +"поддерживает несколько интерфейсов. Например, старый совместимый интерфейс и " +"новый расширенный интерфейс, которые поддерживаются разными драйверами. В " +"этом случае оба драйвера обнаружат устройство. Драйвер, возвращающий большее " +"значение в процедуре обнаружения, получает приоритет (другими словами, " +"драйвер, возвращающий 0, имеет наивысший приоритет, возвращающий -1 — " +"следующий, возвращающий -2 — за ним и так далее). В результате устройства, " +"поддерживающие только старый интерфейс, будут обрабатываться старым " +"драйвером (который должен возвращать -1 из процедуры обнаружения), тогда как " +"устройства, поддерживающие также новый интерфейс, будут обрабатываться новым " +"драйвером (который должен возвращать 0 из процедуры обнаружения). Если " +"несколько драйверов возвращают одинаковое значение, побеждает тот, который " +"был вызван первым. Таким образом, если драйвер возвращает значение 0, он " +"может быть уверен, что выиграл арбитраж приоритетов." + +#. 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 "" +"Процедуры идентификации, специфичные для устройства, также могут назначать " +"устройству не драйвер, а класс драйверов. Затем все драйверы в этом классе " +"проверяются на совместимость с устройством, как в случае с PnP. Эта " +"возможность не реализована ни в одном существующем драйвере и далее в этом " +"документе не рассматривается." + +#. 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 "" +"Поскольку устройства PnP отключены при проверке устаревших устройств, они не " +"будут присоединены дважды (один раз как устаревшие и один раз как PnP). " +"Однако в случае процедур идентификации, зависящих от устройства, " +"ответственность за то, чтобы одно и то же устройство не было присоединено " +"драйвером дважды (один раз как настроенное пользователем устаревшее и один " +"раз как автоматически идентифицированное), лежит на драйвере." + +#. 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 "" +"Еще одно практическое следствие для автоматически определяемых устройств " +"(как PnP, так и специфичных для устройства) заключается в том, что флаги не " +"могут быть переданы им из файла конфигурации ядра. Поэтому они либо не " +"должны использовать флаги вообще, либо использовать флаги из устройства unit " +"0 для всех автоматически определяемых устройств, либо использовать интерфейс " +"sysctl вместо флагов." + +#. 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 "" +"Другие нестандартные конфигурации могут быть реализованы путем прямого " +"доступа к ресурсам конфигурации с использованием функций семейств " +"`resource_query_*()` и `resource_*_value()`. Их реализации находятся в " +"[.filename]#kern/subr_bus.c#. Примеры такого использования есть в старом " +"драйвере диска IDE [.filename]#i386/isa/wd.c#. Однако стандартные методы " +"конфигурации всегда должны быть предпочтительны. Оставьте разбор ресурсов " +"конфигурации коду настройки шины." + +#. 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 "" +"Информация, которую пользователь вводит в файл конфигурации ядра, " +"обрабатывается и передаётся ядру в виде ресурсов конфигурации. Эта " +"информация анализируется кодом конфигурации шины и преобразуется в значение " +"структуры `device_t` и связанные с ней ресурсы шины. Драйверы могут напрямую " +"обращаться к ресурсам конфигурации, используя функции `resource_*` для более " +"сложных случаев конфигурации. Однако, как правило, в этом нет необходимости, " +"и это не рекомендуется, поэтому данный вопрос далее не рассматривается." + +#. 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 "" +"Ресурсы шины связаны с каждым устройством. Они идентифицируются по типу и " +"номеру внутри типа. Для шины ISA определены следующие типы:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:236 +msgid "_SYS_RES_IRQ_ - interrupt number" +msgstr "_SYS_RES_IRQ_ - номер прерывания" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:237 +msgid "_SYS_RES_DRQ_ - ISA DMA channel number" +msgstr "_SYS_RES_DRQ_ - номер канала ISA DMA" + +#. 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 "" +"_SYS_RES_MEMORY_ - диапазон памяти устройства, отображенный в системное " +"адресное пространство" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:239 +msgid "_SYS_RES_IOPORT_ - range of device I/O registers" +msgstr "_SYS_RES_IOPORT_ - диапазон регистров ввода-вывода устройства" + +#. 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 "" +"Перечисление внутри типов начинается с 0, поэтому если устройство имеет две " +"области памяти, оно будет иметь ресурсы типа `SYS_RES_MEMORY` с номерами 0 и " +"1. Тип ресурса не связан с типом языка C, все значения ресурсов имеют тип " +"`unsigned long` в языке C и должны быть приведены по мере необходимости. " +"Номера ресурсов не обязательно должны быть последовательными, хотя для ISA " +"они обычно таковыми являются. Допустимые номера ресурсов для устройств ISA:" + +#. 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 "" +" IRQ: 0-1\n" +" DRQ: 0-1\n" +" MEMORY: 0-3\n" +" IOPORT: 0-7\n" + +#. 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 "" +"Все ресурсы представлены в виде диапазонов с начальным значением и " +"количеством. Для ресурсов IRQ и DRQ количество обычно равно 1. Значения для " +"памяти относятся к физическим адресам." + +#. 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 "Установка — set/get" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:256 +msgid "allocate/release" +msgstr "Выделение — allocate/release" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:257 +msgid "activate/deactivate" +msgstr "Активация — activate/deactivate" + +#. 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 "" +"`int bus_set_resource(device_t dev, int type, int rid, u_long start, u_long " +"count)`" + +#. 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 "" +"Устанавливает диапазон для ресурса. Возвращает 0 при успешном выполнении, в " +"противном случае — код ошибки. Обычно эта функция возвращает ошибку только в " +"том случае, если одно из значений `type`, `rid`, `start` или `count` выходит " +"за пределы допустимого диапазона." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:267 +msgid "dev - driver's device" +msgstr "dev - устройство драйвера" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:268 +msgid "type - type of resource, SYS_RES_*" +msgstr "тип - тип ресурса, SYS_RES_*" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:269 +msgid "rid - resource number (ID) within type" +msgstr "rid - номер ресурса (ID) в пределах типа" + +#. 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 "" +"`int bus_get_resource(device_t dev, int type, int rid, u_long *startp, " +"u_long *countp)`" + +#. 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 "" +"Получает диапазон ресурса. Возвращает 0 при успехе, код ошибки, если ресурс " +"ещё не определён." + +#. 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 "" +"`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)`" + +#. 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 "" +"Удобные функции для получения только начала или количества. Возвращают 0 в " +"случае ошибки, поэтому если начало ресурса может законно содержать 0, " +"невозможно определить, является ли значение 0 или произошла ошибка. К " +"счастью, ни один ресурс ISA для дополнительных драйверов не может иметь " +"начальное значение, равное 0." + +#. 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 "`void bus_delete_resource(device_t dev, int type, int rid)`" + +#. 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 "" +"`struct resource * bus_alloc_resource(device_t dev, int type, int *rid, " +"u_long start, u_long end, u_long count, u_int flags)`" + +#. 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 "" +"Выделяет ресурс как диапазон значений count, не выделенных никем другим, где-" +"то между start и end. Увы, выравнивание не поддерживается. Если ресурс ещё " +"не был установлен, он автоматически создаётся. Специальные значения start " +"равное 0 и end равное ~0 (все единицы) означают, что должны использоваться " +"фиксированные значения, ранее установленные `bus_set_resource()`: start и " +"count как есть, а end=(start+count). В этом случае, если ресурс не был " +"определён ранее, возвращается ошибка. Хотя rid передаётся по ссылке, он " +"нигде не устанавливается кодом выделения ресурсов шины ISA. Другие шины " +"могут использовать иной подход и изменять его." + +#. 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 "" +"_RF_ACTIVE_ - приводит к автоматической активации ресурса после его " +"выделения." + +#. 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 "" +"_RF_SHAREABLE_ - ресурс может использоваться одновременно несколькими " +"драйверами." + +#. 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 "" +"_RF_TIMESHARE_ - ресурс может разделяться по времени несколькими драйверами, " +"т.е. выделяться одновременно многими, но активироваться только одним в любой " +"момент времени." + +#. 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 "" +"Возвращает 0 при ошибке. Выделенные значения могут быть получены из " +"возвращённого дескриптора с использованием методов `rhand_*()`." + +#. 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 "" +"`int bus_release_resource(device_t dev, int type, int rid, struct resource " +"*r)`" + +#. 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 "" +"Освобождает ресурс, r — это дескриптор, возвращённый `bus_alloc_resource()`. " +"Возвращает 0 при успехе, код ошибки в противном случае." + +#. 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 "" +"`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)`" + +#. 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 "" +"Активирует или деактивирует ресурс. Возвращает 0 при успехе, в противном " +"случае — код ошибки. Если ресурс разделяемый и в данный момент активирован " +"другим драйвером, возвращается `EBUSY`." + +#. 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 "" +"`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)`" + +#. 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 "" +"Связывает или разрывает связь обработчика прерывания с устройством. " +"Возвращает 0 при успехе, код ошибки в противном случае." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:297 +msgid "r - the activated resource handler describing the IRQ" +msgstr "r - активированный обработчик ресурсов, описывающий IRQ" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:299 +msgid "flags - the interrupt priority level, one of:" +msgstr "flags - уровень приоритета прерывания, один из:" + +#. 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 "" +"`INTR_TYPE_TTY` - терминалы и другие аналогичные символьные устройства. Для " +"их маскировки используйте `spltty()`." + +#. 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 "" +"`(INTR_TYPE_TTY | INTR_TYPE_FAST)` - терминальные устройства с малым буфером " +"ввода, критичные к потере данных на входе (например, устаревшие " +"последовательные порты). Для их маскирования используйте `spltty()`." + +#. 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 "" +"`INTR_TYPE_BIO` - блочные устройства, за исключением тех, что подключены к " +"контроллерам CAM. Для их маскирования используйте `splbio()`." + +#. 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 "" +"`INTR_TYPE_CAM` - контроллеры шины CAM (Common Access Method). Для их " +"маскирования используйте `splcam()`." + +#. 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 "" +"`INTR_TYPE_NET` - контроллеры сетевых интерфейсов. Для их маскирования " +"используйте `splimp()`." + +#. 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 "" +"`INTR_TYPE_MISC` — прочие устройства. Нет другого способа их маскировки, " +"кроме `splhigh()`, который маскирует все прерывания." + +#. 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 "" +"Когда обработчик прерывания выполняется, все другие прерывания, " +"соответствующие его уровню приоритета, будут заблокированы. Единственное " +"исключение — уровень MISC, для которого никакие другие прерывания не " +"блокируются и который сам не блокируется другими прерываниями." + +#. 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 "" +"_handler_ - указатель на функцию-обработчик, тип driver_intr_t определён как " +"`void driver_intr_t(void *)`" + +#. 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 "" +"_arg_ - аргумент, передаваемый обработчику для идентификации конкретного " +"устройства. Приводится обработчиком от void* к фактическому типу. Старая " +"конвенция для обработчиков прерываний ISA предполагала использование номера " +"устройства в качестве аргумента, новая (рекомендуемая) конвенция " +"предполагает использование указателя на структуру softc устройства." + +#. 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 "" +"_cookie[p]_ - значение, полученное из `setup()`, используется для " +"идентификации обработчика при передаче в `teardown()`" + +#. 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 "" +"Определены несколько методов для работы с обработчиками ресурсов (struct " +"resource *). Вот те из них, которые представляют интерес для разработчиков " +"драйверов устройств:" + +#. 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 "" +"`u_long rman_get_start(r) u_long rman_get_end(r)` Получают начало и конец " +"выделенного диапазона ресурсов." + +#. 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 "" +"`void *rman_get_virtual(r)` Получает виртуальный адрес активированного " +"ресурса памяти." + +#. 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 "(b) память — это основная память компьютера" + +#. 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 "" +"В случае (a) драйвер всегда копирует данные между памятью на карте и " +"основной памятью по мере необходимости. Для отображения памяти на карте в " +"виртуальное адресное пространство ядра физический адрес и длина памяти на " +"карте должны быть определены как ресурс `SYS_RES_MEMORY`. Этот ресурс может " +"быть затем выделен и активирован, а его виртуальный адрес получен с помощью " +"`rman_get_virtual()`. Более старые драйверы использовали для этой цели " +"функцию `pmap_mapdev()`, которую больше не следует использовать напрямую. " +"Теперь это один из внутренних шагов активации ресурса." + +#. 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 "" +"Большинство ISA-карт имеют память, настроенную на физическое расположение в " +"диапазоне 640 КБ–1 МБ. Некоторые ISA-карты требуют большего диапазона " +"памяти, который должен быть размещён ниже 16 МБ (из-за 24-битного " +"ограничения адресации на шине ISA). В таком случае, если в машине больше " +"памяти, чем начальный адрес памяти устройства (другими словами, они " +"пересекаются), необходимо настроить \"дыру\" в памяти по диапазону адресов, " +"используемому устройствами. Многие BIOS позволяют настроить \"дыру\" в " +"памяти размером 1 МБ, начиная с 14 МБ или 15 МБ. FreeBSD корректно " +"обрабатывает \"дыры\" в памяти, если BIOS правильно их сообщает (эта функция " +"может не работать в старых BIOS)." + +#. 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 "" +"В случае (b) только адрес данных отправляется на устройство, и устройство " +"использует DMA для фактического доступа к данным в основной памяти. " +"Существуют два ограничения: во-первых, карты ISA могут обращаться только к " +"памяти ниже 16 МБ. Во-вторых, непрерывные страницы в виртуальном адресном " +"пространстве могут не быть непрерывными в физическом адресном пространстве, " +"поэтому устройству может потребоваться выполнять операции scatter/gather. " +"Подсистема шины предоставляет готовые решения для некоторых из этих проблем, " +"остальное должно быть реализовано самими драйверами." + +#. 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 "" +"Для выделения памяти DMA используются две структуры: `bus_dma_tag_t` и " +"`bus_dmamap_t`. Тег (`tag`) описывает свойства, необходимые для памяти DMA. " +"Карта (`map`) представляет собой блок памяти, выделенный в соответствии с " +"этими свойствами. С одним тегом может быть связано несколько карт." + +#. 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 "" +"Второй момент: произвольная область виртуальной памяти может быть загружена " +"в карту. Каждая страница этой памяти будет проверяться на соответствие " +"требованиям карты. Если она соответствует, то остается на своем исходном " +"месте. Если нет, то выделяется новая соответствующая \"отскоковая страница\" " +"(bounce page), которая используется как промежуточное хранилище. При записи " +"данных с несоответствующих исходных страниц они сначала копируются на свои " +"отскоковые страницы, а затем передаются с отскоковых страниц на устройство. " +"При чтении данные поступают с устройства на отскоковые страницы, а затем " +"копируются на свои несоответствующие исходные страницы. Процесс копирования " +"между исходными и отскоковыми страницами называется синхронизацией. Обычно " +"это используется для каждой передачи: буфер для каждой передачи загружается, " +"передача выполняется, и буфер выгружается." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:346 +msgid "The functions working on the DMA memory are:" +msgstr "Функции, работающие с памятью DMA:" + +#. 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 "" +"`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)`" + +#. 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 "" +"Создать новый тег. Возвращает 0 при успехе, код ошибки в противном случае." + +#. 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 "" +"_parent_ - родительский тег, или NULL для создания тега верхнего уровня." + +#. 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 "" +"_alignment_ - требуемое физическое выравнивание области памяти, которая " +"будет выделена для этого тега. Используйте значение 1 для \"без " +"специфического выравнивания\". Применяется только к будущим вызовам " +"`bus_dmamem_alloc()`, но не `bus_dmamap_create()`." + +#. 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 "" +"_boundary_ - физическая граница адреса, которую нельзя пересекать при " +"выделении памяти. Используйте значение 0 для обозначения \"нет границы\". " +"Применяется только к будущим вызовам `bus_dmamem_alloc()`, но не " +"`bus_dmamap_create()`. Должна быть степенью 2. Если память планируется " +"использовать в некаскадном режиме DMA (т.е. адреса DMA будут предоставляться " +"не самим устройством, а контроллером DMA ISA), то граница не должна " +"превышать 64 КБ (64*1024) из-за ограничений аппаратного обеспечения DMA." + +#. 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 "" +"_lowaddr, highaddr_ - названия немного вводят в заблуждение; эти значения " +"используются для ограничения допустимого диапазона физических адресов, " +"используемых для выделения памяти. Точное значение зависит от " +"предполагаемого будущего использования:" + +#. 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 "" +"Для `bus_dmamem_alloc()` все адреса от 0 до lowaddr-1 считаются " +"разрешёнными, а более высокие — запрещёнными." + +#. 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 "" +"Для `bus_dmamap_create()` все адреса вне включительного диапазона [lowaddr; " +"highaddr] считаются доступными. Адреса страниц внутри диапазона передаются в " +"функцию-фильтр, которая определяет, доступны ли они. Если функция-фильтр не " +"предоставлена, то весь диапазон считается недоступным." + +#. 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 "Для устройств ISA обычные значения (без функции фильтрации) следующие:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:361 +msgid "lowaddr = BUS_SPACE_MAXADDR_24BIT" +msgstr "lowaddr = BUS_SPACE_MAXADDR_24BIT" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:363 +msgid "highaddr = BUS_SPACE_MAXADDR" +msgstr "highaddr = BUS_SPACE_MAXADDR" + +#. 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 "" +"_filter, filterarg_ - функция фильтра и её аргумент. Если передаётся NULL " +"для filter, то весь диапазон [lowaddr, highaddr] считается недоступным при " +"выполнении `bus_dmamap_create()`. В противном случае физический адрес каждой " +"страницы в диапазоне [lowaddr; highaddr] передаётся в функцию фильтра, " +"которая определяет, доступна ли она. Прототип функции фильтра: `int " +"filterfunc(void *arg, bus_addr_t paddr)`. Функция должна вернуть 0, если " +"страница доступна, и ненулевое значение в противном случае." + +#. 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 "" +"_maxsize_ - максимальный размер памяти (в байтах), который может быть " +"выделен через этот тег. Если сложно оценить или он может быть произвольно " +"большим, для устройств ISA следует использовать значение " +"`BUS_SPACE_MAXSIZE_24BIT`." + +#. 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 "" +"_nsegments_ - максимальное количество сегментов scatter-gather, " +"поддерживаемых устройством. Если ограничений нет, следует использовать " +"значение `BUS_SPACE_UNRESTRICTED`. Это значение рекомендуется для " +"родительских тегов, фактические ограничения затем будут указаны для дочерних " +"тегов. Теги с nsegments равным `BUS_SPACE_UNRESTRICTED` не могут " +"использоваться для фактической загрузки отображений, они могут применяться " +"только как родительские теги. Практический предел для nsegments составляет " +"около 250-300, более высокие значения вызовут переполнение стека ядра " +"(аппаратное обеспечение обычно не поддерживает такое большое количество " +"scatter-gather буферов в любом случае)." + +#. 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 "" +"_maxsegsz_ — максимальный размер сегмента scatter-gather, поддерживаемый " +"устройством. Максимальное значение для устройства ISA будет " +"`BUS_SPACE_MAXSIZE_24BIT`." + +#. 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 "_flags_ - битовая маска флагов. Единственный интересный флаг:" + +#. 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 "" +"_BUS_DMA_ALLOCNOW_ - запрашивает выделение всех потенциально необходимых " +"страниц отскока при создании тега." + +#. 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 "_dmat_ - указатель на хранилище для нового возвращаемого тега." + +#. 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 "`int bus_dma_tag_destroy(bus_dma_tag_t dmat)`" + +#. 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 "" +"Уничтожить тег. Возвращает 0 при успехе, код ошибки в противном случае." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:379 +msgid "dmat - the tag to be destroyed." +msgstr "dmat - тег, который должен быть уничтожен." + +#. 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 "" +"`int bus_dmamem_alloc(bus_dma_tag_t dmat, void** vaddr, int flags, " +"bus_dmamap_t *mapp)`" + +#. 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 "" +"Выделить область непрерывной памяти, описанную тегом. Размер выделяемой " +"памяти соответствует maxsize тега. Возвращает 0 при успехе, иначе код " +"ошибки. Результат всё ещё должен быть загружен с помощью `bus_dmamap_load()` " +"перед использованием для получения физического адреса памяти." + +#. 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 "_dmat_ - тег" + +#. 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 "" +"_vaddr_ - указатель на хранилище для возвращаемого виртуального адреса ядра " +"выделенной области." + +#. 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 "flags - битовая карта флагов. Единственный интересный флаг:" + +#. 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 "" +"_BUS_DMA_NOWAIT_ - если память недоступна немедленно, вернуть ошибку. Если " +"этот флаг не установлен, то процедуре разрешено ожидать до тех пор, пока " +"память не станет доступной." + +#. 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 "_mapp_ - указатель на хранилище для возвращаемой новой карты." + +#. 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 "" +"`void bus_dmamem_free(bus_dma_tag_t dmat, void *vaddr, bus_dmamap_t map)`" + +#. 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 "" +"Освободить память, выделенную `bus_dmamem_alloc()`. В настоящее время " +"освобождение памяти, выделенной с ограничениями ISA, не реализовано. В связи " +"с этим рекомендуется сохранять и повторно использовать выделенные области " +"как можно дольше. Не следует без необходимости освобождать область и вскоре " +"снова её выделять. Это не означает, что `bus_dmamem_free()` не следует " +"использовать вовсе: есть надежда, что вскоре она будет реализована должным " +"образом." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:397 +msgid "_vaddr_ - the kernel virtual address of the memory" +msgstr "_vaddr_ - виртуальный адрес памяти ядра" + +#. 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 "_map_ - карта памяти (как возвращается из `bus_dmamem_alloc()`)" + +#. 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 "" +"`int bus_dmamap_create(bus_dma_tag_t dmat, int flags, bus_dmamap_t *mapp)`" + +#. 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 "" +"Создать карту для тега, которая будет использоваться в `bus_dmamap_load()` " +"позже. Возвращает 0 при успехе, в противном случае — код ошибки." + +#. 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 "" +"_flags_ - теоретически, битовая карта флагов. Однако пока никакие флаги не " +"определены, поэтому в настоящее время значение всегда будет 0." + +#. 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 "" +"_mapp_ - указатель на хранилище для новой карты, которая будет возвращена" + +#. 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 "`int bus_dmamap_destroy(bus_dma_tag_t dmat, bus_dmamap_t map)`" + +#. 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 "" +"Уничтожить карту. Возвращает 0 при успехе, в противном случае — код ошибки." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:412 +msgid "dmat - the tag to which the map is associated" +msgstr "dmat - тег, с которым ассоциирована карта" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:413 +msgid "map - the map to be destroyed" +msgstr "map - карта, подлежащая уничтожению" + +#. 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 "" +"`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)`" + +#. 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 "" +"Загрузить буфер в карту (карта должна быть предварительно создана с помощью " +"`bus_dmamap_create()` или `bus_dmamem_alloc()`). Все страницы буфера " +"проверяются на соответствие требованиям тега, и для несоответствующих " +"выделяются страницы отскока. Создается массив дескрипторов физических " +"сегментов и передается в подпрограмму обратного вызова. Ожидается, что эта " +"подпрограмма обработает его каким-либо образом. Количество буферов отскока в " +"системе ограничено, поэтому, если эти буферы требуются, но недоступны " +"немедленно, запрос будет поставлен в очередь, и обратный вызов будет " +"выполнен, когда буферы отскова станут доступны. Возвращает 0, если обратный " +"вызов был выполнен немедленно, или `EINPROGRESS`, если запрос был поставлен " +"в очередь для выполнения в будущем. В последнем случае синхронизация с " +"подпрограммой обратного вызова, поставленной в очередь, является " +"обязанностью драйвера." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:420 +msgid "_map_ - the map" +msgstr "_map_ - карта" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:421 +msgid "_buf_ - kernel virtual address of the buffer" +msgstr "_buf_ - виртуальный адрес буфера в пространстве ядра" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:422 +msgid "_buflen_ - length of the buffer" +msgstr "_buflen_ - длина буфера" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:423 +msgid "_callback_, `callback_arg` - the callback function and its argument" +msgstr "_callback_, `callback_arg` - функция обратного вызова и её аргумент" + +#. 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 "" +"Прототип функции обратного вызова: `void callback(void *arg, " +"bus_dma_segment_t *seg, int nseg, int error)`" + +#. 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 "" +"_arg_ - то же самое, что и callback_arg, переданный в `bus_dmamap_load()`" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:428 +msgid "_seg_ - array of the segment descriptors" +msgstr "_seg_ - массив дескрипторов сегментов" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:429 +msgid "_nseg_ - number of descriptors in array" +msgstr "_nseg_ - количество дескрипторов в массиве" + +#. 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 "" +"_error_ - указание на переполнение номера сегмента: если установлено " +"значение `EFBIG`, значит буфер не поместился в максимальное количество " +"сегментов, разрешённых тегом. В этом случае в массиве будет только " +"разрешённое количество дескрипторов. Обработка этой ситуации зависит от " +"драйвера: в зависимости от желаемой семантики он может либо считать это " +"ошибкой, либо разделить буфер на две части и обработать вторую часть отдельно" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:432 +msgid "Each entry in the segments array contains the fields:" +msgstr "Каждая запись в массиве segments содержит поля:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:434 +msgid "_ds_addr_ - physical bus address of the segment" +msgstr "_ds_addr_ - физический адрес шины сегмента" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:435 +msgid "_ds_len_ - length of the segment" +msgstr "_ds_len_ - длина сегмента" + +#. 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 "`void bus_dmamap_unload(bus_dma_tag_t dmat, bus_dmamap_t map)`" + +#. 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 "_dmat_ - тег" + +#. 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 "_map_ - загруженная карта" + +#. 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 "" +"`void bus_dmamap_sync (bus_dma_tag_t dmat, bus_dmamap_t map, " +"bus_dmasync_op_t op)`" + +#. 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 "_op_ - тип операции синхронизации для выполнения:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:452 +msgid "`BUS_DMASYNC_PREREAD` - before reading from device into buffer" +msgstr "`BUS_DMASYNC_PREREAD` - перед чтением с устройства в буфер" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:453 +msgid "`BUS_DMASYNC_POSTREAD` - after reading from device into buffer" +msgstr "`BUS_DMASYNC_POSTREAD` - после чтения из устройства в буфер" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:454 +msgid "`BUS_DMASYNC_PREWRITE` - before writing the buffer to device" +msgstr "`BUS_DMASYNC_PREWRITE` - перед записью буфера в устройство" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:455 +msgid "`BUS_DMASYNC_POSTWRITE` - after writing the buffer to device" +msgstr "`BUS_DMASYNC_POSTWRITE` - после записи буфера в устройство" + +#. 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 "" +"На данный момент PREREAD и POSTWRITE являются пустыми операциями, но это " +"может измениться в будущем, поэтому их нельзя игнорировать в драйвере. " +"Синхронизация не требуется для памяти, полученной из `bus_dmamem_alloc()`." + +#. 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 "" +"Перед вызовом функции обратного вызова из `bus_dmamap_load()` массив " +"сегментов сохраняется в стеке. Он предварительно выделяется для " +"максимального количества сегментов, разрешенного тегом. В результате этого " +"практический предел количества сегментов на архитектуре i386 составляет " +"около 250-300 (размер стека ядра — 4 КБ минус размер структуры пользователя, " +"размер элемента массива сегментов — 8 байт, и необходимо оставить некоторое " +"пространство). Поскольку массив выделяется исходя из максимального числа, " +"это значение не должно быть установлено выше, чем действительно необходимо. " +"К счастью, для большинства оборудования максимально поддерживаемое " +"количество сегментов значительно ниже. Но если драйвер должен обрабатывать " +"буферы с очень большим количеством сегментов scatter-gather, он должен " +"делать это по частям: загрузить часть буфера, передать его устройству, " +"загрузить следующую часть буфера и так далее." + +#. 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 "" +"Еще одно практическое следствие заключается в том, что количество сегментов " +"может ограничивать размер буфера. Если все страницы в буфере окажутся " +"физически несмежными, то максимальный поддерживаемый размер буфера для " +"такого фрагментированного случая будет равен (nsegments * page_size). " +"Например, если поддерживается максимальное количество сегментов, равное 10, " +"то на i386 максимальный гарантированно поддерживаемый размер буфера составит " +"40K. Если требуется больший размер, то в драйвере следует использовать " +"специальные приемы." + +#. 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 "" +"Если оборудование не поддерживает scatter-gather вообще или драйвер хочет " +"поддерживать некоторый размер буфера, даже если он сильно фрагментирован, то " +"решение состоит в выделении непрерывного буфера в драйвере и использовании " +"его в качестве промежуточного хранилища, если исходный буфер не подходит." + +#. 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 "" +"bus_dmamem_alloc -> bus_dmamap_load -> ...use buffer... -> -> " +"bus_dmamap_unload -> bus_dmamem_free" + +#. 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 "" +" 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" + +#. 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 "" +"При загрузке карты, созданной `bus_dmamem_alloc()`, переданные адрес и " +"размер буфера должны быть такими же, как использованные в " +"`bus_dmamem_alloc()`. В этом случае гарантируется, что весь буфер будет " +"отображен как один сегмент (так что обратный вызов может основываться на " +"этом предположении) и запрос будет выполнен немедленно (EINPROGRESS никогда " +"не будет возвращен). Все, что нужно сделать обратному вызову в этом случае, " +"— это сохранить физический адрес." + +#. 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 "" +" 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" + +#. 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 "" +" ...\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" + +#. 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 "" +" 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" + +#. 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 "" +" error = bus_dmamem_alloc(tag_somedata, &vsomedata, /* flags*/ 0,\n" +" &map_somedata);\n" +" if(error)\n" +" return error;\n" + +#. 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 "" +" bus_dmamap_load(tag_somedata, map_somedata, (void *)vsomedata,\n" +" sizeof (struct somedata), alloc_callback,\n" +" (void *) &psomedata, /*flags*/0);\n" + +#. 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 "" +"При загрузке произвольного буфера в карту, созданную `bus_dmamap_create()`, " +"необходимо принять специальные меры для синхронизации с обратным вызовом, " +"если он будет задержан. Код будет выглядеть следующим образом:" + +#. 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 "" +" {\n" +" int s;\n" +" int error;\n" + +#. 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 "" +" 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" + +#. 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 "" +"Если запросы завершаются путём явной пометки их как выполненных (например, " +"запросы CAM), то было бы проще поместить всю дальнейшую обработку в драйвер " +"обратного вызова, который отмечал бы запрос по его завершении. В этом случае " +"не потребуется много дополнительной синхронизации. По соображениям " +"управления потоком может быть полезно заморозить очередь запросов до " +"завершения этого запроса." + +#. 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 "" +"Если запросы завершаются при возврате функции (например, классические " +"запросы на чтение или запись для символьных устройств), то в дескрипторе " +"буфера должен быть установлен флаг синхронизации и вызвана функция " +"`tsleep()`. Позже, когда будет вызван обратный вызов, он выполнит свою " +"обработку и проверит этот флаг синхронизации. Если флаг установлен, обратный " +"вызов должен инициировать пробуждение. При таком подходе функция обратного " +"вызова может либо выполнить всю необходимую обработку (как в предыдущем " +"случае), либо просто сохранить массив сегментов в дескрипторе буфера. Затем " +"после завершения обратного вызова вызывающая функция может использовать этот " +"сохранённый массив сегментов и выполнить всю обработку." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:560 +#, no-wrap +msgid "DMA" +msgstr "DMA" + +#. 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 "" +"Прямой доступ к памяти (DMA) реализован в шине ISA через контроллер DMA (на " +"самом деле их два, но это несущественная деталь). Чтобы сделать ранние " +"устройства ISA простыми и дешёвыми, логика управления шиной и генерации " +"адресов была сосредоточена в контроллере DMA. К счастью, FreeBSD " +"предоставляет набор функций, которые в основном скрывают раздражающие детали " +"работы контроллера DMA от драйверов устройств." + +#. 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 "" +"Самый простой случай — для достаточно интеллектуальных устройств. Например, " +"устройства с bus mastering на PCI могут сами генерировать шинные циклы и " +"адреса памяти. Единственное, что им действительно нужно от контроллера DMA, " +"— это арбитраж шины. Для этой цели они притворяются каскадированными " +"подчинёнными контроллерами DMA. И единственное, что требуется от системного " +"контроллера DMA, — это включить каскадный режим на канале DMA, вызвав " +"следующую функцию при присоединении драйвера:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:567 +msgid "`void isa_dmacascade(int channel_number)`" +msgstr "`void isa_dmacascade(int channel_number)`" + +#. 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 "" +"Все последующие действия выполняются путем программирования устройства. При " +"отсоединении драйвера нет необходимости вызывать функции, связанные с DMA." + +#. 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 "`int isa_dma_acquire(int chanel_number)`" + +#. 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 "" +"Зарезервировать канал DMA. Возвращает 0 при успехе или EBUSY, если канал уже " +"зарезервирован этим или другим драйвером. Большинство устройств ISA не " +"способны совместно использовать каналы DMA, поэтому обычно эта функция " +"вызывается при присоединении устройства. Это резервирование стало избыточным " +"с появлением современного интерфейса ресурсов шины, но всё ещё должно " +"использоваться в дополнение к последнему. Если резервирование не " +"использовать, то в дальнейшем другие процедуры DMA вызовут панику ядра." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:576 +msgid "`int isa_dma_release(int chanel_number)`" +msgstr "`int isa_dma_release(int chanel_number)`" + +#. 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 "" +"Освободить ранее зарезервированный канал DMA. На момент освобождения канала " +"не должно быть активных передач (дополнительно устройство не должно пытаться " +"инициировать передачу после освобождения канала)." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:579 +msgid "`void isa_dmainit(int chan, u_int bouncebufsize)`" +msgstr "`void isa_dmainit(int chan, u_int bouncebufsize)`" + +#. 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 "" +"Выделить буфер отскока для использования с указанным каналом. Запрашиваемый " +"размер буфера не может превышать 64 КБ. Этот буфер отскока будет " +"автоматически использован в дальнейшем, если передаваемый буфер окажется не " +"физически непрерывным, находится вне памяти, доступной шине ISA, или " +"пересекает границу 64 КБ. Если передача всегда будет выполняться из буферов, " +"соответствующих этим условиям (например, выделенных с помощью " +"`bus_dmamem_alloc()` с соответствующими ограничениями), то вызов " +"`isa_dmainit()` не требуется. Однако довольно удобно передавать произвольные " +"данные с использованием контроллера DMA. Буфер отскока автоматически решит " +"проблемы с разбросанно-собираемыми данными." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:583 +msgid "_chan_ - channel number" +msgstr "_chan_ - номер канала" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:584 +msgid "_bouncebufsize_ - size of the bounce buffer in bytes" +msgstr "_bouncebufsize_ - размер буфера отскока в байтах" + +#. 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 "`void isa_dmastart(int flags, caddr_t addr, u_int nbytes, int chan)`" + +#. 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 "" +"Подготовка к началу передачи DMA. Эта функция должна быть вызвана для " +"настройки контроллера DMA перед фактическим началом передачи на устройстве. " +"Она проверяет, что буфер является непрерывным и попадает в диапазон памяти " +"ISA, если нет, то автоматически используется буфер отскока. Если требуется " +"буфер отскока, но он не настроен с помощью `isa_dmainit()` или слишком мал " +"для запрошенного размера передачи, система перейдет в состояние паники. В " +"случае запроса на запись с буфером отскока данные будут автоматически " +"скопированы в этот буфер." + +#. 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 "" +"flags - битовая маска, определяющая тип выполняемой операции. Бит " +"направления B_READ и B_WRITE являются взаимоисключающими." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:591 +msgid "B_READ - read from the ISA bus into memory" +msgstr "B_READ - чтение с шины ISA в память" + +#. 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 "B_WRITE - запись из памяти на шину ISA" + +#. 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 "" +"B_RAW - если установлен, то контроллер DMA запомнит буфер и после завершения " +"передачи автоматически переинициализирует себя для повторной передачи того " +"же буфера (конечно, драйвер может изменить данные в буфере перед " +"инициированием следующей передачи на устройстве). Если не установлен, то " +"параметры будут работать только для одной передачи, и перед инициированием " +"следующей передачи снова потребуется вызвать `isa_dmastart()`. Использование " +"B_RAW имеет смысл только если буфер отскока не используется." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:595 +msgid "addr - virtual address of the buffer" +msgstr "addr - виртуальный адрес буфера" + +#. 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 "" +"nbytes - длина буфера. Должна быть меньше или равна 64 КБ. Длина 0 не " +"допускается: контроллер DMA интерпретирует это как 64 КБ, в то время как код " +"ядра поймёт это как 0, что приведёт к непредсказуемым последствиям. Для " +"каналов номер 4 и выше длина должна быть чётной, так как эти каналы передают " +"по 2 байта за раз. В случае нечётной длины последний байт не будет передан." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:597 +msgid "chan - channel number" +msgstr "chan - номер канала" + +#. 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 "`void isa_dmadone(int flags, caddr_t addr, int nbytes, int chan)`" + +#. 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 "" +"Синхронизировать память после того, как устройство сообщает о завершении " +"передачи. Если это была операция чтения с буфером отскока, то данные будут " +"скопированы из этого буфера в исходный буфер. Аргументы такие же, как у " +"`isa_dmastart()`. Флаг B_RAW разрешён, но он никак не влияет на " +"`isa_dmadone()`." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:601 +msgid "`int isa_dmastatus(int channel_number)`" +msgstr "`int isa_dmastatus(int channel_number)`" + +#. 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 "" +"Возвращает количество оставшихся для передачи байт в текущей передаче. Если " +"флаг B_READ был установлен в `isa_dmastart()`, возвращаемое значение никогда " +"не будет равно нулю. В конце передачи оно автоматически сбрасывается обратно " +"к длине буфера. Обычное использование — проверка количества оставшихся байт " +"после того, как устройство сигнализирует о завершении передачи. Если " +"количество байт не равно 0, то, вероятно, в передаче произошла ошибка." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:604 +msgid "`int isa_dmastop(int channel_number)`" +msgstr "`int isa_dmastop(int channel_number)`" + +#. 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 "xxx_isa_probe" + +#. 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 "" +"Как и для любой другой шины, если устройство не может быть обнаружено, или " +"обнаружено, но не прошло самопроверку, или возникла другая проблема, то " +"возвращается положительное значение ошибки. Значение `ENXIO` должно " +"возвращаться, если устройство отсутствует. Другие значения ошибок могут " +"означать иные условия. Нулевые или отрицательные значения означают успех. " +"Большинство драйверов возвращают ноль в случае успеха." + +#. 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 "" +"Отрицательные возвращаемые значения используются, когда устройство PnP " +"поддерживает несколько интерфейсов. Например, старый совместимый интерфейс и " +"новый расширенный интерфейс, которые поддерживаются разными драйверами. В " +"этом случае оба драйвера обнаружат устройство. Драйвер, который возвращает " +"большее значение в процедуре обнаружения, получает приоритет (другими " +"словами, драйвер, возвращающий 0, имеет наивысший приоритет, возвращающий -1 " +"— следующий, возвращающий -2 — за ним и так далее). В результате устройства, " +"поддерживающие только старый интерфейс, будут обрабатываться старым " +"драйвером (который должен возвращать -1 из процедуры probe), а устройства, " +"поддерживающие также новый интерфейс, будут обрабатываться новым драйвером " +"(который должен возвращать 0 из процедуры обнаружения)." + +#. 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 "" +"Структура дескриптора устройства `xxx_softc` выделяется системой до вызова " +"процедуры обнаружения. Если процедура обнаружения возвращает ошибку, " +"дескриптор автоматически освобождается системой. Поэтому при возникновении " +"ошибки обнаружения драйвер должен убедиться, что все ресурсы, использованные " +"во время обнаружения, освобождены и ничто не мешает безопасному освобождению " +"дескриптора.Если обнаружение завершается успешно, дескриптор сохраняется " +"системой и позже передаётся в процедуру `xxx_isa_attach()`. Если драйвер " +"возвращает отрицательное значение, он не может быть уверен, что получит " +"наивысший приоритет и его процедура присоеднинения будет вызвана. Поэтому в " +"этом случае он также должен освободить все ресурсы перед возвратом и, если " +"необходимо, выделить их снова в процедуре присоединения. Когда " +"`xxx_isa_probe()` возвращает 0, освобождение ресурсов перед возвратом также " +"является хорошей практикой, и корректно работающий драйвер должен так " +"поступать. Однако в случаях, когда возникают проблемы с освобождением " +"ресурсов, драйверу разрешается сохранять ресурсы между возвратом 0 из " +"процедуры обнаружения и выполнением процедуры присоединения." + +#. 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 "" +" struct xxx_softc *sc = device_get_softc(dev);\n" +" int unit = device_get_unit(dev);\n" +" int pnperror;\n" +" int error = 0;\n" + +#. 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 "" +" sc->dev = dev; /* link it back */\n" +" sc->unit = unit;\n" + +#. 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 "" +"Затем проверьте устройства PnP. Проверка осуществляется с помощью таблицы, " +"содержащей список PnP ID, поддерживаемых этим драйвером, и удобочитаемые " +"описания моделей устройств, соответствующих этим ID." + +#. 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 "" +" pnperror=ISA_PNP_PROBE(device_get_parent(dev), dev,\n" +" xxx_pnp_ids); if(pnperror == ENXIO) return ENXIO;\n" + +#. 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 "" +"Логика работы `ISA_PNP_PROBE` следующая: если данная карта (устройство) не " +"была обнаружена как PnP, то будет возвращено `ENOENT`. Если она была " +"обнаружена как PnP, но её обнаруженный ID не совпадает ни с одним из ID в " +"таблице, то возвращается `ENXIO`. Наконец, если устройство поддерживает PnP " +"и его ID совпадает с одним из ID в таблице, возвращается `0`, а " +"соответствующее описание из таблицы устанавливается с помощью " +"`device_set_desc()`." + +#. 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 "" +"Если драйвер поддерживает только устройства PnP, то условие будет выглядеть " +"следующим образом:" + +#. 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 "" +" if(pnperror != 0)\n" +" return pnperror;\n" + +#. 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 "" +"Для драйверов, которые не поддерживают PnP, не требуется специальной " +"обработки, так как они передают пустую таблицу идентификаторов PnP и всегда " +"будут получать ENXIO при вызове на PnP-карте." + +#. 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 "" +"Функция обнаружения обычно требует как минимум некоторый минимальный набор " +"ресурсов, например, номер порта ввода-вывода, чтобы найти карту и проверить " +"её. В зависимости от оборудования драйвер может автоматически обнаружить " +"другие необходимые ресурсы. Устройства PnP имеют все ресурсы, предварительно " +"установленные подсистемой PnP, поэтому драйверу не нужно обнаруживать их " +"самостоятельно." + +#. 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 "" +" sc->port0 = bus_get_resource_start(dev,\n" +" SYS_RES_IOPORT, 0 /*rid*/); if(sc->port0 == 0) return ENXIO;\n" + +#. 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 "" +"Базовый адрес порта сохраняется в структуре softc для последующего " +"использования. Если он будет использоваться очень часто, то вызов функции " +"ресурса каждый раз будет неприемлемо медленным. Если мы не получаем порт, мы " +"просто возвращаем ошибку. Некоторые драйверы устройств могут вместо этого " +"быть умнее и попытаться обнаружить все возможные порты, например:" + +#. 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 "" +" /* 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" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:681 +#, no-wrap +msgid "" +" ...\n" +" int port, i;\n" +" ...\n" +msgstr "" +" ...\n" +" int port, i;\n" +" ...\n" + +#. 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 "" +" 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" + +#. 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 "" +" /* 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" + +#. 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 "" +" /* 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" + +#. 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 "" +" /* 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" + +#. 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 "" +" 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" + +#. 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 "" +"Конечно, обычно для таких вещей следует использовать процедуру `identify()` " +"драйвера. Однако может быть одна веская причина, почему лучше сделать это в " +"`probe()`: если этот обнаружение может привести к сбою другого " +"чувствительного устройства. Процедуры обнаружения упорядочены с учетом флага " +"`sensitive`: чувствительные устройства проверяются первыми, а остальные " +"устройства — позже. Но процедуры `identify()` вызываются до любого " +"обнаружения, поэтому они не учитывают чувствительные устройства и могут " +"вызвать их сбой." + +#. 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 "" +"Вот, после того как мы получили начальный порт, необходимо установить " +"количество портов (за исключением устройств PnP), так как в файле " +"конфигурации ядра эта информация отсутствует." + +#. 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 "" +" 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" + +#. 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 "" +"Наконец, выделите и активируйте часть адресного пространства порта " +"(специальные значения start и end означают \"используйте те, что мы " +"установили через ``bus_set_resource()``\"):" + +#. 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 "" +" 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" + +#. 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 "" +" if(sc->port0_r == NULL)\n" +" return ENXIO;\n" + +#. 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 "" +"Обычно драйверы не настраивают обработчики прерываний до вызова процедуры " +"присоединения. Вместо этого они выполняют проверки в режиме опроса, " +"используя функцию `DELAY()` для таймаута. Процедура проверки никогда не " +"должна зависать навсегда, все ожидания ответа от устройства должны " +"выполняться с таймаутами. Если устройство не отвечает в течение заданного " +"времени, вероятно, оно неисправно или неправильно настроено, и драйвер " +"должен вернуть ошибку. При определении интервала таймаута следует давать " +"устройству дополнительное время для надежности: хотя предполагается, что " +"`DELAY()` задерживает выполнение на одинаковое время на любой машине, " +"существует некоторая погрешность, зависящая от конкретного процессора." + +#. 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 "" +" /* implemented in some very device-specific way */\n" +" if(error = xxx_probe_ports(sc))\n" +" goto bad; /* will deallocate the resources before returning */\n" + +#. 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 "" +"Функция `xxx_probe_ports()` также может устанавливать описание устройства в " +"зависимости от конкретной модели обнаруженного устройства. Но если " +"поддерживается только одна модель устройства, это можно сделать и жёстко " +"заданным способом. Конечно, для PnP-устройств поддержка PnP автоматически " +"устанавливает описание из таблицы." + +#. 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 "" +" if(pnperror)\n" +" device_set_desc(dev, \"Our device model 1234\");\n" + +#. 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 "" +" /* 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" + +#. 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 "" +" 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" + +#. 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 "" +" /* 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" + +#. 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 "" +" 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" + +#. 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 "" +" if(xxx_set_mem0_size_on_device(sc) < 0)\n" +" goto bad; /* device does not support that size */\n" + +#. 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 "" +" 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" + +#. 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 "Ресурсы для IRQ и DRQ легко проверить по аналогии." + +#. 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 "" +" xxx_free_resources(sc);\n" +" return 0;\n" + +#. 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 "" +"Наконец, обработайте проблемные ситуации. Все ресурсы должны быть " +"освобождены перед возвратом. Мы используем тот факт, что перед передачей нам " +"структуры `softc` она обнуляется, поэтому мы можем определить, был ли " +"выделен какой-либо ресурс: если его дескриптор не равен нулю." + +#. 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 " bad:\n" + +#. 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 "" +" xxx_free_resources(sc);\n" +" if(error)\n" +" return error;\n" +" else /* exact error is unknown */\n" +" return ENXIO;\n" + +#. 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 "" +"static void\n" +" xxx_free_resources(sc)\n" +" struct xxx_softc *sc;\n" +" {\n" +" /* check every resource and free if not zero */\n" + +#. 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 "" +" /* 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" + +#. 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 "" +" /* 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" + +#. 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 " ... free other maps and tags if we have them ...\n" + +#. 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 "" +" if(sc->parent_tag) {\n" +" bus_dma_tag_destroy(sc->parent_tag);\n" +" sc->parent_tag = 0;\n" +" }\n" + +#. 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 "" +" /* 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" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:894 +#, no-wrap +msgid "xxx_isa_attach" +msgstr "xxx_isa_attach" + +#. 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 "" +"Процедура присоединения фактически подключает драйвер к системе, если " +"процедура обнаружения вернула успех и система решила подключить этот " +"драйвер. Если процедура обнаружения вернула 0, то процедура присоединения " +"может ожидать, что получит структуру устройства `softc` в неизменном виде, " +"как она была установлена процедкрой обнаружения. Также, если обнаружение " +"возвращает 0, она можно ожидать, что процедкра присоединения для этого " +"устройства будет вызвана в какой-то момент в будущем. Если процедка " +"обнаружения возвращает отрицательное значение, то драйвер не может делать " +"никаких из этих предположений." + +#. 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 "" +"Процедура присоединение возвращает 0 при успешном завершении или код ошибки " +"в противном случае." + +#. 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 "" +" struct xxx_softc *sc = device_get_softc(dev);\n" +" int unit = device_get_unit(dev);\n" +" int error = 0;\n" + +#. 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 "" +"Затем выделите и активируйте все необходимые ресурсы. Обычно диапазон портов " +"освобождается перед возвратом из обнаружения, поэтому его необходимо " +"выделить снова. Мы предполагаем, что процедура обнаружения корректно " +"установила все диапазоны ресурсов, а также сохранила их в структуре softc. " +"Если процедура обнаружения оставила некоторые ресурсы выделенными, то их не " +"нужно выделять снова (это будет считаться ошибкой)." + +#. 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 "" +" 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" + +#. 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 "" +" if(sc->port0_r == NULL)\n" +" return ENXIO;\n" + +#. 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 "" +" /* 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" + +#. 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 "" +" if(sc->mem0_r == NULL)\n" +" goto bad;\n" + +#. 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 "" +" /* get its virtual address */\n" +" sc->mem0_v = rman_get_virtual(sc->mem0_r);\n" + +#. 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 "" +"Канал запроса DMA (DRQ) выделяется аналогично. Для его инициализации " +"используйте функции семейства `isa_dma*()`. Например:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:935 +msgid "`isa_dmacascade(sc->drq0);`" +msgstr "`isa_dmacascade(sc->drq0);`" + +#. 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 "" +"Строка запроса прерывания (IRQ) является особенной. Помимо выделения, " +"обработчик прерывания драйвера должен быть связан с ней. Исторически в " +"старых драйверах ISA аргумент, передаваемый системой обработчику прерывания, " +"был номером устройства. Однако в современных драйверах принято передавать " +"указатель на структуру `softc`. Важная причина этого заключается в том, что " +"когда структуры `softc` выделяются динамически, получение номера устройства " +"из `softc` является простым, в то время как получение `softc` из номера " +"устройства затруднительно. Кроме того, такое соглашение делает драйверы для " +"различных шин более однородными и позволяет им совместно использовать код: " +"каждая шина получает свои собственные процедуры обнаружения, присоединения, " +"отсоединения и другие специфичные для шины функции, в то время как основная " +"часть кода драйвера может быть общей для них." + +#. 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 "" +" 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" + +#. 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 "" +" if(sc->intr_r == NULL)\n" +" goto bad;\n" + +#. 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 "" +" /*\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" + +#. 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 "" +"Если устройству необходимо выполнять DMA в основную память, то эта память " +"должна быть выделена, как описано ранее:" + +#. 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 "" +" 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" + +#. 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 "" +" /* 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" + +#. 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 "" +" error = bus_dmamem_alloc(sc->data_tag, &sc->data, /* flags*/ 0,\n" +" &sc->data_map);\n" +" if(error)\n" +" goto bad;\n" + +#. 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 "" +" /* 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" + +#. 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 "" +" if(xxx_initialize(sc) < 0)\n" +" goto bad;\n" + +#. 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 " device_printf(dev, \"has on-card FIFO buffer of %d bytes\\n\", sc->fifosize);\n" + +#. 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 "" +"Последним шагом процедуры присоединения является подключение устройства к " +"его функциональной подсистеме в ядре. Конкретный способ зависит от типа " +"драйвера: символьное устройство, блочное устройство, сетевое устройство, " +"устройство шины CAM SCSI и так далее." + +#. 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 "" +" error = xxx_attach_subsystem(sc);\n" +" if(error)\n" +" goto bad;\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1040 +#, no-wrap +msgid " return 0;\n" +msgstr " return 0;\n" + +#. 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 "" +"Наконец, обработаем проблемные ситуации. Все ресурсы должны быть освобождены " +"перед возвратом ошибки. Мы используем тот факт, что перед передачей " +"структуры `softc` она обнуляется, поэтому мы можем определить, был ли " +"выделен какой-либо ресурс: если его дескриптор ненулевой." + +#. 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 "" +" xxx_free_resources(sc);\n" +" if(error)\n" +" return error;\n" +" else /* exact error is unknown */\n" +" return ENXIO;\n" + +#. 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 "xxx_isa_detach" + +#. 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 "" +"Если эта функция присутствует в драйвере и драйвер скомпилирован как " +"загружаемый модуль, то драйвер получает возможность быть выгруженным. Это " +"важная функция, если оборудование поддерживает горячее подключение. Однако " +"шина ISA не поддерживает горячее подключение, поэтому эта функция не " +"особенно важна для устройств ISA. Возможность выгрузки драйвера может быть " +"полезна при его отладке, но во многих случаях установка новой версии " +"драйвера потребуется только после того, как старая версия каким-то образом " +"заблокирует систему и перезагрузка все равно будет необходима, поэтому " +"усилия, затраченные на написание процедуры отсоединения, могут не окупиться. " +"Другой аргумент, что выгрузка позволит обновлять драйверы на рабочей машине, " +"кажется в основном теоретическим. Установка новой версии драйвера — это " +"опасная операция, которую никогда не следует выполнять на рабочей машине (и " +"которая не разрешена, когда система работает в безопасном режиме). Тем не " +"менее, процедура отсоединения может быть предоставлена для полноты." + +#. 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 "" +"Процедура отсоединения возвращает 0, если драйвер был успешно отсоединён, " +"или код ошибки в противном случае." + +#. 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 "" +" struct xxx_softc *sc = device_get_softc(dev);\n" +" int error;\n" + +#. 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 "" +" error = xxx_detach_subsystem(sc);\n" +" if(error)\n" +" return error;\n" + +#. 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 "" +"Далее драйвер может сбросить аппаратное обеспечение в согласованное " +"состояние. Это включает остановку любых текущих передач, отключение каналов " +"DMA и прерываний, чтобы избежать повреждения памяти устройством. Для " +"большинства драйверов это именно то, что делает процедура выключения, " +"поэтому, если она присутствует в драйвере, мы можем просто вызвать её." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1079 +msgid "`xxx_isa_shutdown(dev);`" +msgstr "`xxx_isa_shutdown(dev);`" + +#. 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 "xxx_isa_shutdown" + +#. 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 "" +"Эта процедура вызывается, когда система собирается быть выключена. " +"Ожидается, что она приведет оборудование в согласованное состояние. Для " +"большинства устройств ISA не требуется никаких специальных действий, поэтому " +"функция не является действительно необходимой, так как устройство будет " +"переинициализировано при перезагрузке в любом случае. Однако некоторые " +"устройства должны быть выключены с помощью специальной процедуры, чтобы " +"убедиться, что они будут правильно обнаружены после мягкой перезагрузки (это " +"особенно актуально для многих устройств с проприетарными протоколами " +"идентификации). В любом случае отключение DMA и прерываний в регистрах " +"устройства и остановка любых текущих передач — это хорошая идея. Точные " +"действия зависят от оборудования, поэтому мы не рассматриваем их здесь " +"подробно." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/isa/_index.adoc:1094 +#, no-wrap +msgid "xxx_intr" +msgstr "xxx_intr" + +#. 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 "" +"Обработчик прерывания вызывается при получении прерывания, которое может " +"быть от данного конкретного устройства. Шина ISA не поддерживает разделение " +"прерываний (за исключением некоторых специальных случаев), поэтому на " +"практике, если вызывается обработчик прерывания, то прерывание почти " +"наверняка поступило от его устройства. Тем не менее, обработчик прерывания " +"должен опросить регистры устройства и убедиться, что прерывание было " +"сгенерировано его устройством. Если нет, он должен просто вернуть управление." + +#. 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 "" +"Старая практика для драйверов ISA заключалась в получении номера устройства " +"в качестве аргумента. Это устарело, и новые драйверы получают любой " +"аргумент, указанный для них в процедуре присоединения при вызове " +"`bus_setup_intr()`. Согласно новой практике, это должен быть указатель на " +"структуру softc. Таким образом, обработчик прерываний обычно начинается так:" + +#. 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 "" +" static void\n" +" xxx_intr(struct xxx_softc *sc)\n" +" {\n" + +#. 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 "" +"Он выполняется на уровне приоритета прерывания, указанном параметром типа " +"прерывания в `bus_setup_intr()`. Это означает, что все остальные прерывания " +"того же типа, а также все программные прерывания, отключены." + +#. 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 "" +" while(xxx_interrupt_pending(sc)) {\n" +" xxx_process_interrupt(sc);\n" +" xxx_acknowledge_interrupt(sc);\n" +" }\n" + +#. 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/ru/books/arch-handbook/jail/_index.adoc b/documentation/content/ru/books/arch-handbook/jail/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/jail/_index.adoc @@ -0,0 +1,529 @@ +--- +description: 'Подсистема клеток' +next: books/arch-handbook/sysinit +params: + path: /books/arch-handbook/jail/ +prev: books/arch-handbook/kobj +showBookMenu: true +tags: ["jail", "architecture", "networking", "kernel"] +title: 'Глава 4. Подсистема клеток' +weight: 5 +--- + +[[jail]] += Подсистема клеток +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 4 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +На большинстве систем UNIX(R) пользователь `root` обладает неограниченной властью. Это не способствует безопасности. Если злоумышленник получит права `root` в системе, у него окажутся все функции под рукой. В FreeBSD существуют sysctl-параметры, которые ограничивают власть `root`, чтобы минимизировать ущерб от действий злоумышленника. В частности, одна из таких функций называется `уровни безопасности`. Аналогично, другая функция, доступная начиная с FreeBSD 4.0, — это утилита man:jail[8] — клетка. Клетка создает chroot-окружение и накладывает определенные ограничения на процессы, запущенные внутри `клетки`. Например, процесс в `клетке` не может влиять на процессы вне её, использовать определенные системные вызовы или наносить какой-либо ущерб основной системе. + +Клетка становится новой моделью безопасности. Пользователи запускают потенциально уязвимые серверы, такие как Apache, BIND и sendmail, внутри клеток, так что если злоумышленник получит права `root` внутри клетки, это будет лишь неудобством, а не катастрофой. Данная статья в основном сосредоточена на внутреннем устройстве (исходном коде) клетки. Для получения информации о настройке клетки см. extref:{handbook} jails/[раздел о клетках Руководства FreeBSD, jails-synopsis]. + +[[jail-arch]] +== Архитектура + +`Клетка` состоит из двух областей: пользовательской программы man:jail[8] и кода, реализованного в ядре: системного вызова man:jail[2] и связанных с ним ограничений. Я расскажу о пользовательской программе, а затем о том, как `клетка` реализована в ядре. + +=== Код в пользовательском пространстве + +Исходный код пользовательской части `клетки` находится в [.filename]#/usr/src/usr.sbin/jail# и состоит из одного файла [.filename]#jail.c#. Программа принимает следующие аргументы: путь к `клетке`, имя хоста, IP-адрес и команду для выполнения. + +==== Структуры данных + +В файле [.filename]#jail.c# первое, на что я бы обратил внимание, это объявление важной структуры `struct jail j;`, которая была включена из [.filename]#/usr/include/sys/jail.h#. + +Определение структуры `jail` выглядит следующим образом: + +[.programlisting] +.... +/usr/include/sys/jail.h: + +struct jail { + u_int32_t version; + char *path; + char *hostname; + u_int32_t ip_number; +}; +.... + +Как видно, существует запись для каждого из аргументов, переданных программе man:jail[8], и действительно, они устанавливаются во время её выполнения. + +[.programlisting] +.... +/usr/src/usr.sbin/jail/jail.c +char path[PATH_MAX]; +... +if (realpath(argv[0], path) == NULL) + err(1, "realpath: %s", argv[0]); +if (chdir(path) != 0) + err(1, "chdir: %s", path); +memset(&j, 0, sizeof(j)); +j.version = 0; +j.path = path; +j.hostname = argv[1]; +.... + +==== Сетевое взаимодействие + +Один из аргументов, передаваемых программе man:jail[8], — это IP-адрес, по которому можно получить доступ к клетке через сеть. man:jail[8] преобразует указанный IP-адрес в порядок байтов хоста и сохраняет его в `j` (структура `jail`). + +[.programlisting] +.... +/usr/src/usr.sbin/jail/jail.c: +struct in_addr in; +... +if (inet_aton(argv[2], &in) == 0) + errx(1, "Could not make sense of ip-number: %s", argv[2]); +j.ip_number = ntohl(in.s_addr); +.... + +Функция man:inet_aton[3] "интерпретирует указанную строку символов как интернет-адрес, помещая адрес в предоставленную структуру." Член структуры `ip_number` в структуре `jail` устанавливается только тогда, когда IP-адрес, помещённый в структуру `in` функцией man:inet_aton[3], преобразуется в порядок байтов хоста с помощью man:ntohl[3]. + +==== Процесс в клетке + +Наконец, пользовательская программа помещает процесс в `клетку`. Теперь `клетка` становится самим заключенным процессом и выполняет команду, используя man:execv[3]. + +[.programlisting] +.... +/usr/src/usr.sbin/jail/jail.c +i = jail(&j); +... +if (execv(argv[3], argv + 3) != 0) + err(1, "execv: %s", argv[3]); +.... + +Как видно, вызывается функция `jail()`, и её аргументом является структура `jail`, заполненная аргументами, переданными программе. В конце выполняется указанная вами программа. Теперь я расскажу о том, как `клетка` реализована в ядре. + +=== Пространство ядра системы + +Мы сейчас рассмотрим файл [.filename]#/usr/src/sys/kern/kern_jail.c#. В этом файле определены системный вызов man:jail[2], соответствующие sysctls и сетевые функции. + +==== Управляемые переменные ядра sysctl + +В файле [.filename]#kern_jail.c# определены следующие параметры sysctl: + +[.programlisting] +.... +/usr/src/sys/kern/kern_jail.c: +int jail_set_hostname_allowed = 1; +SYSCTL_INT(_security_jail, OID_AUTO, set_hostname_allowed, CTLFLAG_RW, + &jail_set_hostname_allowed, 0, + "Processes in jail can set their hostnames"); + +int jail_socket_unixiproute_only = 1; +SYSCTL_INT(_security_jail, OID_AUTO, socket_unixiproute_only, CTLFLAG_RW, + &jail_socket_unixiproute_only, 0, + "Processes in jail are limited to creating UNIX/IPv4/route sockets only"); + +int jail_sysvipc_allowed = 0; +SYSCTL_INT(_security_jail, OID_AUTO, sysvipc_allowed, CTLFLAG_RW, + &jail_sysvipc_allowed, 0, + "Processes in jail can use System V IPC primitives"); + +static int jail_enforce_statfs = 2; +SYSCTL_INT(_security_jail, OID_AUTO, enforce_statfs, CTLFLAG_RW, + &jail_enforce_statfs, 0, + "Processes in jail cannot see all mounted file systems"); + +int jail_allow_raw_sockets = 0; +SYSCTL_INT(_security_jail, OID_AUTO, allow_raw_sockets, CTLFLAG_RW, + &jail_allow_raw_sockets, 0, + "Prison root can create raw sockets"); + +int jail_chflags_allowed = 0; +SYSCTL_INT(_security_jail, OID_AUTO, chflags_allowed, CTLFLAG_RW, + &jail_chflags_allowed, 0, + "Processes in jail can alter system file flags"); + +int jail_mount_allowed = 0; +SYSCTL_INT(_security_jail, OID_AUTO, mount_allowed, CTLFLAG_RW, + &jail_mount_allowed, 0, + "Processes in jail can mount/unmount jail-friendly file systems"); +.... + +Каждый из этих параметров sysctl может быть доступен пользователю через программу man:sysctl[8]. В ядре эти конкретные параметры sysctl распознаются по их именам. Например, имя первого параметра sysctl — `security.jail.set_hostname_allowed`. + +==== Системный вызов man:jail[2] + +Как и все системные вызовы, системный вызов man:jail[2] принимает два аргумента: `struct thread *td` и `struct jail_args *uap`. `td` — это указатель на структуру `thread`, которая описывает вызывающий поток. В данном контексте `uap` — это указатель на структуру, в которой содержится указатель на структуру `jail`, переданную из пользовательского пространства [.filename]#jail.c#. Ранее, когда я описывал пользовательскую программу, вы видели, что системному вызову man:jail[2] была передана структура `jail` в качестве собственного аргумента. + +[.programlisting] +.... +/usr/src/sys/kern/kern_jail.c: +/* + * struct jail_args { + * struct jail *jail; + * }; + */ +int +jail(struct thread *td, struct jail_args *uap) +.... + +Следовательно, `uap->jail` можно использовать для доступа к структуре `jail`, которая была передана системному вызову. Далее системный вызов копирует структуру `клетка` в пространство ядра с помощью функции man:copyin[9]. man:copyin[9] принимает три аргумента: адрес данных, которые нужно скопировать в пространство ядра (`uap->jail`), место для записи данных (`j`) и размер хранилища. Структура `jail`, на которую указывает `uap->jail`, копируется в пространство ядра и сохраняется в другой структуре `клетка` — `j`. + +[.programlisting] +.... +/usr/src/sys/kern/kern_jail.c: +error = copyin(uap->jail, &j, sizeof(j)); +.... + +В [.filename]#jail.h# определена ещё одна важная структура — `prison`. Структура `prison` используется исключительно в пространстве ядра. Вот определение структуры `prison`. + +[.programlisting] +.... +/usr/include/sys/jail.h: +struct prison { + LIST_ENTRY(prison) pr_list; /* (a) all prisons */ + int pr_id; /* (c) prison id */ + int pr_ref; /* (p) refcount */ + char pr_path[MAXPATHLEN]; /* (c) chroot path */ + struct vnode *pr_root; /* (c) vnode to rdir */ + char pr_host[MAXHOSTNAMELEN]; /* (p) jail hostname */ + u_int32_t pr_ip; /* (c) ip addr host */ + void *pr_linux; /* (p) linux abi */ + int pr_securelevel; /* (p) securelevel */ + struct task pr_task; /* (d) destroy task */ + struct mtx pr_mtx; + void **pr_slots; /* (p) additional data */ +}; +.... + +Системный вызов man:jail[2] затем выделяет память для структуры `prison` и копирует данные между структурой `клетка` и структурой `prison`. + +[.programlisting] +.... +/usr/src/sys/kern/kern_jail.c: +MALLOC(pr, struct prison *, sizeof(*pr), M_PRISON, M_WAITOK | M_ZERO); +... +error = copyinstr(j.path, &pr->pr_path, sizeof(pr->pr_path), 0); +if (error) + goto e_killmtx; +... +error = copyinstr(j.hostname, &pr->pr_host, sizeof(pr->pr_host), 0); +if (error) + goto e_dropvnref; +pr->pr_ip = j.ip_number; +.... + +Далее мы рассмотрим ещё один важный системный вызов man:jail_attach[2], который реализует функцию помещения процесса в клетку. + +[.programlisting] +.... +/usr/src/sys/kern/kern_jail.c: +/* + * struct jail_attach_args { + * int jid; + * }; + */ +int +jail_attach(struct thread *td, struct jail_attach_args *uap) +.... + +Этот системный вызов вносит изменения, которые позволяют отличить процесс в клетке от процессов вне клетки. Чтобы понять, что делает man:jail_attach[2], необходима некоторая справочная информация. + +В FreeBSD каждый видимый ядром поток идентифицируется своей структурой `thread`, а процессы описываются их структурами `proc`. Определения структур `thread` и `proc` можно найти в [.filename]#/usr/include/sys/proc.h#. Например, аргумент `td` в любом системном вызове на самом деле является указателем на структуру `thread` вызывающего потока, как было указано ранее. Член `td_proc` в структуре `thread`, на которую указывает `td`, является указателем на структуру `proc`, представляющую процесс, содержащий поток, представленный структурой `td`. Структура `proc` содержит члены, которые могут описывать идентификацию владельца (`p_ucred`), ограничения ресурсов процесса (`p_limit`) и так далее. В структуре `ucred`, на которую указывает член `p_ucred` в структуре `proc`, есть указатель на структуру `prison` (`cr_prison`). + +[.programlisting] +.... +/usr/include/sys/proc.h: +struct thread { + ... + struct proc *td_proc; + ... +}; +struct proc { + ... + struct ucred *p_ucred; + ... +}; +/usr/include/sys/ucred.h +struct ucred { + ... + struct prison *cr_prison; + ... +}; +.... + +В файле [.filename]#kern_jail.c# функция `jail()` вызывает функцию `jail_attach()` с заданным `jid`. Затем `jail_attach()` вызывает функцию `change_root()` для изменения корневого каталога вызывающего процесса. Функция `jail_attach()` создает новую структуру `ucred` и присоединяет её к вызывающему процессу после успешного присоединения структуры `prison` к структуре `ucred`. С этого момента вызывающий процесс считается находящимся в клетке. Когда в ядре вызывается функция `jailed()` с вновь созданной структурой `ucred` в качестве аргумента, она возвращает 1, указывая, что учётные данные связаны с клеткой. Общим родительским процессом для всех процессов, созданных внутри клетки, является процесс, запускающий man:jail[8], так как он вызывает системный вызов man:jail[2]. При выполнении программы через man:execve[2] она наследует свойство клетки из структуры `ucred` родительского процесса, следовательно, у нее структура `ucred` тоже со свойством клетки. + +[.programlisting] +.... +/usr/src/sys/kern/kern_jail.c +int +jail(struct thread *td, struct jail_args *uap) +{ +... + struct jail_attach_args jaa; +... + error = jail_attach(td, &jaa); + if (error) + goto e_dropprref; +... +} + +int +jail_attach(struct thread *td, struct jail_attach_args *uap) +{ + struct proc *p; + struct ucred *newcred, *oldcred; + struct prison *pr; +... + p = td->td_proc; +... + pr = prison_find(uap->jid); +... + change_root(pr->pr_root, td); +... + newcred->cr_prison = pr; + p->p_ucred = newcred; +... +} +.... + +Когда процесс создается из родительского процесса, системный вызов man:fork[2] использует `crhold()` для поддержания учетных данных нового процесса. Это автоматически сохраняет учетные данные нового дочернего процесса согласованными с родительским, поэтому дочерний процесс также остается в клетке. + +[.programlisting] +.... +/usr/src/sys/kern/kern_fork.c: +p2->p_ucred = crhold(td->td_ucred); +... +td2->td_ucred = crhold(p2->p_ucred); +.... + +[[jail-restrictions]] +== Ограничения + +В ядре существуют ограничения доступа, связанные с процессами в клетках. Обычно эти ограничения просто проверяют, находится ли процесс в клетке, и если да, возвращают ошибку. Например: + +[.programlisting] +.... +if (jailed(td->td_ucred)) + return (EPERM); +.... + +=== SysV IPC + +System V IPC основан на сообщениях. Процессы могут отправлять друг другу эти сообщения, которые указывают им, как действовать. Функции, работающие с сообщениями: man:msgctl[3], man:msgget[3], man:msgsnd[3] и man:msgrcv[3]. Ранее я упоминал, что существуют определённые sysctl, которые можно включать или выключать для изменения поведения клетки. Один из таких sysctl — `security.jail.sysvipc_allowed`. По умолчанию этот sysctl установлен в 0. Если бы он был установлен в 1, это бы свело на нет весь смысл клетки: привилегированные пользователи внутри клетки смогли бы влиять на процессы за её пределами. Разница между сообщением и сигналом заключается в том, что сообщение состоит только из номера сигнала. + +[.filename]#/usr/src/sys/kern/sysv_msg.c#: + +* `msgget(key, msgflg)`: `msgget` возвращает (и, возможно, создаёт) дескриптор сообщения, который обозначает очередь сообщений для использования в других функциях. +* `msgctl(msgid, cmd, buf)`: С помощью этой функции процесс может запросить статус дескриптора сообщения. +* `msgsnd(msgid, msgp, msgsz, msgflg)`: `msgsnd` отправляет сообщение процессу. +* `msgrcv(msgid, msgp, msgsz, msgtyp, msgflg)`: процесс получает сообщения с помощью этой функции + +В каждом из системных вызовов, соответствующих этим функциям, присутствует следующее условие: + +[.programlisting] +.... +/usr/src/sys/kern/sysv_msg.c: +if (!jail_sysvipc_allowed && jailed(td->td_ucred)) + return (ENOSYS); +.... + +Системные вызовы семафоров позволяют процессам синхронизировать выполнение, атомарно выполняя набор операций над набором семафоров. По сути, семафоры предоставляют ещё один способ для процессов блокировать ресурсы. Однако процесс, ожидающий семафор, который уже используется, будет находиться в состоянии сна до тех пор, пока ресурсы не будут освобождены. Следующие системные вызовы семафоров блокируются внутри клетки: man:semget[2], man:semctl[2] и man:semop[2]. + +[.filename]#/usr/src/sys/kern/sysv_sem.c#: + +* `semctl(semid, semnum, cmd, ...)`: `semctl` выполняет указанную команду `cmd` для очереди семафоров, указанной в `semid`. +* `semget(key, nsems, flag)`: `semget` создает массив семафоров, соответствующих `key`. ++ +`key и flag имеют то же значение, как и в msgget.` +* `semop(semid, array, nops)`: `semop` выполняет набор операций, указанных в `array`, для набора семафоров, идентифицируемых `semid`. + +Система IPC System V позволяет процессам использовать общую память. Процессы могут взаимодействовать напрямую друг с другом, разделяя части своего виртуального адресного пространства и затем читая и записывая данные в общей памяти. Эти системные вызовы заблокированы в среде _клетки_: man:shmdt[2], man:shmat[2], man:shmctl[2] и man:shmget[2]. + +[.filename]#/usr/src/sys/kern/sysv_shm.c#: + +* `shmctl(shmid, cmd, buf)`: `shmctl` выполняет различные управляющие операции над областью разделяемой памяти, идентифицируемой `shmid`. +* `shmget(key, size, flag)`: `shmget` обращается к существующей или создает новую область разделяемой памяти размером `size` байт. +* `shmat(shmid, addr, flag)`: `shmat` присоединяет область разделяемой памяти, идентифицируемую `shmid`, к адресному пространству процесса. +* `shmdt(addr)`: `shmdt` отсоединяет ранее присоединенную область разделяемой памяти по адресу `addr`. + +=== Сокеты + +Клетка обрабатывает системный вызов man:socket[2] и связанные низкоуровневые функции сокетов особым образом. Для определения, разрешено ли создание определённого сокета, сначала проверяется значение sysctl `security.jail.socket_unixiproute_only`. Если оно установлено, сокеты разрешено создавать только в случае, если указанное семейство равно `PF_LOCAL`, `PF_INET` или `PF_ROUTE`. В противном случае возвращается ошибка. + +[.programlisting] +.... +/usr/src/sys/kern/uipc_socket.c: +int +socreate(int dom, struct socket **aso, int type, int proto, + struct ucred *cred, struct thread *td) +{ + struct protosw *prp; +... + if (jailed(cred) && jail_socket_unixiproute_only && + prp->pr_domain->dom_family != PF_LOCAL && + prp->pr_domain->dom_family != PF_INET && + prp->pr_domain->dom_family != PF_ROUTE) { + return (EPROTONOSUPPORT); + } +... +} +.... + +=== Berkeley Packet Filter + +Берклиевский фильтр пакетов (BPF) предоставляет низкоуровневый интерфейс к канальному уровню, независимый от протокола. В настоящее время BPF управляется через man:devfs[8], который определяет возможность его использования в клетке. + +=== Протоколы + +Существуют определенные протоколы, которые очень распространены, такие как TCP, UDP, IP и ICMP. IP и ICMP находятся на одном уровне: сетевом уровне 2. Принимаются определенные меры предосторожности, чтобы предотвратить привязку протокола к определенному адресу процессом в клетке, только если установлен параметр `nam`. `nam` является указателем на структуру `sockaddr`, которая описывает адрес, к которому привязывается служба. Более точное определение заключается в том, что `sockaddr` "может использоваться как шаблон для ссылки на идентификационный тег и длину каждого адреса". В функции `in_pcbbind_setup()`, `sin` — это указатель на структуру `sockaddr_in`, которая содержит порт, адрес, длину и семейство доменов сокета, который должен быть привязан. В основном, это запрещает любым процессам из клетки указывать адрес, который не принадлежит клетке, в которой существует вызывающий процесс. + +[.programlisting] +.... +/usr/src/sys/netinet/in_pcb.c: +int +in_pcbbind_setup(struct inpcb *inp, struct sockaddr *nam, in_addr_t *laddrp, + u_short *lportp, struct ucred *cred) +{ + ... + struct sockaddr_in *sin; + ... + if (nam) { + sin = (struct sockaddr_in *)nam; + ... + if (sin->sin_addr.s_addr != INADDR_ANY) + if (prison_ip(cred, 0, &sin->sin_addr.s_addr)) + return(EINVAL); + ... + if (lport) { + ... + if (prison && prison_ip(cred, 0, &sin->sin_addr.s_addr)) + return (EADDRNOTAVAIL); + ... + } + } + if (lport == 0) { + ... + if (laddr.s_addr != INADDR_ANY) + if (prison_ip(cred, 0, &laddr.s_addr)) + return (EINVAL); + ... + } +... + if (prison_ip(cred, 0, &laddr.s_addr)) + return (EINVAL); +... +} +.... + +Вы можете задаться вопросом, какую функцию выполняет `prison_ip()`. `prison_ip()` принимает три аргумента: указатель на учетные данные (представленные как `cred`), любые флаги и IP-адрес. Она возвращает 1, если IP-адрес НЕ принадлежит клетке, и 0 в противном случае. Как видно из кода, если это действительно IP-адрес, не принадлежащий клетке, протоколу не разрешается привязываться к этому адресу. + +[.programlisting] +.... +/usr/src/sys/kern/kern_jail.c: +int +prison_ip(struct ucred *cred, int flag, u_int32_t *ip) +{ + u_int32_t tmp; + + if (!jailed(cred)) + return (0); + if (flag) + tmp = *ip; + else + tmp = ntohl(*ip); + if (tmp == INADDR_ANY) { + if (flag) + *ip = cred->cr_prison->pr_ip; + else + *ip = htonl(cred->cr_prison->pr_ip); + return (0); + } + if (tmp == INADDR_LOOPBACK) { + if (flag) + *ip = cred->cr_prison->pr_ip; + else + *ip = htonl(cred->cr_prison->pr_ip); + return (0); + } + if (cred->cr_prison->pr_ip != tmp) + return (1); + return (0); +} +.... + +=== Файловая система + +Даже пользователи с правами `root` внутри `клетки` не могут снять или изменить любые флаги файлов, такие как неизменяемый, только для добавления и неудаляемый, если уровень безопасности (`securelevel`) больше 0. + +[.programlisting] +.... +/usr/src/sys/ufs/ufs/ufs_vnops.c: +static int +ufs_setattr(ap) + ... +{ + ... + if (!priv_check_cred(cred, PRIV_VFS_SYSFLAGS, 0)) { + if (ip->i_flags + & (SF_NOUNLINK | SF_IMMUTABLE | SF_APPEND)) { + error = securelevel_gt(cred, 0); + if (error) + return (error); + } + ... + } +} +/usr/src/sys/kern/kern_priv.c +int +priv_check_cred(struct ucred *cred, int priv, int flags) +{ + ... + error = prison_priv_check(cred, priv); + if (error) + return (error); + ... +} +/usr/src/sys/kern/kern_jail.c +int +prison_priv_check(struct ucred *cred, int priv) +{ + ... + switch (priv) { + ... + case PRIV_VFS_SYSFLAGS: + if (jail_chflags_allowed) + return (0); + else + return (EPERM); + ... + } + ... +} +.... diff --git a/documentation/content/ru/books/arch-handbook/jail/_index.po b/documentation/content/ru/books/arch-handbook/jail/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/jail/_index.po @@ -0,0 +1,1452 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-08-16 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 Hash Value: title +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:1 +#, no-wrap +msgid "Chapter 4. The Jail Subsystem" +msgstr "Глава 4. Подсистема клеток" + +#. 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 "" +"На большинстве систем UNIX(R) пользователь `root` обладает неограниченной " +"властью. Это не способствует безопасности. Если злоумышленник получит права " +"`root` в системе, у него окажутся все функции под рукой. В FreeBSD " +"существуют sysctl-параметры, которые ограничивают власть `root`, чтобы " +"минимизировать ущерб от действий злоумышленника. В частности, одна из таких " +"функций называется `уровни безопасности`. Аналогично, другая функция, " +"доступная начиная с FreeBSD 4.0, — это утилита man:jail[8] — клетка. Клетка " +"создает chroot-окружение и накладывает определенные ограничения на процессы, " +"запущенные внутри `клетки`. Например, процесс в `клетке` не может влиять на " +"процессы вне её, использовать определенные системные вызовы или наносить " +"какой-либо ущерб основной системе." + +#. 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 "" +"Клетка становится новой моделью безопасности. Пользователи запускают " +"потенциально уязвимые серверы, такие как Apache, BIND и sendmail, внутри " +"клеток, так что если злоумышленник получит права `root` внутри клетки, это " +"будет лишь неудобством, а не катастрофой. Данная статья в основном " +"сосредоточена на внутреннем устройстве (исходном коде) клетки. Для получения " +"информации о настройке клетки см. extref:{handbook} jails/[раздел о клетках " +"Руководства FreeBSD, jails-synopsis]." + +#. 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 "" +"`Клетка` состоит из двух областей: пользовательской программы man:jail[8] и " +"кода, реализованного в ядре: системного вызова man:jail[2] и связанных с ним " +"ограничений. Я расскажу о пользовательской программе, а затем о том, как " +"`клетка` реализована в ядре." + +#. 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 "" +"Исходный код пользовательской части `клетки` находится в [.filename]#/usr/" +"src/usr.sbin/jail# и состоит из одного файла [.filename]#jail.c#. Программа " +"принимает следующие аргументы: путь к `клетке`, имя хоста, IP-адрес и " +"команду для выполнения." + +#. 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 "" +"В файле [.filename]#jail.c# первое, на что я бы обратил внимание, это " +"объявление важной структуры `struct jail j;`, которая была включена из " +"[.filename]#/usr/include/sys/jail.h#." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:69 +msgid "The definition of the `jail` structure is:" +msgstr "Определение структуры `jail` выглядит следующим образом:" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:73 +#, no-wrap +msgid "/usr/include/sys/jail.h:\n" +msgstr "/usr/include/sys/jail.h:\n" + +#. 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 "" +"struct jail {\n" +" u_int32_t version;\n" +" char *path;\n" +" char *hostname;\n" +" u_int32_t ip_number;\n" +"};\n" + +#. 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 "" +"Как видно, существует запись для каждого из аргументов, переданных программе " +"man:jail[8], и действительно, они устанавливаются во время её выполнения." + +#. 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 "" +"/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" + +#. 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 "" +"Один из аргументов, передаваемых программе man:jail[8], — это IP-адрес, по " +"которому можно получить доступ к клетке через сеть. man:jail[8] преобразует " +"указанный IP-адрес в порядок байтов хоста и сохраняет его в `j` (структура " +"`jail`)." + +#. 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 "" +"/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" + +#. 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 "" +"Функция man:inet_aton[3] \"интерпретирует указанную строку символов как " +"интернет-адрес, помещая адрес в предоставленную структуру.\" Член структуры " +"`ip_number` в структуре `jail` устанавливается только тогда, когда IP-адрес, " +"помещённый в структуру `in` функцией man:inet_aton[3], преобразуется в " +"порядок байтов хоста с помощью man:ntohl[3]." + +#. 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 "" +"Наконец, пользовательская программа помещает процесс в `клетку`. Теперь " +"`клетка` становится самим заключенным процессом и выполняет команду, " +"используя man:execv[3]." + +#. 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 "" +"/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" + +#. 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 "" +"Как видно, вызывается функция `jail()`, и её аргументом является структура " +"`jail`, заполненная аргументами, переданными программе. В конце выполняется " +"указанная вами программа. Теперь я расскажу о том, как `клетка` реализована " +"в ядре." + +#. 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 "" +"Мы сейчас рассмотрим файл [.filename]#/usr/src/sys/kern/kern_jail.c#. В этом " +"файле определены системный вызов man:jail[2], соответствующие sysctls и " +"сетевые функции." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:134 +#, no-wrap +msgid "Sysctls" +msgstr "Управляемые переменные ядра sysctl" + +#. 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 "" +"В файле [.filename]#kern_jail.c# определены следующие параметры sysctl:" + +#. 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 "" +"/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" + +#. 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 "" +"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" + +#. 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 "" +"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" + +#. 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 "" +"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" + +#. 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 "" +"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" + +#. 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 "" +"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" + +#. 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 "" +"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" + +#. 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 "" +"Каждый из этих параметров sysctl может быть доступен пользователю через " +"программу man:sysctl[8]. В ядре эти конкретные параметры sysctl распознаются " +"по их именам. Например, имя первого параметра sysctl — " +"`security.jail.set_hostname_allowed`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:179 +#, no-wrap +msgid "man:jail[2] System Call" +msgstr "Системный вызов man:jail[2]" + +#. 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 "" +"Как и все системные вызовы, системный вызов man:jail[2] принимает два " +"аргумента: `struct thread *td` и `struct jail_args *uap`. `td` — это " +"указатель на структуру `thread`, которая описывает вызывающий поток. В " +"данном контексте `uap` — это указатель на структуру, в которой содержится " +"указатель на структуру `jail`, переданную из пользовательского пространства " +"[.filename]#jail.c#. Ранее, когда я описывал пользовательскую программу, вы " +"видели, что системному вызову man:jail[2] была передана структура `jail` в " +"качестве собственного аргумента." + +#. 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 "" +"/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" + +#. 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 "" +"Следовательно, `uap->jail` можно использовать для доступа к структуре " +"`jail`, которая была передана системному вызову. Далее системный вызов " +"копирует структуру `клетка` в пространство ядра с помощью функции " +"man:copyin[9]. man:copyin[9] принимает три аргумента: адрес данных, которые " +"нужно скопировать в пространство ядра (`uap->jail`), место для записи данных " +"(`j`) и размер хранилища. Структура `jail`, на которую указывает `uap-" +">jail`, копируется в пространство ядра и сохраняется в другой структуре " +"`клетка` — `j`." + +#. 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 "" +"/usr/src/sys/kern/kern_jail.c:\n" +"error = copyin(uap->jail, &j, sizeof(j));\n" + +#. 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 "" +"В [.filename]#jail.h# определена ещё одна важная структура — `prison`. " +"Структура `prison` используется исключительно в пространстве ядра. Вот " +"определение структуры `prison`." + +#. 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 "" +"/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" + +#. 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 "" +"Системный вызов man:jail[2] затем выделяет память для структуры `prison` и " +"копирует данные между структурой `клетка` и структурой `prison`." + +#. 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 "" +"/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" + +#. 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 "" +"Далее мы рассмотрим ещё один важный системный вызов man:jail_attach[2], " +"который реализует функцию помещения процесса в клетку." + +#. 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 "" +"/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" + +#. 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 "" +"Этот системный вызов вносит изменения, которые позволяют отличить процесс в " +"клетке от процессов вне клетки. Чтобы понять, что делает man:jail_attach[2], " +"необходима некоторая справочная информация." + +#. 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 "" +"В FreeBSD каждый видимый ядром поток идентифицируется своей структурой " +"`thread`, а процессы описываются их структурами `proc`. Определения структур " +"`thread` и `proc` можно найти в [.filename]#/usr/include/sys/proc.h#. " +"Например, аргумент `td` в любом системном вызове на самом деле является " +"указателем на структуру `thread` вызывающего потока, как было указано ранее. " +"Член `td_proc` в структуре `thread`, на которую указывает `td`, является " +"указателем на структуру `proc`, представляющую процесс, содержащий поток, " +"представленный структурой `td`. Структура `proc` содержит члены, которые " +"могут описывать идентификацию владельца (`p_ucred`), ограничения ресурсов " +"процесса (`p_limit`) и так далее. В структуре `ucred`, на которую указывает " +"член `p_ucred` в структуре `proc`, есть указатель на структуру `prison` " +"(`cr_prison`)." + +#. 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 "" +"/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" + +#. 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 "" +"В файле [.filename]#kern_jail.c# функция `jail()` вызывает функцию " +"`jail_attach()` с заданным `jid`. Затем `jail_attach()` вызывает функцию " +"`change_root()` для изменения корневого каталога вызывающего процесса. " +"Функция `jail_attach()` создает новую структуру `ucred` и присоединяет её к " +"вызывающему процессу после успешного присоединения структуры `prison` к " +"структуре `ucred`. С этого момента вызывающий процесс считается находящимся " +"в клетке. Когда в ядре вызывается функция `jailed()` с вновь созданной " +"структурой `ucred` в качестве аргумента, она возвращает 1, указывая, что " +"учётные данные связаны с клеткой. Общим родительским процессом для всех " +"процессов, созданных внутри клетки, является процесс, запускающий " +"man:jail[8], так как он вызывает системный вызов man:jail[2]. При выполнении " +"программы через man:execve[2] она наследует свойство клетки из структуры " +"`ucred` родительского процесса, следовательно, у нее структура `ucred` тоже " +"со свойством клетки." + +#. 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 "" +"/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" + +#. 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 "" +"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" + +#. 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 "" +"Когда процесс создается из родительского процесса, системный вызов " +"man:fork[2] использует `crhold()` для поддержания учетных данных нового " +"процесса. Это автоматически сохраняет учетные данные нового дочернего " +"процесса согласованными с родительским, поэтому дочерний процесс также " +"остается в клетке." + +#. 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 "" +"/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" + +#. 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 "" +"if (jailed(td->td_ucred))\n" +" return (EPERM);\n" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:337 +#, no-wrap +msgid "SysV IPC" +msgstr "SysV IPC" + +#. 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 "" +"System V IPC основан на сообщениях. Процессы могут отправлять друг другу эти " +"сообщения, которые указывают им, как действовать. Функции, работающие с " +"сообщениями: man:msgctl[3], man:msgget[3], man:msgsnd[3] и man:msgrcv[3]. " +"Ранее я упоминал, что существуют определённые sysctl, которые можно включать " +"или выключать для изменения поведения клетки. Один из таких sysctl — " +"`security.jail.sysvipc_allowed`. По умолчанию этот sysctl установлен в 0. " +"Если бы он был установлен в 1, это бы свело на нет весь смысл клетки: " +"привилегированные пользователи внутри клетки смогли бы влиять на процессы за " +"её пределами. Разница между сообщением и сигналом заключается в том, что " +"сообщение состоит только из номера сигнала." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:342 +msgid "[.filename]#/usr/src/sys/kern/sysv_msg.c#:" +msgstr "[.filename]#/usr/src/sys/kern/sysv_msg.c#:" + +#. 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 "" +"`msgget(key, msgflg)`: `msgget` возвращает (и, возможно, создаёт) дескриптор " +"сообщения, который обозначает очередь сообщений для использования в других " +"функциях." + +#. 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 "" +"`msgctl(msgid, cmd, buf)`: С помощью этой функции процесс может запросить " +"статус дескриптора сообщения." + +#. 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 "" +"`msgsnd(msgid, msgp, msgsz, msgflg)`: `msgsnd` отправляет сообщение процессу." + +#. 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 "" +"`msgrcv(msgid, msgp, msgsz, msgtyp, msgflg)`: процесс получает сообщения с " +"помощью этой функции" + +#. 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 "" +"/usr/src/sys/kern/sysv_msg.c:\n" +"if (!jail_sysvipc_allowed && jailed(td->td_ucred))\n" +" return (ENOSYS);\n" + +#. 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 "" +"Системные вызовы семафоров позволяют процессам синхронизировать выполнение, " +"атомарно выполняя набор операций над набором семафоров. По сути, семафоры " +"предоставляют ещё один способ для процессов блокировать ресурсы. Однако " +"процесс, ожидающий семафор, который уже используется, будет находиться в " +"состоянии сна до тех пор, пока ресурсы не будут освобождены. Следующие " +"системные вызовы семафоров блокируются внутри клетки: man:semget[2], " +"man:semctl[2] и man:semop[2]." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:360 +msgid "[.filename]#/usr/src/sys/kern/sysv_sem.c#:" +msgstr "[.filename]#/usr/src/sys/kern/sysv_sem.c#:" + +#. 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 "" +"`semctl(semid, semnum, cmd, ...)`: `semctl` выполняет указанную команду " +"`cmd` для очереди семафоров, указанной в `semid`." + +#. 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 "" +"`semget(key, nsems, flag)`: `semget` создает массив семафоров, " +"соответствующих `key`." + +#. 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 "`key и flag имеют то же значение, как и в msgget.`" + +#. 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 "" +"`semop(semid, array, nops)`: `semop` выполняет набор операций, указанных в " +"`array`, для набора семафоров, идентифицируемых `semid`." + +#. 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 "" +"Система IPC System V позволяет процессам использовать общую память. Процессы " +"могут взаимодействовать напрямую друг с другом, разделяя части своего " +"виртуального адресного пространства и затем читая и записывая данные в общей " +"памяти. Эти системные вызовы заблокированы в среде _клетки_: man:shmdt[2], " +"man:shmat[2], man:shmctl[2] и man:shmget[2]." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:370 +msgid "[.filename]#/usr/src/sys/kern/sysv_shm.c#:" +msgstr "[.filename]#/usr/src/sys/kern/sysv_shm.c#:" + +#. 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 "" +"`shmctl(shmid, cmd, buf)`: `shmctl` выполняет различные управляющие операции " +"над областью разделяемой памяти, идентифицируемой `shmid`." + +#. 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 "" +"`shmget(key, size, flag)`: `shmget` обращается к существующей или создает " +"новую область разделяемой памяти размером `size` байт." + +#. 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 "" +"`shmat(shmid, addr, flag)`: `shmat` присоединяет область разделяемой памяти, " +"идентифицируемую `shmid`, к адресному пространству процесса." + +#. 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 "" +"`shmdt(addr)`: `shmdt` отсоединяет ранее присоединенную область разделяемой " +"памяти по адресу `addr`." + +#. 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 "" +"Клетка обрабатывает системный вызов man:socket[2] и связанные низкоуровневые " +"функции сокетов особым образом. Для определения, разрешено ли создание " +"определённого сокета, сначала проверяется значение sysctl " +"`security.jail.socket_unixiproute_only`. Если оно установлено, сокеты " +"разрешено создавать только в случае, если указанное семейство равно " +"`PF_LOCAL`, `PF_INET` или `PF_ROUTE`. В противном случае возвращается ошибка." + +#. 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 "" +"/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" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/jail/_index.adoc:399 +#, no-wrap +msgid "Berkeley Packet Filter" +msgstr "Berkeley Packet Filter" + +#. 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 "" +"Берклиевский фильтр пакетов (BPF) предоставляет низкоуровневый интерфейс к " +"канальному уровню, независимый от протокола. В настоящее время BPF " +"управляется через man:devfs[8], который определяет возможность его " +"использования в клетке." + +#. 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 "" +"Существуют определенные протоколы, которые очень распространены, такие как " +"TCP, UDP, IP и ICMP. IP и ICMP находятся на одном уровне: сетевом уровне 2. " +"Принимаются определенные меры предосторожности, чтобы предотвратить привязку " +"протокола к определенному адресу процессом в клетке, только если установлен " +"параметр `nam`. `nam` является указателем на структуру `sockaddr`, которая " +"описывает адрес, к которому привязывается служба. Более точное определение " +"заключается в том, что `sockaddr` \"может использоваться как шаблон для " +"ссылки на идентификационный тег и длину каждого адреса\". В функции " +"`in_pcbbind_setup()`, `sin` — это указатель на структуру `sockaddr_in`, " +"которая содержит порт, адрес, длину и семейство доменов сокета, который " +"должен быть привязан. В основном, это запрещает любым процессам из клетки " +"указывать адрес, который не принадлежит клетке, в которой существует " +"вызывающий процесс." + +#. 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 "" +"/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" + +#. 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 "" +"Вы можете задаться вопросом, какую функцию выполняет `prison_ip()`. " +"`prison_ip()` принимает три аргумента: указатель на учетные данные " +"(представленные как `cred`), любые флаги и IP-адрес. Она возвращает 1, если " +"IP-адрес НЕ принадлежит клетке, и 0 в противном случае. Как видно из кода, " +"если это действительно IP-адрес, не принадлежащий клетке, протоколу не " +"разрешается привязываться к этому адресу." + +#. 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 "" +"/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" + +#. 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 "" +" 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" + +#. 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 "" +"Даже пользователи с правами `root` внутри `клетки` не могут снять или " +"изменить любые флаги файлов, такие как неизменяемый, только для добавления и " +"неудаляемый, если уровень безопасности (`securelevel`) больше 0." + +#. 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 "" +"/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" diff --git a/documentation/content/ru/books/arch-handbook/kobj/_index.adoc b/documentation/content/ru/books/arch-handbook/kobj/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/kobj/_index.adoc @@ -0,0 +1,259 @@ +--- +description: 'Объекты ядра' +next: books/arch-handbook/jail +params: + path: /books/arch-handbook/kobj/ +prev: books/arch-handbook/locking +showBookMenu: true +tags: ["kernel objects", "kobj", "guide", "FreeBSD"] +title: 'Глава 3. Объекты ядра' +weight: 4 +--- + +[[kernel-objects]] += Объекты ядра +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 3 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +Объекты ядра, или _Kobj_, предоставляют объектно-ориентированную систему программирования на языке C для ядра. Таким образом, данные, с которыми производится работа, содержат описание того, как над ними следует выполнять операции. Это позволяет добавлять и удалять операции из интерфейса во время выполнения без нарушения бинарной совместимости. + +[[kernel-objects-term]] +== Терминология + +Объект:: +Набор данных - структура данных - аллокация данных. + +Метод:: +Операция — функция. + +Класс:: +Один или несколько методов. + +Интерфейс:: +Стандартный набор из одного или нескольких методов. + +[[kernel-objects-operation]] +== Как работает Kobj + +Kobj работает путем генерации описаний методов. Каждое описание содержит уникальный идентификатор, а также функцию по умолчанию. Адрес описания используется для однозначной идентификации метода в таблице методов класса. + +Класс создается путем построения таблицы методов, связывающей одну или несколько функций с описаниями методов. Перед использованием класс компилируется. В процессе компиляции выделяется кэш и связывается с классом. Уникальный идентификатор назначается каждому описанию метода в таблице методов класса, если это еще не было сделано другой ссылающейся компиляцией класса. Для каждого используемого метода скриптом генерируется функция для проверки аргументов и автоматического обращения к описанию метода для поиска. Сгенерированная функция ищет метод, используя уникальный идентификатор, связанный с описанием метода, в качестве хэша для доступа к кэшу, связанному с классом объекта. Если метод не найден в кэше, сгенерированная функция использует таблицу класса для поиска метода. Если метод найден, используется связанная с ним функция внутри класса; в противном случае используется функция по умолчанию, связанная с описанием метода. + +Эти перенаправления можно визуализировать следующим образом: + +[.programlisting] +.... +object->cache<->class +.... + +[[kernel-objects-using]] +== Использование Kobj + +=== Структуры + +[.programlisting] +.... +struct kobj_method +.... + +=== Функции + +[.programlisting] +.... +void kobj_class_compile(kobj_class_t cls); +void kobj_class_compile_static(kobj_class_t cls, kobj_ops_t ops); +void kobj_class_free(kobj_class_t cls); +kobj_t kobj_create(kobj_class_t cls, struct malloc_type *mtype, int mflags); +void kobj_init(kobj_t obj, kobj_class_t cls); +void kobj_delete(kobj_t obj, struct malloc_type *mtype); +.... + +=== Макросы + +[.programlisting] +.... +KOBJ_CLASS_FIELDS +KOBJ_FIELDS +DEFINE_CLASS(name, methods, size) +KOBJMETHOD(NAME, FUNC) +.... + +=== Заголовки + +[.programlisting] +.... + + +.... + +=== Создание шаблона интерфейса + +Первым шагом в использовании Kobj является создание интерфейса. Создание интерфейса включает в себя создание шаблона, который скрипт [.filename]#src/sys/kern/makeobjops.pl# может использовать для генерации заголовочного файла и кода объявлений методов и функций поиска методов. + +В этом шаблоне используются следующие ключевые слова: `#include`, `INTERFACE`, `CODE`, `EPILOG`, `HEADER`, `METHOD`, `PROLOG`, `STATICMETHOD` и `DEFAULT`. + +Включение директивы `#include` и всего, что следует за ней, копируется дословно в начало сгенерированного файла с кодом. + +Например: + +[.programlisting] +.... +#include +.... + +Ключевое слово `INTERFACE` используется для определения имени интерфейса. Это имя объединяется с каждым именем метода в формате [имя интерфейса]_[имя метода]. Его синтаксис: `INTERFACE [имя интерфейса];`. + +Например: + +[.programlisting] +.... +INTERFACE foo; +.... + +Ключевое слово `CODE` копирует свои аргументы дословно в файл кода. Его синтаксис: `CODE { [что угодно] };` + +Например: + +[.programlisting] +.... +CODE { + struct foo * foo_alloc_null(struct bar *) + { + return NULL; + } +}; +.... + +Ключевое слово `HEADER` копирует свои аргументы в заголовочный файл без изменений. Его синтаксис: `HEADER { [что угодно] };` + +Например: + +[.programlisting] +.... +HEADER { + struct mumble; + struct grumble; +}; +.... + +Ключевое слово `METHOD` описывает метод. Его синтаксис: `METHOD [возвращаемый тип] [имя метода] { [объект [, аргументы]] };` + +Например: + +[.programlisting] +.... +METHOD int bar { + struct object *; + struct foo *; + struct bar; +}; +.... + +Ключевое слово `DEFAULT` может следовать за ключевым словом `METHOD`. Оно расширяет ключевое слово `METHOD`, включая функцию по умолчанию для метода. Расширенный синтаксис выглядит так: `METHOD [тип возвращаемого значения] [имя метода] { [объект; [другие аргументы]] } DEFAULT [функция по умолчанию];` + +Например: + +[.programlisting] +.... +METHOD int bar { + struct object *; + struct foo *; + int bar; +} DEFAULT foo_hack; +.... + +Ключевое слово `STATICMETHOD` используется аналогично ключевому слову `METHOD`, за исключением того, что данные kobj не находятся в начале структуры объекта, поэтому приведение к типу kobj_t было бы некорректным. Вместо этого `STATICMETHOD` полагается на то, что данные Kobj указаны как 'ops'. Это также полезно для вызова методов напрямую из таблицы методов класса. + +Ключевые слова `PROLOG` и `EPILOG` вставляют код непосредственно перед или сразу после `METHOD`, к которому они прикреплены. Эта функция в основном используется для профилирования в ситуациях, когда сложно получить информацию другим способом. + +Другие полные примеры: + +[.programlisting] +.... +src/sys/kern/bus_if.m +src/sys/kern/device_if.m +.... + +=== Создание класса + +Второй шаг в использовании Kobj — это создание класса. Класс состоит из имени, таблицы методов и размера объектов, если используются средства обработки объектов Kobj. Для создания класса используйте макрос `DEFINE_CLASS()`. Чтобы создать таблицу методов, создайте массив элементов kobj_method_t, завершающийся записью NULL. Каждую не-NULL запись можно создать с помощью макроса `KOBJMETHOD()`. + +Например: + +[.programlisting] +.... +DEFINE_CLASS(fooclass, foomethods, sizeof(struct foodata)); + +kobj_method_t foomethods[] = { + KOBJMETHOD(bar_doo, foo_doo), + KOBJMETHOD(bar_foo, foo_foo), + { NULL, NULL} +}; +.... + +Класс должен быть "скомпилирован". В зависимости от состояния системы на момент инициализации класса, необходимо использовать статически выделенный кэш, "таблицу операций". Это может быть достигнуто путем объявления `struct kobj_ops` и использования `kobj_class_compile_static();` в противном случае следует использовать `kobj_class_compile()`. + +=== Создание объекта + +Третий шаг в использовании Kobj связан с определением объекта. Процедуры создания объекта Kobj предполагают, что данные Kobj находятся в начале объекта. Если это не подходит, вам придется самостоятельно выделить память для объекта, а затем использовать `kobj_init()` для части объекта, относящейся к Kobj; в противном случае вы можете использовать `kobj_create()` для автоматического выделения и инициализации части объекта, относящейся к Kobj. `kobj_init()` также может использоваться для изменения класса, который использует объект. + +Для интеграции Kobj в объект следует использовать макрос `KOBJ_FIELDS`. + +Например + +[.programlisting] +.... +struct foo_data { + KOBJ_FIELDS; + foo_foo; + foo_bar; +}; +.... + +=== Вызов методов + +Последним шагом в использовании Kobj является простое использование сгенерированных функций для вызова нужного метода в классе объекта. Это так же просто, как использование имени интерфейса и имени метода с небольшими изменениями. Имя интерфейса должно быть соединено с именем метода с использованием символа '_' между ними, все в верхнем регистре. + +Например, если имя интерфейса было foo, а метод — bar, то вызов будет выглядеть следующим образом: + +[.programlisting] +.... +[return value = ] FOO_BAR(object [, other parameters]); +.... + +=== Очистка + +Когда объект, выделенный через `kobj_create()`, больше не нужен, можно вызвать для него `kobj_delete()`, а когда класс больше не используется, можно вызвать для него `kobj_class_free()`. diff --git a/documentation/content/ru/books/arch-handbook/kobj/_index.po b/documentation/content/ru/books/arch-handbook/kobj/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/kobj/_index.po @@ -0,0 +1,622 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-02 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 Hash Value: title +#: documentation/content/en/books/arch-handbook/kobj/_index.adoc:1 +#, no-wrap +msgid "Chapter 3. Kernel Objects" +msgstr "Глава 3. Объекты ядра" + +#. 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 "" +"Объекты ядра, или _Kobj_, предоставляют объектно-ориентированную систему " +"программирования на языке C для ядра. Таким образом, данные, с которыми " +"производится работа, содержат описание того, как над ними следует выполнять " +"операции. Это позволяет добавлять и удалять операции из интерфейса во время " +"выполнения без нарушения бинарной совместимости." + +#. 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 "Как работает Kobj" + +#. 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 "" +"Kobj работает путем генерации описаний методов. Каждое описание содержит " +"уникальный идентификатор, а также функцию по умолчанию. Адрес описания " +"используется для однозначной идентификации метода в таблице методов класса." + +#. 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 "object->cache<->class\n" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/kobj/_index.adoc:94 +#, no-wrap +msgid "Using Kobj" +msgstr "Использование Kobj" + +#. 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 "struct kobj_method\n" + +#. 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 "" +"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" + +#. 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 "" +"KOBJ_CLASS_FIELDS\n" +"KOBJ_FIELDS\n" +"DEFINE_CLASS(name, methods, size)\n" +"KOBJMETHOD(NAME, FUNC)\n" + +#. 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 "" +"\n" +"\n" +msgstr "" +"\n" +"\n" + +#. 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 "" +"Первым шагом в использовании Kobj является создание интерфейса. Создание " +"интерфейса включает в себя создание шаблона, который скрипт [.filename]#src/" +"sys/kern/makeobjops.pl# может использовать для генерации заголовочного файла " +"и кода объявлений методов и функций поиска методов." + +#. 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 "" +"В этом шаблоне используются следующие ключевые слова: `#include`, " +"`INTERFACE`, `CODE`, `EPILOG`, `HEADER`, `METHOD`, `PROLOG`, `STATICMETHOD` " +"и `DEFAULT`." + +#. 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 "" +"Включение директивы `#include` и всего, что следует за ней, копируется " +"дословно в начало сгенерированного файла с кодом." + +#. 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 \n" +msgstr "#include \n" + +#. 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 "" +"Ключевое слово `INTERFACE` используется для определения имени интерфейса. " +"Это имя объединяется с каждым именем метода в формате [имя интерфейса]_[имя " +"метода]. Его синтаксис: `INTERFACE [имя интерфейса];`." + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/kobj/_index.adoc:158 +#, no-wrap +msgid "INTERFACE foo;\n" +msgstr "INTERFACE foo;\n" + +#. 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 "" +"Ключевое слово `CODE` копирует свои аргументы дословно в файл кода. Его " +"синтаксис: `CODE { [что угодно] };`" + +#. 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 "" +"CODE {\n" +"\tstruct foo * foo_alloc_null(struct bar *)\n" +"\t{\n" +"\t\treturn NULL;\n" +"\t}\n" +"};\n" + +#. 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 "" +"Ключевое слово `HEADER` копирует свои аргументы в заголовочный файл без " +"изменений. Его синтаксис: `HEADER { [что угодно] };`" + +#. 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 "" +"HEADER {\n" +" struct mumble;\n" +" struct grumble;\n" +"};\n" + +#. 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 "" +"Ключевое слово `METHOD` описывает метод. Его синтаксис: `METHOD " +"[возвращаемый тип] [имя метода] { [объект [, аргументы]] };`" + +#. 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 "" +"METHOD int bar {\n" +"\tstruct object *;\n" +"\tstruct foo *;\n" +"\tstruct bar;\n" +"};\n" + +#. 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 "" +"Ключевое слово `DEFAULT` может следовать за ключевым словом `METHOD`. Оно " +"расширяет ключевое слово `METHOD`, включая функцию по умолчанию для метода. " +"Расширенный синтаксис выглядит так: `METHOD [тип возвращаемого значения] " +"[имя метода] { [объект; [другие аргументы]] } DEFAULT [функция по " +"умолчанию];`" + +#. 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 "" +"METHOD int bar {\n" +"\tstruct object *;\n" +"\tstruct foo *;\n" +"\tint bar;\n" +"} DEFAULT foo_hack;\n" + +#. 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 "" +"Ключевое слово `STATICMETHOD` используется аналогично ключевому слову " +"`METHOD`, за исключением того, что данные kobj не находятся в начале " +"структуры объекта, поэтому приведение к типу kobj_t было бы некорректным. " +"Вместо этого `STATICMETHOD` полагается на то, что данные Kobj указаны как " +"'ops'. Это также полезно для вызова методов напрямую из таблицы методов " +"класса." + +#. 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 "" +"Ключевые слова `PROLOG` и `EPILOG` вставляют код непосредственно перед или " +"сразу после `METHOD`, к которому они прикреплены. Эта функция в основном " +"используется для профилирования в ситуациях, когда сложно получить " +"информацию другим способом." + +#. 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 "" +"src/sys/kern/bus_if.m\n" +"src/sys/kern/device_if.m\n" + +#. 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 "" +"Второй шаг в использовании Kobj — это создание класса. Класс состоит из " +"имени, таблицы методов и размера объектов, если используются средства " +"обработки объектов Kobj. Для создания класса используйте макрос " +"`DEFINE_CLASS()`. Чтобы создать таблицу методов, создайте массив элементов " +"kobj_method_t, завершающийся записью NULL. Каждую не-NULL запись можно " +"создать с помощью макроса `KOBJMETHOD()`." + +#. 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 "DEFINE_CLASS(fooclass, foomethods, sizeof(struct foodata));\n" + +#. 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 "" +"kobj_method_t foomethods[] = {\n" +"\tKOBJMETHOD(bar_doo, foo_doo),\n" +"\tKOBJMETHOD(bar_foo, foo_foo),\n" +"\t{ NULL, NULL}\n" +"};\n" + +#. 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 "" +"Класс должен быть \"скомпилирован\". В зависимости от состояния системы на " +"момент инициализации класса, необходимо использовать статически выделенный " +"кэш, \"таблицу операций\". Это может быть достигнуто путем объявления " +"`struct kobj_ops` и использования `kobj_class_compile_static();` в противном " +"случае следует использовать `kobj_class_compile()`." + +#. 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 "" +"Третий шаг в использовании Kobj связан с определением объекта. Процедуры " +"создания объекта Kobj предполагают, что данные Kobj находятся в начале " +"объекта. Если это не подходит, вам придется самостоятельно выделить память " +"для объекта, а затем использовать `kobj_init()` для части объекта, " +"относящейся к Kobj; в противном случае вы можете использовать " +"`kobj_create()` для автоматического выделения и инициализации части объекта, " +"относящейся к Kobj. `kobj_init()` также может использоваться для изменения " +"класса, который использует объект." + +#. 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 "" +"Для интеграции Kobj в объект следует использовать макрос `KOBJ_FIELDS`." + +#. 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 "" +"struct foo_data {\n" +"\tKOBJ_FIELDS;\n" +"\tfoo_foo;\n" +"\tfoo_bar;\n" +"};\n" + +#. 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 "" +"Последним шагом в использовании Kobj является простое использование " +"сгенерированных функций для вызова нужного метода в классе объекта. Это так " +"же просто, как использование имени интерфейса и имени метода с небольшими " +"изменениями. Имя интерфейса должно быть соединено с именем метода с " +"использованием символа '_' между ними, все в верхнем регистре." + +#. 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 "" +"Например, если имя интерфейса было foo, а метод — bar, то вызов будет " +"выглядеть следующим образом:" + +#. 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 "[return value = ] FOO_BAR(object [, other parameters]);\n" + +#. 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 "" +"Когда объект, выделенный через `kobj_create()`, больше не нужен, можно " +"вызвать для него `kobj_delete()`, а когда класс больше не используется, " +"можно вызвать для него `kobj_class_free()`." diff --git a/documentation/content/ru/books/arch-handbook/locking/_index.adoc b/documentation/content/ru/books/arch-handbook/locking/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/locking/_index.adoc @@ -0,0 +1,145 @@ +--- +description: 'Заметки о блокировках' +next: books/arch-handbook/kobj +params: + path: /books/arch-handbook/locking/ +prev: books/arch-handbook/boot +showBookMenu: true +tags: ["locking", "notes", "SMP", "Mutexes"] +title: 'Глава 2. Заметки о блокировках' +weight: 3 +--- + +[[locking]] += Заметки о блокировках +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 2 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +_Эта глава сопровождается и поддерживается проектом FreeBSD SMP Next Generation._ + +Этот документ описывает механизмы блокировки, используемые в ядре FreeBSD для эффективной многопроцессорной обработки. Блокировка может быть достигнута несколькими способами. Структуры данных могут защищаться мьютексами или блокировками (lock) из man:lockmgr[9]. Некоторые переменные защищаются просто за счёт использования атомарных операций для доступа к ним. + +[[locking-mutexes]] +== Mutexes + +Мьютекс — это просто блокировка, используемая для обеспечения взаимного исключения. Конкретно, мьютекс может принадлежать только одному объекту в один момент времени. Если другой объект хочет получить мьютекс, который уже принадлежит кому-то, он должен ждать, пока мьютекс не будет освобожден. В ядре FreeBSD мьютексы принадлежат процессам. + +Мьютексы могут быть получены рекурсивно, но предполагается, что они удерживаются в течение короткого периода времени. В частности, нельзя переходить в режим сна, удерживая мьютекс. Если необходимо удерживать блокировку во время сна, используйте блокировку man:lockmgr[9]. + +Каждый мьютекс обладает несколькими важными свойствами: + +Имя переменной:: +Имя переменной struct mtx в исходном коде ядра. + +Логическое имя:: +Имя мьютекса, назначенное ему с помощью `mtx_init`. Это имя отображается в сообщениях трассировки KTR, ошибках и предупреждениях witness, а также используется для различения мьютексов в коде witness. + +Тип:: +Тип мьютекса в терминах флагов `MTX_*`. Значение каждого флага связано с его значением, как описано в man:mutex[9]. + +`MTX_DEF`::: +Мьютекс блокировки с ожиданием + +`MTX_SPIN`::: +Мьютекс с вращающейся блокировкой (spin mutex) + +`MTX_RECURSE`::: +Этот мьютекс допускает рекурсию. + +Защищаемые системы:: +Список структур данных или членов структур данных, которые защищает эта запись. Для членов структур данных имя будет указано в формате `имя структуры`.`имя члена`. + +Зависимые функции:: +Функции, которые могут быть вызваны только при удержании этого мьютекса. + +.Список мьютексов +[cols="15%,10%,10%,55%,20%", frame="all", options="header"] +|=== +| Имя переменной +| Логическое имя +| Тип +| Защищаемые системы +| Зависимые функции + +|sched_lock +|"sched lock" +|`MTX_SPIN` \| `MTX_RECURSE` +|`_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` +|`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` + +|vm86pcb_lock +|"vm86pcb lock" +|`MTX_DEF` +|`vm86pcb` +|`vm86_bioscall` + +|Giant +|"Giant" +|`MTX_DEF` \| `MTX_RECURSE` +|почти всё +|много + +|callout_lock +|"callout lock" +|`MTX_SPIN` \| `MTX_RECURSE` +|`callfree`, `callwheel`, `nextsoftcheck`, `proc`.`p_itcallout`, `proc`.`p_slpcallout`, `softticks`, `ticks` +| +|=== + +[[locking-sx]] +== Разделяемые эксклюзивные блокировки + +Эти блокировки обеспечивают базовую функциональность типа читатель-писатель и могут удерживаться спящим процессом. В настоящее время они реализованы через man:lockmgr[9]. + +.Список разделяемых эксклюзивных блокировок +[cols="20%,80%", options="header"] +|=== +| Имя переменной +| Защищаемые системы + +|`allproc_lock` +|`allproc` `zombproc` `pidhashtbl` `proc`.`p_list` `proc`.`p_hash` `nextpid` + +|`proctree_lock` +|`proc`.`p_children` `proc`.`p_sibling` +|=== + +[[locking-atomic]] +== Атомарно защищённые переменные + +Переменная с атомарной защитой — это специальная переменная, которая не защищена явной блокировкой. Вместо этого все операции доступа к данным этой переменной используют специальные атомарные операции, как описано в man:atomic[9]. Очень немногие переменные обрабатываются таким образом, хотя другие примитивы синхронизации, такие как мьютексы, реализованы с использованием переменных с атомарной защитой. + +* `mtx`.`mtx_lock` diff --git a/documentation/content/ru/books/arch-handbook/locking/_index.po b/documentation/content/ru/books/arch-handbook/locking/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/locking/_index.po @@ -0,0 +1,390 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-06-30 23:10+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 Hash Value: title +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:1 +#, no-wrap +msgid "Chapter 2. Locking Notes" +msgstr "Глава 2. Заметки о блокировках" + +#. 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 "" +"_Эта глава сопровождается и поддерживается проектом FreeBSD SMP Next " +"Generation._" + +#. 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 "" +"Этот документ описывает механизмы блокировки, используемые в ядре FreeBSD " +"для эффективной многопроцессорной обработки. Блокировка может быть " +"достигнута несколькими способами. Структуры данных могут защищаться " +"мьютексами или блокировками (lock) из man:lockmgr[9]. Некоторые переменные " +"защищаются просто за счёт использования атомарных операций для доступа к ним." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:56 +#, no-wrap +msgid "Mutexes" +msgstr "Mutexes" + +#. 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 "" +"Мьютекс — это просто блокировка, используемая для обеспечения взаимного " +"исключения. Конкретно, мьютекс может принадлежать только одному объекту в " +"один момент времени. Если другой объект хочет получить мьютекс, который уже " +"принадлежит кому-то, он должен ждать, пока мьютекс не будет освобожден. В " +"ядре FreeBSD мьютексы принадлежат процессам." + +#. 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 "" +"Мьютексы могут быть получены рекурсивно, но предполагается, что они " +"удерживаются в течение короткого периода времени. В частности, нельзя " +"переходить в режим сна, удерживая мьютекс. Если необходимо удерживать " +"блокировку во время сна, используйте блокировку man:lockmgr[9]." + +#. 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 "Имя переменной struct mtx в исходном коде ядра." + +#. 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 "" +"Имя мьютекса, назначенное ему с помощью `mtx_init`. Это имя отображается в " +"сообщениях трассировки KTR, ошибках и предупреждениях witness, а также " +"используется для различения мьютексов в коде witness." + +#. 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 "" +"Тип мьютекса в терминах флагов `MTX_*`. Значение каждого флага связано с его " +"значением, как описано в man:mutex[9]." + +#. 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 "`MTX_DEF`" + +#. 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 "`MTX_SPIN`" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:78 +msgid "A spin mutex" +msgstr "Мьютекс с вращающейся блокировкой (spin mutex)" + +#. 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 "`MTX_RECURSE`" + +#. 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 "sched_lock" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:99 +#, no-wrap +msgid "\"sched lock\"" +msgstr "\"sched lock\"" + +#. 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 "`MTX_SPIN` \\" + +#. 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 "`_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`" + +#. 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 "`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`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:104 +#, no-wrap +msgid "vm86pcb_lock" +msgstr "vm86pcb_lock" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:105 +#, no-wrap +msgid "\"vm86pcb lock\"" +msgstr "\"vm86pcb lock\"" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:107 +#, no-wrap +msgid "`vm86pcb`" +msgstr "`vm86pcb`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:109 +#, no-wrap +msgid "`vm86_bioscall`" +msgstr "`vm86_bioscall`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:110 +#, no-wrap +msgid "Giant" +msgstr "Giant" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:111 +#, no-wrap +msgid "\"Giant\"" +msgstr "\"Giant\"" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:111 +#, no-wrap +msgid "`MTX_DEF` \\" +msgstr "`MTX_DEF` \\" + +#. 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 "callout_lock" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:117 +#, no-wrap +msgid "\"callout lock\"" +msgstr "\"callout lock\"" + +#. 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 "`callfree`, `callwheel`, `nextsoftcheck`, `proc`.`p_itcallout`, `proc`.`p_slpcallout`, `softticks`, `ticks`" + +#. 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 "" +"Эти блокировки обеспечивают базовую функциональность типа читатель-писатель " +"и могут удерживаться спящим процессом. В настоящее время они реализованы " +"через man:lockmgr[9]." + +#. 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 "`allproc_lock`" + +#. 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 "`allproc` `zombproc` `pidhashtbl` `proc`.`p_list` `proc`.`p_hash` `nextpid`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:137 +#, no-wrap +msgid "`proctree_lock`" +msgstr "`proctree_lock`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:138 +#, no-wrap +msgid "`proc`.`p_children` `proc`.`p_sibling`" +msgstr "`proc`.`p_children` `proc`.`p_sibling`" + +#. 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 "" +"Переменная с атомарной защитой — это специальная переменная, которая не " +"защищена явной блокировкой. Вместо этого все операции доступа к данным этой " +"переменной используют специальные атомарные операции, как описано в " +"man:atomic[9]. Очень немногие переменные обрабатываются таким образом, хотя " +"другие примитивы синхронизации, такие как мьютексы, реализованы с " +"использованием переменных с атомарной защитой." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/locking/_index.adoc:145 +msgid "`mtx`.`mtx_lock`" +msgstr "`mtx`.`mtx_lock`" diff --git a/documentation/content/ru/books/arch-handbook/mac/_index.adoc b/documentation/content/ru/books/arch-handbook/mac/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/mac/_index.adoc @@ -0,0 +1,5080 @@ +--- +authors: + - + author: 'Chris Costello' + email: chris@FreeBSD.org + - + author: 'Robert Watson' + email: rwatson@FreeBSD.org +description: 'Фреймворк TrustedBSD MAC' +next: books/arch-handbook/vm +params: + path: /books/arch-handbook/mac/ +prev: books/arch-handbook/sysinit +showBookMenu: true +tags: ["TrustedBSD", "MAC"] +title: 'Глава 6. Фреймворк TrustedBSD MAC' +weight: 7 +--- + +[[mac]] += Фреймворк TrustedBSD MAC +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 6 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[mac-copyright]] +== Авторские права документации MAC + +Этот документ был разработан для проекта FreeBSD Крисом Костелло из Safeport Network Services и Network Associates Laboratories, подразделения исследований безопасности Network Associates, Inc., по контракту DARPA/SPAWAR N66001-01-C-8035 ("CBOSS") в рамках исследовательской программы DARPA CHATS. + +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: + +. 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. +. Распространение в скомпилированной форме (преобразованное в другие DTD, конвертированное в PDF, PostScript, RTF и другие форматы) должно включать указанное выше уведомление об авторских правах, данный список условий и следующий отказ от ответственности в документации и/или других материалах, предоставляемых вместе с распространением. + +[IMPORTANT] +==== +ЭТА ДОКУМЕНТАЦИЯ ПРЕДОСТАВЛЯЕТСЯ NETWORKS ASSOCIATES TECHNOLOGY, INC «КАК ЕСТЬ», И ЛЮБЫЕ ЯВНЫЕ ИЛИ ПОДРАЗУМЕВАЕМЫЕ ГАРАНТИИ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ИМИ, ПОДРАЗУМЕВАЕМЫЕ ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ И ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ ОТРИЦАЮТСЯ. НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ NETWORKS ASSOCIATES TECHNOLOGY, INC НЕ НЕСЕТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ ПРЯМЫЕ, КОСВЕННЫЕ, СЛУЧАЙНЫЕ, СПЕЦИАЛЬНЫЕ, ШТРАФНЫЕ ИЛИ КОСВЕННЫЕ УБЫТКИ (ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ИМИ, ЗАТРАТЫ НА ЗАМЕНУ ТОВАРОВ ИЛИ УСЛУГ; ПОТЕРЮ ИСПОЛЬЗОВАНИЯ, ДАННЫХ ИЛИ ПРИБЫЛИ; ЛИБО ПРЕРЫВАНИЕ БИЗНЕСА), ВЫЗВАННЫЕ ЛЮБЫМ ОБРАЗОМ И НА ОСНОВАНИИ ЛЮБОЙ ТЕОРИИ ОТВЕТСТВЕННОСТИ, БУДЬ ТО В РАМКАХ ДОГОВОРА, СТРОГОЙ ОТВЕТСТВЕННОСТИ ИЛИ ДЕЛИКТА (ВКЛЮЧАЯ НЕБРЕЖНОСТЬ ИЛИ ИНОЕ), ВОЗНИКШИЕ ВСЛЕДСТВИЕ ИСПОЛЬЗОВАНИЯ ЭТОЙ ДОКУМЕНТАЦИИ, ДАЖЕ ЕСЛИ БЫЛО ПРЕДУПРЕЖДЕНИЕ О ВОЗМОЖНОСТИ ТАКИХ УБЫТКОВ. +==== + +[[mac-synopsis]] +== Обзор + +FreeBSD включает экспериментальную поддержку нескольких политик обязательного контроля доступа, а также инфраструктуру для расширяемости безопасности ядра — TrustedBSD MAC Framework. MAC Framework представляет собой модульную инфраструктуру контроля доступа, позволяющую легко встраивать новые политики безопасности в ядро, загружать их при старте системы или динамически во время работы. Инфраструктура предоставляет множество возможностей для упрощения реализации новых политик безопасности, включая возможность легко присваивать метки безопасности (например, информацию о конфиденциальности) объектам системы. + +Эта глава представляет фреймворк политик MAC и содержит документацию для образца модуля политики MAC. + +[[mac-introduction]] +== Введение + +Фреймворк TrustedBSD MAC предоставляет механизм для расширения модели контроля доступа ядра во время компиляции или выполнения. Новые политики системы могут быть реализованы в виде модулей ядра и связаны с ним; если присутствуют несколько модулей политик, их результаты будут объединены. Фреймворк MAC предоставляет различные инфраструктурные сервисы контроля доступа для помощи разработчикам политик, включая поддержку временных и постоянных меток безопасности объектов, не зависящих от политик. В настоящее время эта поддержка считается экспериментальной. + +Эта глава предоставляет информацию, предназначенную для разработчиков модулей политик, а также потенциальных пользователей сред с поддержкой MAC, чтобы узнать о том, как MAC Framework поддерживает расширение контроля доступа в ядре. + +[[mac-background]] +== Общие сведения о политиках + +Мандатное управление доступом (MAC — Mandatory Access Control) относится к набору политик контроля доступа, которые в обязательном порядке применяются операционной системой к пользователям. Политики MAC можно противопоставить защите на основе дискреционного управления доступом (DAC — Discretionary Access Control), при которой непривилегированные пользователи могут (по своему усмотрению) защищать объекты. В традиционных UNIX-системах защита DAC включает права доступа к файлам и списки контроля доступа; защита MAC включает управление процессами, предотвращающее отладку между пользователями, и межсетевые экраны. Различные политики MAC были разработаны создателями операционных систем и исследователями безопасности, включая политику конфиденциальности многоуровневой безопасности (MLS — Multi-Level Security), политику целостности Biba, управление доступом на основе ролей (RBAC — Role-Based Access Control), принудительное применение доменов и типов (DTE — Domain and Type Enforcement) и принудительное применение типов (TE — Type Enforcement). Каждая модель основывает решения на различных факторах, включая идентификатор пользователя, роль и уровень доступа, а также метки безопасности на объектах, представляющих такие концепции, как конфиденциальность и целостность данных. + +Фреймворк TrustedBSD MAC способен поддерживать модули политик, реализующие все эти политики, а также широкий класс политик усиления защиты системы, которые могут использовать существующие атрибуты безопасности, такие как идентификаторы пользователей и групп, а также расширенные атрибуты файлов и другие свойства системы. Кроме того, несмотря на название, фреймворк MAC также может использоваться для реализации чисто дискреционных политик, поскольку модулям политик предоставляется значительная гибкость в том, как они авторизуют защиту. + +[[mac-framework-kernel-arch]] +== Архитектура MAC Framework в ядре + +Фреймворк TrustedBSD MAC позволяет модулям ядра расширять политику безопасности операционной системы, а также предоставляет функциональность инфраструктуры, необходимую многим модулям контроля доступа. Если одновременно загружено несколько политик, фреймворк MAC полезным образом (в некотором смысле полезным) объединит результаты этих политик. + +[[mac-framework-kernel-arch-elements]] +=== Элементы ядра + +В рамках MAC Framework реализован ряд элементов ядра: + +* Интерфейсы управления фреймворком +* Параллелизм и примитивы синхронизации. +* Регистрация политики +* Расширяемая метка безопасности для объектов ядра +* Операторы композиции точки входа политики +* Примитивы управления метками +* Точка входа API, вызываемая службами ядра +* Точка входа API для модулей политик +* Реализации точек входа (жизненный цикл политики, жизненный цикл объекта/управление метками, проверки контроля доступа). +* Системные вызовы, независимые от политик, для управления метками +* `mac_syscall()` мультиплексный системный вызов +* Различные политики безопасности, реализованные в виде модулей политики MAC + +[[mac-framework-kernel-arch-management]] +=== Интерфейсы управления фреймворком + +Фреймворком TrustedBSD MAC можно напрямую управлять с помощью sysctl, параметров загрузчика и системных вызовов. + +В большинстве случаев одноимённые параметры sysctl и настройки загрузчика изменяют одни и те же параметры и управляют поведением, таким как применение защитных механизмов, связанных с различными подсистемами ядра. Кроме того, если в ядро включена поддержка отладки MAC, будет вестись несколько счётчиков для отслеживания выделения меток. Обычно рекомендуется не использовать общие настройки подсистем для управления поведением политик в рабочих средах, так как они широко влияют на работу всех активных политик. Вместо этого следует предпочитать настройки отдельных политик, поскольку они обеспечивают более высокую детализацию и большую операционную согласованность для модулей политик. + +Загрузка и выгрузка модулей политики выполняется с использованием системных вызовов управления модулями и других системных интерфейсов, включая переменные загрузчика; модули политики получат возможность влиять на события загрузки и выгрузки, включая предотвращение нежелательной выгрузки политики. + +[[mac-framework-kernel-arch-synchronization]] +=== Список политик параллелизма и синхронизации + +Поскольку набор активных политик может изменяться во время выполнения, а вызов точек входа не является атомарным, требуется синхронизация для предотвращения загрузки или выгрузки политик во время выполнения вызова точки входа, фиксируя набор активных политик на время выполнения. Это достигается с помощью счетчика занятости фреймворка: при входе в точку входа счетчик увеличивается; при выходе из нее — уменьшается. Пока счетчик занятости повышен, изменения списка политик запрещены, и потоки, пытающиеся изменить список политик, будут ждать, пока список не освободится. Счетчик занятости защищается мьютексом, а условная переменная используется для пробуждения потоков, ожидающих изменений списка политик. Побочным эффектом этой модели синхронизации является то, что рекурсивный вход в MAC Framework из модуля политики разрешен, хотя обычно не используется. + +Для снижения накладных расходов счётчика занятости используются различные оптимизации, включая избегание полной стоимости увеличения и уменьшения, если список пуст или содержит только статические записи (политики, загруженные до старта системы, которые нельзя выгрузить). Также предоставляется опция на этапе компиляции, которая предотвращает любые изменения в наборе загруженных политик во время выполнения, что устраняет затраты на блокировку мьютексов, связанные с поддержкой динамически загружаемых и выгружаемых политик, поскольку синхронизация больше не требуется. + +Поскольку MAC Framework не может блокировать некоторые точки входа, обычная блокировка сна не может быть использована; в результате попытка загрузки или выгрузки может блокироваться на значительное время, ожидая, пока фреймворк станет свободным. + +[[mac-framework-kernel-arch-label-synchronization]] +=== Синхронизация меток + +Поскольку к объектам ядра обычно может обращаться более одного потока одновременно, и допускается одновременный вход нескольких потоков в MAC Framework, хранение атрибутов безопасности, поддерживаемое MAC Framework, тщательно синхронизировано. Как правило, существующая синхронизация ядра для данных объектов ядра используется для защиты меток безопасности MAC Framework на объекте: например, метки MAC на сокетах защищаются с помощью существующего мьютекса сокета. Аналогично, семантика параллельного доступа обычно идентична семантике контейнерных объектов: для учетных данных поддерживается семантика копирования при записи для содержимого меток, как и для остальной структуры учетных данных. MAC Framework устанавливает необходимые блокировки на объекты при вызове с ссылкой на объект. Авторам политик необходимо учитывать эти семантики синхронизации, так как они иногда ограничивают типы доступа к меткам: например, когда ссылка только для чтения на учетные данные передается политике через точку входа, разрешены только операции чтения для состояния метки, прикрепленного к учетным данным. + +[[mac-framework-kernel-arch-policy-synchronization]] +=== Синхронизация политики и параллелизм + +Модули политик должны быть написаны с учетом того, что множество потоков ядра могут одновременно войти в одну или несколько точек входа политики из-за параллельной и вытесняющей природы ядра FreeBSD. Если модуль политики использует изменяемое состояние, это может потребовать применения примитивов синхронизации внутри политики, чтобы предотвратить несогласованные представления этого состояния, ведущие к некорректной работе политики. Политики, как правило, могут использовать существующие примитивы синхронизации FreeBSD для этой цели, включая мьютексы, блокировки с ожиданием, условные переменные и счётные семафоры. Однако политики должны быть написаны так, чтобы применять эти примитивы осторожно, соблюдая существующие порядки блокировок в ядре и учитывая, что некоторые точки входа не допускают ожидания, ограничивая использование примитивов в этих точках входа мьютексами и операциями пробуждения. + +Когда модули политики обращаются к другим подсистемам ядра, они обычно должны освобождать любые блокировки внутри политики, чтобы избежать нарушения порядка блокировок ядра или риска рекурсивных блокировок. Это позволит сохранить блокировки политики как конечные блокировки в глобальном порядке блокировок, помогая избежать взаимоблокировки. + +[[mac-framework-kernel-arch-registration]] +=== Регистрация политики + +Фреймворк MAC поддерживает два списка активных политик: статический список и динамический список. Списки отличаются только в отношении их семантики блокировки: для использования статического списка не требуется повышенный счетчик ссылок. Когда загружаются модули ядра, содержащие политики фреймворка MAC, модуль политики использует `SYSINIT` для вызова функции регистрации; когда модуль политики выгружается, `SYSINIT` аналогично вызывает функцию отмены регистрации. Регистрация может завершиться неудачей, если модуль политики загружается более одного раза, если для регистрации недостаточно ресурсов (например, политика может требовать маркировки, а доступного состояния маркировки может быть недостаточно), или другие предварительные условия политики могут не выполняться (некоторые политики могут быть загружены только до загрузки системы). Аналогично, отмена регистрации может завершиться неудачей, если политика помечена как невыгружаемая. + +[[mac-framework-kernel-arch-entrypoints]] +=== Точки входа + +Ядро взаимодействует с MAC Framework двумя способами: вызывает набор API для уведомления фреймворка о соответствующих событиях и предоставляет указатель на структуру меток, не зависящую от политики, в объектах, связанных с безопасностью. Указатель метки управляется MAC Framework через точки входа управления метками, что позволяет фреймворку предоставлять службу маркировки модулям политик с относительно минимальными изменениями в подсистеме ядра, управляющей объектом. Например, указатели меток были добавлены к процессам, учетным данным процессов, сокетам, каналам, vnode, Mbuf, сетевым интерфейсам, очередям сборки IP-пакетов и множеству других структур, связанных с безопасностью. Ядро также вызывает MAC Framework при принятии важных решений по безопасности, позволяя модулям политик дополнять эти решения на основе собственных критериев (включая, возможно, данные, хранящиеся в метках безопасности). Большинство этих критически важных решений по безопасности будут явными проверками контроля доступа; однако некоторые влияют на более общие функции принятия решений, такие как сопоставление пакетов для сокетов и переход меток при выполнении программы. + +[[mac-framework-kernel-arch-composition]] +=== Композиция политик + +Когда в ядро загружено более одного модуля политики одновременно, результаты работы модулей политики будут объединены фреймворком с использованием оператора композиции. Этот оператор в настоящее время жёстко закодирован и требует, чтобы все активные политики одобрили запрос для возврата успешного результата. Поскольку политики могут возвращать различные условия ошибки (успех, доступ запрещён, объект не существует, ...), оператор старшинства выбирает результирующую ошибку из набора ошибок, возвращаемых политиками. В общем случае, ошибки, указывающие на то, что объект не существует, будут предпочтительнее ошибок, указывающих на запрет доступа к объекту. Хотя не гарантируется, что результирующая композиция будет полезной или безопасной, мы обнаружили, что это так для многих полезных наборов политик. Например, традиционные доверенные системы часто поставляются с двумя или более политиками, использующими аналогичную композицию. + +[[mac-framework-kernel-arch-labels]] +=== Поддержка меток + +Поскольку многие интересные расширения контроля доступа зависят от меток безопасности объектов, MAC Framework предоставляет набор системных вызовов для управления метками, не зависящих от политик, охватывающих различные объекты, доступные пользователю. Общие типы меток включают идентификаторы разделов, метки конфиденциальности, метки целостности, отделы (compartment), домены, роли и типы. Под "не зависящими от политик" подразумевается, что модули политик могут полностью определять семантику метаданных, связанных с объектом. Модули политик участвуют в интернализации и экстернализации строковых меток, предоставляемых пользовательскими приложениями, и могут при необходимости предоставлять приложениям несколько элементов меток. + +Метки в памяти хранятся в `struct label`, выделяемой через slab-аллокатор. Эта структура состоит из массива фиксированной длины, содержащего объединения, каждое из которых хранит указатель `void *` и значение типа `long`. Политикам, регистрирующим хранилище меток, назначается идентификатор "слота", который может использоваться для разыменования хранилища меток. Семантика хранилища полностью определяется модулем политики: модулям предоставляется набор точек входа, связанных с жизненным циклом объектов ядра, включая инициализацию, связывание/создание и уничтожение. Используя эти интерфейсы, можно реализовать подсчёт ссылок и другие модели хранения. Прямой доступ к структуре объекта, как правило, не требуется модулям политики для получения метки, поскольку MAC Framework обычно передаёт в точки входа как указатель на объект, так и прямой указатель на метку объекта. Основным исключением из этого правила являются учётные данные процесса, для доступа к метке которых требуется ручное разыменование. Это может измениться в будущих версиях MAC Framework. + +Входные точки инициализации часто включают флаг режима сна, указывающий, разрешено ли инициализации переходить в режим сна; если сон не разрешен, может быть возвращена ошибка для отмены выделения метки (и, следовательно, объекта). Это может произойти, например, в сетевом стеке во время обработки прерывания, где сон не разрешен, или пока вызывающий удерживает мьютекс. Из-за затрат производительности на поддержание меток на передаваемых сетевых пакетах (Mbuf), политики должны явно объявлять требование о выделении меток для Mbuf. Динамически загружаемые политики, использующие метки, должны быть способны обрабатывать случай, когда их функция инициализации не была вызвана для объекта, так как объекты могут уже существовать при загрузке политики. MAC Framework гарантирует, что неинициализированные слоты меток будут содержать значение 0 или NULL, что политики могут использовать для обнаружения неинициализированных значений. Однако, поскольку выделение меток для Mbuf условно, политики также должны быть способны обрабатывать указатель на метку NULL для Mbuf, если они были загружены динамически. + +В случае меток файловых систем предусмотрена специальная поддержка для постоянного хранения меток безопасности в расширенных атрибутах. Там, где это возможно, используются транзакции расширенных атрибутов, чтобы обеспечить согласованные составные обновления меток безопасности на vnode — в настоящее время такая поддержка присутствует только в файловой системе UFS2. Авторы политик могут выбрать реализацию многометочных меток объектов файловой системы с использованием одного (или нескольких) расширенных атрибутов. По соображениям эффективности метка vnode (`v_label`) является кэшем любой метки на диске; политики могут загружать значения в кэш при создании vnode и обновлять кеш по мере необходимости. В результате нет необходимости напрямую обращаться к расширенному атрибуту при каждой проверке контроля доступа. + +[NOTE] +==== +В настоящее время, если помеченная политика разрешает динамическую выгрузку, её слот состояния не может быть освобождён, что накладывает строгое (и относительно низкое) ограничение на количество операций выгрузки-перезагрузки для помеченных политик. +==== + +[[mac-framework-kernel-arch-syscalls]] +=== Системные вызовы + +В рамках MAC Framework реализован ряд системных вызовов: большинство из них поддерживают API для получения и управления метками, не зависящий от политики и доступный пользовательским приложениям. + +Вызовы управления метками принимают структуру описания метки `struct mac`, которая содержит серию элементов метки MAC. Каждый элемент содержит строку с именем и строку со значением. Каждой политике будет предоставлена возможность запросить определённое имя элемента, позволяя политикам предоставлять несколько независимых элементов, если это необходимо. Модули политик выполняют интернализацию и экстернализацию между метками ядра и метками, предоставленными пользователем, через точки входа, что позволяет использовать различные семантики. Системные вызовы управления метками обычно обёрнуты в функции пользовательской библиотеки для выполнения выделения памяти и обработки ошибок, упрощая пользовательские приложения, которые должны управлять метками. + +В ядре FreeBSD есть следующие системные вызовы, связанные с MAC: + +* `mac_get_proc()` может использоваться для получения метки текущего процесса. +* `mac_set_proc()` может использоваться, чтобы запросить изменение метки текущего процесса. +* `mac_get_fd()` может использоваться для получения метки объекта (файл, сокет, канал, ...), на который ссылается файловый дескриптор. +* `mac_get_file()` может использоваться для получения метки объекта, на который ссылается путь в файловой системе. +* `mac_set_fd()` может использоваться для запроса изменения метки объекта (файл, сокет, канал, ...), на который ссылается файловый дескриптор. +* `mac_set_file()` может использоваться для запроса изменения метки объекта, указанного по пути в файловой системе. +* `mac_syscall()` позволяет модулям политик создавать новые системные вызовы без изменения таблицы системных вызовов; она принимает имя целевой политики, номер операции и непрозрачный аргумент для использования политикой. +* `mac_get_pid()` может использоваться для запроса метки другого процесса по его идентификатору. +* `mac_get_link()` идентична `mac_get_file()`, но не переходит по символической ссылке, если она является конечным элементом пути, поэтому может использоваться для получения метки на символьной ссылке. +* `mac_set_link()` идентична `mac_set_file()`, за исключением того, что она не следует по символической ссылке, если это конечный элемент пути, поэтому может использоваться для изменения метки на символьной ссылке. +* `mac_execve()` идентична системному вызову `execve()`, но также принимает запрошенную метку, которая будет установлена для процесса при начале выполнения новой программы. Это изменение метки при выполнении называется "переходом". +* `mac_get_peer()`, фактически реализованный через параметр сокета, извлекает метку удалённого узла на сокете, если она доступна. + +В дополнение к этим системным вызовам, сетевые ioctl-команды `SIOCSIGMAC` и `SIOCSIFMAC` позволяют получать и устанавливать метки на сетевых интерфейсах. + +[[mac-policy-architecture]] +== Архитектура политик MAC + +Политики безопасности либо непосредственно встроены в ядро, либо скомпилированы в загружаемые модули ядра, которые могут быть загружены при загрузке системы или динамически с использованием системных вызовов загрузки модулей во время выполнения. Модули политик взаимодействуют с системой через набор объявленных точек входа, предоставляя доступ к потоку системных событий и позволяя политике влиять на решения контроля доступа. Каждая политика содержит ряд элементов: + +* Необязательные параметры конфигурации для политики. +* Централизованная реализация логики политики и параметров. +* Необязательная реализация событий жизненного цикла политики, таких как инициализация и уничтожение. +* Необязательная поддержка инициализации, обслуживания и удаления меток на выбранных объектах ядра. +* Дополнительная поддержка проверки процессов пользователя и изменения меток на выбранных объектах. +* Реализация выбранных точек входа контроля доступа, представляющих интерес для политики. +* Объявление идентификатора политики, точек входа модуля и свойств политики. + +[[mac-policy-declaration]] +=== Объявление политики + +Модули могут быть объявлены с использованием макроса `MAC_POLICY_SET()`, который задаёт имя политики, предоставляет ссылку на вектор точек входа MAC, указывает флаги загрузки, определяющие, как фреймворк политик должен обрабатывать политику, и при необходимости запрашивает выделение состояния метки фреймворком. + +[.programlisting] +.... +static struct mac_policy_ops mac_policy_ops = +{ + .mpo_destroy = mac_policy_destroy, + .mpo_init = mac_policy_init, + .mpo_init_bpfdesc_label = mac_policy_init_bpfdesc_label, + .mpo_init_cred_label = mac_policy_init_label, +/* ... */ + .mpo_check_vnode_setutimes = mac_policy_check_vnode_setutimes, + .mpo_check_vnode_stat = mac_policy_check_vnode_stat, + .mpo_check_vnode_write = mac_policy_check_vnode_write, +}; +.... + +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. + +Поле имени модуля в объявлении политики существует для того, чтобы модуль мог быть однозначно идентифицирован с целью управления зависимостями модулей. Следует выбрать подходящую строку. Полное имя политики отображается пользователю в журнале ядра при загрузке и выгрузке, а также экспортируется при предоставлении информации о статусе процессам в пользовательском пространстве. + +[[mac-policy-flags]] +=== Флаги политик + +Поле флагов объявления политики позволяет модулю предоставлять фреймворку информацию о своих возможностях во время загрузки модуля. В настоящее время определены три флага: + +MPC_LOADTIME_FLAG_UNLOADOK:: +Этот флаг указывает, что модуль политики может быть выгружен. Если этот флаг не указан, то фреймворк политики отклонит запросы на выгрузку модуля. Этот флаг может использоваться модулями, которые выделяют состояние метки и не могут освободить это состояние во время выполнения. + +MPC_LOADTIME_FLAG_NOTLATE:: +Этот флаг указывает, что модуль политики должен быть загружен и инициализирован на раннем этапе процесса загрузки. Если флаг указан, попытки зарегистрировать модуль после загрузки будут отклонены. Флаг может использоваться политиками, которые требуют повсеместной маркировки всех системных объектов и не могут обрабатывать объекты, не прошедшие надлежащую инициализацию политикой. + +MPC_LOADTIME_FLAG_LABELMBUFS:: +Этот флаг указывает, что модуль политики требует маркировки Mbuf, и память всегда должна выделяться для хранения меток Mbuf. По умолчанию MAC Framework не выделяет память для хранения меток Mbuf, если хотя бы одна загруженная политика не установила этот флаг. Это заметно улучшает производительность сети, когда политики не требуют маркировки Mbuf. Существует опция ядра `MAC_ALWAYS_LABEL_MBUF`, которая заставляет MAC Framework выделять память для хранения меток Mbuf независимо от установки этого флага, и может быть полезной в некоторых средах. + +[NOTE] +==== +Политики, использующие `MPC_LOADTIME_FLAG_LABELMBUFS` без установленного флага `MPC_LOADTIME_FLAG_NOTLATE`, должны корректно обрабатывать переданные `NULL` указатели меток Mbuf в точках входа. Это необходимо, так как Mbuf в процессе передачи без хранилища меток могут сохраняться после загрузки политики, включающей маркировку Mbuf. Если политика загружена до активации сетевой подсистемы (т.е. политика не загружается поздно), то все Mbuf гарантированно имеют хранилище меток. +==== + +[[mac-policy-entry-points]] +=== Точки входа политики + +Четыре класса точек входа предоставляются политикам, зарегистрированным в рамках системы: точки входа, связанные с регистрацией и управлением политиками, точки входа, обозначающие инициализацию, создание, уничтожение и другие события жизненного цикла объектов ядра, события, связанные с решениями контроля доступа, на которые политика может влиять, и вызовы, связанные с управлением метками на объектах. Кроме того, предоставляется точка входа `mac_syscall()`, позволяющая политикам расширять интерфейс ядра без регистрации новых системных вызовов. + +Авторы модулей политик должны быть осведомлены о стратегии блокировок в ядре, а также о том, какие блокировки объектов доступны на различных точках входа. Им следует избегать сценариев взаимоблокировок, не захватывая нелистовые блокировки внутри точек входа, а также соблюдать протокол блокировок для доступа и изменения объектов. В частности, авторы должны учитывать, что хотя необходимые блокировки для доступа к объектам и их меткам обычно удерживаются, достаточные блокировки для изменения объекта или его метки могут отсутствовать для всех точек входа. Информация о блокировках аргументов документирована в описании точек входа фреймворка MAC. + +Точки входа политики будут передавать ссылку на метку объекта вместе с самим объектом. Это позволяет помеченным политикам не знать внутренней структуры объекта, но при этом принимать решения на основе метки. Исключением из этого являются учетные данные процесса, для которые предполагается, что политики понимают их, как объект безопасности первого класса в ядре. + +[[mac-entry-point-reference]] +== Справочник по точкам входа политики MAC + +[[mac-mpo-general]] +=== Общие точки входа модуля + +[[mac-mpo-init]] +==== `mpo_init` + +[source, c] +---- +void mpo_init(struct mac_policy_conf *conf); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`conf` +|Определение политики MAC +| +|=== + +Событие загрузки политики. Мьютекс списка политик удерживается, поэтому операции ожидания выполнить нельзя, а вызовы других подсистем ядра должны осуществляться с осторожностью. Если во время инициализации политики требуются потенциально блокирующие выделения памяти, их следует выполнять с использованием отдельного модуля SYSINIT(). + +[[mpo-destroy]] +==== `mpo_destroy` + +[source, c] +---- +void mpo_destroy(struct mac_policy_conf *conf); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`conf` +|Определение политики MAC +| +|=== + +Событие загрузки политики. Мьютекс списка политик удерживается, поэтому следует соблюдать осторожность. + +[[mac-mpo-syscall]] +==== `mpo_syscall` + +[source, c] +---- +int mpo_syscall(struct thread *td, int call, void *arg); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`td` +|Вызывающий поток +| + +|`call` +|Номер системного вызова, зависящий от политики +| + +|`arg` +|Указатель на аргументы системного вызова +| +|=== + +Этот точку входа предоставляет мультиплексированный системный вызов на основе политик, что позволяет политикам предоставлять дополнительные сервисы пользовательским процессам без регистрации конкретных системных вызовов. Имя политики, указанное при регистрации, используется для демультиплексирования вызовов из пользовательского пространства, а аргументы будут переданы в эту точку входа. При реализации новых сервисов модули безопасности должны убедиться, что вызывают соответствующие проверки контроля доступа из MAC-фреймворка по мере необходимости. Например, если политика реализует расширенную функциональность сигналов, она должна вызывать необходимые проверки контроля доступа сигналов для задействования MAC-фреймворка и других зарегистрированных политик. + +[NOTE] +==== +Модули в настоящее время должны самостоятельно выполнять `copyin()` для данных системного вызова. +==== + +[[mac-mpo-thread-userret]] +==== `mpo_thread_userret` + +[source, c] +---- +void mpo_thread_userret(struct thread *td); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`td` +|Возвращающий поток +| +|=== + +Этот точка входа позволяет модулям политики выполнять события, связанные с MAC, когда поток возвращается в пользовательское пространство, через возврат системного вызова, возврат из ловушки или иным образом. Это необходимо для политик, имеющих плавающие метки процессов, так как не всегда возможно получить блокировку процесса в произвольных точках стека во время обработки системного вызова; метки процессов могут представлять традиционные данные аутентификации, информацию об истории процесса или другие данные. Для использования этого механизма предполагаемые изменения метки учётных данных процесса могут быть сохранены в `p_label`, защищённом спин-блокировкой для каждой политики, а затем установить флаг `TDF_ASTPENDING` для потока и флаг `PS_MACPENDM` для процесса, чтобы запланировать вызов точки входа `userret`. С этой точки входа политика может создать замену учётных данных с меньшими опасениями относительно контекста блокировки. Авторам политик следует учитывать, что порядок событий, связанных с планированием AST и выполнением AST, может быть сложным и переплетённым в многопоточных приложениях. + +[[mac-label-ops]] +=== Операции с метками + +[[mac-mpo-init-bpfdesc]] +==== `mpo_init_bpfdesc_label` + +[source, c] +---- +void mpo_init_bpfdesc_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Новая метка для инициализации +| +|=== + +Инициализировать метку на только что созданном bpfdesc (дескрипторе BPF). Разрешено использование режима сна. + +[[mac-mpo-init-cred-label]] +==== `mpo_init_cred_label` + +[source, c] +---- +void mpo_init_cred_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Новая метка для инициализации +| +|=== + +Инициализировать метку для вновь созданных учетных данных пользователя. Разрешено приостанавливать выполнение. + +[[mac-mpo-init-devfsdirent]] +==== `mpo_init_devfsdirent_label` + +[source, c] +---- +void mpo_init_devfsdirent_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Новая метка для инициализации +| +|=== + +Инициализировать метку на только что созданной записи devfs. Разрешено использование режима сна. + +[[mac-mpo-init-ifnet]] +==== `mpo_init_ifnet_label` + +[source, c] +---- +void mpo_init_ifnet_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Новая метка для инициализации +| +|=== + +Инициализировать метку на только что созданном сетевом интерфейсе. Разрешено приостанавливать выполнение. + +[[mac-mpo-init-ipq]] +==== `mpo_init_ipq_label` + +[source, c] +---- +void mpo_init_ipq_label(struct label *label, int flag); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Новая метка для инициализации +| + +|`flag` +|Спящий/неспящий man:malloc[9]; см. ниже +| +|=== + +Инициализировать метку в только что созданной очереди сборки IP-фрагментов. Поле `flag` может принимать одно из значений M_WAITOK или M_NOWAIT и должно использоваться, чтобы избежать выполнения "спящего" man:malloc[9] во время этого вызова инициализации. Выделение очереди сборки IP-фрагментов часто происходит в средах, чувствительных к производительности, и реализация должна избегать "спящих" или длительных операций. Этой точке входа разрешено завершаться неудачей, что приведёт к невозможности выделения очереди сборки IP-фрагментов. + +[[mac-mpo-init-mbuf]] +==== `mpo_init_mbuf_label` + +[source, c] +---- +void mpo_init_mbuf_label(int flag, struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`flag` +|Спящий/неспящий man:malloc[9]; см. ниже +| + +|`label` +|Метка политики для инициализации +| +|=== + +Инициализировать на только что созданном заголовке пакета mbuf метку (`mbuf`). Поле `flag` может принимать одно из значений M_WAITOK или M_NOWAIT и должно использоваться, чтобы избежать выполнения "спящего" man:malloc[9] во время этого вызова инициализации. Выделение mbuf часто происходит в чувствительных к производительности средах, и реализация должна избегать "спящего" режима или длительных операций. Этой точке входа разрешено завершаться неудачей, что приведёт к невозможности выделения заголовка mbuf. + +[[mac-mpo-init-mount]] +==== `mpo_init_mount_label` + +[source, c] +---- +void mpo_init_mount_label(struct label *mntlabel, struct label *fslabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`mntlabel` +|Метка политики для инициализации самой точки монтирования +| + +|`fslabel` +|Метка политики для инициализации файловой системы +| +|=== + +Инициализировать метки на новой точке монтирования. Разрешено приостанавливать выполнение. + +[[mac-mpo-init-mount-fs-label]] +==== `mpo_init_mount_fs_label` + +[source, c] +---- +void mpo_init_mount_fs_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для инициализации +| +|=== + +Инициализировать метку на только что смонтированной файловой системе. Разрешено приостановление работы + +[[mac-mpo-init-pipe-label]] +==== `mpo_init_pipe_label` + +[source, c] +---- +void mpo_init_pipe_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для заполнения +| +|=== + +Инициализировать метку для только что созданного канала. Разрешено приостановление выполнения. + +[[mac-mpo-init-socket]] +==== `mpo_init_socket_label` + +[source, c] +---- +void mpo_init_socket_label(struct label *label, int flag); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Новая метка для инициализации +| + +|`flag` +|флаги man:malloc[9] +| +|=== + +Инициализировать метку для нового сокета. Поле `flag` может принимать одно из значений M_WAITOK или M_NOWAIT и должно использоваться, чтобы избежать выполнения спящего man:malloc[9] во время этого вызова инициализации. + +[[mac-mpo-init-socket-peer-label]] +==== `mpo_init_socket_peer_label` + +[source, c] +---- +void mpo_init_socket_peer_label(struct label *label, int flag); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Новая метка для инициализации +| + +|`flag` +|флаги man:malloc[9] +| +|=== + +Инициализировать метку однорангового узла (peer) для вновь созданного сокета. Поле `flag` может принимать одно из значений M_WAITOK или M_NOWAIT и должно использоваться для избежания выполнения спящего man:malloc[9] во время этого вызова инициализации. + +[[mac-mpo-init-proc-label]] +==== `mpo_init_proc_label` + +[source, c] +---- +void mpo_init_proc_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Новая метка для инициализации +| +|=== + +Инициализировать метку для вновь созданного процесса. Разрешено приостановление выполнения. + +[[mac-mpo-init-vnode]] +==== `mpo_init_vnode_label` + +[source, c] +---- +void mpo_init_vnode_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Новая метка для инициализации +| +|=== + +Инициализировать метку на только что созданном vnode. Разрешено приостанавливать выполнение. + +[[mac-mpo-destroy-bpfdesc]] +==== `mpo_destroy_bpfdesc_label` + +[source, c] +---- +void mpo_destroy_bpfdesc_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|bpfdesc label +| +|=== + +Уничтожить метку на дескрипторе BPF. В этой точке входа политика должна освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно было уничтожить. + +[[mac-mpo-destroy-cred]] +==== `mpo_destroy_cred_label` + +[source, c] +---- +void mpo_destroy_cred_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка уничтожается +| +|=== + +Уничтожить метку на учетных данных. В этой точке входа модуль политики должен освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно было уничтожить. + +[[mac-mpo-destroy-devfsdirent]] +==== `mpo_destroy_devfsdirent_label` + +[source, c] +---- +void mpo_destroy_devfsdirent_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка уничтожается +| +|=== + +Уничтожить метку на записи devfs. В этой точке входа модуль политики должен освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно было уничтожить. + +[[mac-mpo-destroy-ifnet-label]] +==== `mpo_destroy_ifnet_label` + +[source, c] +---- +void mpo_destroy_ifnet_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка уничтожается +| +|=== + +Уничтожить метку на удаленном интерфейсе. В этой точке входа модуль политики должен освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно было уничтожить. + +[[mac-mpo-destroy-ipq-label]] +==== `mpo_destroy_ipq_label` + +[source, c] +---- +void mpo_destroy_ipq_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка уничтожается +| +|=== + +Уничтожить метку в очереди IP-фрагментов. В этой точке входа модуль политики должен освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно было уничтожить. + +[[mac-mpo-destroy-mbuf-label]] +==== `mpo_destroy_mbuf_label` + +[source, c] +---- +void mpo_destroy_mbuf_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка уничтожается +| +|=== + +Уничтожить метку в заголовке mbuf. В этой точке входа модуль политики должен освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно было уничтожить. + +[[mac-mpo-destroy-mount-label]] +==== `mpo_destroy_mount_label` + +[source, c] +---- +void mpo_destroy_mount_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Точка монтирования метки уничтожается +| +|=== + +Уничтожить метки на точке монтирования. В этой точке входа модуль политики должен освободить внутреннее хранилище, связанное с `mntlabel`, чтобы ее можно было уничтожить. + +[[mac-mpo-destroy-mount]] +==== `mpo_destroy_mount_label` + +[source, c] +---- +void mpo_destroy_mount_label(struct label *mntlabel, struct label *fslabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`mntlabel` +|Точка монтирования метки уничтожается +| + +|`fslabel` +|Метка файловой системы уничтожается +| +|=== + +Уничтожить метки на точке монтирования. В этой точке входа модуль политики должен освободить внутреннее хранилище, связанное с `mntlabel` и `fslabel`, чтобы их можно было уничтожить. + +[[mac-mpo-destroy-socket]] +==== `mpo_destroy_socket_label` + +[source, c] +---- +void mpo_destroy_socket_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Уничтожение метки сокета +| +|=== + +Уничтожить метку на сокете. В этой точке входа модуль политики должен освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно было уничтожить. + +[[mac-mpo-destroy-socket-peer-label]] +==== `mpo_destroy_socket_peer_label` + +[source, c] +---- +void mpo_destroy_socket_peer_label(struct label *peerlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`peerlabel` +|Сокет: метка однорангового узла уничтожается +| +|=== + +Уничтожить метку однорангового узла на сокете. В этой точке входа модуль политики должен освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно было уничтожить. + +[[mac-mpo-destroy-pipe-label]] +==== `mpo_destroy_pipe_label` + +[source, c] +---- +void mpo_destroy_pipe_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка канала (pipe) +| +|=== + +Уничтожить метку на канале. В этой точке входа модуль политики должен освободить всю внутреннюю память, связанную с `label`, чтобы её можно было уничтожить. + +[[mac-mpo-destroy-proc-label]] +==== `mpo_destroy_proc_label` + +[source, c] +---- +void mpo_destroy_proc_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка процесса +| +|=== + +Уничтожить метку на процессе. В этой точке входа модуль политики должен освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно было уничтожить. + +[[mac-mpo-destroy-vnode-label]] +==== `mpo_destroy_vnode_label` + +[source, c] +---- +void mpo_destroy_vnode_label(struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка процесса +| +|=== + +Уничтожить метку на vnode. В этой точке входа модуль политики должен освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно было уничтожить. + +[[mac-mpo-copy-mbuf-label]] +==== `mpo_copy_mbuf_label` + +[source, c] +---- +void mpo_copy_mbuf_label(struct label *src, struct label *dest); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`src` +|Метка источника +| + +|`dest` +|Метка назначения +| +|=== + +Скопировать информацию метки из `src` в `dest`. + +[[mac-mpo-copy-pipe-label]] +==== `mpo_copy_pipe_label` + +[source, c] +---- +void mpo_copy_pipe_label(struct label *src, struct label *dest); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`src` +|Метка источника +| + +|`dest` +|Метка назначения +| +|=== + +Скопировать информацию метки из `src` в `dest`. + +[[mac-mpo-copy-vnode-label]] +==== `mpo_copy_vnode_label` + +[source, c] +---- +void mpo_copy_vnode_label(struct label *src, struct label *dest); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`src` +|Метка источника +| + +|`dest` +|Метка назначения +| +|=== + +Скопировать информацию метки из `src` в `dest`. + +[[mac-mpo-externalize-cred-label]] +==== `mpo_externalize_cred_label` + +[source, c] +---- +int mpo_externalize_cred_label(struct label *label, char *element_name, + struct sbuf *sb, int *claimed); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для вынесения во внешний ресурс +| + +|`element_name` +|Имя политики, метка которой должна быть вынесена во внешний ресурс +| + +|`sb` +|Буфер строки для заполнения текстовым представлением метки +| + +|`claimed` +|Должно быть увеличено, когда `element_data` может быть заполнено. +| +|=== + +Создать внешнее представление метки на основе переданной структуры метки. Внешнее представление метки состоит из текстового представления содержимого метки, которое может использоваться пользовательскими приложениями и прочитано пользователем. В настоящее время будут вызываться точки входа `externalize` всех политик, поэтому реализация должна проверить содержимое `element_name` перед попыткой заполнить `sb`. Если `element_name` не соответствует имени вашей политики, просто верните 0. Возвращайте ненулевое значение только в случае ошибки при внешнем представлении данных метки. После того как политика заполнит `element_data`, `*claimed` должен быть увеличен. + +[[mac-mpo-externalize-ifnet-label]] +==== `mpo_externalize_ifnet_label` + +[source, c] +---- +int mpo_externalize_ifnet_label(struct label *label, char *element_name, + struct sbuf *sb, int *claimed); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для вынесения во внешний ресурс +| + +|`element_name` +|Имя политики, метка которой должна быть вынесена во внешний ресурс +| + +|`sb` +|Буфер строки для заполнения текстовым представлением метки +| + +|`claimed` +|Должно быть увеличено, когда `element_data` может быть заполнено. +| +|=== + +Создать внешнее представление метки на основе переданной структуры метки. Внешнее представление метки состоит из текстового представления содержимого метки, которое может использоваться пользовательскими приложениями и прочитано пользователем. В настоящее время будут вызываться точки входа `externalize` всех политик, поэтому реализация должна проверить содержимое `element_name` перед попыткой заполнить `sb`. Если `element_name` не соответствует имени вашей политики, просто верните 0. Возвращайте ненулевое значение только в случае ошибки при внешнем представлении данных метки. После того как политика заполнит `element_data`, `*claimed` должен быть увеличен. + +[[mac-mpo-externalize-pipe-label]] +==== `mpo_externalize_pipe_label` + +[source, c] +---- +int mpo_externalize_pipe_label(struct label *label, char *element_name, + struct sbuf *sb, int *claimed); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для вынесения во внешний ресурс +| + +|`element_name` +|Имя политики, метка которой должна быть вынесена во внешний ресурс +| + +|`sb` +|Буфер строки для заполнения текстовым представлением метки +| + +|`claimed` +|Должно быть увеличено, когда `element_data` может быть заполнено. +| +|=== + +Создать внешнее представление метки на основе переданной структуры метки. Внешнее представление метки состоит из текстового представления содержимого метки, которое может использоваться пользовательскими приложениями и прочитано пользователем. В настоящее время будут вызываться точки входа `externalize` всех политик, поэтому реализация должна проверить содержимое `element_name` перед попыткой заполнить `sb`. Если `element_name` не соответствует имени вашей политики, просто верните 0. Возвращайте ненулевое значение только в случае ошибки при внешнем представлении данных метки. После того как политика заполнит `element_data`, `*claimed` должен быть увеличен. + +[[mac-mpo-externalize-socket-label]] +==== `mpo_externalize_socket_label` + +[source, c] +---- +int mpo_externalize_socket_label(struct label *label, char *element_name, + struct sbuf *sb, int *claimed); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для вынесения во внешний ресурс +| + +|`element_name` +|Имя политики, метка которой должна быть вынесена во внешний ресурс +| + +|`sb` +|Буфер строки для заполнения текстовым представлением метки +| + +|`claimed` +|Должно быть увеличено, когда `element_data` может быть заполнено. +| +|=== + +Создать внешнее представление метки на основе переданной структуры метки. Внешнее представление метки состоит из текстового представления содержимого метки, которое может использоваться пользовательскими приложениями и прочитано пользователем. В настоящее время будут вызываться точки входа `externalize` всех политик, поэтому реализация должна проверить содержимое `element_name` перед попыткой заполнить `sb`. Если `element_name` не соответствует имени вашей политики, просто верните 0. Возвращайте ненулевое значение только в случае ошибки при внешнем представлении данных метки. После того как политика заполнит `element_data`, `*claimed` должен быть увеличен. + +[[mac-mpo-externalize-socket-peer-label]] +==== `mpo_externalize_socket_peer_label` + +[source, c] +---- +int mpo_externalize_socket_peer_label(struct label *label, char *element_name, + struct sbuf *sb, int *claimed); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для вынесения во внешний ресурс +| + +|`element_name` +|Имя политики, метка которой должна быть вынесена во внешний ресурс +| + +|`sb` +|Буфер строки для заполнения текстовым представлением метки +| + +|`claimed` +|Должно быть увеличено, когда `element_data` может быть заполнено. +| +|=== + +Создать внешнее представление метки на основе переданной структуры метки. Внешнее представление метки состоит из текстового представления содержимого метки, которое может использоваться пользовательскими приложениями и прочитано пользователем. В настоящее время будут вызываться точки входа `externalize` всех политик, поэтому реализация должна проверить содержимое `element_name` перед попыткой заполнить `sb`. Если `element_name` не соответствует имени вашей политики, просто верните 0. Возвращайте ненулевое значение только в случае ошибки при внешнем представлении данных метки. После того как политика заполнит `element_data`, `*claimed` должен быть увеличен. + +[[mac-mpo-externalize-vnode-label]] +==== `mpo_externalize_vnode_label` + +[source, c] +---- +int mpo_externalize_vnode_label(struct label *label, char *element_name, + struct sbuf *sb, int *claimed); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для вынесения во внешний ресурс +| + +|`element_name` +|Имя политики, метка которой должна быть вынесена во внешний ресурс +| + +|`sb` +|Буфер строки для заполнения текстовым представлением метки +| + +|`claimed` +|Должно быть увеличено, когда `element_data` может быть заполнено. +| +|=== + +Создать внешнее представление метки на основе переданной структуры метки. Внешнее представление метки состоит из текстового представления содержимого метки, которое может использоваться пользовательскими приложениями и прочитано пользователем. В настоящее время будут вызываться точки входа `externalize` всех политик, поэтому реализация должна проверить содержимое `element_name` перед попыткой заполнить `sb`. Если `element_name` не соответствует имени вашей политики, просто верните 0. Возвращайте ненулевое значение только в случае ошибки при внешнем представлении данных метки. После того как политика заполнит `element_data`, `*claimed` должен быть увеличен. + +[[mac-mpo-internalize-cred-label]] +==== `mpo_internalize_cred_label` + +[source, c] +---- +int mpo_internalize_cred_label(struct label *label, char *element_name, + char *element_data, int *claimed); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для заполнения +| + +|`element_name` +|Имя политики, метка которой должна быть приведена к внутреннему представлению +| + +|`element_data` +|Текстовые данные для преобразования к внутреннему представлению +| + +|`claimed` +|Должно увеличиваться, когда данные могут быть успешно преобразовываться вовнутреннее представление. +| +|=== + +Создать внутреннюю структуру меток на основе данных метки вов нешнем представлении в текстовом формате. В настоящее время, при запросе преобразования во внутреннее представление вызываются точки входа `internalize` всех политик, поэтому реализация должна сравнивать содержимое `element_name` со своим именем, чтобы убедиться, что она должна преобразовывать данные в `element_data`. Как и в точках входа `externalize`, точка входа должна возвращать 0, если `element_name` не совпадает с её собственным именем, или когда данные могут быть успешно преобразованы, в этом случае `*claimed` должен быть увеличен. + +[[mac-mpo-internalize-ifnet-label]] +==== `mpo_internalize_ifnet_label` + +[source, c] +---- +int mpo_internalize_ifnet_label(struct label *label, char *element_name, + char *element_data, int *claimed); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для заполнения +| + +|`element_name` +|Имя политики, метка которой должна быть приведена к внутреннему представлению +| + +|`element_data` +|Текстовые данные для преобразования к внутреннему представлению +| + +|`claimed` +|Должно увеличиваться, когда данные могут быть успешно преобразовываться вовнутреннее представление. +| +|=== + +Создать внутреннюю структуру меток на основе данных метки вов нешнем представлении в текстовом формате. В настоящее время, при запросе преобразования во внутреннее представление вызываются точки входа `internalize` всех политик, поэтому реализация должна сравнивать содержимое `element_name` со своим именем, чтобы убедиться, что она должна преобразовывать данные в `element_data`. Как и в точках входа `externalize`, точка входа должна возвращать 0, если `element_name` не совпадает с её собственным именем, или когда данные могут быть успешно преобразованы, в этом случае `*claimed` должен быть увеличен. + +[[mac-mpo-internalize-pipe-label]] +==== `mpo_internalize_pipe_label` + +[source, c] +---- +int mpo_internalize_pipe_label(struct label *label, char *element_name, + char *element_data, int *claimed); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для заполнения +| + +|`element_name` +|Имя политики, метка которой должна быть приведена к внутреннему представлению +| + +|`element_data` +|Текстовые данные для преобразования к внутреннему представлению +| + +|`claimed` +|Должно увеличиваться, когда данные могут быть успешно преобразовываться вовнутреннее представление. +| +|=== + +Создать внутреннюю структуру меток на основе данных метки вов нешнем представлении в текстовом формате. В настоящее время, при запросе преобразования во внутреннее представление вызываются точки входа `internalize` всех политик, поэтому реализация должна сравнивать содержимое `element_name` со своим именем, чтобы убедиться, что она должна преобразовывать данные в `element_data`. Как и в точках входа `externalize`, точка входа должна возвращать 0, если `element_name` не совпадает с её собственным именем, или когда данные могут быть успешно преобразованы, в этом случае `*claimed` должен быть увеличен. + +[[mac-mpo-internalize-socket-label]] +==== `mpo_internalize_socket_label` + +[source, c] +---- +int mpo_internalize_socket_label(struct label *label, char *element_name, + char *element_data, int *claimed); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для заполнения +| + +|`element_name` +|Имя политики, метка которой должна быть приведена к внутреннему представлению +| + +|`element_data` +|Текстовые данные для преобразования к внутреннему представлению +| + +|`claimed` +|Должно увеличиваться, когда данные могут быть успешно преобразовываться вовнутреннее представление. +| +|=== + +Создать внутреннюю структуру меток на основе данных метки вов нешнем представлении в текстовом формате. В настоящее время, при запросе преобразования во внутреннее представление вызываются точки входа `internalize` всех политик, поэтому реализация должна сравнивать содержимое `element_name` со своим именем, чтобы убедиться, что она должна преобразовывать данные в `element_data`. Как и в точках входа `externalize`, точка входа должна возвращать 0, если `element_name` не совпадает с её собственным именем, или когда данные могут быть успешно преобразованы, в этом случае `*claimed` должен быть увеличен. + +[[mac-mpo-internalize-vnode-label]] +==== `mpo_internalize_vnode_label` + +[source, c] +---- +int mpo_internalize_vnode_label(struct label *label, char *element_name, + char *element_data, int *claimed); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`label` +|Метка для заполнения +| + +|`element_name` +|Имя политики, метка которой должна быть приведена к внутреннему представлению +| + +|`element_data` +|Текстовые данные для преобразования к внутреннему представлению +| + +|`claimed` +|Должно увеличиваться, когда данные могут быть успешно преобразовываться вовнутреннее представление. +| +|=== + +Создать внутреннюю структуру меток на основе данных метки вов нешнем представлении в текстовом формате. В настоящее время, при запросе преобразования во внутреннее представление вызываются точки входа `internalize` всех политик, поэтому реализация должна сравнивать содержимое `element_name` со своим именем, чтобы убедиться, что она должна преобразовывать данные в `element_data`. Как и в точках входа `externalize`, точка входа должна возвращать 0, если `element_name` не совпадает с её собственным именем, или когда данные могут быть успешно преобразованы, в этом случае `*claimed` должен быть увеличен. + +[[mac-label-events]] +=== События метки + +Этот класс точек входа используется фреймворком MAC для разрешения политикам поддерживать информацию о метках на объектах ядра. Для каждого помеченного объекта ядра, представляющего интерес для политики MAC, могут быть зарегистрированы точки входа для соответствующих событий жизненного цикла. Все объекты реализуют хуки инициализации, создания и уничтожения. Некоторые объекты также реализуют перемаркировку, позволяя пользовательским процессам изменять метки на объектах. Некоторые объекты также реализуют специфичные для объекта события, такие как события меток, связанные с повторной сборкой IP. Типичный помеченный объект будет иметь следующий жизненный цикл точек входа: + +[.programlisting] +.... +Label initialization o +(object-specific wait) \ +Label creation o + \ +Relabel events, o--<--. +Various object-specific, | | +Access control events ~-->--o + \ +Label destruction o +.... + +Инициализация меток позволяет политикам выделять память и устанавливать начальные значения для меток без контекста использования объекта. Слот метки, выделенный для политики, по умолчанию будет обнулен, поэтому некоторым политикам может не потребоваться выполнять инициализацию. + +Создание метки происходит, когда структура ядра связывается с реальным объектом ядра. Например, Mbuf могут быть выделены и оставаться неиспользованными в пуле до тех пор, пока они не понадобятся. Выделение mbuf приводит к инициализации метки на mbuf, но создание mbuf происходит, когда mbuf связывается с датаграммой. Обычно для события создания предоставляется контекст, включая обстоятельства создания и метки других значимых объектов в процессе создания. Например, когда mbuf создаётся из сокета, сокет и его метка будут переданы зарегистрированным политикам в дополнение к новому mbuf и его метке. Выделение памяти в событиях создания не рекомендуется, так как это может происходить в чувствительных к производительности участках ядра; кроме того, вызовы создания не могут завершиться неудачей, поэтому невозможность выделить память не может быть сообщена. + +События, привящанные к объектам, обычно не попадают в другие классы событий меток, но, как правило, предоставляют возможность изменить или обновить метку объекта на основе дополнительного контекста. Например, метка в очереди сборки IP-фрагментов может быть обновлена во время точки входа `MAC_UPDATE_IPQ` в результате принятия дополнительного mbuf в эту очередь. + +События контроля доступа подробно рассматриваются в следующем разделе. + +Уничтожение метки позволяет политикам освобождать хранилище или состояние, связанное с меткой во время её ассоциации с объектом, чтобы структуры данных ядра, поддерживающие объект, могли быть повторно использованы или освобождены. + +В дополнение к меткам, связанным с определёнными объектами ядра, существует дополнительный класс меток: временные метки. Эти метки используются для хранения информации об обновлениях, отправляемых пользовательскими процессами. Они инициализируются и уничтожаются так же, как и другие типы меток, но событие создания — это `MAC_INTERNALIZE`, которое принимает пользовательскую метку для преобразования во внутреннее представление в ядре. + +[[mac-fs-label-event-ops]] +==== Действия с событиями меток объектов файловой системы + +[[mac-mpo-associate-vnode-devfs]] +===== `mpo_associate_vnode_devfs` + +[source, c] +---- +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] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`mp` +|Точка монтирования devfs +| + +|`fslabel` +|Метка файловой системы devfs (`mp->mnt_fslabel`) +| + +|`de` +|Запись каталога devfs +| + +|`delabel` +|Метка политики, связанная с `de` +| + +|`vp` +|узел vnode, связанный с `de` +| + +|`vlabel` +|Метка политики, связанная с `vp` +| +|=== + +Заполнить метку (`vlabel`) для только что созданного devfs vnode на основе записи каталога devfs, переданной в `de`, и её метки. + +[[mac-mpo-associate-vnode-extattr]] +===== `mpo_associate_vnode_extattr` + +[source, c] +---- +int mpo_associate_vnode_extattr(struct mount *mp, struct label *fslabel, + struct vnode *vp, struct label *vlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`mp` +|Точка монтирования файловой системы +| + +|`fslabel` +|Метка файловой системы +| + +|`vp` +|Узел vnode для метки +| + +|`vlabel` +|Метка политики, связанная с `vp` +| +|=== + +Попытка получить метку для `vp` из расширенных атрибутов файловой системы. В случае успеха возвращается значение `0`. Если получение расширенных атрибутов не поддерживается, допустимым резервным вариантом является копирование `fslabel` в `vlabel`. В случае ошибки должно быть возвращено соответствующее значение `errno`. + +[[mac-mpo-associate-vnode-singlelabel]] +===== `mpo_associate_vnode_singlelabel` + +[source, c] +---- +void mpo_associate_vnode_singlelabel(struct mount *mp, struct label *fslabel, + struct vnode *vp, struct label *vlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`mp` +|Точка монтирования файловой системы +| + +|`fslabel` +|Метка файловой системы +| + +|`vp` +|Узел vnode для метки +| + +|`vlabel` +|Метка политики, связанная с `vp` +| +|=== + +На файловых системах без поддержки multilabel эта точка входа вызывается для установки метки политики для `vp` на основе метки файловой системы `fslabel`. + +[[mac-mpo-create-devfs-device]] +===== `mpo_create_devfs_device` + +[source, c] +---- +void mpo_create_devfs_device(dev_t dev, struct devfs_dirent *devfs_dirent, + struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`dev` +|Устройство, соответствующее `devfs_dirent` +| + +|`devfs_dirent` +|Запись в каталоге devfs, для которой создается метка. +| + +|`label` +|Метка для `devfs_dirent`, которую нужно заполнить. +| +|=== + +Заполнить метку на devfs_dirent, создаваемом для переданного устройства. Этот вызов будет выполнен при монтировании файловой системы устройств, её восстановлении или при появлении нового устройства. + +[[mac-mpo-create-devfs-directory]] +===== `mpo_create_devfs_directory` + +[source, c] +---- +void mpo_create_devfs_directory(char *dirname, int dirnamelen, + struct devfs_dirent *devfs_dirent, struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`dirname` +|Имя создаваемого каталога +| + +|`namelen` +|Длина строки `dirname` +| + +|`devfs_dirent` +|Запись в devfs для создаваемого каталога. +| +|=== + +Заполнить метку на devfs_dirent, создаваемом для переданного каталога. Этот вызов будет выполнен при монтировании файловой системы устройств, её восстановлении или при появлении нового устройства, требующего определённой иерархии каталогов. + +[[mac-mpo-create-devfs-symlink]] +===== `mpo_create_devfs_symlink` + +[source, c] +---- +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] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`mp` +|Точка монтирования devfs +| + +|`dd` +|Назначения cсылки +| + +|`ddlabel` +|Метка, связанная с `dd` +| + +|`de` +|Символьная ссылка записи +| + +|`delabel` +|Метка, связанная с `de` +| +|=== + +Заполнить метку (`delabel`) для новой структуры man:devfs[5] символьной ссылки. + +[[mac-mpo-create-vnode-extattr]] +===== `mpo_create_vnode_extattr` + +[source, c] +---- +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] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`mount` +|Точка монтирования файловой системы +| + +|`label` +|Метка файловой системы +| + +|`dvp` +|Родительский каталог vnode +| + +|`dlabel` +|Метка, связанная с `dvp` +| + +|`vp` +|Вновь созданная vnode +| + +|`vlabel` +|Метка политики, связанная с `vp` +| + +|`cnp` +|Название компонента для `vp` +| +|=== + +Записать метку для `vp` в соответствующий расширенный атрибут. Если запись прошла успешно, заполняет `vlabel` меткой и возвращает 0. В противном случае вернет соответствующую ошибку. + +[[mac-mpo-create-mount]] +===== `mpo_create_mount` + +[source, c] +---- +void mpo_create_mount(struct ucred *cred, struct mount *mp, struct label *mnt, + struct label *fslabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`mp` +|Объект; файловая система, которая монтируется +| + +|`mntlabel` +|Метка политики для заполнения в `mp` +| + +|`fslabel` +|Метка политики для файловой системы, монтируемой в `mp`. +| +|=== + +Заполнить метки на точке монтирования, создаваемой переданными учетными данными субъекта. Этот вызов будет выполнен при монтировании новой файловой системы. + +[[mac-mpo-create-root-mount]] +===== `mpo_create_root_mount` + +[source, c] +---- +void mpo_create_root_mount(struct ucred *cred, struct mount *mp, + struct label *mntlabel, struct label *fslabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +3+|См. crossref:mac[mac-mpo-create-mount, `mpo_create_mount`]. +|=== + +Заполнить метки на точке монтирования, создаваемой переданными учетными данными субъекта. Этот вызов будет выполнен при монтировании корневой файловой системы после `mpo_create_mount;`. + +[[mac-mpo-relabel-vnode]] +===== `mpo_relabel_vnode` + +[source, c] +---- +void mpo_relabel_vnode(struct ucred *cred, struct vnode *vp, + struct label *vnodelabel, struct label *newlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|vnode для перемаркировки +| + +|`vnodelabel` +|Существующая метка политики для `vp` +| + +|`newlabel` +|Новая, возможно частичная метка для замены `vnodelabel` +| +|=== + +Обновить метку на переданном vnode с учетом переданной обновленной метки vnode и переданных учетных данных субъекта. + +[[mac-mpo-setlabel-vnode-extattr]] +===== `mpo_setlabel_vnode_extattr` + +[source, c] +---- +int mpo_setlabel_vnode_extattr(struct ucred *cred, struct vnode *vp, + struct label *vlabel, struct label *intlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|vnode, для которой записывается метка +| + +|`vlabel` +|Метка политики, связанная с `vp` +| + +|`intlabel` +|Метка для записи +| +|=== + +Записать политику из `intlabel` в расширенный атрибут. Этот метод вызывается из `vop_stdcreatevnode_ea`. + +[[mac-mpo-update-devfsdirent]] +===== `mpo_update_devfsdirent` + +[source, c] +---- +void mpo_update_devfsdirent(struct devfs_dirent *devfs_dirent, + struct label *direntlabel, struct vnode *vp, struct label *vnodelabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`devfs_dirent` +|Объект; каталожная запись devfs +| + +|`direntlabel` +|Метка политики для `devfs_dirent`, которая будет обновлена. +| + +|`vp` +|Родительский vnode +|Заблокирован + +|`vnodelabel` +|Метка политики для `vp` +| +|=== + +Обновить метку `devfs_dirent` из переданной метки devfs vnode. Этот вызов будет выполнен, когда devfs vnode успешно перемаркирован, чтобы зафиксировать изменение метки, чтобы оно сохранилось, даже если vnode будет переиспользован. Он также будет выполнен при создании символьной ссылки в devfs после вызова `mac_vnode_create_from_vnode` для инициализации метки vnode. + +[[mac-ipc-label-ops]] +==== Действия с событиями меток объектов IPC + +[[mac-mpo-create-mbuf-from-socket]] +===== `mpo_create_mbuf_from_socket` + +[source, c] +---- +void mpo_create_mbuf_from_socket(struct socket *so, struct label *socketlabel, + struct mbuf *m, struct label *mbuflabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`socket` +|Сокет +|Блокировка сокетов — работа в процессе + +|`socketlabel` +|Метка политики для `socket` +| + +|`m` +|Объект; mbuf +| + +|`mbuflabel` +|Метка политики для заполнения для `m` +| +|=== + +Установить метку на только что созданном заголовке mbuf из переданной метки сокета. Этот вызов выполняется, когда новый датаграмма или сообщение генерируется сокетом и сохраняется в переданном mbuf. + +[[mac-mpo-create-pipe]] +===== `mpo_create_pipe` + +[source, c] +---- +void mpo_create_pipe(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`pipe` +|Канал +| + +|`pipelabel` +|Метка политики, связанная с `pipe` +| +|=== + +Установить метку на только что созданном канале из переданных учетных данных субъекта. Этот вызов выполняется при создании нового канала. + +[[mac-mpo-create-socket]] +===== `mpo_create_socket` + +[source, c] +---- +void mpo_create_socket(struct ucred *cred, struct socket *so, + struct label *socketlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +|Неизменяемый + +|`so` +|Объект; сокет для добавления метки +| + +|`socketlabel` +|Метка для заполнения для `so` +| +|=== + +Установить метку на новом сокете из переданных учетных данных субъекта. Этот вызов выполняется при создании сокета. + +[[mac-mpo-create-socket-from-socket]] +===== `mpo_create_socket_from_socket` + +[source, c] +---- +void mpo_create_socket_from_socket(struct socket *oldsocket, + struct label *oldsocketlabel, struct socket *newsocket, + struct label *newsocketlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`oldsocket` +|Сокет, вызвавший listen +| + +|`oldsocketlabel` +|Метка политики, связанная с `oldsocket` +| + +|`newsocket` +|Новый сокет +| + +|`newsocketlabel` +|Метка политики, связанная с `newsocketlabel` +| +|=== + +Создать метку сокета `newsocket`, только что принявшему соединение через man:accept[2], на основе сокета `oldsocket`, вызвавшего man:listen[2] . + +[[mac-mpo-relabel-pipe]] +===== `mpo_relabel_pipe` + +[source, c] +---- +void mpo_relabel_pipe(struct ucred *cred, struct pipe *pipe, + struct label *oldlabel, struct label *newlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`pipe` +|Канал +| + +|`oldlabel` +|Текущая метка политики, связанная с `pipe` +| + +|`newlabel` +|Обновление метки политики для применения к `pipe` +| +|=== + +Применить новую метку `newlabel` к `pipe`. + +[[mac-mpo-relabel-socket]] +===== `mpo_relabel_socket` + +[source, c] +---- +void mpo_relabel_socket(struct ucred *cred, struct socket *so, + struct label *oldlabel, struct label *newlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +|Неизменяемый + +|`so` +|Объект; сокет +| + +|`oldlabel` +|Текущая метка для `so` +| + +|`newlabel` +|Метка обновления для `so` +| +|=== + +Обновить метку на сокете из переданного обновления метки сокета. + +[[mpo-set-socket-peer-from-mbuf]] +===== `mpo_set_socket_peer_from_mbuf` + +[source, c] +---- +void mpo_set_socket_peer_from_mbuf(struct mbuf *mbuf, struct label *mbuflabel, + struct label *oldlabel, struct label *newlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`mbuf` +|Первый датаграмм, полученный через сокет +| + +|`mbuflabel` +|Метка для `mbuf` +| + +|`oldlabel` +|Текущая метка для сокета +| + +|`newlabel` +|Метка политики для заполнения сокета +| +|=== + +Установить метку однорангового узла на потоковом сокете из переданной метки mbuf. Этот вызов будет выполнен при получении первого датаграммы потоковым сокетом, за исключением сокетов домена Unix. + +[[mac-mpo-set-socket-peer-from-socket]] +===== `mpo_set_socket_peer_from_socket` + +[source, c] +---- +void mpo_set_socket_peer_from_socket(struct socket *oldsocket, + struct label *oldsocketlabel, struct socket *newsocket, + struct label *newsocketpeerlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`oldsocket` +|Локальный сокет +| + +|`oldsocketlabel` +|Метка политики для `oldsocket` +| + +|`newsocket` +|Сокет однорангового узла (peer socket) +| + +|`newsocketpeerlabel` +|Метка политики для заполнения для `newsocket` +| +|=== + +Установите метку однорангового узла на потоковом UNIX-сокете из переданной конечной точки удаленного сокета. Этот вызов будет выполнен при соединении пары сокетов и будет произведен для обеих конечных точек. + +[[mac-net-labeling-event-ops]] +==== Действия с событиями меток сетевых объектов + +[[mac-mpo-create-bpfdesc]] +===== `mpo_create_bpfdesc` + +[source, c] +---- +void mpo_create_bpfdesc(struct ucred *cred, struct bpf_d *bpf_d, + struct label *bpflabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +|Неизменяемый + +|`bpf_d` +|Объект; дескриптор bpf +| + +|`bpf` +|Метка политики для заполнения для `bpf_d` +| +|=== + +Установить метку на новом дескрипторе BPF из переданных учётных данных субъекта. Этот вызов будет выполнен при открытии узла устройства BPF процессом с переданными учётными данными субъекта. + +[[mac-mpo-create-ifnet]] +===== `mpo_create_ifnet` + +[source, c] +---- +void mpo_create_ifnet(struct ifnet *ifnet, struct label *ifnetlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`ifnet` +|Сетевой интерфейс +| + +|`ifnetlabel` +|Метка политики для заполнения для `ifnet` +| +|=== + +Установить метку на вновь созданном интерфейсе. Этот вызов может быть выполнен, когда новое физическое устройство становится доступным системе, или когда псевдо-интерфейс создаётся во время загрузки или в результате действия пользователя. + +[[mac-mpo-create-ipq]] +===== `mpo_create_ipq` + +[source, c] +---- +void mpo_create_ipq(struct mbuf *fragment, struct label *fragmentlabel, + struct ipq *ipq, struct label *ipqlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`fragment` +|Первый полученный IP-фрагмент +| + +|`fragmentlabel` +|Метка политики для `fragment` +| + +|`ipq` +|Очередь повторной сборки IP, которой добавляетя метка +| + +|`ipqlabel` +|Метка политики для заполнения в `ipq` +| +|=== + +Установить метку на вновь созданной очереди сборки IP-фрагментов из заголовка mbuf первого полученного фрагмента. + +[[mac-mpo-create-datagram-from-ipq]] +===== `mpo_create_datagram_from_ipq` + +[source, c] +---- +void mpo_create_create_datagram_from_ipq(struct ipq *ipq, + struct label *ipqlabel, struct mbuf *datagram, struct label *datagramlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`ipq` +|Очередь повторной сборки IP +| + +|`ipqlabel` +|Метка политики для `ipq` +| + +|`datagram` +|Датаграмма для добавления метки +| + +|`datagramlabel` +|Метка политики для заполнения в `datagramlabel` +| +|=== + +Установите метку на вновь собранный IP-датаграмму из очереди сборки IP-фрагментов, из которой он был сгенерирован. + +[[mac-mpo-create-fragment]] +===== `mpo_create_fragment` + +[source, c] +---- +void mpo_create_fragment(struct mbuf *datagram, struct label *datagramlabel, + struct mbuf *fragment, struct label *fragmentlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`datagram` +|Датаграмма +| + +|`datagramlabel` +|Метка политики для `datagram` +| + +|`fragment` +|Фрагмент, которому будет установлена метка +| + +|`fragmentlabel` +|Метка политики для заполнения для `datagram` +| +|=== + +Установить метку на заголовке mbuf вновь созданного IP-фрагмента из метки на заголовке mbuf датаграммы, из которой он был сгенерирован. + +[[mac-mpo-create-mbuf-from-mbuf]] +===== `mpo_create_mbuf_from_mbuf` + +[source, c] +---- +void mpo_create_mbuf_from_mbuf(struct mbuf *oldmbuf, struct label *oldmbuflabel, + struct mbuf *newmbuf, struct label *newmbuflabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`oldmbuf` +|Существующий (исходный) mbuf +| + +|`oldmbuflabel` +|Метка политики для `oldmbuf` +| + +|`newmbuf` +|Новый mbuf для добавления метки +| + +|`newmbuflabel` +|Метка политики для заполнения в `newmbuf` +| +|=== + +Установить метку в заголовке mbuf для вновь созданной датаграммы на основе заголовка mbuf существующей датаграммы. Этот вызов может быть выполнен в ряде ситуаций, включая случаи, когда для mbuf заново выделяется память для целей выравнивания. + +[[mac-mpo-create-mbuf-linklayer]] +===== `mpo_create_mbuf_linklayer` + +[source, c] +---- +void mpo_create_mbuf_linklayer(struct ifnet *ifnet, struct label *ifnetlabel, + struct mbuf *mbuf, struct label *mbuflabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`ifnet` +|Сетевой интерфейс +| + +|`ifnetlabel` +|Метка политики для `ifnet` +| + +|`mbuf` +|заголовок mbuf для новой датаграммы +| + +|`mbuflabel` +|Метка политики для заполнения для `mbuf` +| +|=== + +Установить метку в заголовке mbuf для вновь созданной датаграммы, сгенерированного для целей ответа на канальном уровне для переданного интерфейса. Этот вызов может быть выполнен в ряде ситуаций, включая ответы ARP или ND6 в стеках IPv4 и IPv6. + +[[mac-mpo-create-mbuf-from-bpfdesc]] +===== `mpo_create_mbuf_from_bpfdesc` + +[source, c] +---- +void mpo_create_mbuf_from_bpfdesc(struct bpf_d *bpf_d, struct label *bpflabel, + struct mbuf *mbuf, struct label *mbuflabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`bpf_d` +|Дескриптор BPF +| + +|`bpflabel` +|Метка политики для `bpflabel` +| + +|`mbuf` +|Новый mbuf для добавления метки +| + +|`mbuflabel` +|Метка политики для заполнения `mbuf` +| +|=== + +Установить метку на заголовок mbuf вновь созданной датаграммы, сгенерированной с использованием переданного дескриптора BPF. Этот вызов выполняется при записи в устройство BPF, связанное с переданным дескриптором BPF. + +[[mac-mpo-create-mbuf-from-ifnet]] +===== `mpo_create_mbuf_from_ifnet` + +[source, c] +---- +void mpo_create_mbuf_from_ifnet(struct ifnet *ifnet, struct label *ifnetlabel, + struct mbuf *mbuf, struct label *mbuflabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`ifnet` +|Сетевой интерфейс +| + +|`ifnetlabel` +|Метка политики для `ifnetlabel` +| + +|`mbuf` +|заголовок mbuf для новой датаграммы +| + +|`mbuflabel` +|Метка политики для заполнения для `mbuf` +| +|=== + +Установить метку на заголовке mbuf вновь созданной датаграммы, сгенерированной из переданного сетевого интерфейса. + +[[mac-mpo-create-mbuf-multicast-encap]] +===== `mpo_create_mbuf_multicast_encap` + +[source, c] +---- +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] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`oldmbuf` +|Заголовок mbuf для существующего датаграммы +| + +|`oldmbuflabel` +|Метка политики для `oldmbuf` +| + +|`ifnet` +|Сетевой интерфейс +| + +|`ifnetlabel` +|Метка политики для `ifnet` +| + +|`newmbuf` +|Заголовок mbuf для пометки новой датаграммы +| + +|`newmbuflabel` +|Метка политики для заполнения в `newmbuf` +| +|=== + +Установить метку в заголовке mbuf для вновь созданной датаграммы, сгенерированной из существующей переданной датаграммы, при её обработке переданным интерфейсом мультикастовой инкапсуляции. Этот вызов происходит при доставке mbuf с использованием виртуального интерфейса. + +[[mac-mpo-create-mbuf-netlayer]] +===== `mpo_create_mbuf_netlayer` + +[source, c] +---- +void mpo_create_mbuf_netlayer(struct mbuf *oldmbuf, struct label *oldmbuflabel, + struct mbuf *newmbuf, struct label *newmbuflabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`oldmbuf` +|Полученная датаграмма +| + +|`oldmbuflabel` +|Метка политики для `oldmbuf` +| + +|`newmbuf` +|Вновь созданная датаграмма +| + +|`newmbuflabel` +|Метка политики для `newmbuf` +| +|=== + +Установить метку на заголовок mbuf вновь созданной датаграммы, сгенерированной стеком IP в ответ на полученную датаграмму (`oldmbuf`). Этот вызов может быть выполнен в различных ситуациях, включая ответ на датаграммы ICMP-запросов. + +[[mac-mpo-fragment-match]] +===== `mpo_fragment_match` + +[source, c] +---- +int mpo_fragment_match(struct mbuf *fragment, struct label *fragmentlabel, + struct ipq *ipq, struct label *ipqlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`fragment` +|Фрагмент IP-датаграммы +| + +|`fragmentlabel` +|Метка политики для `fragment` +| + +|`ipq` +|Очередь сборки IP-фрагментов +| + +|`ipqlabel` +|Метка политики для `ipq` +| +|=== + +Определить, соответствует ли заголовок mbuf, содержащий фрагмент IP-датаграммы (`fragment`), метке переданной очереди сборки IP-фрагментов (`ipq`). Возвращает (1) при успешном совпадении или (0) при отсутствии совпадения. Этот вызов выполняется, когда IP-стек пытается найти существующую очередь сборки фрагментов для вновь полученного фрагмента; если поиск не удаётся, для фрагмента может быть создана новая очередь сборки. Политики могут использовать эту точку входа, чтобы предотвратить сборку в остальном подходящих IP-фрагментов, если политика не разрешает их сборку на основе метки или другой информации. + +[[mac-mpo-ifnet-relabel]] +===== `mpo_relabel_ifnet` + +[source, c] +---- +void mpo_relabel_ifnet(struct ucred *cred, struct ifnet *ifnet, + struct label *ifnetlabel, struct label *newlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`ifnet` +|Объект; Сетевой интерфейс +| + +|`ifnetlabel` +|Метка политики для `ifnet` +| + +|`newlabel` +|Метка обновления для применения к `ifnet` +| +|=== + +Обновить метку сетевого интерфейса, `ifnet`, на основе переданной новой метки, `newlabel`, и переданных учетных данных субъекта, `cred`. + +[[mac-mpo-update-ipq]] +===== `mpo_update_ipq` + +[source, c] +---- +void mpo_update_ipq(struct mbuf *fragment, struct label *fragmentlabel, + struct ipq *ipq, struct label *ipqlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`mbuf` +|IP фрагмент +| + +|`mbuflabel` +|Метка политики для `mbuf` +| + +|`ipq` +|Очередь сборки IP-фрагментов +| + +|`ipqlabel` +|Метка политики для обновления для `ipq` +| +|=== + +Обновить метку в очереди сборки IP-фрагментов (`ipq`) на основе принятия переданного заголовка IP-фрагмента mbuf (`mbuf`). + +[[mac-proc-labeling-event-ops]] +==== Действия с событиями меток процессов + +[[mac-mpo-create-cred]] +===== `mpo_create_cred` + +[source, c] +---- +void mpo_create_cred(struct ucred *parent_cred, struct ucred *child_cred); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`parent_cred` +|Учетные данные субъекта‐родителя +| + +|`child_cred` +|Учётные данные дочернего субъекта +| +|=== + +Установить метку вновь созданного субъекта из переданного субъекта. Этот вызов будет выполнен при вызове man:crcopy[9] для только что созданной структуры `struct ucred`. Этот вызов не следует путать с событием создания или ветвления процесса. + +[[mac-mpo-execve-transition]] +===== `mpo_execve_transition` + +[source, c] +---- +void mpo_execve_transition(struct ucred *old, struct ucred *new, + struct vnode *vp, struct label *vnodelabel); + +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`old` +|Учетные данные существующего субъекта +|Неизменяемый + +|`new` +|Учетные данные нового субъекта для добавления метки +| + +|`vp` +|Файл для выполнения +|Заблокирован + +|`vnodelabel` +|Метка политики для `vp` +| +|=== + +Обновить метку учетных данных вновь созданного субъекта (`new`) на основе переданных учетных данных существующего субъекта (`old`) в соответствии с переходом метки, вызванным выполнением переданного vnode (`vp`). Этот вызов происходит, когда процесс выполняет переданный vnode, и одна из политик возвращает успех из точки входа `mpo_execve_will_transition`. Политики могут выбрать реализацию этого вызова просто путем вызова `mpo_create_cred` и передачи двух субъектов учетных данных, чтобы не реализовывать событие перехода. Политики не должны оставлять эту точку входа нереализованной, если они реализуют `mpo_create_cred`, даже если они не реализуют `mpo_execve_will_transition`. + +[[mac-mpo-execve-will-transition]] +===== `mpo_execve_will_transition` + +[source, c] +---- +int mpo_execve_will_transition(struct ucred *old, struct vnode *vp, + struct label *vnodelabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`old` +|Учетные данные субъекта перед man:execve[2] +|Неизменяемый + +|`vp` +|Файл для выполнения +| + +|`vnodelabel` +|Метка политики для `vp` +| +|=== + +Определить, будет ли политика выполнять событие перехода в результате выполнения переданного vnode с использованием переданных учетных данных субъекта. Вернуть 1, если переход требуется, и 0, если нет. Даже если политика возвращает 0, она должна корректно обрабатывать неожиданный вызов `mpo_execve_transition`, так как этот вызов может произойти из-за запроса перехода другой политикой. + +[[mac-mpo-create-proc0]] +===== `mpo_create_proc0` + +[source, c] +---- +void mpo_create_proc0(struct ucred *cred); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта для заполнения +| +|=== + +Создать учетные данные субъекта процесса 0, родителя всех процессов ядра. + +[[mac-mpo-create-proc1]] +===== `mpo_create_proc1` + +[source, c] +---- +void mpo_create_proc1(struct ucred *cred); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта для заполнения +| +|=== + +Создать учетные данные субъекта процесса 1, родителя всех пользовательских процессов. + +[[mac-mpo-relabel-cred]] +===== `mpo_relabel_cred` + +[source, c] +---- +void mpo_relabel_cred(struct ucred *cred, struct label *newlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`newlabel` +|Обновление метки для применения к `cred` +| +|=== + +Обновить метку на учетных данных субъекта из переданной обновляемой метки. + +[[mac-access-control-checks]] +=== Проверки контроля доступа + +Точки входа контроля доступа позволяют модулям политики влиять на решения по контролю доступа, принимаемые ядром. Обычно, хотя и не всегда, аргументы точки входа контроля доступа включают одно или несколько удостоверяющих полномочий, информацию (возможно, включая метку) для любых других объектов, участвующих в операции. Точка входа контроля доступа может вернуть 0 для разрешения операции или значение ошибки man:errno[2]. Результаты вызова точки входа через различные зарегистрированные модули политики будут объединены следующим образом: если все модули разрешают успешное выполнение операции, будет возвращен успех. Если один или несколько модулей возвращают ошибку, будет возвращена ошибка. Если более одного модуля возвращают ошибку, значение errno, которое будет возвращено пользователю, выбирается с использованием следующего приоритета, реализованного функцией `error_select()` в [.filename]#kern_mac.c#: + +[.informaltable] +[cols="1,1", frame="none"] +|=== + +|Наивысший приоритет +|EDEADLK + +| +|EINVAL + +| +|ESRCH + +| +|EACCES + +|Наименьший приоритет +|EPERM +|=== + +Если ни одно из значений ошибок, возвращаемых всеми модулями, не указано в таблице приоритетов, будет возвращено произвольно выбранное значение из набора. В общем случае правила устанавливают следующий порядок приоритетов ошибок: сбои ядра, неверные аргументы, отсутствие объекта, отсутствие доступа, прочие. + +[[mac-mpo-bpfdesc-check-receive-from-ifnet]] +==== `mpo_check_bpfdesc_receive` + +[source, c] +---- +int mpo_check_bpfdesc_receive(struct bpf_d *bpf_d, struct label *bpflabel, + struct ifnet *ifnet, struct label *ifnetlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`bpf_d` +|Субъект; Дескриптор BPF +| + +|`bpflabel` +|Метка политики для `bpf_d` +| + +|`ifnet` +|Объект; сетевой интерфейс +| + +|`ifnetlabel` +|Метка политики для `ifnet` +| +|=== + +Определить, должен ли framework MAC разрешать доставку датаграмм с переданного интерфейса в буферы переданного BPF-дескриптора. Возвращает (0) при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии меток, EPERM при отсутствии привилегий. + +[[mac-mpo-check-kenv-dump]] +==== `mpo_check_kenv_dump` + +[source, c] +---- +int mpo_check_kenv_dump(struct ucred *cred); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| +|=== + +Определить, следует ли разрешить субъекту получать доступ к окружению ядра (см. man:kenv[2]). + +[[mac-mpo-check-kenv-get]] +==== `mpo_check_kenv_get` + +[source, c] +---- +int mpo_check_kenv_get(struct ucred *cred, char *name); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`name` +|Имя переменной окружения ядра +| +|=== + +Определить, следует ли разрешить субъекту получать значение указанной переменной окружения ядра. + +[[mac-mpo-check-kenv-set]] +==== `mpo_check_kenv_set` + +[source, c] +---- +int mpo_check_kenv_set(struct ucred *cred, char *name); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`name` +|Имя переменной окружения ядра +| +|=== + +Определить, следует ли разрешить субъекту устанавливать указанную переменную окружения ядра. + +[[mac-mpo-check-kenv-unset]] +==== `mpo_check_kenv_unset` + +[source, c] +---- +int mpo_check_kenv_unset(struct ucred *cred, char *name); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`name` +|Имя переменной окружения ядра +| +|=== + +Определить, следует ли разрешить субъекту сбросить указанную переменную окружения ядра. + +[[mac-mpo-check-kld-load]] +==== `mpo_check_kld_load` + +[source, c] +---- +int mpo_check_kld_load(struct ucred *cred, struct vnode *vp, + struct label *vlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|vnode модуля ядра +| + +|`vlabel` +|Метка, связанная с `vp` +| +|=== + +Определить, следует ли разрешить субъекту загружать указанный файл модуля. + +[[mac-mpo-check-kld-stat]] +==== `mpo_check_kld_stat` + +[source, c] +---- +int mpo_check_kld_stat(struct ucred *cred); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| +|=== + +Определить, следует ли разрешить субъекту получать список загруженных файлов модулей ядра и связанную с ними статистику. + +[[mac-mpo-check-kld-unload]] +==== `mpo_check_kld_unload` + +[source, c] +---- +int mpo_check_kld_unload(struct ucred *cred); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| +|=== + +Определить, следует ли разрешить субъекту выгружать модуль ядра. + +[[mac-mpo-check-pipe-ioctl]] +==== `mpo_check_pipe_ioctl` + +[source, c] +---- +int mpo_check_pipe_ioctl(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel, unsigned long cmd, void *data); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`pipe` +|Канал +| + +|`pipelabel` +|Метка политики, связанная с `pipe` +| + +|`cmd` +|команда nman:ioctl[2] +| + +|`data` +|данные man:ioctl[2] +| +|=== + +Определить, следует ли разрешить субъекту выполнять указанный вызов man:ioctl[2]. + +[[mac-mpo-check-pipe-poll]] +==== `mpo_check_pipe_poll` + +[source, c] +---- +int mpo_check_pipe_poll(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`pipe` +|Канал +| + +|`pipelabel` +|Метка политики, связанная с `pipe` +| +|=== + +Определить, следует ли разрешить субъекту опрашивать `pipe`. + +[[mac-mpo-check-pipe-read]] +==== `mpo_check_pipe_read` + +[source, c] +---- +int mpo_check_pipe_read(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`pipe` +|Канал +| + +|`pipelabel` +|Метка политики, связанная с `pipe` +| +|=== + +Определить, следует ли разрешить субъекту доступ на чтение к `pipe`. + +[[mac-mpo-check-pipe-relabel]] +==== `mpo_check_pipe_relabel` + +[source, c] +---- +int mpo_check_pipe_relabel(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel, struct label *newlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`pipe` +|Канал +| + +|`pipelabel` +|Текущая метка политики, связанная с `pipe` +| + +|`newlabel` +|Обновление метки до `pipelabel` +| +|=== + +Определить, следует ли разрешить субъекту изменять метку `pipe`. + +[[mac-mpo-check-pipe-stat]] +==== `mpo_check_pipe_stat` + +[source, c] +---- +int mpo_check_pipe_stat(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`pipe` +|Канал +| + +|`pipelabel` +|Метка политики, связанная с `pipe` +| +|=== + +Определить, следует ли разрешить субъекту получать статистику, связанную с `pipe`. + +[[mac-mpo-check-pipe-write]] +==== `mpo_check_pipe_write` + +[source, c] +---- +int mpo_check_pipe_write(struct ucred *cred, struct pipe *pipe, + struct label *pipelabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`pipe` +|Канал +| + +|`pipelabel` +|Метка политики, связанная с `pipe` +| +|=== + +Определить, следует ли разрешить субъекту запись в `pipe`. + +[[mac-mpo-cred-check-socket-bind]] +==== `mpo_check_socket_bind` + +[source, c] +---- +int mpo_check_socket_bind(struct ucred *cred, struct socket *socket, + struct label *socketlabel, struct sockaddr *sockaddr); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`socket` +|Сокет для привязки +| + +|`socketlabel` +|Метка политики для `socket` +| + +|`sockaddr` +|Адрес `socket` +| +|=== + +[[mac-mpo-cred-check-socket-connect]] +==== `mpo_check_socket_connect` + +[source, c] +---- +int mpo_check_socket_connect(struct ucred *cred, struct socket *socket, + struct label *socketlabel, struct sockaddr *sockaddr); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`socket` +|Сокет для подключения +| + +|`socketlabel` +|Метка политики для `socket` +| + +|`sockaddr` +|Адрес `socket` +| +|=== + +Определить, может ли субъект с учётными данными (`cred`) подключить переданный сокет (`socket`) к переданному адресу сокета (`sockaddr`). Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии меток, EPERM при отсутствии прав. + +[[mac-mpo-check-socket-receive]] +==== `mpo_check_socket_receive` + +[source, c] +---- +int mpo_check_socket_receive(struct ucred *cred, struct socket *so, + struct label *socketlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`so` +|Сокет +| + +|`socketlabel` +|Метка политики, связанная с `so` +| +|=== + +Определить, следует ли разрешить субъекту получать информацию из сокета `so`. + +[[mac-mpo-check-socket-send]] +==== `mpo_check_socket_send` + +[source, c] +---- +int mpo_check_socket_send(struct ucred *cred, struct socket *so, + struct label *socketlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`so` +|Сокет +| + +|`socketlabel` +|Метка политики, связанная с `so` +| +|=== + +Определить, следует ли разрешить субъекту передавать информацию через сокет `so`. + +[[mac-mpo-check-cred-visible]] +==== `mpo_check_cred_visible` + +[source, c] +---- +int mpo_check_cred_visible(struct ucred *u1, struct ucred *u2); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`u1` +|Учетные данные субъекта +| + +|`u2` +|Учетные данные объекта +| +|=== + +Определить, может ли субъект с учётными данными `u1` "видеть" другие субъекты с переданными учётными данными `u2`. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии меток, EPERM при отсутствии привилегий или ESRCH для скрытия видимости. Этот вызов может выполняться в различных ситуациях, включая системные вызовы состояния межпроцессного взаимодействия, используемые `ps`, и при поиске в procfs. + +[[mac-mpo-cred-check-socket-visible]] +==== `mpo_check_socket_visible` + +[source, c] +---- +int mpo_check_socket_visible(struct ucred *cred, struct socket *socket, + struct label *socketlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`socket` +|Объект; сокет +| + +|`socketlabel` +|Метка политики для `socket` +| +|=== + +[[mac-mpo-cred-check-ifnet-relabel]] +==== `mpo_check_ifnet_relabel` + +[source, c] +---- +int mpo_check_ifnet_relabel(struct ucred *cred, struct ifnet *ifnet, + struct label *ifnetlabel, struct label *newlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`ifnet` +|Объект; сетевой интерфейс +| + +|`ifnetlabel` +|Существующая метка политики для `ifnet` +| + +|`newlabel` +|Обновление метки политики для последующего применения к `ifnet` +| +|=== + +Определить, может ли учетные данные субъекта перемаркировать переданный сетевой интерфейс в соответствии с переданным обновлением метки. + +[[mac-mpo-cred-check-socket-relabel]] +==== `mpo_check_socket_relabel` + +[source, c] +---- +int mpo_check_socket_relabel(struct ucred *cred, struct socket *socket, + struct label *socketlabel, struct label *newlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`socket` +|Объект; сокет +| + +|`socketlabel` +|Метка существующей политики для `socket` +| + +|`newlabel` +|Обновление метки для последующего применения к `socketlabel` +| +|=== + +Определить, могут ли учётные данные субъекта перемаркировать переданный сокет в соответствии с переданным обновлением метки. + +[[mac-mpo-cred-check-cred-relabel]] +==== `mpo_check_cred_relabel` + +[source, c] +---- +int mpo_check_cred_relabel(struct ucred *cred, struct label *newlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`newlabel` +|Обновление метки для последующего применения к `cred` +| +|=== + +Определить, могут ли учетные данные субъекта перемаркировать себя в соответствии с переданным обновлением метки. + +[[mac-mpo-cred-check-vnode-relabel]] +==== `mpo_check_vnode_relabel` + +[source, c] +---- +int mpo_check_vnode_relabel(struct ucred *cred, struct vnode *vp, + struct label *vnodelabel, struct label *newlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +|Неизменяемый + +|`vp` +|Объект; vnode +|Заблокирован + +|`vnodelabel` +|Существующая метка политики для `vp` +| + +|`newlabel` +|Обновление метки политики для последующего применения к `vp` +| +|=== + +Определить, могут ли учётные данные субъекта изменить метку переданного vnode на переданную обновлённую метку. + +[[mpo-cred-check-mount-stat]] +==== `mpo_check_mount_stat` + +[source, c] +---- +int mpo_check_mount_stat(struct ucred *cred, struct mount *mp, + struct label *mountlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`mp` +|Объект; точка монтирования файловой системы +| + +|`mountlabel` +|Метка политики для `mp` +| +|=== + +Определить, могут ли учетные данные субъекта видеть результаты выполнения statfs для файловой системы. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии меток или EPERM при отсутствии привилегий. Этот вызов может выполняться в различных ситуациях, включая вызовы man:statfs[2] и связанных функций, а также для определения, какие файловые системы исключать из списка, например, при вызове man:getfsstat[2]. + +[[mac-mpo-cred-check-proc-debug]] +==== `mpo_check_proc_debug` + +[source, c] +---- +int mpo_check_proc_debug(struct ucred *cred, struct proc *proc); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +|Неизменяемый + +|`proc` +|Объект; процесс +| +|=== + +Определить, могут ли учётные данные субъекта отлаживать переданный процесс. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки, EPERM при недостатке прав или ESRCH для скрытия видимости цели. Этот вызов может использоваться в различных ситуациях, включая использование API man:ptrace[2] и man:ktrace[2], а также для некоторых операций с procfs. + +[[mac-mpo-cred-check-vnode-access]] +==== `mpo_check_vnode_access` + +[source, c] +---- +int mpo_check_vnode_access(struct ucred *cred, struct vnode *vp, + struct label *label, int flags); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode +| + +|`label` +|Метка политики для `vp` +| + +|`flags` +|флаги man:access[2] +| +|=== + +Определить, как должны возвращаться вызовы man:access[2] и связанные вызовы для субъекта с указанными учетными данными при выполнении на переданном vnode с использованием переданных флагов доступа. Обычно это должно быть реализовано с использованием той же семантики, что и в `mpo_check_vnode_open`. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии меток или EPERM при отсутствии привилегий. + +[[mac-mpo-cred-check-vnode-chdir]] +==== `mpo_check_vnode_chdir` + +[source, c] +---- +int mpo_check_vnode_chdir(struct ucred *cred, struct vnode *dvp, + struct label *dlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`dvp` +|Объект; vnode, в который делается man:chdir[2] +| + +|`dlabel` +|Метка политики для `dvp` +| +|=== + +Определить, могут ли учётные данные субъекта изменить рабочий каталог процесса на переданный vnode. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-check-vnode-chroot]] +==== `mpo_check_vnode_chroot` + +[source, c] +---- +int mpo_check_vnode_chroot(struct ucred *cred, struct vnode *dvp, + struct label *dlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`dvp` +|vnode каталога +| + +|`dlabel` +|Метка политики, связанная с `dvp` +| +|=== + +Определить, следует ли разрешить субъекту выполнять man:chroot[2] в указанный каталог (`dvp`). + +[[mac-mpo-cred-check-vnode-create]] +==== `mpo_check_vnode_create` + +[source, c] +---- +int mpo_check_vnode_create(struct ucred *cred, struct vnode *dvp, + struct label *dlabel, struct componentname *cnp, struct vattr *vap); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`dvp` +|Объект; vnode +| + +|`dlabel` +|Метка политики для `dvp` +| + +|`cnp` +|Название компонента для `dvp` +| + +|`vap` +|атрибуты vnode для `vap` +| +|=== + +Определить, могут ли учетные данные субъекта создать vnode с указанной родительской директорией, информацией о имени и атрибутами. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. Этот вызов может выполняться в различных ситуациях, включая вызовы man:open[2] с O_CREAT, man:mkfifo[2] и другие. + +[[mac-mpo-cred-check-vnode-delete]] +==== `mpo_check_vnode_delete` + +[source, c] +---- +int mpo_check_vnode_delete(struct ucred *cred, struct vnode *dvp, + struct label *dlabel, struct vnode *vp, void *label, + struct componentname *cnp); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`dvp` +|Родительский каталог vnode +| + +|`dlabel` +|Метка политики для `dvp` +| + +|`vp` +|Объект; vnode для удаления +| + +|`label` +|Метка политики для `vp` +| + +|`cnp` +|Название компонента для `vp` +| +|=== + +Определить, может ли субъект с данными учетными данными удалить vnode из переданного родительского каталога и переданной информации о имени. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. Этот вызов может быть выполнен в различных ситуациях, включая вызовы man:unlink[2] и man:rmdir[2]. Политики, реализующие эту точку входа, также должны реализовывать `mpo_check_rename_to` для авторизации удаления объектов в результате их переименования. + +[[mac-mpo-cred-check-vnode-deleteacl]] +==== `mpo_check_vnode_deleteacl` + +[source, c] +---- +int mpo_check_vnode_deleteacl(struct ucred *cred, struct vnode *vp, + struct label *label, acl_type_t type); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +|Неизменяемый + +|`vp` +|Объект; vnode +|Заблокирован + +|`label` +|Метка политики для `vp` +| + +|`type` +|Тип ACL +| +|=== + +Определить, могут ли учетные данные субъекта удалить ACL указанного типа из переданного vnode. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-cred-check-vnode-exec]] +==== `mpo_check_vnode_exec` + +[source, c] +---- +int mpo_check_vnode_exec(struct ucred *cred, struct vnode *vp, + struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode для выполнения +| + +|`label` +|Метка политики для `vp` +| +|=== + +Определить, могут ли учётные данные субъекта выполнить переданный vnode. Проверка права на выполнение осуществляется отдельно от решений о любом переходном событии. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии прав. + +[[mpo-cred-check-vnode-getacl]] +==== `mpo_check_vnode_getacl` + +[source, c] +---- +int mpo_check_vnode_getacl(struct ucred *cred, struct vnode *vp, + struct label *label, acl_type_t type); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode +| + +|`label` +|Метка политики для `vp` +| + +|`type` +|Тип ACL +| +|=== + +Определить, может ли учётное данное субъекта получить ACL указанного типа из переданного vnode. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-cred-check-vnode-getextattr]] +==== `mpo_check_vnode_getextattr` + +[source, c] +---- +int mpo_check_vnode_getextattr(struct ucred *cred, struct vnode *vp, + struct label *label, int attrnamespace, const char *name, struct uio *uio); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode +| + +|`label` +|Метка политики для `vp` +| + +|`attrnamespace` +|Пространство имен расширенных атрибутов +| + +|`name` +|Имя расширенного атрибута +| + +|`uio` +|Указатель структуры ввода-вывода; см. man:uio[9] +| +|=== + +Определить, может ли субъект с указанными учетными данными получить расширенный атрибут с заданным пространством имен и именем из указанного vnode. Политики, реализующие маркировку с использованием расширенных атрибутов, могут требовать особой обработки операций с этими атрибутами. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-check-vnode-link]] +==== `mpo_check_vnode_link` + +[source, c] +---- +int mpo_check_vnode_link(struct ucred *cred, struct vnode *dvp, + struct label *dlabel, struct vnode *vp, struct label *label, + struct componentname *cnp); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`dvp` +|vnode каталога +| + +|`dlabel` +|Метка политики, связанная с `dvp` +| + +|`vp` +|vnode целевого линка +| + +|`label` +|Метка политики, связанная с `vp` +| + +|`cnp` +|Имя компонента для создаваемой ссылки +| +|=== + +Определить, следует ли разрешить субъекту создавать ссылку на vnode `vp` с именем, указанным в `cnp`. + +[[mac-mpo-check-vnode-mmap]] +==== `mpo_check_vnode_mmap` + +[source, c] +---- +int mpo_check_vnode_mmap(struct ucred *cred, struct vnode *vp, + struct label *label, int prot); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|vnode для mmap +| + +|`label` +|Метка политики, связанная с `vp` +| + +|`prot` +|Защита mmap (см. man:mmap[2]) +| +|=== + +Определить, следует ли разрешить субъекту отображать vnode `vp` с указанными в `prot` правами доступа. + +[[mac-mpo-check-vnode-mmap-downgrade]] +==== `mpo_check_vnode_mmap_downgrade` + +[source, c] +---- +void mpo_check_vnode_mmap_downgrade(struct ucred *cred, struct vnode *vp, + struct label *label, int *prot); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|См. crossref:mac[mac-mpo-check-vnode-mmap, `mpo_check_vnode_mmap`]. +| + +|`vp` +| +| + +|`label` +| +| + +|`prot` +|Защита mmap для понижения уровня +| +|=== + +Понизить уровень защиты mmap на основе меток субъекта и объекта. + +[[mac-mpo-check-vnode-mprotect]] +==== `mpo_check_vnode_mprotect` + +[source, c] +---- +int mpo_check_vnode_mprotect(struct ucred *cred, struct vnode *vp, + struct label *label, int prot); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Отображенный vnode +| + +|`prot` +|Защита памяти +| +|=== + +Определить, следует ли разрешить субъекту устанавливать указанные защиты памяти для памяти, отображенной из vnode `vp`. + +[[mac-mpo-check-vnode-poll]] +==== `mpo_check_vnode_poll` + +[source, c] +---- +int mpo_check_vnode_poll(struct ucred *active_cred, struct ucred *file_cred, + struct vnode *vp, struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`active_cred` +|Учетные данные субъекта +| + +|`file_cred` +|Учетные данные, связанные со структурой file +| + +|`vp` +|vnode, на котором вызывается poll +| + +|`label` +|Метка политики, связанная с `vp` +| +|=== + +Определить, следует ли разрешить субъекту вызывать poll на vnode `vp`. + +[[mac-mpo-check-vnode-rename-from]] +==== `mpo_check_vnode_rename_from` + +[source, c] +---- +int mpo_vnode_rename_from(struct ucred *cred, struct vnode *dvp, + struct label *dlabel, struct vnode *vp, struct label *label, + struct componentname *cnp); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`dvp` +|vnode каталога +| + +|`dlabel` +|Метка политики, связанная с `dvp` +| + +|`vp` +|vnode для переименования +| + +|`label` +|Метка политики, связанная с `vp` +| + +|`cnp` +|Название компонента для `vp` +| +|=== + +Определить, следует ли разрешить субъекту переименовать vnode `vp` во что-то другое. + +[[mac-mpo-check-vnode-rename-to]] +==== `mpo_check_vnode_rename_to` + +[source, c] +---- +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] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`dvp` +|vnode каталога +| + +|`dlabel` +|Метка политики, связанная с `dvp` +| + +|`vp` +|vnode, который будет перезаписан +| + +|`label` +|Метка политики, связанная с `vp` +| + +|`samedir` +|Логическое значение; `1`, если исходный и целевой каталоги совпадают +| + +|`cnp` +|Имя компонента назначения +| +|=== + +Определить, следует ли разрешить субъекту переименование vnode `vp` в директорию `dvp` или в имя, представленное `cnp`. Если не существует файла для перезаписи, `vp` и `label` будут NULL. + +[[mac-mpo-cred-check-socket-listen]] +==== `mpo_check_socket_listen` + +[source, c] +---- +int mpo_check_socket_listen(struct ucred *cred, struct socket *socket, + struct label *socketlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`socket` +|Объект; сокет +| + +|`socketlabel` +|Метка политики для `socket` +| +|=== + +Определить, могут ли учётные данные субъекта прослушивать переданный сокет (вызывать listen). Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-cred-check-vnode-lookup]] +==== `mpo_check_vnode_lookup` + +[source, c] +---- +int mpo_check_vnode_lookup(struct ucred *cred, struct vnode *dvp, + struct label *dlabel, struct componentname *cnp); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`dvp` +|Объект; vnode +| + +|`dlabel` +|Метка политики для `dvp` +| + +|`cnp` +|Имя компонента, который ищется +| +|=== + +Определить, могут ли учётные данные субъекта выполнить поиск указанного имени в каталог с переданном vnode. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-cred-check-vnode-open]] +==== `mpo_check_vnode_open` + +[source, c] +---- +int mpo_check_vnode_open(struct ucred *cred, struct vnode *vp, + struct label *label, int acc_mode); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode +| + +|`label` +|Метка политики для `vp` +| + +|`acc_mode` +|режим доступа от man:open[2] +| +|=== + +Определить, могут ли учетные данные субъекта выполнить операцию открытия переданного vnode с указанным режимом доступа. Возвращает 0 в случае успеха или значение errno при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[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); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`dvp` +|Объект; vnode каталога +| + +|`dlabel` +|Метка политики для `dvp` +| +|=== + +Определить, могут ли учетные данные субъекта выполнить операцию `readdir` для переданного vnode каталога. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-cred-check-vnode-readlink]] +==== `mpo_check_vnode_readlink` + +[source, c] +---- +int mpo_check_vnode_readlink(struct ucred *cred, struct vnode *vp, + struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode +| + +|`label` +|Метка политики для `vp` +| +|=== + +Определить, могут ли учетные данные субъекта выполнить операцию `readlink` для переданного символьного vnode. Возвращает 0 в случае успеха или значение `errno` в случае ошибки. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. Этот вызов может быть выполнен в различных ситуациях, включая явный вызов `readlink` пользовательским процессом или неявный `readlink` во время поиска имени процессом. + +[[mac-mpo-cred-check-vnode-revoke]] +==== `mpo_check_vnode_revoke` + +[source, c] +---- +int mpo_check_vnode_revoke(struct ucred *cred, struct vnode *vp, + struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode +| + +|`label` +|Метка политики для `vp` +| +|=== + +Определить, могут ли учётные данные субъекта отозвать доступ к переданному vnode. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-cred-check-vnode-setacl]] +==== `mpo_check_vnode_setacl` + +[source, c] +---- +int mpo_check_vnode_setacl(struct ucred *cred, struct vnode *vp, + struct label *label, acl_type_t type, struct acl *acl); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode +| + +|`label` +|Метка политики для `vp` +| + +|`type` +|Тип ACL +| + +|`acl` +|ACL +| +|=== + +Определить, могут ли учётные данные субъекта установить переданный ACL указанного типа для переданного vnode. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-cred-check-vnode-setextattr]] +==== `mpo_check_vnode_setextattr` + +[source, c] +---- +int mpo_check_vnode_setextattr(struct ucred *cred, struct vnode *vp, + struct label *label, int attrnamespace, const char *name, struct uio *uio); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode +| + +|`label` +|Метка политики для `vp` +| + +|`attrnamespace` +|Пространство имен расширенных атрибутов +| + +|`name` +|Имя расширенного атрибута +| + +|`uio` +|Указатель структуры ввода-вывода; см. man:uio[9] +| +|=== + +Определить, могут ли учетные данные субъекта установить расширенный атрибут с переданным именем и пространством имен на переданном vnode. Политики, реализующие метки безопасности, основанные на расширенных атрибутах, могут предусматривать дополнительные защиты для этих атрибутов. Кроме того, политикам следует избегать принятия решений на основе данных, на которые ссылается `uio`, так как существует потенциальное состояние гонки между этой проверкой и фактической операцией. `uio` также может быть `NULL`, если выполняется операция удаления. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-cred-check-vnode-setflags]] +==== `mpo_check_vnode_setflags` + +[source, c] +---- +int mpo_check_vnode_setflags(struct ucred *cred, struct vnode *vp, + struct label *label, u_long flags); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode +| + +|`label` +|Метка политики для `vp` +| + +|`flags` +|Флаги файла; см. man:chflags[2] +| +|=== + +Определить, могут ли учётные данные субъекта установить переданные флаги на переданном vnode. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-cred-check-vnode-setmode]] +==== `mpo_check_vnode_setmode` + +[source, c] +---- +int mpo_check_vnode_setmode(struct ucred *cred, struct vnode *vp, + struct label *label, mode_t mode); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode +| + +|`label` +|Метка политики для `vp` +| + +|`mode` +|Режим файла; см. man:chmod[2] +| +|=== + +Определить, могут ли учётные данные субъекта установить переданный режим для переданного vnode. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при недостатке привилегий. + +[[mac-mpo-cred-check-vnode-setowner]] +==== `mpo_check_vnode_setowner` + +[source, c] +---- +int mpo_check_vnode_setowner(struct ucred *cred, struct vnode *vp, + struct label *label, uid_t uid, gid_t gid); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode +| + +|`label` +|Метка политики для `vp` +| + +|`uid` +|User ID +| + +|`gid` +|Идентификатор группы +| +|=== + +Определить, могут ли учетные данные субъекта установить переданный uid и переданный gid в качестве uid файла и gid файла для переданного vnode. Идентификаторы могут быть установлены в (`-1`) для запроса отсутствия обновления. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[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); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vp +| + +|`label` +|Метка политики для `vp` +| + +|`atime` +|Время доступа; см. man:utimes[2] +| + +|`mtime` +|Время изменения; см. man:utimes[2] +| +|=== + +Определить, могут ли учётные данные субъекта установить переданные времена доступа на переданном vnode. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-cred-check-proc-sched]] +==== `mpo_check_proc_sched` + +[source, c] +---- +int mpo_check_proc_sched(struct ucred *ucred, struct proc *proc); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`proc` +|Объект; процесс +| +|=== + +Определить, могут ли учетные данные субъекта изменить параметры планирования переданного процесса. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки, EPERM при отсутствии привилегий или ESRCH для ограничения видимости. + +См. man:setpriority[2] для получения дополнительной информации. + +[[mac-mpo-cred-check-proc-signal]] +==== `mpo_check_proc_signal` + +[source, c] +---- +int mpo_check_proc_signal(struct ucred *cred, struct proc *proc, int signal); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`proc` +|Объект; процесс +| + +|`signal` +|Сигнал; см. man:kill[2] +| +|=== + +Определить, могут ли учётные данные субъекта доставить указанный сигнал указанному процессу. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые коды ошибок: EACCES при несоответствии метки, EPERM при недостатке прав или ESRCH для ограничения видимости. + +[[mac-mpo-cred-check-vnode-stat]] +==== `mpo_check_vnode_stat` + +[source, c] +---- +int mpo_check_vnode_stat(struct ucred *cred, struct vnode *vp, + struct label *label); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Объект; vnode +| + +|`label` +|Метка политики для `vp` +| +|=== + +Определить, могут ли учетные данные субъекта выполнять `stat` для переданного vnode. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +См. man:stat[2] для получения дополнительной информации. + +[[mac-mpo-cred-check-ifnet-transmit]] +==== `mpo_check_ifnet_transmit` + +[source, c] +---- +int mpo_check_ifnet_transmit(struct ucred *cred, struct ifnet *ifnet, + struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`ifnet` +|Сетевой интерфейс +| + +|`ifnetlabel` +|Метка политики для `ifnet` +| + +|`mbuf` +|Объект; mbuf для отправки +| + +|`mbuflabel` +|Метка политики для `mbuf` +| +|=== + +Определить, может ли сетевой интерфейс передать mbuf, переданный в качестве параметра. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-cred-check-socket-deliver]] +==== `mpo_check_socket_deliver` + +[source, c] +---- +int mpo_check_socket_deliver(struct ucred *cred, struct ifnet *ifnet, + struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`ifnet` +|Сетевой интерфейс +| + +|`ifnetlabel` +|Метка политики для `ifnet` +| + +|`mbuf` +|Объект; mbuf для доставки +| + +|`mbuflabel` +|Метка политики для `mbuf` +| +|=== + +Определить, может ли сокет принять датаграмму, хранящуюся в переданном заголовке mbuf. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. + +[[mac-mpo-check-socket-visible]] +==== `mpo_check_socket_visible` + +[source, c] +---- +int mpo_check_socket_visible(struct ucred *cred, struct socket *so, + struct label *socketlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +|Неизменяемый + +|`so` +|Объект; сокет +| + +|`socketlabel` +|Метка политики для `so` +| +|=== + +Определить, могут ли учетные данные субъекта cred "видеть" переданный сокет (`socket`), используя функции системного мониторинга, такие как те, что применяются в man:netstat[8] и man:sockstat[1]. Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии меток, EPERM при отсутствии привилегий или ESRCH для скрытия видимости. + +[[mac-mpo-check-system-acct]] +==== `mpo_check_system_acct` + +[source, c] +---- +int mpo_check_system_acct(struct ucred *ucred, struct vnode *vp, + struct label *vlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`ucred` +|Учетные данные субъекта +| + +|`vp` +|Файл учёта; man:acct[5] +| + +|`vlabel` +|Метка, связанная с `vp` +| +|=== + +Определить, следует ли разрешить субъекту включение учёта, основываясь на его метке и метке файла журнала учёта. + +[[mac-mpo-check-system-nfsd]] +==== `mpo_check_system_nfsd` + +[source, c] +---- +int mpo_check_system_nfsd(struct ucred *cred); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| +|=== + +Определить, следует ли разрешить субъекту вызывать man:nfssvc[2]. + +[[mac-mpo-check-system-reboot]] +==== `mpo_check_system_reboot` + +[source, c] +---- +int mpo_check_system_reboot(struct ucred *cred, int howto); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`howto` +|Параметр `howto` из man:reboot[2] +| +|=== + +Определить, следует ли разрешить субъекту перезагружать систему указанным способом. + +[[mac-mpo-check-system-settime]] +==== `mpo_check_system_settime` + +[source, c] +---- +int mpo_check_system_settime(struct ucred *cred); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| +|=== + +Определить, разрешено ли пользователю устанавливать системные часы. + +[[mac-mpo-check-system-swapon]] +==== `mpo_check_system_swapon` + +[source, c] +---- +int mpo_check_system_swapon(struct ucred *cred, struct vnode *vp, + struct label *vlabel); +---- + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`vp` +|Устройство подкачки +| + +|`vlabel` +|Метка, связанная с `vp` +| +|=== + +Определить, следует ли разрешить субъекту добавлять `vp` как устройство подкачки. + +[[mac-mpo-check-system-sysctl]] +==== `mpo_check_system_sysctl` + +[source, c] +---- +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] +[cols="1,1,1", frame="none", options="header"] +|=== +| Параметр +| Описание +| Блокировка + +|`cred` +|Учетные данные субъекта +| + +|`name` +|См. man:sysctl[3] +| + +|`namelen` +| +| + +|`old` +| +| + +|`oldlenp` +| +| + +|`inkernel` +|Логический; `1`, если вызвано из ядра +| + +|`new` +|См. man:sysctl[3] +| + +|`newlen` +| +| +|=== + +Определить, следует ли разрешить субъекту выполнять указанную транзакцию man:sysctl[3]. + +[[mac-label-management]] +=== Вызовы при управления метками + +События изменения метки происходят, когда пользовательский процесс запрашивает изменение метки на объекте. Происходит двухэтапное обновление: сначала выполняется проверка контроля доступа, чтобы определить, является ли обновление допустимым и разрешённым, а затем само обновление выполняется через отдельную точку входа. Точки входа для изменения метки обычно принимают объект, ссылку на метку объекта и новую метку, предоставленную процессом. Выделение памяти во время изменения метки не рекомендуется, так как вызовы изменения метки не могут завершиться неудачей (ошибка должна быть обнаружена ранее на этапе проверки изменения метки). + +[[mac-userland-arch]] +== Пользовательская архитектура + +В фреймворк TrustedBSD MAC входит ряд элементов, не зависящих от политик, включая интерфейсы MAC-библиотеки для абстрактного управления метками, изменения в управлении системными учетными данными и библиотеках входа в систему для поддержки назначения MAC-меток пользователям, а также набор инструментов для мониторинга и изменения меток процессов, файлов и сетевых интерфейсов. Более подробная информация о пользовательской архитектуре будет добавлена в этот раздел в ближайшее время. + +[[mac-userland-labels]] +=== API для управления метками, не зависящими от политики + +Фреймворк TrustedBSD MAC предоставляет ряд библиотечных и системных вызовов, позволяющих приложениям управлять метками MAC на объектах с использованием политико-независимого интерфейса. Это позволяет приложениям манипулировать метками для различных политик без необходимости поддержки конкретных политик. Эти интерфейсы используются универсальными инструментами, такими как man:ifconfig[8], man:ls[1] и man:ps[1], для просмотра меток на сетевых интерфейсах, файлах и процессах. API также поддерживают инструменты управления MAC, включая man:getfmac[8], man:getpmac[8], man:setfmac[8], man:setfsmac[8] и man:setpmac[8]. API MAC документированы в man:mac[3]. + +Приложения обрабатывают метки MAC в двух формах: внутренней форме, используемой для возврата и установки меток для процессов и объектов (`mac_t`), и внешней форме, основанной на строках C, подходящих для хранения в конфигурационных файлах, отображения пользователю или ввода от пользователя. Каждая метка MAC содержит ряд элементов, каждый из которых состоит из пары имя-значение. Модули политик в ядре привязываются к определённым именам и интерпретируют значения специфичным для политики образом. Во внешней строковой форме метки представляются списком пар имя-значение, разделённых запятыми и символом `/`. Метки могут быть напрямую преобразованы в текст и обратно с использованием предоставленных API; при извлечении меток из ядра внутреннее хранилище меток должно быть сначала подготовлено для желаемого набора элементов метки. Обычно это делается одним из двух способов: с использованием man:mac_prepare[3] и произвольного списка желаемых элементов метки, или одной из вариаций вызова, который загружает набор элементов по умолчанию из конфигурационного файла man:mac.conf[5]. Значения по умолчанию для каждого объекта позволяют разработчикам приложений удобно отображать метки, связанные с объектами, без необходимости знать о присутствующих в системе политиках. + +[NOTE] +==== +В настоящее время прямое манипулирование элементами меток, кроме как путем преобразования в текстовую строку, редактирования строки и обратного преобразования во внутреннюю метку, не поддерживается библиотекой MAC. Такие интерфейсы могут быть добавлены в будущем, если окажется, что они необходимы разработчикам приложений. +==== + +[[mac-userland-credentials]] +=== Привязка меток к пользователям + +Стандартный интерфейс управления контекстом пользователя, man:setusercontext[3], был изменён для получения меток MAC, связанных с классом пользователя, из man:login.conf[5]. Эти метки устанавливаются вместе с остальным контекстом пользователя, когда указан `LOGIN_SETALL` или явно указан `LOGIN_SETMAC`. + +[NOTE] +==== +Ожидается, что в будущей версии FreeBSD база данных меток MAC будет отделена от абстракции классов пользователей [.filename]#login.conf# и будет поддерживаться в отдельной базе данных. Однако API man:setusercontext[3] должно остаться неизменным после такого изменения. +==== + +[[mac-conclusion]] +== Заключение + +Фреймворк TrustedBSD MAC позволяет модулям ядра расширять политику безопасности системы высокоинтегрированным способом. Они могут делать это на основе существующих свойств объектов или данных меток, которые поддерживаются с помощью фреймворка MAC. Фреймворк достаточно гибкий для реализации различных типов политик, включая политики безопасности информационных потоков, такие как MLS и Biba, а также политики, основанные на существующих учетных данных BSD или защите файлов. Авторам политик может быть полезно ознакомиться с этой документацией, а также с существующими модулями безопасности при реализации новой службы безопасности. diff --git a/documentation/content/ru/books/arch-handbook/mac/_index.po b/documentation/content/ru/books/arch-handbook/mac/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/mac/_index.po @@ -0,0 +1,8639 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-12 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 "Фреймворк TrustedBSD MAC" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1 +#, no-wrap +msgid "Chapter 6. The TrustedBSD MAC Framework" +msgstr "Глава 6. Фреймворк TrustedBSD MAC" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:57 +#, no-wrap +msgid "MAC Documentation Copyright" +msgstr "Авторские права документации MAC" + +#. 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 "" +"Этот документ был разработан для проекта FreeBSD Крисом Костелло из Safeport " +"Network Services и Network Associates Laboratories, подразделения " +"исследований безопасности Network Associates, Inc., по контракту DARPA/" +"SPAWAR N66001-01-C-8035 (\"CBOSS\") в рамках исследовательской программы " +"DARPA CHATS." + +#. 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 "" +"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:" + +#. 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 "" +"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." + +#. 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 "" +"Распространение в скомпилированной форме (преобразованное в другие DTD, " +"конвертированное в PDF, PostScript, RTF и другие форматы) должно включать " +"указанное выше уведомление об авторских правах, данный список условий и " +"следующий отказ от ответственности в документации и/или других материалах, " +"предоставляемых вместе с распространением." + +#. 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 "" +"ЭТА ДОКУМЕНТАЦИЯ ПРЕДОСТАВЛЯЕТСЯ NETWORKS ASSOCIATES TECHNOLOGY, INC «КАК " +"ЕСТЬ», И ЛЮБЫЕ ЯВНЫЕ ИЛИ ПОДРАЗУМЕВАЕМЫЕ ГАРАНТИИ, ВКЛЮЧАЯ, НО НЕ " +"ОГРАНИЧИВАЯСЬ ИМИ, ПОДРАЗУМЕВАЕМЫЕ ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ И " +"ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ ОТРИЦАЮТСЯ. НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ " +"NETWORKS ASSOCIATES TECHNOLOGY, INC НЕ НЕСЕТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ " +"ПРЯМЫЕ, КОСВЕННЫЕ, СЛУЧАЙНЫЕ, СПЕЦИАЛЬНЫЕ, ШТРАФНЫЕ ИЛИ КОСВЕННЫЕ УБЫТКИ " +"(ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ИМИ, ЗАТРАТЫ НА ЗАМЕНУ ТОВАРОВ ИЛИ УСЛУГ; " +"ПОТЕРЮ ИСПОЛЬЗОВАНИЯ, ДАННЫХ ИЛИ ПРИБЫЛИ; ЛИБО ПРЕРЫВАНИЕ БИЗНЕСА), " +"ВЫЗВАННЫЕ ЛЮБЫМ ОБРАЗОМ И НА ОСНОВАНИИ ЛЮБОЙ ТЕОРИИ ОТВЕТСТВЕННОСТИ, БУДЬ ТО " +"В РАМКАХ ДОГОВОРА, СТРОГОЙ ОТВЕТСТВЕННОСТИ ИЛИ ДЕЛИКТА (ВКЛЮЧАЯ НЕБРЕЖНОСТЬ " +"ИЛИ ИНОЕ), ВОЗНИКШИЕ ВСЛЕДСТВИЕ ИСПОЛЬЗОВАНИЯ ЭТОЙ ДОКУМЕНТАЦИИ, ДАЖЕ ЕСЛИ " +"БЫЛО ПРЕДУПРЕЖДЕНИЕ О ВОЗМОЖНОСТИ ТАКИХ УБЫТКОВ." + +#. 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 "" +"FreeBSD включает экспериментальную поддержку нескольких политик " +"обязательного контроля доступа, а также инфраструктуру для расширяемости " +"безопасности ядра — TrustedBSD MAC Framework. MAC Framework представляет " +"собой модульную инфраструктуру контроля доступа, позволяющую легко " +"встраивать новые политики безопасности в ядро, загружать их при старте " +"системы или динамически во время работы. Инфраструктура предоставляет " +"множество возможностей для упрощения реализации новых политик безопасности, " +"включая возможность легко присваивать метки безопасности (например, " +"информацию о конфиденциальности) объектам системы." + +#. 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 "" +"Эта глава представляет фреймворк политик MAC и содержит документацию для " +"образца модуля политики MAC." + +#. 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 "" +"Фреймворк TrustedBSD MAC предоставляет механизм для расширения модели " +"контроля доступа ядра во время компиляции или выполнения. Новые политики " +"системы могут быть реализованы в виде модулей ядра и связаны с ним; если " +"присутствуют несколько модулей политик, их результаты будут объединены. " +"Фреймворк MAC предоставляет различные инфраструктурные сервисы контроля " +"доступа для помощи разработчикам политик, включая поддержку временных и " +"постоянных меток безопасности объектов, не зависящих от политик. В настоящее " +"время эта поддержка считается экспериментальной." + +#. 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 "" +"Эта глава предоставляет информацию, предназначенную для разработчиков " +"модулей политик, а также потенциальных пользователей сред с поддержкой MAC, " +"чтобы узнать о том, как MAC Framework поддерживает расширение контроля " +"доступа в ядре." + +#. 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 "" +"Мандатное управление доступом (MAC — Mandatory Access Control) относится к " +"набору политик контроля доступа, которые в обязательном порядке применяются " +"операционной системой к пользователям. Политики MAC можно противопоставить " +"защите на основе дискреционного управления доступом (DAC — Discretionary " +"Access Control), при которой непривилегированные пользователи могут (по " +"своему усмотрению) защищать объекты. В традиционных UNIX-системах защита DAC " +"включает права доступа к файлам и списки контроля доступа; защита MAC " +"включает управление процессами, предотвращающее отладку между " +"пользователями, и межсетевые экраны. Различные политики MAC были разработаны " +"создателями операционных систем и исследователями безопасности, включая " +"политику конфиденциальности многоуровневой безопасности (MLS — Multi-Level " +"Security), политику целостности Biba, управление доступом на основе ролей " +"(RBAC — Role-Based Access Control), принудительное применение доменов и " +"типов (DTE — Domain and Type Enforcement) и принудительное применение типов " +"(TE — Type Enforcement). Каждая модель основывает решения на различных " +"факторах, включая идентификатор пользователя, роль и уровень доступа, а " +"также метки безопасности на объектах, представляющих такие концепции, как " +"конфиденциальность и целостность данных." + +#. 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 "" +"Фреймворк TrustedBSD MAC способен поддерживать модули политик, реализующие " +"все эти политики, а также широкий класс политик усиления защиты системы, " +"которые могут использовать существующие атрибуты безопасности, такие как " +"идентификаторы пользователей и групп, а также расширенные атрибуты файлов и " +"другие свойства системы. Кроме того, несмотря на название, фреймворк MAC " +"также может использоваться для реализации чисто дискреционных политик, " +"поскольку модулям политик предоставляется значительная гибкость в том, как " +"они авторизуют защиту." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:104 +#, no-wrap +msgid "MAC Framework Kernel Architecture" +msgstr "Архитектура MAC Framework в ядре" + +#. 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 "" +"Фреймворк TrustedBSD MAC позволяет модулям ядра расширять политику " +"безопасности операционной системы, а также предоставляет функциональность " +"инфраструктуры, необходимую многим модулям контроля доступа. Если " +"одновременно загружено несколько политик, фреймворк MAC полезным образом (в " +"некотором смысле полезным) объединит результаты этих политик." + +#. 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 "В рамках MAC Framework реализован ряд элементов ядра:" + +#. 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 "Точка входа API, вызываемая службами ядра" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:122 +msgid "Entry point API to policy modules" +msgstr "Точка входа API для модулей политик" + +#. 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 "`mac_syscall()` мультиплексный системный вызов" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:126 +msgid "Various security policies implemented as MAC policy modules" +msgstr "" +"Различные политики безопасности, реализованные в виде модулей политики MAC" + +#. 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 "" +"Фреймворком TrustedBSD MAC можно напрямую управлять с помощью sysctl, " +"параметров загрузчика и системных вызовов." + +#. 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 "" +"В большинстве случаев одноимённые параметры sysctl и настройки загрузчика " +"изменяют одни и те же параметры и управляют поведением, таким как применение " +"защитных механизмов, связанных с различными подсистемами ядра. Кроме того, " +"если в ядро включена поддержка отладки MAC, будет вестись несколько " +"счётчиков для отслеживания выделения меток. Обычно рекомендуется не " +"использовать общие настройки подсистем для управления поведением политик в " +"рабочих средах, так как они широко влияют на работу всех активных политик. " +"Вместо этого следует предпочитать настройки отдельных политик, поскольку они " +"обеспечивают более высокую детализацию и большую операционную " +"согласованность для модулей политик." + +#. 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 "" +"Поскольку набор активных политик может изменяться во время выполнения, а " +"вызов точек входа не является атомарным, требуется синхронизация для " +"предотвращения загрузки или выгрузки политик во время выполнения вызова " +"точки входа, фиксируя набор активных политик на время выполнения. Это " +"достигается с помощью счетчика занятости фреймворка: при входе в точку входа " +"счетчик увеличивается; при выходе из нее — уменьшается. Пока счетчик " +"занятости повышен, изменения списка политик запрещены, и потоки, пытающиеся " +"изменить список политик, будут ждать, пока список не освободится. Счетчик " +"занятости защищается мьютексом, а условная переменная используется для " +"пробуждения потоков, ожидающих изменений списка политик. Побочным эффектом " +"этой модели синхронизации является то, что рекурсивный вход в MAC Framework " +"из модуля политики разрешен, хотя обычно не используется." + +#. 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 "" +"Поскольку MAC Framework не может блокировать некоторые точки входа, обычная " +"блокировка сна не может быть использована; в результате попытка загрузки или " +"выгрузки может блокироваться на значительное время, ожидая, пока фреймворк " +"станет свободным." + +#. 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 "" +"Поскольку к объектам ядра обычно может обращаться более одного потока " +"одновременно, и допускается одновременный вход нескольких потоков в MAC " +"Framework, хранение атрибутов безопасности, поддерживаемое MAC Framework, " +"тщательно синхронизировано. Как правило, существующая синхронизация ядра для " +"данных объектов ядра используется для защиты меток безопасности MAC " +"Framework на объекте: например, метки MAC на сокетах защищаются с помощью " +"существующего мьютекса сокета. Аналогично, семантика параллельного доступа " +"обычно идентична семантике контейнерных объектов: для учетных данных " +"поддерживается семантика копирования при записи для содержимого меток, как и " +"для остальной структуры учетных данных. MAC Framework устанавливает " +"необходимые блокировки на объекты при вызове с ссылкой на объект. Авторам " +"политик необходимо учитывать эти семантики синхронизации, так как они иногда " +"ограничивают типы доступа к меткам: например, когда ссылка только для чтения " +"на учетные данные передается политике через точку входа, разрешены только " +"операции чтения для состояния метки, прикрепленного к учетным данным." + +#. 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 "" +"Модули политик должны быть написаны с учетом того, что множество потоков " +"ядра могут одновременно войти в одну или несколько точек входа политики из-" +"за параллельной и вытесняющей природы ядра FreeBSD. Если модуль политики " +"использует изменяемое состояние, это может потребовать применения примитивов " +"синхронизации внутри политики, чтобы предотвратить несогласованные " +"представления этого состояния, ведущие к некорректной работе политики. " +"Политики, как правило, могут использовать существующие примитивы " +"синхронизации FreeBSD для этой цели, включая мьютексы, блокировки с " +"ожиданием, условные переменные и счётные семафоры. Однако политики должны " +"быть написаны так, чтобы применять эти примитивы осторожно, соблюдая " +"существующие порядки блокировок в ядре и учитывая, что некоторые точки входа " +"не допускают ожидания, ограничивая использование примитивов в этих точках " +"входа мьютексами и операциями пробуждения." + +#. 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 "" +"Фреймворк MAC поддерживает два списка активных политик: статический список и " +"динамический список. Списки отличаются только в отношении их семантики " +"блокировки: для использования статического списка не требуется повышенный " +"счетчик ссылок. Когда загружаются модули ядра, содержащие политики " +"фреймворка MAC, модуль политики использует `SYSINIT` для вызова функции " +"регистрации; когда модуль политики выгружается, `SYSINIT` аналогично " +"вызывает функцию отмены регистрации. Регистрация может завершиться неудачей, " +"если модуль политики загружается более одного раза, если для регистрации " +"недостаточно ресурсов (например, политика может требовать маркировки, а " +"доступного состояния маркировки может быть недостаточно), или другие " +"предварительные условия политики могут не выполняться (некоторые политики " +"могут быть загружены только до загрузки системы). Аналогично, отмена " +"регистрации может завершиться неудачей, если политика помечена как " +"невыгружаемая." + +#. 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 "" +"Ядро взаимодействует с MAC Framework двумя способами: вызывает набор API для " +"уведомления фреймворка о соответствующих событиях и предоставляет указатель " +"на структуру меток, не зависящую от политики, в объектах, связанных с " +"безопасностью. Указатель метки управляется MAC Framework через точки входа " +"управления метками, что позволяет фреймворку предоставлять службу маркировки " +"модулям политик с относительно минимальными изменениями в подсистеме ядра, " +"управляющей объектом. Например, указатели меток были добавлены к процессам, " +"учетным данным процессов, сокетам, каналам, vnode, Mbuf, сетевым " +"интерфейсам, очередям сборки IP-пакетов и множеству других структур, " +"связанных с безопасностью. Ядро также вызывает MAC Framework при принятии " +"важных решений по безопасности, позволяя модулям политик дополнять эти " +"решения на основе собственных критериев (включая, возможно, данные, " +"хранящиеся в метках безопасности). Большинство этих критически важных " +"решений по безопасности будут явными проверками контроля доступа; однако " +"некоторые влияют на более общие функции принятия решений, такие как " +"сопоставление пакетов для сокетов и переход меток при выполнении программы." + +#. 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 "" +"Поскольку многие интересные расширения контроля доступа зависят от меток " +"безопасности объектов, MAC Framework предоставляет набор системных вызовов " +"для управления метками, не зависящих от политик, охватывающих различные " +"объекты, доступные пользователю. Общие типы меток включают идентификаторы " +"разделов, метки конфиденциальности, метки целостности, отделы (compartment), " +"домены, роли и типы. Под \"не зависящими от политик\" подразумевается, что " +"модули политик могут полностью определять семантику метаданных, связанных с " +"объектом. Модули политик участвуют в интернализации и экстернализации " +"строковых меток, предоставляемых пользовательскими приложениями, и могут при " +"необходимости предоставлять приложениям несколько элементов меток." + +#. 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 "" +"Метки в памяти хранятся в `struct label`, выделяемой через slab-аллокатор. " +"Эта структура состоит из массива фиксированной длины, содержащего " +"объединения, каждое из которых хранит указатель `void *` и значение типа " +"`long`. Политикам, регистрирующим хранилище меток, назначается идентификатор " +"\"слота\", который может использоваться для разыменования хранилища меток. " +"Семантика хранилища полностью определяется модулем политики: модулям " +"предоставляется набор точек входа, связанных с жизненным циклом объектов " +"ядра, включая инициализацию, связывание/создание и уничтожение. Используя " +"эти интерфейсы, можно реализовать подсчёт ссылок и другие модели хранения. " +"Прямой доступ к структуре объекта, как правило, не требуется модулям " +"политики для получения метки, поскольку MAC Framework обычно передаёт в " +"точки входа как указатель на объект, так и прямой указатель на метку " +"объекта. Основным исключением из этого правила являются учётные данные " +"процесса, для доступа к метке которых требуется ручное разыменование. Это " +"может измениться в будущих версиях MAC Framework." + +#. 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 "" +"Входные точки инициализации часто включают флаг режима сна, указывающий, " +"разрешено ли инициализации переходить в режим сна; если сон не разрешен, " +"может быть возвращена ошибка для отмены выделения метки (и, следовательно, " +"объекта). Это может произойти, например, в сетевом стеке во время обработки " +"прерывания, где сон не разрешен, или пока вызывающий удерживает мьютекс. Из-" +"за затрат производительности на поддержание меток на передаваемых сетевых " +"пакетах (Mbuf), политики должны явно объявлять требование о выделении меток " +"для Mbuf. Динамически загружаемые политики, использующие метки, должны быть " +"способны обрабатывать случай, когда их функция инициализации не была вызвана " +"для объекта, так как объекты могут уже существовать при загрузке политики. " +"MAC Framework гарантирует, что неинициализированные слоты меток будут " +"содержать значение 0 или NULL, что политики могут использовать для " +"обнаружения неинициализированных значений. Однако, поскольку выделение меток " +"для Mbuf условно, политики также должны быть способны обрабатывать указатель " +"на метку NULL для Mbuf, если они были загружены динамически." + +#. 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 "" +"В случае меток файловых систем предусмотрена специальная поддержка для " +"постоянного хранения меток безопасности в расширенных атрибутах. Там, где " +"это возможно, используются транзакции расширенных атрибутов, чтобы " +"обеспечить согласованные составные обновления меток безопасности на vnode — " +"в настоящее время такая поддержка присутствует только в файловой системе " +"UFS2. Авторы политик могут выбрать реализацию многометочных меток объектов " +"файловой системы с использованием одного (или нескольких) расширенных " +"атрибутов. По соображениям эффективности метка vnode (`v_label`) является " +"кэшем любой метки на диске; политики могут загружать значения в кэш при " +"создании vnode и обновлять кеш по мере необходимости. В результате нет " +"необходимости напрямую обращаться к расширенному атрибуту при каждой " +"проверке контроля доступа." + +#. 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 "" +"В рамках MAC Framework реализован ряд системных вызовов: большинство из них " +"поддерживают API для получения и управления метками, не зависящий от " +"политики и доступный пользовательским приложениям." + +#. 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 "" +"Вызовы управления метками принимают структуру описания метки `struct mac`, " +"которая содержит серию элементов метки MAC. Каждый элемент содержит строку с " +"именем и строку со значением. Каждой политике будет предоставлена " +"возможность запросить определённое имя элемента, позволяя политикам " +"предоставлять несколько независимых элементов, если это необходимо. Модули " +"политик выполняют интернализацию и экстернализацию между метками ядра и " +"метками, предоставленными пользователем, через точки входа, что позволяет " +"использовать различные семантики. Системные вызовы управления метками обычно " +"обёрнуты в функции пользовательской библиотеки для выполнения выделения " +"памяти и обработки ошибок, упрощая пользовательские приложения, которые " +"должны управлять метками." + +#. 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 "В ядре FreeBSD есть следующие системные вызовы, связанные с MAC:" + +#. 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 "" +"`mac_get_proc()` может использоваться для получения метки текущего процесса." + +#. 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 "" +"`mac_set_proc()` может использоваться, чтобы запросить изменение метки " +"текущего процесса." + +#. 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 "" +"`mac_get_fd()` может использоваться для получения метки объекта (файл, " +"сокет, канал, ...), на который ссылается файловый дескриптор." + +#. 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 "" +"`mac_get_file()` может использоваться для получения метки объекта, на " +"который ссылается путь в файловой системе." + +#. 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 "" +"`mac_set_fd()` может использоваться для запроса изменения метки объекта " +"(файл, сокет, канал, ...), на который ссылается файловый дескриптор." + +#. 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 "" +"`mac_set_file()` может использоваться для запроса изменения метки объекта, " +"указанного по пути в файловой системе." + +#. 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 "" +"`mac_syscall()` позволяет модулям политик создавать новые системные вызовы " +"без изменения таблицы системных вызовов; она принимает имя целевой политики, " +"номер операции и непрозрачный аргумент для использования политикой." + +#. 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 "" +"`mac_get_pid()` может использоваться для запроса метки другого процесса по " +"его идентификатору." + +#. 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 "" +"`mac_get_link()` идентична `mac_get_file()`, но не переходит по " +"символической ссылке, если она является конечным элементом пути, поэтому " +"может использоваться для получения метки на символьной ссылке." + +#. 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 "" +"`mac_set_link()` идентична `mac_set_file()`, за исключением того, что она не " +"следует по символической ссылке, если это конечный элемент пути, поэтому " +"может использоваться для изменения метки на символьной ссылке." + +#. 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 "" +"`mac_execve()` идентична системному вызову `execve()`, но также принимает " +"запрошенную метку, которая будет установлена для процесса при начале " +"выполнения новой программы. Это изменение метки при выполнении называется " +"\"переходом\"." + +#. 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 "" +"`mac_get_peer()`, фактически реализованный через параметр сокета, извлекает " +"метку удалённого узла на сокете, если она доступна." + +#. 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 "" +"В дополнение к этим системным вызовам, сетевые ioctl-команды `SIOCSIGMAC` и " +"`SIOCSIFMAC` позволяют получать и устанавливать метки на сетевых интерфейсах." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:265 +#, no-wrap +msgid "MAC Policy Architecture" +msgstr "Архитектура политик MAC" + +#. 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 "" +"Модули могут быть объявлены с использованием макроса `MAC_POLICY_SET()`, " +"который задаёт имя политики, предоставляет ссылку на вектор точек входа MAC, " +"указывает флаги загрузки, определяющие, как фреймворк политик должен " +"обрабатывать политику, и при необходимости запрашивает выделение состояния " +"метки фреймворком." + +#. 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 "" +"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" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:306 +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. .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." +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 "MPC_LOADTIME_FLAG_UNLOADOK" + +#. 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 "MPC_LOADTIME_FLAG_NOTLATE" + +#. 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 "MPC_LOADTIME_FLAG_LABELMBUFS" + +#. 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 "" +"Этот флаг указывает, что модуль политики требует маркировки Mbuf, и память " +"всегда должна выделяться для хранения меток Mbuf. По умолчанию MAC Framework " +"не выделяет память для хранения меток Mbuf, если хотя бы одна загруженная " +"политика не установила этот флаг. Это заметно улучшает производительность " +"сети, когда политики не требуют маркировки Mbuf. Существует опция ядра " +"`MAC_ALWAYS_LABEL_MBUF`, которая заставляет MAC Framework выделять память " +"для хранения меток Mbuf независимо от установки этого флага, и может быть " +"полезной в некоторых средах." + +#. 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 "" +"Политики, использующие `MPC_LOADTIME_FLAG_LABELMBUFS` без установленного " +"флага `MPC_LOADTIME_FLAG_NOTLATE`, должны корректно обрабатывать переданные " +"`NULL` указатели меток Mbuf в точках входа. Это необходимо, так как Mbuf в " +"процессе передачи без хранилища меток могут сохраняться после загрузки " +"политики, включающей маркировку Mbuf. Если политика загружена до активации " +"сетевой подсистемы (т.е. политика не загружается поздно), то все Mbuf " +"гарантированно имеют хранилище меток." + +#. 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 "" +"Четыре класса точек входа предоставляются политикам, зарегистрированным в " +"рамках системы: точки входа, связанные с регистрацией и управлением " +"политиками, точки входа, обозначающие инициализацию, создание, уничтожение и " +"другие события жизненного цикла объектов ядра, события, связанные с " +"решениями контроля доступа, на которые политика может влиять, и вызовы, " +"связанные с управлением метками на объектах. Кроме того, предоставляется " +"точка входа `mac_syscall()`, позволяющая политикам расширять интерфейс ядра " +"без регистрации новых системных вызовов." + +#. 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 "" +"Авторы модулей политик должны быть осведомлены о стратегии блокировок в " +"ядре, а также о том, какие блокировки объектов доступны на различных точках " +"входа. Им следует избегать сценариев взаимоблокировок, не захватывая " +"нелистовые блокировки внутри точек входа, а также соблюдать протокол " +"блокировок для доступа и изменения объектов. В частности, авторы должны " +"учитывать, что хотя необходимые блокировки для доступа к объектам и их " +"меткам обычно удерживаются, достаточные блокировки для изменения объекта или " +"его метки могут отсутствовать для всех точек входа. Информация о блокировках " +"аргументов документирована в описании точек входа фреймворка MAC." + +#. 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 "Справочник по точкам входа политики MAC" + +#. 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 "`mpo_init`" + +#. 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 "void mpo_init(struct mac_policy_conf *conf);\n" + +#. 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 "`conf`" + +#. 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 "Определение политики MAC" + +#. 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 "" +"Событие загрузки политики. Мьютекс списка политик удерживается, поэтому " +"операции ожидания выполнить нельзя, а вызовы других подсистем ядра должны " +"осуществляться с осторожностью. Если во время инициализации политики " +"требуются потенциально блокирующие выделения памяти, их следует выполнять с " +"использованием отдельного модуля SYSINIT()." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:386 +#, no-wrap +msgid "`mpo_destroy`" +msgstr "`mpo_destroy`" + +#. 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 "void mpo_destroy(struct mac_policy_conf *conf);\n" + +#. 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 "`mpo_syscall`" + +#. 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 "int mpo_syscall(struct thread *td, int call, void *arg);\n" + +#. 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 "`td`" + +#. 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 "`call`" + +#. 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 "`arg`" + +#. 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 "" +"Этот точку входа предоставляет мультиплексированный системный вызов на " +"основе политик, что позволяет политикам предоставлять дополнительные сервисы " +"пользовательским процессам без регистрации конкретных системных вызовов. Имя " +"политики, указанное при регистрации, используется для демультиплексирования " +"вызовов из пользовательского пространства, а аргументы будут переданы в эту " +"точку входа. При реализации новых сервисов модули безопасности должны " +"убедиться, что вызывают соответствующие проверки контроля доступа из MAC-" +"фреймворка по мере необходимости. Например, если политика реализует " +"расширенную функциональность сигналов, она должна вызывать необходимые " +"проверки контроля доступа сигналов для задействования MAC-фреймворка и " +"других зарегистрированных политик." + +#. 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 "" +"Модули в настоящее время должны самостоятельно выполнять `copyin()` для " +"данных системного вызова." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:447 +#, no-wrap +msgid "`mpo_thread_userret`" +msgstr "`mpo_thread_userret`" + +#. 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 "void mpo_thread_userret(struct thread *td);\n" + +#. 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 "" +"Этот точка входа позволяет модулям политики выполнять события, связанные с " +"MAC, когда поток возвращается в пользовательское пространство, через возврат " +"системного вызова, возврат из ловушки или иным образом. Это необходимо для " +"политик, имеющих плавающие метки процессов, так как не всегда возможно " +"получить блокировку процесса в произвольных точках стека во время обработки " +"системного вызова; метки процессов могут представлять традиционные данные " +"аутентификации, информацию об истории процесса или другие данные. Для " +"использования этого механизма предполагаемые изменения метки учётных данных " +"процесса могут быть сохранены в `p_label`, защищённом спин-блокировкой для " +"каждой политики, а затем установить флаг `TDF_ASTPENDING` для потока и флаг " +"`PS_MACPENDM` для процесса, чтобы запланировать вызов точки входа `userret`. " +"С этой точки входа политика может создать замену учётных данных с меньшими " +"опасениями относительно контекста блокировки. Авторам политик следует " +"учитывать, что порядок событий, связанных с планированием AST и выполнением " +"AST, может быть сложным и переплетённым в многопоточных приложениях." + +#. 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 "`mpo_init_bpfdesc_label`" + +#. 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 "void mpo_init_bpfdesc_label(struct label *label);\n" + +#. 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 "`label`" + +#. 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 "" +"Инициализировать метку на только что созданном bpfdesc (дескрипторе BPF). " +"Разрешено использование режима сна." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:499 +#, no-wrap +msgid "`mpo_init_cred_label`" +msgstr "`mpo_init_cred_label`" + +#. 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 "void mpo_init_cred_label(struct label *label);\n" + +#. 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 "`mpo_init_devfsdirent_label`" + +#. 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 "void mpo_init_devfsdirent_label(struct label *label);\n" + +#. 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 "" +"Инициализировать метку на только что созданной записи devfs. Разрешено " +"использование режима сна." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:545 +#, no-wrap +msgid "`mpo_init_ifnet_label`" +msgstr "`mpo_init_ifnet_label`" + +#. 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 "void mpo_init_ifnet_label(struct label *label);\n" + +#. 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 "`mpo_init_ipq_label`" + +#. 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 "void mpo_init_ipq_label(struct label *label, int flag);\n" + +#. 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 "`flag`" + +#. 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 "Спящий/неспящий man:malloc[9]; см. ниже" + +#. 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 "" +"Инициализировать метку в только что созданной очереди сборки IP-фрагментов. " +"Поле `flag` может принимать одно из значений M_WAITOK или M_NOWAIT и должно " +"использоваться, чтобы избежать выполнения \"спящего\" man:malloc[9] во время " +"этого вызова инициализации. Выделение очереди сборки IP-фрагментов часто " +"происходит в средах, чувствительных к производительности, и реализация " +"должна избегать \"спящих\" или длительных операций. Этой точке входа " +"разрешено завершаться неудачей, что приведёт к невозможности выделения " +"очереди сборки IP-фрагментов." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:597 +#, no-wrap +msgid "`mpo_init_mbuf_label`" +msgstr "`mpo_init_mbuf_label`" + +#. 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 "void mpo_init_mbuf_label(int flag, struct label *label);\n" + +#. 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 "" +"Инициализировать на только что созданном заголовке пакета mbuf метку " +"(`mbuf`). Поле `flag` может принимать одно из значений M_WAITOK или M_NOWAIT " +"и должно использоваться, чтобы избежать выполнения \"спящего\" man:malloc[9] " +"во время этого вызова инициализации. Выделение mbuf часто происходит в " +"чувствительных к производительности средах, и реализация должна избегать " +"\"спящего\" режима или длительных операций. Этой точке входа разрешено " +"завершаться неудачей, что приведёт к невозможности выделения заголовка mbuf." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:626 +#, no-wrap +msgid "`mpo_init_mount_label`" +msgstr "`mpo_init_mount_label`" + +#. 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 "void mpo_init_mount_label(struct label *mntlabel, struct label *fslabel);\n" + +#. 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 "`mntlabel`" + +#. 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 "`fslabel`" + +#. 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 "`mpo_init_mount_fs_label`" + +#. 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 "void mpo_init_mount_fs_label(struct label *label);\n" + +#. 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 "`mpo_init_pipe_label`" + +#. 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 "void mpo_init_pipe_label(struct label *label);\n" + +#. 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 "`mpo_init_socket_label`" + +#. 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 "void mpo_init_socket_label(struct label *label, int flag);\n" + +#. 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 "флаги man:malloc[9]" + +#. 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 "" +"Инициализировать метку для нового сокета. Поле `flag` может принимать одно " +"из значений M_WAITOK или M_NOWAIT и должно использоваться, чтобы избежать " +"выполнения спящего man:malloc[9] во время этого вызова инициализации." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:726 +#, no-wrap +msgid "`mpo_init_socket_peer_label`" +msgstr "`mpo_init_socket_peer_label`" + +#. 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 "void mpo_init_socket_peer_label(struct label *label, int flag);\n" + +#. 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 "" +"Инициализировать метку однорангового узла (peer) для вновь созданного " +"сокета. Поле `flag` может принимать одно из значений M_WAITOK или M_NOWAIT и " +"должно использоваться для избежания выполнения спящего man:malloc[9] во " +"время этого вызова инициализации." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:753 +#, no-wrap +msgid "`mpo_init_proc_label`" +msgstr "`mpo_init_proc_label`" + +#. 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 "void mpo_init_proc_label(struct label *label);\n" + +#. 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 "`mpo_init_vnode_label`" + +#. 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 "void mpo_init_vnode_label(struct label *label);\n" + +#. 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 "" +"Инициализировать метку на только что созданном vnode. Разрешено " +"приостанавливать выполнение." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:799 +#, no-wrap +msgid "`mpo_destroy_bpfdesc_label`" +msgstr "`mpo_destroy_bpfdesc_label`" + +#. 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 "void mpo_destroy_bpfdesc_label(struct label *label);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:815 +#, no-wrap +msgid "bpfdesc label" +msgstr "bpfdesc label" + +#. 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 "" +"Уничтожить метку на дескрипторе BPF. В этой точке входа политика должна " +"освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно " +"было уничтожить." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:822 +#, no-wrap +msgid "`mpo_destroy_cred_label`" +msgstr "`mpo_destroy_cred_label`" + +#. 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 "void mpo_destroy_cred_label(struct label *label);\n" + +#. 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 "" +"Уничтожить метку на учетных данных. В этой точке входа модуль политики " +"должен освободить любое внутреннее хранилище, связанное с `label`, чтобы ее " +"можно было уничтожить." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:845 +#, no-wrap +msgid "`mpo_destroy_devfsdirent_label`" +msgstr "`mpo_destroy_devfsdirent_label`" + +#. 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 "void mpo_destroy_devfsdirent_label(struct label *label);\n" + +#. 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 "" +"Уничтожить метку на записи devfs. В этой точке входа модуль политики должен " +"освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно " +"было уничтожить." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:868 +#, no-wrap +msgid "`mpo_destroy_ifnet_label`" +msgstr "`mpo_destroy_ifnet_label`" + +#. 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 "void mpo_destroy_ifnet_label(struct label *label);\n" + +#. 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 "" +"Уничтожить метку на удаленном интерфейсе. В этой точке входа модуль политики " +"должен освободить любое внутреннее хранилище, связанное с `label`, чтобы ее " +"можно было уничтожить." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:891 +#, no-wrap +msgid "`mpo_destroy_ipq_label`" +msgstr "`mpo_destroy_ipq_label`" + +#. 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 "void mpo_destroy_ipq_label(struct label *label);\n" + +#. 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 "" +"Уничтожить метку в очереди IP-фрагментов. В этой точке входа модуль политики " +"должен освободить любое внутреннее хранилище, связанное с `label`, чтобы ее " +"можно было уничтожить." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:914 +#, no-wrap +msgid "`mpo_destroy_mbuf_label`" +msgstr "`mpo_destroy_mbuf_label`" + +#. 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 "void mpo_destroy_mbuf_label(struct label *label);\n" + +#. 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 "" +"Уничтожить метку в заголовке mbuf. В этой точке входа модуль политики должен " +"освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно " +"было уничтожить." + +#. 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 "`mpo_destroy_mount_label`" + +#. 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 "void mpo_destroy_mount_label(struct label *label);\n" + +#. 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 "" +"Уничтожить метки на точке монтирования. В этой точке входа модуль политики " +"должен освободить внутреннее хранилище, связанное с `mntlabel`, чтобы ее " +"можно было уничтожить." + +#. 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 "void mpo_destroy_mount_label(struct label *mntlabel, struct label *fslabel);\n" + +#. 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 "" +"Уничтожить метки на точке монтирования. В этой точке входа модуль политики " +"должен освободить внутреннее хранилище, связанное с `mntlabel` и `fslabel`, " +"чтобы их можно было уничтожить." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:987 +#, no-wrap +msgid "`mpo_destroy_socket_label`" +msgstr "`mpo_destroy_socket_label`" + +#. 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 "void mpo_destroy_socket_label(struct label *label);\n" + +#. 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 "" +"Уничтожить метку на сокете. В этой точке входа модуль политики должен " +"освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно " +"было уничтожить." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1010 +#, no-wrap +msgid "`mpo_destroy_socket_peer_label`" +msgstr "`mpo_destroy_socket_peer_label`" + +#. 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 "void mpo_destroy_socket_peer_label(struct label *peerlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1025 +#, no-wrap +msgid "`peerlabel`" +msgstr "`peerlabel`" + +#. 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 "" +"Уничтожить метку однорангового узла на сокете. В этой точке входа модуль " +"политики должен освободить любое внутреннее хранилище, связанное с `label`, " +"чтобы ее можно было уничтожить." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1033 +#, no-wrap +msgid "`mpo_destroy_pipe_label`" +msgstr "`mpo_destroy_pipe_label`" + +#. 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 "void mpo_destroy_pipe_label(struct label *label);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1049 +#, no-wrap +msgid "Pipe label" +msgstr "Метка канала (pipe)" + +#. 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 "" +"Уничтожить метку на канале. В этой точке входа модуль политики должен " +"освободить всю внутреннюю память, связанную с `label`, чтобы её можно было " +"уничтожить." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1056 +#, no-wrap +msgid "`mpo_destroy_proc_label`" +msgstr "`mpo_destroy_proc_label`" + +#. 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 "void mpo_destroy_proc_label(struct label *label);\n" + +#. 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 "" +"Уничтожить метку на процессе. В этой точке входа модуль политики должен " +"освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно " +"было уничтожить." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1079 +#, no-wrap +msgid "`mpo_destroy_vnode_label`" +msgstr "`mpo_destroy_vnode_label`" + +#. 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 "void mpo_destroy_vnode_label(struct label *label);\n" + +#. 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 "" +"Уничтожить метку на vnode. В этой точке входа модуль политики должен " +"освободить любое внутреннее хранилище, связанное с `label`, чтобы ее можно " +"было уничтожить." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1102 +#, no-wrap +msgid "`mpo_copy_mbuf_label`" +msgstr "`mpo_copy_mbuf_label`" + +#. 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 "void mpo_copy_mbuf_label(struct label *src, struct label *dest);\n" + +#. 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 "`src`" + +#. 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 "`dest`" + +#. 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 "Скопировать информацию метки из `src` в `dest`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1128 +#, no-wrap +msgid "`mpo_copy_pipe_label`" +msgstr "`mpo_copy_pipe_label`" + +#. 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 "void mpo_copy_pipe_label(struct label *src, struct label *dest);\n" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1154 +#, no-wrap +msgid "`mpo_copy_vnode_label`" +msgstr "`mpo_copy_vnode_label`" + +#. 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 "void mpo_copy_vnode_label(struct label *src, struct label *dest);\n" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1180 +#, no-wrap +msgid "`mpo_externalize_cred_label`" +msgstr "`mpo_externalize_cred_label`" + +#. 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 "" +"int mpo_externalize_cred_label(struct label *label, char *element_name,\n" +" struct sbuf *sb, int *claimed);\n" + +#. 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 "`element_name`" + +#. 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 "`sb`" + +#. 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 "`claimed`" + +#. 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 "Должно быть увеличено, когда `element_data` может быть заполнено." + +#. 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 "" +"Создать внешнее представление метки на основе переданной структуры метки. " +"Внешнее представление метки состоит из текстового представления содержимого " +"метки, которое может использоваться пользовательскими приложениями и " +"прочитано пользователем. В настоящее время будут вызываться точки входа " +"`externalize` всех политик, поэтому реализация должна проверить содержимое " +"`element_name` перед попыткой заполнить `sb`. Если `element_name` не " +"соответствует имени вашей политики, просто верните 0. Возвращайте ненулевое " +"значение только в случае ошибки при внешнем представлении данных метки. " +"После того как политика заполнит `element_data`, `*claimed` должен быть " +"увеличен." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1220 +#, no-wrap +msgid "`mpo_externalize_ifnet_label`" +msgstr "`mpo_externalize_ifnet_label`" + +#. 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 "" +"int mpo_externalize_ifnet_label(struct label *label, char *element_name,\n" +" struct sbuf *sb, int *claimed);\n" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1260 +#, no-wrap +msgid "`mpo_externalize_pipe_label`" +msgstr "`mpo_externalize_pipe_label`" + +#. 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 "" +"int mpo_externalize_pipe_label(struct label *label, char *element_name,\n" +" struct sbuf *sb, int *claimed);\n" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1300 +#, no-wrap +msgid "`mpo_externalize_socket_label`" +msgstr "`mpo_externalize_socket_label`" + +#. 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 "" +"int mpo_externalize_socket_label(struct label *label, char *element_name,\n" +" struct sbuf *sb, int *claimed);\n" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1340 +#, no-wrap +msgid "`mpo_externalize_socket_peer_label`" +msgstr "`mpo_externalize_socket_peer_label`" + +#. 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 "" +"int mpo_externalize_socket_peer_label(struct label *label, char *element_name,\n" +" struct sbuf *sb, int *claimed);\n" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1380 +#, no-wrap +msgid "`mpo_externalize_vnode_label`" +msgstr "`mpo_externalize_vnode_label`" + +#. 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 "" +"int mpo_externalize_vnode_label(struct label *label, char *element_name,\n" +" struct sbuf *sb, int *claimed);\n" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1420 +#, no-wrap +msgid "`mpo_internalize_cred_label`" +msgstr "`mpo_internalize_cred_label`" + +#. 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 "" +"int mpo_internalize_cred_label(struct label *label, char *element_name,\n" +" char *element_data, int *claimed);\n" + +#. 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 "`element_data`" + +#. 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 "" +"Создать внутреннюю структуру меток на основе данных метки вов нешнем " +"представлении в текстовом формате. В настоящее время, при запросе " +"преобразования во внутреннее представление вызываются точки входа " +"`internalize` всех политик, поэтому реализация должна сравнивать содержимое " +"`element_name` со своим именем, чтобы убедиться, что она должна " +"преобразовывать данные в `element_data`. Как и в точках входа `externalize`, " +"точка входа должна возвращать 0, если `element_name` не совпадает с её " +"собственным именем, или когда данные могут быть успешно преобразованы, в " +"этом случае `*claimed` должен быть увеличен." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1457 +#, no-wrap +msgid "`mpo_internalize_ifnet_label`" +msgstr "`mpo_internalize_ifnet_label`" + +#. 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 "" +"int mpo_internalize_ifnet_label(struct label *label, char *element_name,\n" +" char *element_data, int *claimed);\n" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1494 +#, no-wrap +msgid "`mpo_internalize_pipe_label`" +msgstr "`mpo_internalize_pipe_label`" + +#. 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 "" +"int mpo_internalize_pipe_label(struct label *label, char *element_name,\n" +" char *element_data, int *claimed);\n" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1531 +#, no-wrap +msgid "`mpo_internalize_socket_label`" +msgstr "`mpo_internalize_socket_label`" + +#. 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 "" +"int mpo_internalize_socket_label(struct label *label, char *element_name,\n" +" char *element_data, int *claimed);\n" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1568 +#, no-wrap +msgid "`mpo_internalize_vnode_label`" +msgstr "`mpo_internalize_vnode_label`" + +#. 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 "" +"int mpo_internalize_vnode_label(struct label *label, char *element_name,\n" +" char *element_data, int *claimed);\n" + +#. 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 "" +"Этот класс точек входа используется фреймворком MAC для разрешения политикам " +"поддерживать информацию о метках на объектах ядра. Для каждого помеченного " +"объекта ядра, представляющего интерес для политики MAC, могут быть " +"зарегистрированы точки входа для соответствующих событий жизненного цикла. " +"Все объекты реализуют хуки инициализации, создания и уничтожения. Некоторые " +"объекты также реализуют перемаркировку, позволяя пользовательским процессам " +"изменять метки на объектах. Некоторые объекты также реализуют специфичные " +"для объекта события, такие как события меток, связанные с повторной сборкой " +"IP. Типичный помеченный объект будет иметь следующий жизненный цикл точек " +"входа:" + +#. 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 "" +"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" + +#. 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 "" +"Создание метки происходит, когда структура ядра связывается с реальным " +"объектом ядра. Например, Mbuf могут быть выделены и оставаться " +"неиспользованными в пуле до тех пор, пока они не понадобятся. Выделение mbuf " +"приводит к инициализации метки на mbuf, но создание mbuf происходит, когда " +"mbuf связывается с датаграммой. Обычно для события создания предоставляется " +"контекст, включая обстоятельства создания и метки других значимых объектов в " +"процессе создания. Например, когда mbuf создаётся из сокета, сокет и его " +"метка будут переданы зарегистрированным политикам в дополнение к новому mbuf " +"и его метке. Выделение памяти в событиях создания не рекомендуется, так как " +"это может происходить в чувствительных к производительности участках ядра; " +"кроме того, вызовы создания не могут завершиться неудачей, поэтому " +"невозможность выделить память не может быть сообщена." + +#. 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 "" +"События, привящанные к объектам, обычно не попадают в другие классы событий " +"меток, но, как правило, предоставляют возможность изменить или обновить " +"метку объекта на основе дополнительного контекста. Например, метка в очереди " +"сборки IP-фрагментов может быть обновлена во время точки входа " +"`MAC_UPDATE_IPQ` в результате принятия дополнительного mbuf в эту очередь." + +#. 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 "" +"В дополнение к меткам, связанным с определёнными объектами ядра, существует " +"дополнительный класс меток: временные метки. Эти метки используются для " +"хранения информации об обновлениях, отправляемых пользовательскими " +"процессами. Они инициализируются и уничтожаются так же, как и другие типы " +"меток, но событие создания — это `MAC_INTERNALIZE`, которое принимает " +"пользовательскую метку для преобразования во внутреннее представление в ядре." + +#. 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 "`mpo_associate_vnode_devfs`" + +#. 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 "" +"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" + +#. 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 "`mp`" + +#. 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 "Точка монтирования devfs" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1674 +#, no-wrap +msgid "Devfs file system label (`mp->mnt_fslabel`)" +msgstr "Метка файловой системы devfs (`mp->mnt_fslabel`)" + +#. 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 "`de`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1678 +#, no-wrap +msgid "Devfs directory entry" +msgstr "Запись каталога devfs" + +#. 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 "`delabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1682 +#, no-wrap +msgid "Policy label associated with `de`" +msgstr "Метка политики, связанная с `de`" + +#. 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 "`vp`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1686 +#, no-wrap +msgid "vnode associated with `de`" +msgstr "узел vnode, связанный с `de`" + +#. 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 "`vlabel`" + +#. 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 "Метка политики, связанная с `vp`" + +#. 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 "" +"Заполнить метку (`vlabel`) для только что созданного devfs vnode на основе " +"записи каталога devfs, переданной в `de`, и её метки." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1696 +#, no-wrap +msgid "`mpo_associate_vnode_extattr`" +msgstr "`mpo_associate_vnode_extattr`" + +#. 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 "" +"int mpo_associate_vnode_extattr(struct mount *mp, struct label *fslabel,\n" +" struct vnode *vp, struct label *vlabel);\n" + +#. 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 "Узел vnode для метки" + +#. 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 "" +"Попытка получить метку для `vp` из расширенных атрибутов файловой системы. В " +"случае успеха возвращается значение `0`. Если получение расширенных " +"атрибутов не поддерживается, допустимым резервным вариантом является " +"копирование `fslabel` в `vlabel`. В случае ошибки должно быть возвращено " +"соответствующее значение `errno`." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1734 +#, no-wrap +msgid "`mpo_associate_vnode_singlelabel`" +msgstr "`mpo_associate_vnode_singlelabel`" + +#. 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 "" +"void mpo_associate_vnode_singlelabel(struct mount *mp, struct label *fslabel,\n" +" struct vnode *vp, struct label *vlabel);\n" + +#. 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 "" +"На файловых системах без поддержки multilabel эта точка входа вызывается для " +"установки метки политики для `vp` на основе метки файловой системы `fslabel`." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1769 +#, no-wrap +msgid "`mpo_create_devfs_device`" +msgstr "`mpo_create_devfs_device`" + +#. 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 "" +"void mpo_create_devfs_device(dev_t dev, struct devfs_dirent *devfs_dirent,\n" +" struct label *label);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1785 +#, no-wrap +msgid "`dev`" +msgstr "`dev`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1786 +#, no-wrap +msgid "Device corresponding with `devfs_dirent`" +msgstr "Устройство, соответствующее `devfs_dirent`" + +#. 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 "`devfs_dirent`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1790 +#, no-wrap +msgid "Devfs directory entry to be labeled." +msgstr "Запись в каталоге devfs, для которой создается метка." + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1794 +#, no-wrap +msgid "Label for `devfs_dirent` to be filled in." +msgstr "Метка для `devfs_dirent`, которую нужно заполнить." + +#. 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 "" +"Заполнить метку на devfs_dirent, создаваемом для переданного устройства. " +"Этот вызов будет выполнен при монтировании файловой системы устройств, её " +"восстановлении или при появлении нового устройства." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1801 +#, no-wrap +msgid "`mpo_create_devfs_directory`" +msgstr "`mpo_create_devfs_directory`" + +#. 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 "" +"void mpo_create_devfs_directory(char *dirname, int dirnamelen,\n" +" struct devfs_dirent *devfs_dirent, struct label *label);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1817 +#, no-wrap +msgid "`dirname`" +msgstr "`dirname`" + +#. 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 "`namelen`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1822 +#, no-wrap +msgid "Length of string `dirname`" +msgstr "Длина строки `dirname`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1826 +#, no-wrap +msgid "Devfs directory entry for directory being created." +msgstr "Запись в devfs для создаваемого каталога." + +#. 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 "" +"Заполнить метку на devfs_dirent, создаваемом для переданного каталога. Этот " +"вызов будет выполнен при монтировании файловой системы устройств, её " +"восстановлении или при появлении нового устройства, требующего определённой " +"иерархии каталогов." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1833 +#, no-wrap +msgid "`mpo_create_devfs_symlink`" +msgstr "`mpo_create_devfs_symlink`" + +#. 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 "" +"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" + +#. 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 "`cred`" + +#. 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 "`dd`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1859 +#, no-wrap +msgid "Link destination" +msgstr "Назначения cсылки" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1862 +#, no-wrap +msgid "`ddlabel`" +msgstr "`ddlabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1863 +#, no-wrap +msgid "Label associated with `dd`" +msgstr "Метка, связанная с `dd`" + +#. 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 "Метка, связанная с `de`" + +#. 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 "" +"Заполнить метку (`delabel`) для новой структуры man:devfs[5] символьной " +"ссылки." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1877 +#, no-wrap +msgid "`mpo_create_vnode_extattr`" +msgstr "`mpo_create_vnode_extattr`" + +#. 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 "" +"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" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1898 +#, no-wrap +msgid "`mount`" +msgstr "`mount`" + +#. 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 "`dvp`" + +#. 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 "Родительский каталог vnode" + +#. 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 "`dlabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1911 +#, no-wrap +msgid "Label associated with `dvp`" +msgstr "Метка, связанная с `dvp`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1915 +#, no-wrap +msgid "Newly created vnode" +msgstr "Вновь созданная vnode" + +#. 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 "`cnp`" + +#. 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 "Название компонента для `vp`" + +#. 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 "" +"Записать метку для `vp` в соответствующий расширенный атрибут. Если запись " +"прошла успешно, заполняет `vlabel` меткой и возвращает 0. В противном случае " +"вернет соответствующую ошибку." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1931 +#, no-wrap +msgid "`mpo_create_mount`" +msgstr "`mpo_create_mount`" + +#. 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 "" +"void mpo_create_mount(struct ucred *cred, struct mount *mp, struct label *mnt,\n" +" struct label *fslabel);\n" + +#. 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 "Метка политики для заполнения в `mp`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1960 +#, no-wrap +msgid "Policy label for the file system `mp` mounts." +msgstr "Метка политики для файловой системы, монтируемой в `mp`." + +#. 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 "`mpo_create_root_mount`" + +#. 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 "" +"void mpo_create_root_mount(struct ucred *cred, struct mount *mp,\n" +" struct label *mntlabel, struct label *fslabel);\n" + +#. 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 "См. crossref:mac[mac-mpo-create-mount, `mpo_create_mount`]." + +#. 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 "" +"Заполнить метки на точке монтирования, создаваемой переданными учетными " +"данными субъекта. Этот вызов будет выполнен при монтировании корневой " +"файловой системы после `mpo_create_mount;`." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:1989 +#, no-wrap +msgid "`mpo_relabel_vnode`" +msgstr "`mpo_relabel_vnode`" + +#. 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 "" +"void mpo_relabel_vnode(struct ucred *cred, struct vnode *vp,\n" +" struct label *vnodelabel, struct label *newlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2010 +#, no-wrap +msgid "vnode to relabel" +msgstr "vnode для перемаркировки" + +#. 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 "`vnodelabel`" + +#. 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 "Существующая метка политики для `vp`" + +#. 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 "`newlabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2018 +#, no-wrap +msgid "New, possibly partial label to replace `vnodelabel`" +msgstr "Новая, возможно частичная метка для замены `vnodelabel`" + +#. 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 "" +"Обновить метку на переданном vnode с учетом переданной обновленной метки " +"vnode и переданных учетных данных субъекта." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2024 +#, no-wrap +msgid "`mpo_setlabel_vnode_extattr`" +msgstr "`mpo_setlabel_vnode_extattr`" + +#. 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 "" +"int mpo_setlabel_vnode_extattr(struct ucred *cred, struct vnode *vp,\n" +" struct label *vlabel, struct label *intlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2045 +#, no-wrap +msgid "Vnode for which the label is being written" +msgstr "vnode, для которой записывается метка" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2052 +#, no-wrap +msgid "`intlabel`" +msgstr "`intlabel`" + +#. 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 "" +"Записать политику из `intlabel` в расширенный атрибут. Этот метод вызывается " +"из `vop_stdcreatevnode_ea`." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2060 +#, no-wrap +msgid "`mpo_update_devfsdirent`" +msgstr "`mpo_update_devfsdirent`" + +#. 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 "" +"void mpo_update_devfsdirent(struct devfs_dirent *devfs_dirent,\n" +" struct label *direntlabel, struct vnode *vp, struct label *vnodelabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2077 +#, no-wrap +msgid "Object; devfs directory entry" +msgstr "Объект; каталожная запись devfs" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2080 +#, no-wrap +msgid "`direntlabel`" +msgstr "`direntlabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2081 +#, no-wrap +msgid "Policy label for `devfs_dirent` to be updated." +msgstr "Метка политики для `devfs_dirent`, которая будет обновлена." + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2085 +#, no-wrap +msgid "Parent vnode" +msgstr "Родительский vnode" + +#. 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 "Метка политики для `vp`" + +#. 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 "" +"Обновить метку `devfs_dirent` из переданной метки devfs vnode. Этот вызов " +"будет выполнен, когда devfs vnode успешно перемаркирован, чтобы " +"зафиксировать изменение метки, чтобы оно сохранилось, даже если vnode будет " +"переиспользован. Он также будет выполнен при создании символьной ссылки в " +"devfs после вызова `mac_vnode_create_from_vnode` для инициализации метки " +"vnode." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2097 +#, no-wrap +msgid "IPC Object Labeling Event Operations" +msgstr "Действия с событиями меток объектов IPC" + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2100 +#, no-wrap +msgid "`mpo_create_mbuf_from_socket`" +msgstr "`mpo_create_mbuf_from_socket`" + +#. 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 "" +"void mpo_create_mbuf_from_socket(struct socket *so, struct label *socketlabel,\n" +" struct mbuf *m, struct label *mbuflabel);\n" + +#. 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 "`socket`" + +#. 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 "`socketlabel`" + +#. 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 "Метка политики для `socket`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2124 +#, no-wrap +msgid "`m`" +msgstr "`m`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2125 +#, no-wrap +msgid "Object; mbuf" +msgstr "Объект; mbuf" + +#. 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 "`mbuflabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2129 +#, no-wrap +msgid "Policy label to fill in for `m`" +msgstr "Метка политики для заполнения для `m`" + +#. 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 "" +"Установить метку на только что созданном заголовке mbuf из переданной метки " +"сокета. Этот вызов выполняется, когда новый датаграмма или сообщение " +"генерируется сокетом и сохраняется в переданном mbuf." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2136 +#, no-wrap +msgid "`mpo_create_pipe`" +msgstr "`mpo_create_pipe`" + +#. 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 "" +"void mpo_create_pipe(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel);\n" + +#. 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 "`pipe`" + +#. 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 "`pipelabel`" + +#. 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 "Метка политики, связанная с `pipe`" + +#. 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 "`mpo_create_socket`" + +#. 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 "" +"void mpo_create_socket(struct ucred *cred, struct socket *so,\n" +" struct label *socketlabel);\n" + +#. 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 "`so`" + +#. 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 "Метка для заполнения для `so`" + +#. 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 "`mpo_create_socket_from_socket`" + +#. 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 "" +"void mpo_create_socket_from_socket(struct socket *oldsocket,\n" +" struct label *oldsocketlabel, struct socket *newsocket,\n" +" struct label *newsocketlabel);\n" + +#. 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 "`oldsocket`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2218 +#, no-wrap +msgid "Listening socket" +msgstr "Сокет, вызвавший listen" + +#. 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 "`oldsocketlabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2222 +#, no-wrap +msgid "Policy label associated with `oldsocket`" +msgstr "Метка политики, связанная с `oldsocket`" + +#. 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 "`newsocket`" + +#. 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 "`newsocketlabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2230 +#, no-wrap +msgid "Policy label associated with `newsocketlabel`" +msgstr "Метка политики, связанная с `newsocketlabel`" + +#. 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 "" +"Создать метку сокета `newsocket`, только что принявшему соединение через " +"man:accept[2], на основе сокета `oldsocket`, вызвавшего man:listen[2] ." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2236 +#, no-wrap +msgid "`mpo_relabel_pipe`" +msgstr "`mpo_relabel_pipe`" + +#. 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 "" +"void mpo_relabel_pipe(struct ucred *cred, struct pipe *pipe,\n" +" struct label *oldlabel, struct label *newlabel);\n" + +#. 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 "`oldlabel`" + +#. 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 "Текущая метка политики, связанная с `pipe`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2265 +#, no-wrap +msgid "Policy label update to apply to `pipe`" +msgstr "Обновление метки политики для применения к `pipe`" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2269 +msgid "Apply a new label, `newlabel`, to `pipe`." +msgstr "Применить новую метку `newlabel` к `pipe`." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2271 +#, no-wrap +msgid "`mpo_relabel_socket`" +msgstr "`mpo_relabel_socket`" + +#. 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 "" +"void mpo_relabel_socket(struct ucred *cred, struct socket *so,\n" +" struct label *oldlabel, struct label *newlabel);\n" + +#. 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 "Текущая метка для `so`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2300 +#, no-wrap +msgid "Label update for `so`" +msgstr "Метка обновления для `so`" + +#. 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 "`mpo_set_socket_peer_from_mbuf`" + +#. 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 "" +"void mpo_set_socket_peer_from_mbuf(struct mbuf *mbuf, struct label *mbuflabel,\n" +" struct label *oldlabel, struct label *newlabel);\n" + +#. 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 "`mbuf`" + +#. 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 "Метка для `mbuf`" + +#. 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 "" +"Установить метку однорангового узла на потоковом сокете из переданной метки " +"mbuf. Этот вызов будет выполнен при получении первого датаграммы потоковым " +"сокетом, за исключением сокетов домена Unix." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2342 +#, no-wrap +msgid "`mpo_set_socket_peer_from_socket`" +msgstr "`mpo_set_socket_peer_from_socket`" + +#. 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 "" +"void mpo_set_socket_peer_from_socket(struct socket *oldsocket,\n" +" struct label *oldsocketlabel, struct socket *newsocket,\n" +" struct label *newsocketpeerlabel);\n" + +#. 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 "Метка политики для `oldsocket`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2368 +#, no-wrap +msgid "Peer socket" +msgstr "Сокет однорангового узла (peer socket)" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2371 +#, no-wrap +msgid "`newsocketpeerlabel`" +msgstr "`newsocketpeerlabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2372 +#, no-wrap +msgid "Policy label to fill in for `newsocket`" +msgstr "Метка политики для заполнения для `newsocket`" + +#. 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 "" +"Установите метку однорангового узла на потоковом UNIX-сокете из переданной " +"конечной точки удаленного сокета. Этот вызов будет выполнен при соединении " +"пары сокетов и будет произведен для обеих конечных точек." + +#. 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 "`mpo_create_bpfdesc`" + +#. 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 "" +"void mpo_create_bpfdesc(struct ucred *cred, struct bpf_d *bpf_d,\n" +" struct label *bpflabel);\n" + +#. 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 "`bpf_d`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2403 +#, no-wrap +msgid "Object; bpf descriptor" +msgstr "Объект; дескриптор bpf" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2406 +#, no-wrap +msgid "`bpf`" +msgstr "`bpf`" + +#. 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 "Метка политики для заполнения для `bpf_d`" + +#. 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 "" +"Установить метку на новом дескрипторе BPF из переданных учётных данных " +"субъекта. Этот вызов будет выполнен при открытии узла устройства BPF " +"процессом с переданными учётными данными субъекта." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2414 +#, no-wrap +msgid "`mpo_create_ifnet`" +msgstr "`mpo_create_ifnet`" + +#. 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 "void mpo_create_ifnet(struct ifnet *ifnet, struct label *ifnetlabel);\n" + +#. 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 "`ifnet`" + +#. 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 "`ifnetlabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2434 +#, no-wrap +msgid "Policy label to fill in for `ifnet`" +msgstr "Метка политики для заполнения для `ifnet`" + +#. 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 "`mpo_create_ipq`" + +#. 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 "" +"void mpo_create_ipq(struct mbuf *fragment, struct label *fragmentlabel,\n" +" struct ipq *ipq, struct label *ipqlabel);\n" + +#. 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 "`fragment`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2458 +#, no-wrap +msgid "First received IP fragment" +msgstr "Первый полученный IP-фрагмент" + +#. 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 "`fragmentlabel`" + +#. 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 "Метка политики для `fragment`" + +#. 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 "`ipq`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2466 +#, no-wrap +msgid "IP reassembly queue to be labeled" +msgstr "Очередь повторной сборки IP, которой добавляетя метка" + +#. 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 "`ipqlabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2470 +#, no-wrap +msgid "Policy label to be filled in for `ipq`" +msgstr "Метка политики для заполнения в `ipq`" + +#. 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 "" +"Установить метку на вновь созданной очереди сборки IP-фрагментов из " +"заголовка mbuf первого полученного фрагмента." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2476 +#, no-wrap +msgid "`mpo_create_datagram_from_ipq`" +msgstr "`mpo_create_datagram_from_ipq`" + +#. 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 "" +"void mpo_create_create_datagram_from_ipq(struct ipq *ipq,\n" +" struct label *ipqlabel, struct mbuf *datagram, struct label *datagramlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2493 +#, no-wrap +msgid "IP reassembly queue" +msgstr "Очередь повторной сборки IP" + +#. 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 "Метка политики для `ipq`" + +#. 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 "`datagram`" + +#. 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 "`datagramlabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2505 +#, no-wrap +msgid "Policy label to be filled in for `datagramlabel`" +msgstr "Метка политики для заполнения в `datagramlabel`" + +#. 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 "" +"Установите метку на вновь собранный IP-датаграмму из очереди сборки IP-" +"фрагментов, из которой он был сгенерирован." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2511 +#, no-wrap +msgid "`mpo_create_fragment`" +msgstr "`mpo_create_fragment`" + +#. 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 "" +"void mpo_create_fragment(struct mbuf *datagram, struct label *datagramlabel,\n" +" struct mbuf *fragment, struct label *fragmentlabel);\n" + +#. 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 "Метка политики для `datagram`" + +#. 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 "Метка политики для заполнения для `datagram`" + +#. 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 "" +"Установить метку на заголовке mbuf вновь созданного IP-фрагмента из метки на " +"заголовке mbuf датаграммы, из которой он был сгенерирован." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2546 +#, no-wrap +msgid "`mpo_create_mbuf_from_mbuf`" +msgstr "`mpo_create_mbuf_from_mbuf`" + +#. 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 "" +"void mpo_create_mbuf_from_mbuf(struct mbuf *oldmbuf, struct label *oldmbuflabel,\n" +" struct mbuf *newmbuf, struct label *newmbuflabel);\n" + +#. 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 "`oldmbuf`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2563 +#, no-wrap +msgid "Existing (source) mbuf" +msgstr "Существующий (исходный) mbuf" + +#. 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 "`oldmbuflabel`" + +#. 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 "Метка политики для `oldmbuf`" + +#. 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 "`newmbuf`" + +#. 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 "Новый mbuf для добавления метки" + +#. 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 "`newmbuflabel`" + +#. 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 "Метка политики для заполнения в `newmbuf`" + +#. 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 "" +"Установить метку в заголовке mbuf для вновь созданной датаграммы на основе " +"заголовка mbuf существующей датаграммы. Этот вызов может быть выполнен в " +"ряде ситуаций, включая случаи, когда для mbuf заново выделяется память для " +"целей выравнивания." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2582 +#, no-wrap +msgid "`mpo_create_mbuf_linklayer`" +msgstr "`mpo_create_mbuf_linklayer`" + +#. 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 "" +"void mpo_create_mbuf_linklayer(struct ifnet *ifnet, struct label *ifnetlabel,\n" +" struct mbuf *mbuf, struct label *mbuflabel);\n" + +#. 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 "Метка политики для `ifnet`" + +#. 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 "заголовок mbuf для новой датаграммы" + +#. 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 "Метка политики для заполнения для `mbuf`" + +#. 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 "" +"Установить метку в заголовке mbuf для вновь созданной датаграммы, " +"сгенерированного для целей ответа на канальном уровне для переданного " +"интерфейса. Этот вызов может быть выполнен в ряде ситуаций, включая ответы " +"ARP или ND6 в стеках IPv4 и IPv6." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2618 +#, no-wrap +msgid "`mpo_create_mbuf_from_bpfdesc`" +msgstr "`mpo_create_mbuf_from_bpfdesc`" + +#. 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 "" +"void mpo_create_mbuf_from_bpfdesc(struct bpf_d *bpf_d, struct label *bpflabel,\n" +" struct mbuf *mbuf, struct label *mbuflabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2635 +#, no-wrap +msgid "BPF descriptor" +msgstr "Дескриптор BPF" + +#. 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 "`bpflabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2639 +#, no-wrap +msgid "Policy label for `bpflabel`" +msgstr "Метка политики для `bpflabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2647 +#, no-wrap +msgid "Policy label to fill in for `mbuf`" +msgstr "Метка политики для заполнения `mbuf`" + +#. 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 "" +"Установить метку на заголовок mbuf вновь созданной датаграммы, " +"сгенерированной с использованием переданного дескриптора BPF. Этот вызов " +"выполняется при записи в устройство BPF, связанное с переданным дескриптором " +"BPF." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2654 +#, no-wrap +msgid "`mpo_create_mbuf_from_ifnet`" +msgstr "`mpo_create_mbuf_from_ifnet`" + +#. 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 "" +"void mpo_create_mbuf_from_ifnet(struct ifnet *ifnet, struct label *ifnetlabel,\n" +" struct mbuf *mbuf, struct label *mbuflabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2675 +#, no-wrap +msgid "Policy label for `ifnetlabel`" +msgstr "Метка политики для `ifnetlabel`" + +#. 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 "" +"Установить метку на заголовке mbuf вновь созданной датаграммы, " +"сгенерированной из переданного сетевого интерфейса." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2689 +#, no-wrap +msgid "`mpo_create_mbuf_multicast_encap`" +msgstr "`mpo_create_mbuf_multicast_encap`" + +#. 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 "" +"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" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2707 +#, no-wrap +msgid "mbuf header for existing datagram" +msgstr "Заголовок mbuf для существующего датаграммы" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2723 +#, no-wrap +msgid "mbuf header to be labeled for new datagram" +msgstr "Заголовок mbuf для пометки новой датаграммы" + +#. 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 "" +"Установить метку в заголовке mbuf для вновь созданной датаграммы, " +"сгенерированной из существующей переданной датаграммы, при её обработке " +"переданным интерфейсом мультикастовой инкапсуляции. Этот вызов происходит " +"при доставке mbuf с использованием виртуального интерфейса." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2734 +#, no-wrap +msgid "`mpo_create_mbuf_netlayer`" +msgstr "`mpo_create_mbuf_netlayer`" + +#. 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 "" +"void mpo_create_mbuf_netlayer(struct mbuf *oldmbuf, struct label *oldmbuflabel,\n" +" struct mbuf *newmbuf, struct label *newmbuflabel);\n" + +#. 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 "Метка политики для `newmbuf`" + +#. 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 "" +"Установить метку на заголовок mbuf вновь созданной датаграммы, " +"сгенерированной стеком IP в ответ на полученную датаграмму (`oldmbuf`). Этот " +"вызов может быть выполнен в различных ситуациях, включая ответ на датаграммы " +"ICMP-запросов." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2770 +#, no-wrap +msgid "`mpo_fragment_match`" +msgstr "`mpo_fragment_match`" + +#. 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 "" +"int mpo_fragment_match(struct mbuf *fragment, struct label *fragmentlabel,\n" +" struct ipq *ipq, struct label *ipqlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2787 +#, no-wrap +msgid "IP datagram fragment" +msgstr "Фрагмент IP-датаграммы" + +#. 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 "Очередь сборки IP-фрагментов" + +#. 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 "" +"Определить, соответствует ли заголовок mbuf, содержащий фрагмент IP-" +"датаграммы (`fragment`), метке переданной очереди сборки IP-фрагментов " +"(`ipq`). Возвращает (1) при успешном совпадении или (0) при отсутствии " +"совпадения. Этот вызов выполняется, когда IP-стек пытается найти " +"существующую очередь сборки фрагментов для вновь полученного фрагмента; если " +"поиск не удаётся, для фрагмента может быть создана новая очередь сборки. " +"Политики могут использовать эту точку входа, чтобы предотвратить сборку в " +"остальном подходящих IP-фрагментов, если политика не разрешает их сборку на " +"основе метки или другой информации." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2808 +#, no-wrap +msgid "`mpo_relabel_ifnet`" +msgstr "`mpo_relabel_ifnet`" + +#. 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 "" +"void mpo_relabel_ifnet(struct ucred *cred, struct ifnet *ifnet,\n" +" struct label *ifnetlabel, struct label *newlabel);\n" + +#. 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 "Метка обновления для применения к `ifnet`" + +#. 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 "" +"Обновить метку сетевого интерфейса, `ifnet`, на основе переданной новой " +"метки, `newlabel`, и переданных учетных данных субъекта, `cred`." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2843 +#, no-wrap +msgid "`mpo_update_ipq`" +msgstr "`mpo_update_ipq`" + +#. 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 "" +"void mpo_update_ipq(struct mbuf *fragment, struct label *fragmentlabel,\n" +" struct ipq *ipq, struct label *ipqlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2860 +#, no-wrap +msgid "IP fragment" +msgstr "IP фрагмент" + +#. 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 "Метка политики для `mbuf`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2872 +#, no-wrap +msgid "Policy label to be updated for `ipq`" +msgstr "Метка политики для обновления для `ipq`" + +#. 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 "" +"Обновить метку в очереди сборки IP-фрагментов (`ipq`) на основе принятия " +"переданного заголовка IP-фрагмента mbuf (`mbuf`)." + +#. 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 "`mpo_create_cred`" + +#. 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 "void mpo_create_cred(struct ucred *parent_cred, struct ucred *child_cred);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2896 +#, no-wrap +msgid "`parent_cred`" +msgstr "`parent_cred`" + +#. 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 "`child_cred`" + +#. 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 "" +"Установить метку вновь созданного субъекта из переданного субъекта. Этот " +"вызов будет выполнен при вызове man:crcopy[9] для только что созданной " +"структуры `struct ucred`. Этот вызов не следует путать с событием создания " +"или ветвления процесса." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2909 +#, no-wrap +msgid "`mpo_execve_transition`" +msgstr "`mpo_execve_transition`" + +#. 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 "" +"void mpo_execve_transition(struct ucred *old, struct ucred *new,\n" +" struct vnode *vp, struct label *vnodelabel);\n" + +#. 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 "`old`" + +#. 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 "`new`" + +#. 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 "" +"Обновить метку учетных данных вновь созданного субъекта (`new`) на основе " +"переданных учетных данных существующего субъекта (`old`) в соответствии с " +"переходом метки, вызванным выполнением переданного vnode (`vp`). Этот вызов " +"происходит, когда процесс выполняет переданный vnode, и одна из политик " +"возвращает успех из точки входа `mpo_execve_will_transition`. Политики могут " +"выбрать реализацию этого вызова просто путем вызова `mpo_create_cred` и " +"передачи двух субъектов учетных данных, чтобы не реализовывать событие " +"перехода. Политики не должны оставлять эту точку входа нереализованной, если " +"они реализуют `mpo_create_cred`, даже если они не реализуют " +"`mpo_execve_will_transition`." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2948 +#, no-wrap +msgid "`mpo_execve_will_transition`" +msgstr "`mpo_execve_will_transition`" + +#. 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 "" +"int mpo_execve_will_transition(struct ucred *old, struct vnode *vp,\n" +" struct label *vnodelabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2965 +#, no-wrap +msgid "Subject credential prior to man:execve[2]" +msgstr "Учетные данные субъекта перед man:execve[2]" + +#. 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 "" +"Определить, будет ли политика выполнять событие перехода в результате " +"выполнения переданного vnode с использованием переданных учетных данных " +"субъекта. Вернуть 1, если переход требуется, и 0, если нет. Даже если " +"политика возвращает 0, она должна корректно обрабатывать неожиданный вызов " +"`mpo_execve_transition`, так как этот вызов может произойти из-за запроса " +"перехода другой политикой." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:2981 +#, no-wrap +msgid "`mpo_create_proc0`" +msgstr "`mpo_create_proc0`" + +#. 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 "void mpo_create_proc0(struct ucred *cred);\n" + +#. 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 "" +"Создать учетные данные субъекта процесса 0, родителя всех процессов ядра." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3003 +#, no-wrap +msgid "`mpo_create_proc1`" +msgstr "`mpo_create_proc1`" + +#. 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 "void mpo_create_proc1(struct ucred *cred);\n" + +#. 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 "" +"Создать учетные данные субъекта процесса 1, родителя всех пользовательских " +"процессов." + +#. type: Title ===== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3025 +#, no-wrap +msgid "`mpo_relabel_cred`" +msgstr "`mpo_relabel_cred`" + +#. 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 "void mpo_relabel_cred(struct ucred *cred, struct label *newlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3045 +#, no-wrap +msgid "Label update to apply to `cred`" +msgstr "Обновление метки для применения к `cred`" + +#. 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 "" +"Точки входа контроля доступа позволяют модулям политики влиять на решения по " +"контролю доступа, принимаемые ядром. Обычно, хотя и не всегда, аргументы " +"точки входа контроля доступа включают одно или несколько удостоверяющих " +"полномочий, информацию (возможно, включая метку) для любых других объектов, " +"участвующих в операции. Точка входа контроля доступа может вернуть 0 для " +"разрешения операции или значение ошибки man:errno[2]. Результаты вызова " +"точки входа через различные зарегистрированные модули политики будут " +"объединены следующим образом: если все модули разрешают успешное выполнение " +"операции, будет возвращен успех. Если один или несколько модулей возвращают " +"ошибку, будет возвращена ошибка. Если более одного модуля возвращают ошибку, " +"значение errno, которое будет возвращено пользователю, выбирается с " +"использованием следующего приоритета, реализованного функцией " +"`error_select()` в [.filename]#kern_mac.c#:" + +#. 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 "EDEADLK" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3070 +#, no-wrap +msgid "EINVAL" +msgstr "EINVAL" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3073 +#, no-wrap +msgid "ESRCH" +msgstr "ESRCH" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3076 +#, no-wrap +msgid "EACCES" +msgstr "EACCES" + +#. 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 "EPERM" + +#. 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 "`mpo_check_bpfdesc_receive`" + +#. 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 "" +"int mpo_check_bpfdesc_receive(struct bpf_d *bpf_d, struct label *bpflabel,\n" +" struct ifnet *ifnet, struct label *ifnetlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3101 +#, no-wrap +msgid "Subject; BPF descriptor" +msgstr "Субъект; Дескриптор BPF" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3105 +#, no-wrap +msgid "Policy label for `bpf_d`" +msgstr "Метка политики для `bpf_d`" + +#. 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 "" +"Определить, должен ли framework MAC разрешать доставку датаграмм с " +"переданного интерфейса в буферы переданного BPF-дескриптора. Возвращает (0) " +"при успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при " +"несоответствии меток, EPERM при отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3120 +#, no-wrap +msgid "`mpo_check_kenv_dump`" +msgstr "`mpo_check_kenv_dump`" + +#. 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 "int mpo_check_kenv_dump(struct ucred *cred);\n" + +#. 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 "" +"Определить, следует ли разрешить субъекту получать доступ к окружению ядра " +"(см. man:kenv[2])." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3142 +#, no-wrap +msgid "`mpo_check_kenv_get`" +msgstr "`mpo_check_kenv_get`" + +#. 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 "int mpo_check_kenv_get(struct ucred *cred, char *name);\n" + +#. 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 "`name`" + +#. 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 "`mpo_check_kenv_set`" + +#. 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 "int mpo_check_kenv_set(struct ucred *cred, char *name);\n" + +#. 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 "`mpo_check_kenv_unset`" + +#. 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 "int mpo_check_kenv_unset(struct ucred *cred, char *name);\n" + +#. 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 "`mpo_check_kld_load`" + +#. 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 "" +"int mpo_check_kld_load(struct ucred *cred, struct vnode *vp,\n" +" struct label *vlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3241 +#, no-wrap +msgid "Kernel module vnode" +msgstr "vnode модуля ядра" + +#. 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 "Метка, связанная с `vp`" + +#. 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 "`mpo_check_kld_stat`" + +#. 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 "int mpo_check_kld_stat(struct ucred *cred);\n" + +#. 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 "`mpo_check_kld_unload`" + +#. 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 "int mpo_check_kld_unload(struct ucred *cred);\n" + +#. 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 "`mpo_check_pipe_ioctl`" + +#. 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 "" +"int mpo_check_pipe_ioctl(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel, unsigned long cmd, void *data);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3323 +#, no-wrap +msgid "`cmd`" +msgstr "`cmd`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3324 +#, no-wrap +msgid "man:ioctl[2] command" +msgstr "команда nman:ioctl[2]" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3327 +#, no-wrap +msgid "`data`" +msgstr "`data`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3328 +#, no-wrap +msgid "man:ioctl[2] data" +msgstr "данные man:ioctl[2]" + +#. 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 "" +"Определить, следует ли разрешить субъекту выполнять указанный вызов " +"man:ioctl[2]." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3334 +#, no-wrap +msgid "`mpo_check_pipe_poll`" +msgstr "`mpo_check_pipe_poll`" + +#. 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 "" +"int mpo_check_pipe_poll(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel);\n" + +#. 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 "Определить, следует ли разрешить субъекту опрашивать `pipe`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3365 +#, no-wrap +msgid "`mpo_check_pipe_read`" +msgstr "`mpo_check_pipe_read`" + +#. 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 "" +"int mpo_check_pipe_read(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel);\n" + +#. 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 "Определить, следует ли разрешить субъекту доступ на чтение к `pipe`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3396 +#, no-wrap +msgid "`mpo_check_pipe_relabel`" +msgstr "`mpo_check_pipe_relabel`" + +#. 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 "" +"int mpo_check_pipe_relabel(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel, struct label *newlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3425 +#, no-wrap +msgid "Label update to `pipelabel`" +msgstr "Обновление метки до `pipelabel`" + +#. 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 "Определить, следует ли разрешить субъекту изменять метку `pipe`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3431 +#, no-wrap +msgid "`mpo_check_pipe_stat`" +msgstr "`mpo_check_pipe_stat`" + +#. 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 "" +"int mpo_check_pipe_stat(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel);\n" + +#. 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 "" +"Определить, следует ли разрешить субъекту получать статистику, связанную с " +"`pipe`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3462 +#, no-wrap +msgid "`mpo_check_pipe_write`" +msgstr "`mpo_check_pipe_write`" + +#. 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 "" +"int mpo_check_pipe_write(struct ucred *cred, struct pipe *pipe,\n" +" struct label *pipelabel);\n" + +#. 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 "Определить, следует ли разрешить субъекту запись в `pipe`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3493 +#, no-wrap +msgid "`mpo_check_socket_bind`" +msgstr "`mpo_check_socket_bind`" + +#. 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 "" +"int mpo_check_socket_bind(struct ucred *cred, struct socket *socket,\n" +" struct label *socketlabel, struct sockaddr *sockaddr);\n" + +#. 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 "`sockaddr`" + +#. 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 "Адрес `socket`" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3526 +#, no-wrap +msgid "`mpo_check_socket_connect`" +msgstr "`mpo_check_socket_connect`" + +#. 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 "" +"int mpo_check_socket_connect(struct ucred *cred, struct socket *socket,\n" +" struct label *socketlabel, struct sockaddr *sockaddr);\n" + +#. 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 "" +"Определить, может ли субъект с учётными данными (`cred`) подключить " +"переданный сокет (`socket`) к переданному адресу сокета (`sockaddr`). " +"Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые " +"ошибки: EACCES при несоответствии меток, EPERM при отсутствии прав." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3563 +#, no-wrap +msgid "`mpo_check_socket_receive`" +msgstr "`mpo_check_socket_receive`" + +#. 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 "" +"int mpo_check_socket_receive(struct ucred *cred, struct socket *so,\n" +" struct label *socketlabel);\n" + +#. 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 "Метка политики, связанная с `so`" + +#. 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 "" +"Определить, следует ли разрешить субъекту получать информацию из сокета `so`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3594 +#, no-wrap +msgid "`mpo_check_socket_send`" +msgstr "`mpo_check_socket_send`" + +#. 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 "" +"int mpo_check_socket_send(struct ucred *cred, struct socket *so,\n" +" struct label *socketlabel);\n" + +#. 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 "" +"Определить, следует ли разрешить субъекту передавать информацию через сокет " +"`so`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3625 +#, no-wrap +msgid "`mpo_check_cred_visible`" +msgstr "`mpo_check_cred_visible`" + +#. 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 "int mpo_check_cred_visible(struct ucred *u1, struct ucred *u2);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3640 +#, no-wrap +msgid "`u1`" +msgstr "`u1`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3644 +#, no-wrap +msgid "`u2`" +msgstr "`u2`" + +#. 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 "" +"Определить, может ли субъект с учётными данными `u1` \"видеть\" другие " +"субъекты с переданными учётными данными `u2`. Возвращает 0 при успехе или " +"значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии " +"меток, EPERM при отсутствии привилегий или ESRCH для скрытия видимости. Этот " +"вызов может выполняться в различных ситуациях, включая системные вызовы " +"состояния межпроцессного взаимодействия, используемые `ps`, и при поиске в " +"procfs." + +#. 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 "`mpo_check_socket_visible`" + +#. 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 "" +"int mpo_check_socket_visible(struct ucred *cred, struct socket *socket,\n" +" struct label *socketlabel);\n" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3683 +#, no-wrap +msgid "`mpo_check_ifnet_relabel`" +msgstr "`mpo_check_ifnet_relabel`" + +#. 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 "" +"int mpo_check_ifnet_relabel(struct ucred *cred, struct ifnet *ifnet,\n" +" struct label *ifnetlabel, struct label *newlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3708 +#, no-wrap +msgid "Existing policy label for `ifnet`" +msgstr "Существующая метка политики для `ifnet`" + +#. 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 "Обновление метки политики для последующего применения к `ifnet`" + +#. 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 "`mpo_check_socket_relabel`" + +#. 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 "" +"int mpo_check_socket_relabel(struct ucred *cred, struct socket *socket,\n" +" struct label *socketlabel, struct label *newlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3743 +#, no-wrap +msgid "Existing policy label for `socket`" +msgstr "Метка существующей политики для `socket`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3747 +#, no-wrap +msgid "Label update to later be applied to `socketlabel`" +msgstr "Обновление метки для последующего применения к `socketlabel`" + +#. 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 "`mpo_check_cred_relabel`" + +#. 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 "int mpo_check_cred_relabel(struct ucred *cred, struct label *newlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3773 +#, no-wrap +msgid "Label update to later be applied to `cred`" +msgstr "Обновление метки для последующего применения к `cred`" + +#. 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 "`mpo_check_vnode_relabel`" + +#. 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 "" +"int mpo_check_vnode_relabel(struct ucred *cred, struct vnode *vp,\n" +" struct label *vnodelabel, struct label *newlabel);\n" + +#. 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 "Объект; vnode" + +#. 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 "Обновление метки политики для последующего применения к `vp`" + +#. 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 "" +"Определить, могут ли учётные данные субъекта изменить метку переданного " +"vnode на переданную обновлённую метку." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3814 +#, no-wrap +msgid "`mpo_check_mount_stat`" +msgstr "`mpo_check_mount_stat`" + +#. 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 "" +"int mpo_check_mount_stat(struct ucred *cred, struct mount *mp,\n" +" struct label *mountlabel);\n" + +#. 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 "`mountlabel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3839 +#, no-wrap +msgid "Policy label for `mp`" +msgstr "Метка политики для `mp`" + +#. 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 "" +"Определить, могут ли учетные данные субъекта видеть результаты выполнения " +"statfs для файловой системы. Возвращает 0 при успехе или значение `errno` " +"при ошибке. Рекомендуемые ошибки: EACCES при несоответствии меток или EPERM " +"при отсутствии привилегий. Этот вызов может выполняться в различных " +"ситуациях, включая вызовы man:statfs[2] и связанных функций, а также для " +"определения, какие файловые системы исключать из списка, например, при " +"вызове man:getfsstat[2]." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3848 +#, no-wrap +msgid "`mpo_check_proc_debug`" +msgstr "`mpo_check_proc_debug`" + +#. 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 "int mpo_check_proc_debug(struct ucred *cred, struct proc *proc);\n" + +#. 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 "`proc`" + +#. 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 "" +"Определить, могут ли учётные данные субъекта отлаживать переданный процесс. " +"Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые " +"ошибки: EACCES при несоответствии метки, EPERM при недостатке прав или ESRCH " +"для скрытия видимости цели. Этот вызов может использоваться в различных " +"ситуациях, включая использование API man:ptrace[2] и man:ktrace[2], а также " +"для некоторых операций с procfs." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3877 +#, no-wrap +msgid "`mpo_check_vnode_access`" +msgstr "`mpo_check_vnode_access`" + +#. 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 "" +"int mpo_check_vnode_access(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int flags);\n" + +#. 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 "`flags`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3906 +#, no-wrap +msgid "man:access[2] flags" +msgstr "флаги man:access[2]" + +#. 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 "" +"Определить, как должны возвращаться вызовы man:access[2] и связанные вызовы " +"для субъекта с указанными учетными данными при выполнении на переданном " +"vnode с использованием переданных флагов доступа. Обычно это должно быть " +"реализовано с использованием той же семантики, что и в " +"`mpo_check_vnode_open`. Возвращает 0 при успехе или значение `errno` при " +"ошибке. Рекомендуемые ошибки: EACCES при несоответствии меток или EPERM при " +"отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3915 +#, no-wrap +msgid "`mpo_check_vnode_chdir`" +msgstr "`mpo_check_vnode_chdir`" + +#. 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 "" +"int mpo_check_vnode_chdir(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3936 +#, no-wrap +msgid "Object; vnode to man:chdir[2] into" +msgstr "Объект; vnode, в который делается man:chdir[2]" + +#. 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 "Метка политики для `dvp`" + +#. 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 "" +"Определить, могут ли учётные данные субъекта изменить рабочий каталог " +"процесса на переданный vnode. Возвращает 0 при успехе или значение `errno` " +"при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM " +"при отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3948 +#, no-wrap +msgid "`mpo_check_vnode_chroot`" +msgstr "`mpo_check_vnode_chroot`" + +#. 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 "" +"int mpo_check_vnode_chroot(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel);\n" + +#. 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 "vnode каталога" + +#. 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 "Метка политики, связанная с `dvp`" + +#. 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 "" +"Определить, следует ли разрешить субъекту выполнять man:chroot[2] в " +"указанный каталог (`dvp`)." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:3979 +#, no-wrap +msgid "`mpo_check_vnode_create`" +msgstr "`mpo_check_vnode_create`" + +#. 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 "" +"int mpo_check_vnode_create(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel, struct componentname *cnp, struct vattr *vap);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4008 +#, no-wrap +msgid "Component name for `dvp`" +msgstr "Название компонента для `dvp`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4011 +#, no-wrap +msgid "`vap`" +msgstr "`vap`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4012 +#, no-wrap +msgid "vnode attributes for `vap`" +msgstr "атрибуты vnode для `vap`" + +#. 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 "" +"Определить, могут ли учетные данные субъекта создать vnode с указанной " +"родительской директорией, информацией о имени и атрибутами. Возвращает 0 при " +"успехе или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при " +"несоответствии метки или EPERM при отсутствии привилегий. Этот вызов может " +"выполняться в различных ситуациях, включая вызовы man:open[2] с O_CREAT, " +"man:mkfifo[2] и другие." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4021 +#, no-wrap +msgid "`mpo_check_vnode_delete`" +msgstr "`mpo_check_vnode_delete`" + +#. 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 "" +"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" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4051 +#, no-wrap +msgid "Object; vnode to delete" +msgstr "Объект; vnode для удаления" + +#. 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 "" +"Определить, может ли субъект с данными учетными данными удалить vnode из " +"переданного родительского каталога и переданной информации о имени. " +"Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые " +"ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий. " +"Этот вызов может быть выполнен в различных ситуациях, включая вызовы " +"man:unlink[2] и man:rmdir[2]. Политики, реализующие эту точку входа, также " +"должны реализовывать `mpo_check_rename_to` для авторизации удаления объектов " +"в результате их переименования." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4069 +#, no-wrap +msgid "`mpo_check_vnode_deleteacl`" +msgstr "`mpo_check_vnode_deleteacl`" + +#. 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 "" +"int mpo_check_vnode_deleteacl(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, acl_type_t type);\n" + +#. 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`" + +#. 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 "Тип ACL" + +#. 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 "" +"Определить, могут ли учетные данные субъекта удалить ACL указанного типа из " +"переданного vnode. Возвращает 0 при успехе или значение `errno` при ошибке. " +"Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при " +"отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4106 +#, no-wrap +msgid "`mpo_check_vnode_exec`" +msgstr "`mpo_check_vnode_exec`" + +#. 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 "" +"int mpo_check_vnode_exec(struct ucred *cred, struct vnode *vp,\n" +" struct label *label);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4127 +#, no-wrap +msgid "Object; vnode to execute" +msgstr "Объект; vnode для выполнения" + +#. 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 "" +"Определить, могут ли учётные данные субъекта выполнить переданный vnode. " +"Проверка права на выполнение осуществляется отдельно от решений о любом " +"переходном событии. Возвращает 0 при успехе или значение `errno` при ошибке. " +"Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при " +"отсутствии прав." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4140 +#, no-wrap +msgid "`mpo_check_vnode_getacl`" +msgstr "`mpo_check_vnode_getacl`" + +#. 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 "" +"int mpo_check_vnode_getacl(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, acl_type_t type);\n" + +#. 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 "" +"Определить, может ли учётное данное субъекта получить ACL указанного типа из " +"переданного vnode. Возвращает 0 при успехе или значение `errno` при ошибке. " +"Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при " +"отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4177 +#, no-wrap +msgid "`mpo_check_vnode_getextattr`" +msgstr "`mpo_check_vnode_getextattr`" + +#. 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 "" +"int mpo_check_vnode_getextattr(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int attrnamespace, const char *name, struct uio *uio);\n" + +#. 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 "`attrnamespace`" + +#. 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 "`uio`" + +#. 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 "Указатель структуры ввода-вывода; см. man:uio[9]" + +#. 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 "" +"Определить, может ли субъект с указанными учетными данными получить " +"расширенный атрибут с заданным пространством имен и именем из указанного " +"vnode. Политики, реализующие маркировку с использованием расширенных " +"атрибутов, могут требовать особой обработки операций с этими атрибутами. " +"Возвращает 0 при успехе или значение `errno` при ошибке. Рекомендуемые " +"ошибки: EACCES при несоответствии метки или EPERM при отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4223 +#, no-wrap +msgid "`mpo_check_vnode_link`" +msgstr "`mpo_check_vnode_link`" + +#. 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 "" +"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" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4253 +#, no-wrap +msgid "Link destination vnode" +msgstr "vnode целевого линка" + +#. 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 "" +"Определить, следует ли разрешить субъекту создавать ссылку на vnode `vp` с " +"именем, указанным в `cnp`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4267 +#, no-wrap +msgid "`mpo_check_vnode_mmap`" +msgstr "`mpo_check_vnode_mmap`" + +#. 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 "" +"int mpo_check_vnode_mmap(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int prot);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4288 +#, no-wrap +msgid "Vnode to map" +msgstr "vnode для mmap" + +#. 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 "`prot`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4296 +#, no-wrap +msgid "Mmap protections (see man:mmap[2])" +msgstr "Защита mmap (см. man:mmap[2])" + +#. 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 "" +"Определить, следует ли разрешить субъекту отображать vnode `vp` с указанными " +"в `prot` правами доступа." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4302 +#, no-wrap +msgid "`mpo_check_vnode_mmap_downgrade`" +msgstr "`mpo_check_vnode_mmap_downgrade`" + +#. 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 "" +"void mpo_check_vnode_mmap_downgrade(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int *prot);\n" + +#. 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 "См. crossref:mac[mac-mpo-check-vnode-mmap, `mpo_check_vnode_mmap`]." + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4331 +#, no-wrap +msgid "Mmap protections to be downgraded" +msgstr "Защита mmap для понижения уровня" + +#. 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 "Понизить уровень защиты mmap на основе меток субъекта и объекта." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4337 +#, no-wrap +msgid "`mpo_check_vnode_mprotect`" +msgstr "`mpo_check_vnode_mprotect`" + +#. 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 "" +"int mpo_check_vnode_mprotect(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int prot);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4358 +#, no-wrap +msgid "Mapped vnode" +msgstr "Отображенный vnode" + +#. 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 "" +"Определить, следует ли разрешить субъекту устанавливать указанные защиты " +"памяти для памяти, отображенной из vnode `vp`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4368 +#, no-wrap +msgid "`mpo_check_vnode_poll`" +msgstr "`mpo_check_vnode_poll`" + +#. 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 "" +"int mpo_check_vnode_poll(struct ucred *active_cred, struct ucred *file_cred,\n" +" struct vnode *vp, struct label *label);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4384 +#, no-wrap +msgid "`active_cred`" +msgstr "`active_cred`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4388 +#, no-wrap +msgid "`file_cred`" +msgstr "`file_cred`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4389 +#, no-wrap +msgid "Credential associated with the struct file" +msgstr "Учетные данные, связанные со структурой file" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4393 +#, no-wrap +msgid "Polled vnode" +msgstr "vnode, на котором вызывается poll" + +#. 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 "Определить, следует ли разрешить субъекту вызывать poll на vnode `vp`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4403 +#, no-wrap +msgid "`mpo_check_vnode_rename_from`" +msgstr "`mpo_check_vnode_rename_from`" + +#. 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 "" +"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" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4433 +#, no-wrap +msgid "Vnode to be renamed" +msgstr "vnode для переименования" + +#. 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 "" +"Определить, следует ли разрешить субъекту переименовать vnode `vp` во что-то " +"другое." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4447 +#, no-wrap +msgid "`mpo_check_vnode_rename_to`" +msgstr "`mpo_check_vnode_rename_to`" + +#. 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 "" +"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" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4477 +#, no-wrap +msgid "Overwritten vnode" +msgstr "vnode, который будет перезаписан" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4484 +#, no-wrap +msgid "`samedir`" +msgstr "`samedir`" + +#. 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 "Логическое значение; `1`, если исходный и целевой каталоги совпадают" + +#. 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 "" +"Определить, следует ли разрешить субъекту переименование vnode `vp` в " +"директорию `dvp` или в имя, представленное `cnp`. Если не существует файла " +"для перезаписи, `vp` и `label` будут NULL." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4496 +#, no-wrap +msgid "`mpo_check_socket_listen`" +msgstr "`mpo_check_socket_listen`" + +#. 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 "" +"int mpo_check_socket_listen(struct ucred *cred, struct socket *socket,\n" +" struct label *socketlabel);\n" + +#. 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 "" +"Определить, могут ли учётные данные субъекта прослушивать переданный сокет " +"(вызывать listen). Возвращает 0 при успехе или значение `errno` при ошибке. " +"Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при " +"отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4529 +#, no-wrap +msgid "`mpo_check_vnode_lookup`" +msgstr "`mpo_check_vnode_lookup`" + +#. 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 "" +"int mpo_check_vnode_lookup(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel, struct componentname *cnp);\n" + +#. 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 "" +"Определить, могут ли учётные данные субъекта выполнить поиск указанного " +"имени в каталог с переданном vnode. Возвращает 0 при успехе или значение " +"`errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки " +"или EPERM при отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4566 +#, no-wrap +msgid "`mpo_check_vnode_open`" +msgstr "`mpo_check_vnode_open`" + +#. 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 "" +"int mpo_check_vnode_open(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int acc_mode);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4594 +#, no-wrap +msgid "`acc_mode`" +msgstr "`acc_mode`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4595 +#, no-wrap +msgid "man:open[2] access mode" +msgstr "режим доступа от man:open[2]" + +#. 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 "" +"Определить, могут ли учетные данные субъекта выполнить операцию открытия " +"переданного vnode с указанным режимом доступа. Возвращает 0 в случае успеха " +"или значение errno при ошибке. Рекомендуемые ошибки: EACCES при " +"несоответствии метки или EPERM при отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4603 +#, no-wrap +msgid "`mpo_check_vnode_readdir`" +msgstr "`mpo_check_vnode_readdir`" + +#. 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 "" +"int mpo_check_vnode_readdir(struct ucred *cred, struct vnode *dvp,\n" +" struct label *dlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4624 +#, no-wrap +msgid "Object; directory vnode" +msgstr "Объект; vnode каталога" + +#. 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 "" +"Определить, могут ли учетные данные субъекта выполнить операцию `readdir` " +"для переданного vnode каталога. Возвращает 0 при успехе или значение `errno` " +"при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM " +"при отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4636 +#, no-wrap +msgid "`mpo_check_vnode_readlink`" +msgstr "`mpo_check_vnode_readlink`" + +#. 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 "" +"int mpo_check_vnode_readlink(struct ucred *cred, struct vnode *vp,\n" +" struct label *label);\n" + +#. 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 "" +"Определить, могут ли учетные данные субъекта выполнить операцию `readlink` " +"для переданного символьного vnode. Возвращает 0 в случае успеха или значение " +"`errno` в случае ошибки. Рекомендуемые ошибки: EACCES при несоответствии " +"метки или EPERM при отсутствии привилегий. Этот вызов может быть выполнен в " +"различных ситуациях, включая явный вызов `readlink` пользовательским " +"процессом или неявный `readlink` во время поиска имени процессом." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4670 +#, no-wrap +msgid "`mpo_check_vnode_revoke`" +msgstr "`mpo_check_vnode_revoke`" + +#. 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 "" +"int mpo_check_vnode_revoke(struct ucred *cred, struct vnode *vp,\n" +" struct label *label);\n" + +#. 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 "" +"Определить, могут ли учётные данные субъекта отозвать доступ к переданному " +"vnode. Возвращает 0 при успехе или значение `errno` при ошибке. " +"Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при " +"отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4703 +#, no-wrap +msgid "`mpo_check_vnode_setacl`" +msgstr "`mpo_check_vnode_setacl`" + +#. 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 "" +"int mpo_check_vnode_setacl(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, acl_type_t type, struct acl *acl);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4735 +#, no-wrap +msgid "`acl`" +msgstr "`acl`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4736 +#, no-wrap +msgid "ACL" +msgstr "ACL" + +#. 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 "" +"Определить, могут ли учётные данные субъекта установить переданный ACL " +"указанного типа для переданного vnode. Возвращает 0 при успехе или значение " +"`errno` при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки " +"или EPERM при отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4744 +#, no-wrap +msgid "`mpo_check_vnode_setextattr`" +msgstr "`mpo_check_vnode_setextattr`" + +#. 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 "" +"int mpo_check_vnode_setextattr(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, int attrnamespace, const char *name, struct uio *uio);\n" + +#. 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 "" +"Определить, могут ли учетные данные субъекта установить расширенный атрибут " +"с переданным именем и пространством имен на переданном vnode. Политики, " +"реализующие метки безопасности, основанные на расширенных атрибутах, могут " +"предусматривать дополнительные защиты для этих атрибутов. Кроме того, " +"политикам следует избегать принятия решений на основе данных, на которые " +"ссылается `uio`, так как существует потенциальное состояние гонки между этой " +"проверкой и фактической операцией. `uio` также может быть `NULL`, если " +"выполняется операция удаления. Возвращает 0 при успехе или значение `errno` " +"при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM " +"при отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4792 +#, no-wrap +msgid "`mpo_check_vnode_setflags`" +msgstr "`mpo_check_vnode_setflags`" + +#. 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 "" +"int mpo_check_vnode_setflags(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, u_long flags);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4821 +#, no-wrap +msgid "File flags; see man:chflags[2]" +msgstr "Флаги файла; см. man:chflags[2]" + +#. 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 "" +"Определить, могут ли учётные данные субъекта установить переданные флаги на " +"переданном vnode. Возвращает 0 при успехе или значение `errno` при ошибке. " +"Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при " +"отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4829 +#, no-wrap +msgid "`mpo_check_vnode_setmode`" +msgstr "`mpo_check_vnode_setmode`" + +#. 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 "" +"int mpo_check_vnode_setmode(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, mode_t mode);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4857 +#, no-wrap +msgid "`mode`" +msgstr "`mode`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4858 +#, no-wrap +msgid "File mode; see man:chmod[2]" +msgstr "Режим файла; см. man:chmod[2]" + +#. 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 "" +"Определить, могут ли учётные данные субъекта установить переданный режим для " +"переданного vnode. Возвращает 0 при успехе или значение `errno` при ошибке. " +"Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при " +"недостатке привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4866 +#, no-wrap +msgid "`mpo_check_vnode_setowner`" +msgstr "`mpo_check_vnode_setowner`" + +#. 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 "" +"int mpo_check_vnode_setowner(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, uid_t uid, gid_t gid);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4894 +#, no-wrap +msgid "`uid`" +msgstr "`uid`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4895 +#, no-wrap +msgid "User ID" +msgstr "User ID" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4898 +#, no-wrap +msgid "`gid`" +msgstr "`gid`" + +#. 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 "" +"Определить, могут ли учетные данные субъекта установить переданный uid и " +"переданный gid в качестве uid файла и gid файла для переданного vnode. " +"Идентификаторы могут быть установлены в (`-1`) для запроса отсутствия " +"обновления. Возвращает 0 при успехе или значение `errno` при ошибке. " +"Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при " +"отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4908 +#, no-wrap +msgid "`mpo_check_vnode_setutimes`" +msgstr "`mpo_check_vnode_setutimes`" + +#. 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 "" +"int mpo_check_vnode_setutimes(struct ucred *cred, struct vnode *vp,\n" +" struct label *label, struct timespec atime, struct timespec mtime);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4929 +#, no-wrap +msgid "Object; vp" +msgstr "Объект; vp" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4936 +#, no-wrap +msgid "`atime`" +msgstr "`atime`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4937 +#, no-wrap +msgid "Access time; see man:utimes[2]" +msgstr "Время доступа; см. man:utimes[2]" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4940 +#, no-wrap +msgid "`mtime`" +msgstr "`mtime`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4941 +#, no-wrap +msgid "Modification time; see man:utimes[2]" +msgstr "Время изменения; см. man:utimes[2]" + +#. 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 "" +"Определить, могут ли учётные данные субъекта установить переданные времена " +"доступа на переданном vnode. Возвращает 0 при успехе или значение `errno` " +"при ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM " +"при отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4949 +#, no-wrap +msgid "`mpo_check_proc_sched`" +msgstr "`mpo_check_proc_sched`" + +#. 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 "int mpo_check_proc_sched(struct ucred *ucred, struct proc *proc);\n" + +#. 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 "" +"Определить, могут ли учетные данные субъекта изменить параметры планирования " +"переданного процесса. Возвращает 0 при успехе или значение `errno` при " +"ошибке. Рекомендуемые ошибки: EACCES при несоответствии метки, EPERM при " +"отсутствии привилегий или ESRCH для ограничения видимости." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4977 +msgid "See man:setpriority[2] for more information." +msgstr "См. man:setpriority[2] для получения дополнительной информации." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:4979 +#, no-wrap +msgid "`mpo_check_proc_signal`" +msgstr "`mpo_check_proc_signal`" + +#. 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 "int mpo_check_proc_signal(struct ucred *cred, struct proc *proc, int signal);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5002 +#, no-wrap +msgid "`signal`" +msgstr "`signal`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5003 +#, no-wrap +msgid "Signal; see man:kill[2]" +msgstr "Сигнал; см. man:kill[2]" + +#. 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 "" +"Определить, могут ли учётные данные субъекта доставить указанный сигнал " +"указанному процессу. Возвращает 0 при успехе или значение `errno` при " +"ошибке. Рекомендуемые коды ошибок: EACCES при несоответствии метки, EPERM " +"при недостатке прав или ESRCH для ограничения видимости." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5011 +#, no-wrap +msgid "`mpo_check_vnode_stat`" +msgstr "`mpo_check_vnode_stat`" + +#. 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 "" +"int mpo_check_vnode_stat(struct ucred *cred, struct vnode *vp,\n" +" struct label *label);\n" + +#. 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 "" +"Определить, могут ли учетные данные субъекта выполнять `stat` для " +"переданного vnode. Возвращает 0 при успехе или значение `errno` при ошибке. " +"Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при " +"отсутствии привилегий." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5044 +msgid "See man:stat[2] for more information." +msgstr "См. man:stat[2] для получения дополнительной информации." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5046 +#, no-wrap +msgid "`mpo_check_ifnet_transmit`" +msgstr "`mpo_check_ifnet_transmit`" + +#. 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 "" +"int mpo_check_ifnet_transmit(struct ucred *cred, struct ifnet *ifnet,\n" +" struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5075 +#, no-wrap +msgid "Object; mbuf to be sent" +msgstr "Объект; mbuf для отправки" + +#. 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 "" +"Определить, может ли сетевой интерфейс передать mbuf, переданный в качестве " +"параметра. Возвращает 0 при успехе или значение `errno` при ошибке. " +"Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при " +"отсутствии привилегий." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5087 +#, no-wrap +msgid "`mpo_check_socket_deliver`" +msgstr "`mpo_check_socket_deliver`" + +#. 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 "" +"int mpo_check_socket_deliver(struct ucred *cred, struct ifnet *ifnet,\n" +" struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5116 +#, no-wrap +msgid "Object; mbuf to be delivered" +msgstr "Объект; mbuf для доставки" + +#. 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 "" +"Определить, может ли сокет принять датаграмму, хранящуюся в переданном " +"заголовке mbuf. Возвращает 0 при успехе или значение `errno` при ошибке. " +"Рекомендуемые ошибки: EACCES при несоответствии метки или EPERM при " +"отсутствии привилегий." + +#. 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 "" +"int mpo_check_socket_visible(struct ucred *cred, struct socket *so,\n" +" struct label *socketlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5153 +#, no-wrap +msgid "Policy label for `so`" +msgstr "Метка политики для `so`" + +#. 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 "" +"Определить, могут ли учетные данные субъекта cred \"видеть\" переданный " +"сокет (`socket`), используя функции системного мониторинга, такие как те, " +"что применяются в man:netstat[8] и man:sockstat[1]. Возвращает 0 при успехе " +"или значение `errno` при ошибке. Рекомендуемые ошибки: EACCES при " +"несоответствии меток, EPERM при отсутствии привилегий или ESRCH для скрытия " +"видимости." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5161 +#, no-wrap +msgid "`mpo_check_system_acct`" +msgstr "`mpo_check_system_acct`" + +#. 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 "" +"int mpo_check_system_acct(struct ucred *ucred, struct vnode *vp,\n" +" struct label *vlabel);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5177 +#, no-wrap +msgid "`ucred`" +msgstr "`ucred`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5182 +#, no-wrap +msgid "Accounting file; man:acct[5]" +msgstr "Файл учёта; man:acct[5]" + +#. 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 "`mpo_check_system_nfsd`" + +#. 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 "int mpo_check_system_nfsd(struct ucred *cred);\n" + +#. 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 "Определить, следует ли разрешить субъекту вызывать man:nfssvc[2]." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5214 +#, no-wrap +msgid "`mpo_check_system_reboot`" +msgstr "`mpo_check_system_reboot`" + +#. 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 "int mpo_check_system_reboot(struct ucred *cred, int howto);\n" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5233 +#, no-wrap +msgid "`howto`" +msgstr "`howto`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5234 +#, no-wrap +msgid "`howto` parameter from man:reboot[2]" +msgstr "Параметр `howto` из man:reboot[2]" + +#. 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 "`mpo_check_system_settime`" + +#. 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 "int mpo_check_system_settime(struct ucred *cred);\n" + +#. 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 "`mpo_check_system_swapon`" + +#. 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 "" +"int mpo_check_system_swapon(struct ucred *cred, struct vnode *vp,\n" +" struct label *vlabel);\n" + +#. 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 "" +"Определить, следует ли разрешить субъекту добавлять `vp` как устройство " +"подкачки." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5293 +#, no-wrap +msgid "`mpo_check_system_sysctl`" +msgstr "`mpo_check_system_sysctl`" + +#. 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 "" +"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" + +#. 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 "См. man:sysctl[3]" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5325 +#, no-wrap +msgid "`oldlenp`" +msgstr "`oldlenp`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5329 +#, no-wrap +msgid "`inkernel`" +msgstr "`inkernel`" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5330 +#, no-wrap +msgid "Boolean; `1` if called from kernel" +msgstr "Логический; `1`, если вызвано из ядра" + +#. type: Table +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5337 +#, no-wrap +msgid "`newlen`" +msgstr "`newlen`" + +#. 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 "" +"Определить, следует ли разрешить субъекту выполнять указанную транзакцию " +"man:sysctl[3]." + +#. 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 "" +"В фреймворк TrustedBSD MAC входит ряд элементов, не зависящих от политик, " +"включая интерфейсы MAC-библиотеки для абстрактного управления метками, " +"изменения в управлении системными учетными данными и библиотеках входа в " +"систему для поддержки назначения MAC-меток пользователям, а также набор " +"инструментов для мониторинга и изменения меток процессов, файлов и сетевых " +"интерфейсов. Более подробная информация о пользовательской архитектуре будет " +"добавлена в этот раздел в ближайшее время." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/mac/_index.adoc:5358 +#, no-wrap +msgid "APIs for Policy-Agnostic Label Management" +msgstr "API для управления метками, не зависящими от политики" + +#. 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 "" +"Фреймворк TrustedBSD MAC предоставляет ряд библиотечных и системных вызовов, " +"позволяющих приложениям управлять метками MAC на объектах с использованием " +"политико-независимого интерфейса. Это позволяет приложениям манипулировать " +"метками для различных политик без необходимости поддержки конкретных " +"политик. Эти интерфейсы используются универсальными инструментами, такими " +"как man:ifconfig[8], man:ls[1] и man:ps[1], для просмотра меток на сетевых " +"интерфейсах, файлах и процессах. API также поддерживают инструменты " +"управления MAC, включая man:getfmac[8], man:getpmac[8], man:setfmac[8], " +"man:setfsmac[8] и man:setpmac[8]. API MAC документированы в man:mac[3]." + +#. 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 "" +"Приложения обрабатывают метки MAC в двух формах: внутренней форме, " +"используемой для возврата и установки меток для процессов и объектов " +"(`mac_t`), и внешней форме, основанной на строках C, подходящих для хранения " +"в конфигурационных файлах, отображения пользователю или ввода от " +"пользователя. Каждая метка MAC содержит ряд элементов, каждый из которых " +"состоит из пары имя-значение. Модули политик в ядре привязываются к " +"определённым именам и интерпретируют значения специфичным для политики " +"образом. Во внешней строковой форме метки представляются списком пар имя-" +"значение, разделённых запятыми и символом `/`. Метки могут быть напрямую " +"преобразованы в текст и обратно с использованием предоставленных API; при " +"извлечении меток из ядра внутреннее хранилище меток должно быть сначала " +"подготовлено для желаемого набора элементов метки. Обычно это делается одним " +"из двух способов: с использованием man:mac_prepare[3] и произвольного списка " +"желаемых элементов метки, или одной из вариаций вызова, который загружает " +"набор элементов по умолчанию из конфигурационного файла man:mac.conf[5]. " +"Значения по умолчанию для каждого объекта позволяют разработчикам приложений " +"удобно отображать метки, связанные с объектами, без необходимости знать о " +"присутствующих в системе политиках." + +#. 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 "" +"В настоящее время прямое манипулирование элементами меток, кроме как путем " +"преобразования в текстовую строку, редактирования строки и обратного " +"преобразования во внутреннюю метку, не поддерживается библиотекой MAC. Такие " +"интерфейсы могут быть добавлены в будущем, если окажется, что они необходимы " +"разработчикам приложений." + +#. 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 "" +"Стандартный интерфейс управления контекстом пользователя, " +"man:setusercontext[3], был изменён для получения меток MAC, связанных с " +"классом пользователя, из man:login.conf[5]. Эти метки устанавливаются вместе " +"с остальным контекстом пользователя, когда указан `LOGIN_SETALL` или явно " +"указан `LOGIN_SETMAC`." + +#. 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 "" +"Ожидается, что в будущей версии FreeBSD база данных меток MAC будет отделена " +"от абстракции классов пользователей [.filename]#login.conf# и будет " +"поддерживаться в отдельной базе данных. Однако API man:setusercontext[3] " +"должно остаться неизменным после такого изменения." + +#. 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 "" +"Фреймворк TrustedBSD MAC позволяет модулям ядра расширять политику " +"безопасности системы высокоинтегрированным способом. Они могут делать это на " +"основе существующих свойств объектов или данных меток, которые " +"поддерживаются с помощью фреймворка MAC. Фреймворк достаточно гибкий для " +"реализации различных типов политик, включая политики безопасности " +"информационных потоков, такие как MLS и Biba, а также политики, основанные " +"на существующих учетных данных BSD или защите файлов. Авторам политик может " +"быть полезно ознакомиться с этой документацией, а также с существующими " +"модулями безопасности при реализации новой службы безопасности." + +#~ 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 "" +#~ "Вектор точек входа политики MAC, `mac__policy__ops` в данном примере, " +#~ "связывает функции, определённые в модуле, с конкретными точками входа. " +#~ "Полный список доступных точек входа и их прототипов можно найти в разделе " +#~ "справочника по точкам входа MAC. Особый интерес при регистрации модуля " +#~ "представляют точки входа .mpo_destroy и .mpo_init." + +#, 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 "mpo_init будет вызван после успешной регистрации политики в модульной системе, но до активации других точек входа." + +#~ msgid "" +#~ "This permits the policy to perform any policy-specific allocation and " +#~ "initialization, such as initialization of any data or locks." +#~ msgstr "" +#~ "Это позволяет политике выполнять любые выделения и инициализации, " +#~ "специфичные для данной политики, такие как инициализация данных или " +#~ "блокировок." + +#, 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 "mpo_destroy будет вызван при выгрузке модуля политики для освобождения выделенной памяти и уничтожения блокировок." + +#~ 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 "" +#~ "В настоящее время эти две точки входа вызываются с удержанием мьютекса " +#~ "списка политик MAC, чтобы предотвратить вызов других точек входа: это " +#~ "будет изменено, но до тех пор политики должны быть осторожны с " +#~ "используемыми примитивами ядра, чтобы избежать проблем с порядком " +#~ "блокировок или сном." diff --git a/documentation/content/ru/books/arch-handbook/newbus/_index.adoc b/documentation/content/ru/books/arch-handbook/newbus/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/newbus/_index.adoc @@ -0,0 +1,213 @@ +--- +authors: + - + author: 'Jeroen Ruigrok van der Werven (asmodai)' + email: asmodai@FreeBSD.org + - + author: 'Hiten Pandya' + email: hiten@uk.FreeBSD.org +description: Newbus +next: books/arch-handbook/sound +params: + path: /books/arch-handbook/newbus/ +prev: books/arch-handbook/usb +showBookMenu: true +tags: ["Newbus", "overview", "API"] +title: 'Глава 14. Newbus' +weight: 16 +--- + +[[newbus]] += Newbus +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 14 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +_Особая благодарность Мэтью Н. Додду, Уорнеру Лошу, Биллу Полу, Дагу Рэбсону, Майку Смиту, Питеру Вемму и Скотту Лонгу_. + +Эта глава подробно объясняет фреймворк устройств Newbus. + +[[newbus-devdrivers]] +== Драйверы устройств + +=== Назначение драйвера устройства + +Драйвер устройства — это программный компонент, который предоставляет интерфейс между обобщённым представлением периферийного устройства (например, диска, сетевого адаптера) в ядре и его фактической реализацией. _Интерфейс драйвера устройства (DDI)_ — это определённый интерфейс между ядром и компонентом драйвера устройства. + +=== Типы драйверов устройств + +В UNIX(R), а следовательно, и в FreeBSD, были времена, когда определялось четыре типа устройств: + +* драйверы блочных устройств +* драйверы символьных устройств +* драйверы сетевых устройств +* драйверы псевдоустройств + +_Блочные устройства_ работали таким образом, что использовали блоки [данных] фиксированного размера. Этот тип драйвера зависел от так называемого _буферного кэша_, который кэшировал доступные блоки данных в выделенной части памяти. Часто этот буферный кэш был основан на отложенной записи (write-behind), что означало, что при изменении данных в памяти они синхронизировались с диском во время периодической очистки диска системой, тем самым оптимизируя запись. + +=== Символьные устройства + +Однако в версиях FreeBSD 4.0 и выше различие между блочными и символьными устройствами перестало существовать. + +[[newbus-overview]] +== Обзор Newbus + +_Newbus_ — это реализация новой архитектуры шины, основанной на уровнях абстракции, которая была впервые представлена в FreeBSD 3.0, когда порт для Alpha был добавлен в дерево исходного кода. Однако только в версии 4.0 она стала системой по умолчанию для использования с драйверами устройств. Её цель — предоставить более объектно-ориентированный способ взаимодействия между различными шинами и устройствами, которые хост-система предоставляет _операционной системе_. + +Основные функции включают, среди прочего: + +* динамическое присоединение +* простая модуляризация драйверов +* псевдо-шины + +Одним из наиболее заметных изменений является переход от плоской и нерегламентированной системы к структуре дерева устройств. + +На верхнем уровне находится устройство _"root"_, которое является родительским для всех остальных устройств. Для каждой архитектуры обычно существует единственный дочерний элемент "root", к которому подключены такие компоненты, как _мосты host-to-PCI_ и т.д. Для x86 этим устройством "root" является устройство _"nexus"_. Для Alpha различные модели Alpha имеют разные устройства верхнего уровня, соответствующие различным аппаратным наборам микросхем, включая _lca_, _apecs_, _cia_ и _tsunami_. + +Устройство в контексте Newbus представляет собой отдельную аппаратную сущность в системе. Например, каждое PCI-устройство представлено устройством Newbus. Любое устройство в системе может иметь дочерние устройства; устройство, у которого есть дочерние устройства, часто называют _"шиной"_. Примерами распространённых шин в системе являются ISA и PCI, которые управляют списками устройств, подключённых к шинам ISA и PCI соответственно. + +Часто соединение между различными типами шин представлено устройством _"мост"_, которое обычно имеет один дочерний элемент для подключенной шины. Примером этого является _PCI-to-PCI мост_, который представлен устройством _[.filename]#pcibN#_ на родительской PCI-шине и имеет дочерний элемент _[.filename]#pciN#_ для подключенной шины. Такая структура упрощает реализацию дерева PCI-шин, позволяя использовать общий код как для верхнеуровневых, так и для соединенных через мост шин. + +Каждое устройство в архитектуре Newbus запрашивает у своего родителя отображение своих ресурсов. Затем родитель запрашивает у своего собственного родителя, пока запрос не достигнет nexus. Таким образом, по сути, nexus - это единственная часть системы Newbus, которая знает обо всех ресурсах. + +[TIP] +==== +Устройство ISA может захотеть отобразить свой порт ввода-вывода по адресу `0x230`, поэтому оно запрашивает у своего родителя, в данном случае — шины ISA. Шина ISA передаёт запрос мосту PCI-to-ISA, который, в свою очередь, запрашивает шину PCI. Запрос доходит до моста host-to-PCI и, наконец, до nexus. Прелесть этого восходящего перехода в том, что есть возможность преобразовывать запросы. Например, запрос порта ввода-вывода `0x230` может быть преобразован в отображение памяти по адресу `0xb0000230` на системе MIPS с помощью моста PCI. +==== + +Распределение ресурсов может контролироваться в любом месте дерева устройств. Например, на многих платформах Alpha прерывания ISA управляются отдельно от прерываний PCI, а распределение ресурсов для прерываний ISA осуществляется устройством шины ISA Alpha. На IA-32 прерывания ISA и PCI управляются устройством верхнего уровня nexus. Для обеих архитектур управление пространством памяти и портов осуществляется единым объектом — nexus для IA-32 и соответствующим драйвером чипсета на Alpha (например, CIA или tsunami). + +Для стандартизации доступа к памяти и ресурсам, отображённым на порты, Newbus интегрирует API `bus_space` из NetBSD. Они предоставляют единый API для замены inb/outb и прямых операций чтения/записи в память. Преимущество этого подхода в том, что один драйвер может легко использовать либо регистры, отображённые в память, либо регистры, отображённые на порты (некоторое оборудование поддерживает оба варианта). + +Эта поддержка интегрирована в механизм распределения ресурсов. При выделении ресурса драйвер может получить связанные `bus_space_tag_t` и `bus_space_handle_t` из этого ресурса. + +Newbus также позволяет определять методы интерфейса в файлах, предназначенных для этой цели. Это файлы с расширением [.filename]#.m#, которые находятся в иерархии [.filename]#src/sys#. + +Ядро системы Newbus представляет собой расширяемую модель «объектно-ориентированного программирования». Каждое устройство в системе имеет таблицу поддерживаемых методов. Система и другие устройства используют эти методы для управления устройством и запроса услуг. Различные методы, поддерживаемые устройством, определяются рядом «интерфейсов». «Интерфейс» — это просто группа связанных методов, которые могут быть реализованы устройством. + +В системе Newbus методы для устройства предоставляются различными драйверами устройств в системе. Когда устройство подключается к драйверу во время _автоконфигурации_, оно использует таблицу методов, объявленную драйвером. Устройство может позже _отключиться_ от своего драйвера и _подключиться_ к новому драйверу с новой таблицей методов. Это позволяет динамически заменять драйверы, что может быть полезно для разработки драйверов. + +Интерфейсы описываются языком определения интерфейсов, похожим на язык, используемый для определения операций vnode для файловых систем. Интерфейс хранится в файле методов (который обычно называется [.filename]#foo_if.m#). + +.Методы Newbus +[example] +==== +[.programlisting] +.... + # Foo subsystem/driver (a comment...) + + INTERFACE foo + + METHOD int doit { + device_t dev; + }; + + # DEFAULT is the method that will be used, if a method was not + # provided via: DEVMETHOD() + + METHOD void doit_to_child { + device_t dev; + driver_t child; + } DEFAULT doit_generic_to_child; +.... +==== + +Когда этот интерфейс компилируется, он генерирует заголовочный файл "[.filename]#foo_if.h#", который содержит объявления функций: + +[.programlisting] +.... + int FOO_DOIT(device_t dev); + int FOO_DOIT_TO_CHILD(device_t dev, device_t child); +.... + +Исходный файл `[.filename]#foo_if.c#` также создается для сопровождения автоматически сгенерированного заголовочного файла; он содержит реализации функций, которые ищут расположение соответствующих функций в таблице методов объекта и вызывают эту функцию. + +Система определяет два основных интерфейса. Первый фундаментальный интерфейс называется _"device"_ (устройство) и включает методы, которые относятся ко всем устройствам. Методы в интерфейсе _"device"_ включают _"probe"_ (обнаружение), _"attach"_ (присоединение) и _"detach"_ (отсоединение) для управления обнаружением оборудования, а также _"shutdown"_ (выключение), _"suspend"_ (приостановка) и _"resume"_ (возобновление) для уведомления о критических событиях. + +Второй, более сложный интерфейс — _"bus"_. Этот интерфейс содержит методы, подходящие для устройств, имеющих дочерние элементы, включая методы доступа к специфичной для шины информации об устройстве footnote:[man:bus_generic_read_ivar[9] и man:bus_generic_write_ivar[9]], уведомления о событиях (`_child_detached_`, `_driver_added_`) и управление ресурсами (`_alloc_resource_`, `_activate_resource_`, `_deactivate_resource_`, `_release_resource_`). + +Многие методы в интерфейсе "bus" выполняют сервисы для некоторого дочернего устройства шины. Эти методы обычно используют первые два аргумента для указания шины, предоставляющей сервис, и дочернего устройства, запрашивающего сервис. Для упрощения кода драйвера многие из этих методов имеют вспомогательные функции, которые находят родительское устройство и вызывают метод у родителя. Например, метод `BUS_TEARDOWN_INTR(device_t dev, device_t child, ...)` может быть вызван с помощью функции `bus_teardown_intr(device_t child, ...)`. + +Некоторые типы шин в системе определяют дополнительные интерфейсы для предоставления доступа к специфичной для шины функциональности. Например, драйвер шины PCI определяет интерфейс "pci", который имеет два метода `_read_config_` и `_write_config_` для доступа к конфигурационным регистрам устройства PCI. + +[[newbus-api]] +== Newbus API + +Поскольку API Newbus очень обширен, в этом разделе предпринята попытка его документирования. Дополнительная информация будет добавлена в следующей версии этого документа. + +=== Важные места в иерархии исходного кода + +[.filename]#src/sys/[arch]/[arch]# - Код ядра для конкретной аппаратной архитектуры находится в этом каталоге. Например, архитектура `i386` или архитектура `SPARC64`. + +[.filename]#src/sys/dev/[bus]# - поддержка устройств для конкретной `[bus]` находится в этом каталоге. + +[.filename]#src/sys/dev/pci# - Код поддержки шины PCI находится в этом каталоге. + +[.filename]#src/sys/[isa|pci]# - В этом каталоге находятся драйверы устройств PCI/ISA. Код поддержки шины PCI/ISA располагался в этом каталоге в FreeBSD версии `4.0`. + +=== Важные структуры и определения типов + +`devclass_t` - Это определение типа указателя на `struct devclass`. + +`device_method_t` - Это то же самое, что и `kobj_method_t` (см. [.filename]#src/sys/kobj.h#). + +`device_t` - Это определение типа указателя на структуру `struct device`. `device_t` представляет устройство в системе. Это объект ядра. Подробности реализации см. в [.filename]#src/sys/sys/bus_private.h#. + +`driver_t` - Это определение типа, которое ссылается на `struct driver`. Структура `driver` является классом объекта ядра `device`; она также содержит данные, приватные для драйвера. + +*_driver_t_ Implementation* +[.programlisting] +.... + struct driver { + KOBJ_CLASS_FIELDS; + void *priv; /* driver private data */ + }; +.... + +Тип `device_state_t`, который является перечислением, `device_state`. Он содержит возможные состояния устройства Newbus до и после процесса автонастройки. + +*Device States _device_state_t* +[.programlisting] +.... + /* + * src/sys/sys/bus.h + */ + typedef enum device_state { + DS_NOTPRESENT, /* not probed or probe failed */ + DS_ALIVE, /* probe succeeded */ + DS_ATTACHED, /* attach method called */ + DS_BUSY /* device is open */ + } device_state_t; +.... diff --git a/documentation/content/ru/books/arch-handbook/newbus/_index.po b/documentation/content/ru/books/arch-handbook/newbus/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/newbus/_index.po @@ -0,0 +1,711 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-05 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 "Newbus" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:1 +#, no-wrap +msgid "Chapter 14. Newbus" +msgstr "Глава 14. Newbus" + +#. 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 "Эта глава подробно объясняет фреймворк устройств Newbus." + +#. 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 "" +"Драйвер устройства — это программный компонент, который предоставляет " +"интерфейс между обобщённым представлением периферийного устройства " +"(например, диска, сетевого адаптера) в ядре и его фактической реализацией. " +"_Интерфейс драйвера устройства (DDI)_ — это определённый интерфейс между " +"ядром и компонентом драйвера устройства." + +#. 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 "" +"В UNIX(R), а следовательно, и в FreeBSD, были времена, когда определялось " +"четыре типа устройств:" + +#. 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 "" +"_Блочные устройства_ работали таким образом, что использовали блоки [данных] " +"фиксированного размера. Этот тип драйвера зависел от так называемого " +"_буферного кэша_, который кэшировал доступные блоки данных в выделенной " +"части памяти. Часто этот буферный кэш был основан на отложенной записи " +"(write-behind), что означало, что при изменении данных в памяти они " +"синхронизировались с диском во время периодической очистки диска системой, " +"тем самым оптимизируя запись." + +#. 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 "" +"Однако в версиях FreeBSD 4.0 и выше различие между блочными и символьными " +"устройствами перестало существовать." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:83 +#, no-wrap +msgid "Overview of Newbus" +msgstr "Обзор Newbus" + +#. 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 "" +"_Newbus_ — это реализация новой архитектуры шины, основанной на уровнях " +"абстракции, которая была впервые представлена в FreeBSD 3.0, когда порт для " +"Alpha был добавлен в дерево исходного кода. Однако только в версии 4.0 она " +"стала системой по умолчанию для использования с драйверами устройств. Её " +"цель — предоставить более объектно-ориентированный способ взаимодействия " +"между различными шинами и устройствами, которые хост-система предоставляет " +"_операционной системе_." + +#. 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 "" +"На верхнем уровне находится устройство _\"root\"_, которое является " +"родительским для всех остальных устройств. Для каждой архитектуры обычно " +"существует единственный дочерний элемент \"root\", к которому подключены " +"такие компоненты, как _мосты host-to-PCI_ и т.д. Для x86 этим устройством " +"\"root\" является устройство _\"nexus\"_. Для Alpha различные модели Alpha " +"имеют разные устройства верхнего уровня, соответствующие различным " +"аппаратным наборам микросхем, включая _lca_, _apecs_, _cia_ и _tsunami_." + +#. 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 "" +"Устройство в контексте Newbus представляет собой отдельную аппаратную " +"сущность в системе. Например, каждое PCI-устройство представлено устройством " +"Newbus. Любое устройство в системе может иметь дочерние устройства; " +"устройство, у которого есть дочерние устройства, часто называют _\"шиной\"_. " +"Примерами распространённых шин в системе являются ISA и PCI, которые " +"управляют списками устройств, подключённых к шинам ISA и PCI соответственно." + +#. 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 "" +"Часто соединение между различными типами шин представлено устройством " +"_\"мост\"_, которое обычно имеет один дочерний элемент для подключенной " +"шины. Примером этого является _PCI-to-PCI мост_, который представлен " +"устройством _[.filename]#pcibN#_ на родительской PCI-шине и имеет дочерний " +"элемент _[.filename]#pciN#_ для подключенной шины. Такая структура упрощает " +"реализацию дерева PCI-шин, позволяя использовать общий код как для " +"верхнеуровневых, так и для соединенных через мост шин." + +#. 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 "" +"Каждое устройство в архитектуре Newbus запрашивает у своего родителя " +"отображение своих ресурсов. Затем родитель запрашивает у своего собственного " +"родителя, пока запрос не достигнет nexus. Таким образом, по сути, nexus - " +"это единственная часть системы Newbus, которая знает обо всех ресурсах." + +#. 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 "" +"Устройство ISA может захотеть отобразить свой порт ввода-вывода по адресу " +"`0x230`, поэтому оно запрашивает у своего родителя, в данном случае — шины " +"ISA. Шина ISA передаёт запрос мосту PCI-to-ISA, который, в свою очередь, " +"запрашивает шину PCI. Запрос доходит до моста host-to-PCI и, наконец, до " +"nexus. Прелесть этого восходящего перехода в том, что есть возможность " +"преобразовывать запросы. Например, запрос порта ввода-вывода `0x230` может " +"быть преобразован в отображение памяти по адресу `0xb0000230` на системе " +"MIPS с помощью моста PCI." + +#. 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 "" +"Распределение ресурсов может контролироваться в любом месте дерева " +"устройств. Например, на многих платформах Alpha прерывания ISA управляются " +"отдельно от прерываний PCI, а распределение ресурсов для прерываний ISA " +"осуществляется устройством шины ISA Alpha. На IA-32 прерывания ISA и PCI " +"управляются устройством верхнего уровня nexus. Для обеих архитектур " +"управление пространством памяти и портов осуществляется единым объектом — " +"nexus для IA-32 и соответствующим драйвером чипсета на Alpha (например, CIA " +"или tsunami)." + +#. 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 "" +"Для стандартизации доступа к памяти и ресурсам, отображённым на порты, " +"Newbus интегрирует API `bus_space` из NetBSD. Они предоставляют единый API " +"для замены inb/outb и прямых операций чтения/записи в память. Преимущество " +"этого подхода в том, что один драйвер может легко использовать либо " +"регистры, отображённые в память, либо регистры, отображённые на порты " +"(некоторое оборудование поддерживает оба варианта)." + +#. 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 "" +"Эта поддержка интегрирована в механизм распределения ресурсов. При выделении " +"ресурса драйвер может получить связанные `bus_space_tag_t` и " +"`bus_space_handle_t` из этого ресурса." + +#. 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 "" +"Newbus также позволяет определять методы интерфейса в файлах, " +"предназначенных для этой цели. Это файлы с расширением [.filename]#.m#, " +"которые находятся в иерархии [.filename]#src/sys#." + +#. 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 "" +"Ядро системы Newbus представляет собой расширяемую модель «объектно-" +"ориентированного программирования». Каждое устройство в системе имеет " +"таблицу поддерживаемых методов. Система и другие устройства используют эти " +"методы для управления устройством и запроса услуг. Различные методы, " +"поддерживаемые устройством, определяются рядом «интерфейсов». «Интерфейс» — " +"это просто группа связанных методов, которые могут быть реализованы " +"устройством." + +#. 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 "" +"В системе Newbus методы для устройства предоставляются различными драйверами " +"устройств в системе. Когда устройство подключается к драйверу во время " +"_автоконфигурации_, оно использует таблицу методов, объявленную драйвером. " +"Устройство может позже _отключиться_ от своего драйвера и _подключиться_ к " +"новому драйверу с новой таблицей методов. Это позволяет динамически заменять " +"драйверы, что может быть полезно для разработки драйверов." + +#. 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 "" +"Интерфейсы описываются языком определения интерфейсов, похожим на язык, " +"используемый для определения операций vnode для файловых систем. Интерфейс " +"хранится в файле методов (который обычно называется [.filename]#foo_if.m#)." + +#. type: Block title +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:122 +#, no-wrap +msgid "Newbus Methods" +msgstr "Методы Newbus" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:128 +#, no-wrap +msgid " # Foo subsystem/driver (a comment...)\n" +msgstr " # Foo subsystem/driver (a comment...)\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:130 +#, no-wrap +msgid "\t INTERFACE foo\n" +msgstr "\t INTERFACE foo\n" + +#. 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 "" +"\tMETHOD int doit {\n" +"\t\tdevice_t dev;\n" +"\t};\n" + +#. 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 "" +"\t# DEFAULT is the method that will be used, if a method was not\n" +"\t# provided via: DEVMETHOD()\n" + +#. 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 "" +"\tMETHOD void doit_to_child {\n" +"\t\tdevice_t dev;\n" +"\t\tdriver_t child;\n" +"\t} DEFAULT doit_generic_to_child;\n" + +#. 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 "" +"Когда этот интерфейс компилируется, он генерирует заголовочный файл " +"\"[.filename]#foo_if.h#\", который содержит объявления функций:" + +#. 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 "" +" int FOO_DOIT(device_t dev);\n" +" int FOO_DOIT_TO_CHILD(device_t dev, device_t child);\n" + +#. 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 "" +"Исходный файл `[.filename]#foo_if.c#` также создается для сопровождения " +"автоматически сгенерированного заголовочного файла; он содержит реализации " +"функций, которые ищут расположение соответствующих функций в таблице методов " +"объекта и вызывают эту функцию." + +#. 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 "" +"Система определяет два основных интерфейса. Первый фундаментальный интерфейс " +"называется _\"device\"_ (устройство) и включает методы, которые относятся ко " +"всем устройствам. Методы в интерфейсе _\"device\"_ включают _\"probe\"_ " +"(обнаружение), _\"attach\"_ (присоединение) и _\"detach\"_ (отсоединение) " +"для управления обнаружением оборудования, а также _\"shutdown\"_ " +"(выключение), _\"suspend\"_ (приостановка) и _\"resume\"_ (возобновление) " +"для уведомления о критических событиях." + +#. 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 "" +"Второй, более сложный интерфейс — _\"bus\"_. Этот интерфейс содержит методы, " +"подходящие для устройств, имеющих дочерние элементы, включая методы доступа " +"к специфичной для шины информации об устройстве footnote:" +"[man:bus_generic_read_ivar[9] и man:bus_generic_write_ivar[9]], уведомления " +"о событиях (`_child_detached_`, `_driver_added_`) и управление ресурсами " +"(`_alloc_resource_`, `_activate_resource_`, `_deactivate_resource_`, " +"`_release_resource_`)." + +#. 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 "" +"Многие методы в интерфейсе \"bus\" выполняют сервисы для некоторого " +"дочернего устройства шины. Эти методы обычно используют первые два аргумента " +"для указания шины, предоставляющей сервис, и дочернего устройства, " +"запрашивающего сервис. Для упрощения кода драйвера многие из этих методов " +"имеют вспомогательные функции, которые находят родительское устройство и " +"вызывают метод у родителя. Например, метод `BUS_TEARDOWN_INTR(device_t dev, " +"device_t child, ...)` может быть вызван с помощью функции " +"`bus_teardown_intr(device_t child, ...)`." + +#. 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 "" +"Некоторые типы шин в системе определяют дополнительные интерфейсы для " +"предоставления доступа к специфичной для шины функциональности. Например, " +"драйвер шины PCI определяет интерфейс \"pci\", который имеет два метода " +"`_read_config_` и `_write_config_` для доступа к конфигурационным регистрам " +"устройства PCI." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:164 +#, no-wrap +msgid "Newbus API" +msgstr "Newbus API" + +#. 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 "" +"Поскольку API Newbus очень обширен, в этом разделе предпринята попытка его " +"документирования. Дополнительная информация будет добавлена в следующей " +"версии этого документа." + +#. 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 "" +"[.filename]#src/sys/[arch]/[arch]# - Код ядра для конкретной аппаратной " +"архитектуры находится в этом каталоге. Например, архитектура `i386` или " +"архитектура `SPARC64`." + +#. 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 "" +"[.filename]#src/sys/dev/[bus]# - поддержка устройств для конкретной `[bus]` " +"находится в этом каталоге." + +#. 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 "" +"[.filename]#src/sys/dev/pci# - Код поддержки шины PCI находится в этом " +"каталоге." + +#. 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 "" +"[.filename]#src/sys/[isa|pci]# - В этом каталоге находятся драйверы " +"устройств PCI/ISA. Код поддержки шины PCI/ISA располагался в этом каталоге в " +"FreeBSD версии `4.0`." + +#. 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 "`devclass_t` - Это определение типа указателя на `struct devclass`." + +#. 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 "" +"`device_method_t` - Это то же самое, что и `kobj_method_t` (см. " +"[.filename]#src/sys/kobj.h#)." + +#. 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 "" +"`device_t` - Это определение типа указателя на структуру `struct device`. " +"`device_t` представляет устройство в системе. Это объект ядра. Подробности " +"реализации см. в [.filename]#src/sys/sys/bus_private.h#." + +#. 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 "" +"`driver_t` - Это определение типа, которое ссылается на `struct driver`. " +"Структура `driver` является классом объекта ядра `device`; она также " +"содержит данные, приватные для драйвера." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:189 +#, fuzzy +#| msgid "*_driver_t_ Implementation*\n" +msgid "*_driver_t_ Implementation*" +msgstr "* Реализация _driver_t_*\n" + +#. 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 "" +"\t struct driver {\n" +"\t\tKOBJ_CLASS_FIELDS;\n" +"\t\tvoid\t*priv;\t\t\t/* driver private data */\n" +"\t };\n" + +#. 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 "" +"Тип `device_state_t`, который является перечислением, `device_state`. Он " +"содержит возможные состояния устройства Newbus до и после процесса " +"автонастройки." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/newbus/_index.adoc:200 +#, fuzzy +#| msgid "*Device States _device_state_t*\n" +msgid "*Device States _device_state_t*" +msgstr "*Состояния устройств _device_state_t*\n" + +#. 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 "" +"\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" diff --git a/documentation/content/ru/books/arch-handbook/parti.adoc b/documentation/content/ru/books/arch-handbook/parti.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/parti.adoc @@ -0,0 +1,13 @@ +--- +BundleType: branch +next: books/arch-handbook/boot +params: + path: /books/arch-handbook/parti/ +prev: books/arch-handbook +showBookMenu: true +title: 'Глава I. Ядро' +weight: 1 +--- + +[[kernel]] += Ядро системы diff --git a/documentation/content/ru/books/arch-handbook/parti.po b/documentation/content/ru/books/arch-handbook/parti.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/parti.po @@ -0,0 +1,31 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-06-12 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\n" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/parti.adoc:1 +#, no-wrap +msgid "Part I. Kernel" +msgstr "Глава I. Ядро" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/parti.adoc:13 +#, no-wrap +msgid "Kernel" +msgstr "Ядро системы" diff --git a/documentation/content/ru/books/arch-handbook/partii.adoc b/documentation/content/ru/books/arch-handbook/partii.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/partii.adoc @@ -0,0 +1,12 @@ +--- +next: books/arch-handbook/driverbasics +params: + path: /books/arch-handbook/partii/ +prev: books/arch-handbook/smp +showBookMenu: true +title: 'Глава II. Драйверы устройств' +weight: 10 +--- + +[[devicedrivers]] += Драйверы устройств diff --git a/documentation/content/ru/books/arch-handbook/partii.po b/documentation/content/ru/books/arch-handbook/partii.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/partii.po @@ -0,0 +1,31 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-05-29 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\n" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/partii.adoc:1 +#, no-wrap +msgid "Part II. Device Drivers" +msgstr "Глава II. Драйверы устройств" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/partii.adoc:12 +#, no-wrap +msgid "Device Drivers" +msgstr "Драйверы устройств" diff --git a/documentation/content/ru/books/arch-handbook/partiii.adoc b/documentation/content/ru/books/arch-handbook/partiii.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/partiii.adoc @@ -0,0 +1,12 @@ +--- +next: books/arch-handbook/bibliography +params: + path: /books/arch-handbook/partiii/ +prev: books/arch-handbook/pccard +showBookMenu: true +title: 'Глава III. Приложения' +weight: 19 +--- + +[[appendices]] += Приложения diff --git a/documentation/content/ru/books/arch-handbook/partiii.po b/documentation/content/ru/books/arch-handbook/partiii.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/partiii.po @@ -0,0 +1,31 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-05-29 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\n" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/partiii.adoc:1 +#, no-wrap +msgid "Part III. Appendices" +msgstr "Глава III. Приложения" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/partiii.adoc:12 +#, no-wrap +msgid "Appendices" +msgstr "Приложения" diff --git a/documentation/content/ru/books/arch-handbook/pccard/_index.adoc b/documentation/content/ru/books/arch-handbook/pccard/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/pccard/_index.adoc @@ -0,0 +1,209 @@ +--- +description: 'PC Card' +next: books/arch-handbook/partiii +params: + path: /books/arch-handbook/pccard/ +prev: books/arch-handbook/sound +showBookMenu: true +tags: ["pc card", "overview"] +title: 'Глава 16. PC Card' +weight: 18 +--- + +[[pccard]] += PC Card +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 16 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +Эта глава расскажет о механизмах FreeBSD для написания драйвера устройства для PC Card или CardBus устройства. Однако в настоящее время она лишь документирует, как добавить новое устройство к существующему драйверу pccard. + +[[pccard-adddev]] +== Добавление устройства + +Драйверы устройств знают, какие устройства они поддерживают. В ядре существует таблица поддерживаемых устройств, которую драйверы используют для подключения к устройству. + +[[pccard-overview]] +=== Обзор + +PC Cards идентифицируются одним из двух способов, оба основаны на _Card Information Structure_ (CIS), хранящейся на карте. Первый метод — использование числовых идентификаторов производителя и продукта. Второй метод — использование удобочитаемых строк, также содержащихся в CIS. Шина PC Card использует централизованную базу данных и некоторые макросы для упрощения шаблона проектирования, помогающего автору драйвера сопоставлять устройства с его драйвером. + +Производители оригинального оборудования (OEM) часто разрабатывают эталонный дизайн для продуктов PC Card, а затем продают этот дизайн другим компаниям для продвижения на рынке. Эти компании дорабатывают дизайн, продвигают продукт для своей целевой аудитории или географического региона и размещают на карте свою собственную торговую марку. Доработки физической карты обычно очень незначительны, если они вообще вносятся. Чтобы усилить свой бренд, такие поставщики указывают название своей компании в читаемых человеком строках в пространстве CIS, но оставляют идентификаторы производителя и продукта без изменений. + +Из-за такой практики драйверы FreeBSD обычно полагаются на числовые идентификаторы для распознавания устройств. Использование числовых идентификаторов и централизованной базы данных усложняет добавление ID и поддержку карт в систему. Необходимо тщательно проверять, кто на самом деле произвел карту, особенно когда кажется, что у производителя карты уже может быть другой идентификатор производителя в центральной базе данных. Linksys, D-Link и NetGear — это несколько американских производителей сетевого оборудования, которые часто продают один и тот же дизайн. Эти же дизайны могут продаваться в Японии под такими названиями, как Buffalo и Corega. Часто все эти устройства будут иметь одинаковые идентификаторы производителя и продукта. + +Код шины PC Card хранит централизованную базу данных информации о картах, но не о том, какой драйвер с ними связан, в [.filename]#/sys/dev/pccard/pccarddevs#. Он также предоставляет набор макросов, которые позволяют легко создавать простые записи в таблице, используемой драйвером для заявки устройств. + +Наконец, некоторые устройства очень низкого уровня вообще не содержат идентификации производителя. Эти устройства должны быть обнаружены путем сопоставления читаемых человеком строк CIS. Хотя было бы хорошо, если бы нам не нужен был этот метод в качестве запасного варианта, он необходим для некоторых очень дешевых CD-плееров и Ethernet-карт. Этот метод, как правило, следует избегать, но ряд устройств перечислен в этом разделе, потому что они были добавлены до осознания OEM-характера бизнеса PC Card. При добавлении новых устройств предпочтительнее использовать числовой метод. + +[[pccard-pccarddevs]] +=== Формат файла [.filename]#pccarddevs# + +В файле [.filename]#pccarddevs# есть четыре раздела. Первый раздел содержит номера производителей для вендоров, которые их используют. Этот раздел отсортирован в числовом порядке. Следующий раздел включает все продукты, используемые этими вендорами, вместе с их идентификаторами продуктов и строкой описания. Строка описания обычно не используется (вместо этого мы устанавливаем описание устройства на основе читаемого CIS, даже если совпадение найдено по числовому идентификатору). Затем эти два раздела повторяются для устройств, использующих метод строкового сопоставления. Наконец, C-подобные комментарии, заключенные между символами `/*` и `*/`, допускаются в любом месте файла. + +Первая часть файла содержит идентификаторы производителей. Пожалуйста, сохраняйте этот список в числовом порядке. Также, пожалуйста, согласовывайте изменения в этом файле, так как мы делимся им с NetBSD для создания общего центра обработки этой информации. Например, вот первые несколько идентификаторов производителей: + +[.programlisting] +.... +vendor FUJITSU 0x0004 Fujitsu Corporation +vendor NETGEAR_2 0x000b Netgear +vendor PANASONIC 0x0032 Matsushita Electric Industrial Co. +vendor SANDISK 0x0045 Sandisk Corporation +.... + +Вероятно, запись `NETGEAR_2` на самом деле относится к OEM-производителю, у которого NETGEAR приобретал карты, и автор поддержки этих карт не знал на тот момент, что Netgear использовал чужой идентификатор. Эти записи довольно просты. Ключевое слово `vendor` обозначает тип строки, за которым следует название производителя. Это название будет повторяться позже в [.filename]#pccarddevs#, а также использоваться в таблицах соответствия драйверов, поэтому оно должно быть коротким и допустимым идентификатором в C. Числовой идентификатор в шестнадцатеричном формате указывает производителя. Не добавляйте идентификаторы вида `0xffffffff` или `0xffff`, так как они зарезервированы (первый означает "идентификатор не установлен", а второй иногда встречается в крайне некачественных картах для указания "отсутствует"). Наконец, следует строковое описание компании, производящей карту. Эта строка в FreeBSD ни для чего не используется, кроме как в комментариях. + +Вторая секция файла содержит продукты. Как показано в этом примере, формат аналогичен строкам поставщиков: + +[.programlisting] +.... +/* Allied Telesis K.K. */ +product ALLIEDTELESIS LA_PCM 0x0002 Allied Telesis LA-PCM + +/* Archos */ +product ARCHOS ARC_ATAPI 0x0043 MiniCD +.... + +Ключевое слово `product` следует за именем производителя, повторяющимся сверху. После него идет название продукта, которое используется драйвером и должно быть допустимым идентификатором в C, но также может начинаться с цифры. Как и в случае с производителями, шестнадцатеричный идентификатор продукта для этой карты следует тем же соглашениям для `0xffffffff` и `0xffff`. Наконец, идет строковое описание самого устройства. Эта строка обычно не используется в FreeBSD, поскольку драйвер шины pccard в FreeBSD формирует строку из читаемых человеком записей CIS, но она может быть использована в редких случаях, когда этого недостаточно. Продукты перечислены в алфавитном порядке по производителю, затем в числовом порядке по идентификатору продукта. Перед записями каждого производителя есть комментарий в C, а между записями — пустая строка. + +Третий раздел аналогичен предыдущему разделу производителей, но все числовые идентификаторы производителей установлены в `-1`, что означает "совпадение с любым найденным" в коде шины pccard FreeBSD. Поскольку это идентификаторы C, их имена должны быть уникальными. В остальном формат идентичен первому разделу файла. + +Последний раздел содержит записи для тех карт, которые должны быть идентифицированы по строковым значениям. Формат этого раздела немного отличается от общего раздела: + +[.programlisting] +.... +product ADDTRON AWP100 { "Addtron", "AWP-100&spWireless&spPCMCIA", "Version&sp01.02", NULL } +product ALLIEDTELESIS WR211PCM { "Allied&spTelesis&spK.K.", "WR211PCM", NULL, NULL } Allied Telesis WR211PCM +.... + +Знакомое ключевое слово `product` сопровождается названием производителя и именем карты, как и во втором разделе файла. Здесь формат отличается от использованного ранее. Идёт группировка {}, за которой следует несколько строк. Эти строки соответствуют производителю, продукту и дополнительной информации, определённой в кортеже CIS_INFO. Эти строки фильтруются программой, которая генерирует [.filename]#pccarddevs.h#, чтобы заменить &sp на реальный пробел. Строки NULL означают, что соответствующую часть записи следует игнорировать. В приведённом здесь примере есть некорректная запись. Она не должна содержать номер версии, если только он не критичен для работы карты. Иногда у производителей может быть множество различных версий карты в обращении, которые все работают, и в таком случае эта информация только затрудняет использование аналогичной карты с FreeBSD. Иногда это необходимо, когда производитель хочет продавать множество различных компонентов под одним брендом из-за рыночных соображений (доступность, цена и т. д.). Тогда это может быть критично для различения карты в тех редких случаях, когда производитель сохранил ту же пару производитель/продукт. На данный момент использование регулярных выражений для сопоставления недоступно. + +[[pccard-probe]] +=== Пример процедуры обнаружения + +Чтобы понять, как добавить устройство в список поддерживаемых, необходимо разобраться в процедурах `probe` (обнаружение) и/или `match` (сопоставление), которые есть во многих драйверах. В FreeBSD 5.x это немного сложнее из-за наличия слоя совместимости с OLDCARD. Поскольку различия лишь косметические, здесь будет представлена идеализированная версия. + +[.programlisting] +.... +static const struct pccard_product wi_pccard_products[] = { + PCMCIA_CARD(3COM, 3CRWE737A, 0), + PCMCIA_CARD(BUFFALO, WLI_PCM_S11, 0), + PCMCIA_CARD(BUFFALO, WLI_CF_S11G, 0), + PCMCIA_CARD(TDK, LAK_CD011WL, 0), + { NULL } +}; + +static int +wi_pccard_probe(dev) + device_t dev; +{ + const struct pccard_product *pp; + + if ((pp = pccard_product_lookup(dev, wi_pccard_products, + sizeof(wi_pccard_products[0]), NULL)) != NULL) { + if (pp->pp_name != NULL) + device_set_desc(dev, pp->pp_name); + return (0); + } + return (ENXIO); +} +.... + +Вот простая процедура проверки pccard, которая соответствует нескольким устройствам. Как упоминалось выше, название может отличаться (если это не `foo_pccard_probe()`, то это будет `foo_pccard_match()`). Функция `pccard_product_lookup()` является обобщенной функцией, которая проходит по таблице и возвращает указатель на первую запись, которой соответствует. Некоторые драйверы могут использовать этот механизм для передачи дополнительной информации о некоторых картах остальной части драйвера, поэтому в таблице могут быть вариации. Единственное требование — каждая строка таблицы должна содержать `struct pccard_product` в качестве первого элемента. + +Рассматривая таблицу `wi_pccard_products`, можно заметить, что все записи имеют вид `PCMCIA_CARD(_foo_, _bar_, _baz_)`. Часть _foo_ — это идентификатор производителя из [.filename]#pccarddevs#. Часть _bar_ — это идентификатор продукта. _baz_ — ожидаемый номер функции для этой карты. Многие pccard-устройства могут иметь несколько функций, поэтому требуется способ различать функцию 1 и функцию 0. Вы можете встретить `PCMCIA_CARD_D`, который включает описание устройства из [.filename]#pccarddevs#. Также могут встречаться `PCMCIA_CARD2` и `PCMCIA_CARD2_D`, которые используются, когда необходимо сопоставить как строки CIS, так и номера производителей, в вариантах «использовать описание по умолчанию» и «взять описание из pccarddevs». + +[[pccard-add]] +=== Собираем все вместе + +Для добавления нового устройства необходимо сначала получить идентификационную информацию от устройства. Проще всего это сделать, вставив устройство в слот PC Card или CF и выполнив команду `devinfo -v`. Пример вывода: + +[.programlisting] +.... + cbb1 pnpinfo vendor=0x104c device=0xac51 subvendor=0x1265 subdevice=0x0300 class=0x060700 at slot=10 function=1 + cardbus1 + pccard1 + unknown pnpinfo manufacturer=0x026f product=0x030c cisvendor="BUFFALO" cisproduct="WLI2-CF-S11" function_type=6 at function=0 +.... + +`manufacturer` и `product` являются числовыми идентификаторами данного продукта, в то время как `cisvendor` и `cisproduct` представляют собой строки описания продукта из CIS. + +Поскольку мы сначала хотим предпочесть числовой вариант, попробуем сначала создать запись на его основе. Приведённая выше карта была слегка изменена для целей данного примера. Производитель — BUFFALO, у которого, как мы видим, уже есть запись: + +[.programlisting] +.... +vendor BUFFALO 0x026f BUFFALO (Melco Corporation) +.... + +Но нет записи для этой конкретной карты. Вместо этого мы видим: + +[.programlisting] +.... +/* BUFFALO */ +product BUFFALO WLI_PCM_S11 0x0305 BUFFALO AirStation 11Mbps WLAN +product BUFFALO LPC_CF_CLT 0x0307 BUFFALO LPC-CF-CLT +product BUFFALO LPC3_CLT 0x030a BUFFALO LPC3-CLT Ethernet Adapter +product BUFFALO WLI_CF_S11G 0x030b BUFFALO AirStation 11Mbps CF WLAN +.... + +Чтобы добавить устройство, мы можем просто добавить эту запись в [.filename]#pccarddevs#: + +[.programlisting] +.... +product BUFFALO WLI2_CF_S11G 0x030c BUFFALO AirStation ultra 802.11b CF +.... + +После выполнения этих шагов карту можно добавить в драйвер. Это простая операция добавления одной строки: + +[.programlisting] +.... +static const struct pccard_product wi_pccard_products[] = { + PCMCIA_CARD(3COM, 3CRWE737A, 0), + PCMCIA_CARD(BUFFALO, WLI_PCM_S11, 0), + PCMCIA_CARD(BUFFALO, WLI_CF_S11G, 0), ++ PCMCIA_CARD(BUFFALO, WLI_CF2_S11G, 0), + PCMCIA_CARD(TDK, LAK_CD011WL, 0), + { NULL } +}; +.... + +Обратите внимание, что я добавил символ '`+`' перед строкой, которую добавил, но это только для выделения строки. Не добавляйте его в реальный драйвер. После добавления строки вы можете пересобрать ядро или модуль и протестировать его. Если устройство распознано и работает, отправьте патч. Если оно не работает, определите, что необходимо для его работы, и отправьте патч. Если устройство не распознаётся вообще, вы где-то ошиблись и следует перепроверить каждый шаг. + +Если вы коммиттер исходного кода FreeBSD, и всё работает корректно, то можете закоммитить изменения в дерево. Однако есть несколько небольших нюансов, которые следует учесть. [.filename]#pccarddevs# должен быть закоммичен в дерево первым. Затем [.filename]#pccarddevs.h# необходимо перегенерировать и закоммитить вторым шагом, убедившись, что правильный тег $FreeBSD$ присутствует в последнем файле. В конце закоммитьте добавления в драйвер. + +[[pccard-pr]] +=== Отправка кода для нового устройства + +Пожалуйста, не отправляйте записи о новых устройствах автору напрямую. Вместо этого оформите их как PR и сообщите автору номер PR для учета. Это гарантирует, что записи не будут потеряны. При отправке PR нет необходимости включать в патч diff-файлы [.filename]#pccardevs.h#, так как они будут перегенерированы. Однако необходимо включить описание устройства, а также патчи для клиентского драйвера. Если название устройства неизвестно, используйте имя OEM99, и автор скорректирует OEM99 после изучения. Коммитеры не должны коммитить OEM99, а вместо этого найти наибольший OEM-номер и закоммитить на единицу больше. diff --git a/documentation/content/ru/books/arch-handbook/pccard/_index.po b/documentation/content/ru/books/arch-handbook/pccard/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/pccard/_index.po @@ -0,0 +1,710 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-03 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 "PC Card" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:1 +#, no-wrap +msgid "Chapter 16. PC Card" +msgstr "Глава 16. PC Card" + +#. 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 "" +"Эта глава расскажет о механизмах FreeBSD для написания драйвера устройства " +"для PC Card или CardBus устройства. Однако в настоящее время она лишь " +"документирует, как добавить новое устройство к существующему драйверу pccard." + +#. 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 "" +"PC Cards идентифицируются одним из двух способов, оба основаны на _Card " +"Information Structure_ (CIS), хранящейся на карте. Первый метод — " +"использование числовых идентификаторов производителя и продукта. Второй " +"метод — использование удобочитаемых строк, также содержащихся в CIS. Шина PC " +"Card использует централизованную базу данных и некоторые макросы для " +"упрощения шаблона проектирования, помогающего автору драйвера сопоставлять " +"устройства с его драйвером." + +#. 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 "" +"Производители оригинального оборудования (OEM) часто разрабатывают эталонный " +"дизайн для продуктов PC Card, а затем продают этот дизайн другим компаниям " +"для продвижения на рынке. Эти компании дорабатывают дизайн, продвигают " +"продукт для своей целевой аудитории или географического региона и размещают " +"на карте свою собственную торговую марку. Доработки физической карты обычно " +"очень незначительны, если они вообще вносятся. Чтобы усилить свой бренд, " +"такие поставщики указывают название своей компании в читаемых человеком " +"строках в пространстве CIS, но оставляют идентификаторы производителя и " +"продукта без изменений." + +#. 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 "" +"Из-за такой практики драйверы FreeBSD обычно полагаются на числовые " +"идентификаторы для распознавания устройств. Использование числовых " +"идентификаторов и централизованной базы данных усложняет добавление ID и " +"поддержку карт в систему. Необходимо тщательно проверять, кто на самом деле " +"произвел карту, особенно когда кажется, что у производителя карты уже может " +"быть другой идентификатор производителя в центральной базе данных. Linksys, " +"D-Link и NetGear — это несколько американских производителей сетевого " +"оборудования, которые часто продают один и тот же дизайн. Эти же дизайны " +"могут продаваться в Японии под такими названиями, как Buffalo и Corega. " +"Часто все эти устройства будут иметь одинаковые идентификаторы производителя " +"и продукта." + +#. 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 "" +"Код шины PC Card хранит централизованную базу данных информации о картах, но " +"не о том, какой драйвер с ними связан, в [.filename]#/sys/dev/pccard/" +"pccarddevs#. Он также предоставляет набор макросов, которые позволяют легко " +"создавать простые записи в таблице, используемой драйвером для заявки " +"устройств." + +#. 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 "" +"Наконец, некоторые устройства очень низкого уровня вообще не содержат " +"идентификации производителя. Эти устройства должны быть обнаружены путем " +"сопоставления читаемых человеком строк CIS. Хотя было бы хорошо, если бы нам " +"не нужен был этот метод в качестве запасного варианта, он необходим для " +"некоторых очень дешевых CD-плееров и Ethernet-карт. Этот метод, как правило, " +"следует избегать, но ряд устройств перечислен в этом разделе, потому что они " +"были добавлены до осознания OEM-характера бизнеса PC Card. При добавлении " +"новых устройств предпочтительнее использовать числовой метод." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pccard/_index.adoc:72 +#, no-wrap +msgid "Format of [.filename]#pccarddevs#" +msgstr "Формат файла [.filename]#pccarddevs#" + +#. 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 "" +"В файле [.filename]#pccarddevs# есть четыре раздела. Первый раздел содержит " +"номера производителей для вендоров, которые их используют. Этот раздел " +"отсортирован в числовом порядке. Следующий раздел включает все продукты, " +"используемые этими вендорами, вместе с их идентификаторами продуктов и " +"строкой описания. Строка описания обычно не используется (вместо этого мы " +"устанавливаем описание устройства на основе читаемого CIS, даже если " +"совпадение найдено по числовому идентификатору). Затем эти два раздела " +"повторяются для устройств, использующих метод строкового сопоставления. " +"Наконец, C-подобные комментарии, заключенные между символами `/*` и `*/`, " +"допускаются в любом месте файла." + +#. 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 "" +"Первая часть файла содержит идентификаторы производителей. Пожалуйста, " +"сохраняйте этот список в числовом порядке. Также, пожалуйста, согласовывайте " +"изменения в этом файле, так как мы делимся им с NetBSD для создания общего " +"центра обработки этой информации. Например, вот первые несколько " +"идентификаторов производителей:" + +#. 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 "" +"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" + +#. 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 "" +"Вероятно, запись `NETGEAR_2` на самом деле относится к OEM-производителю, у " +"которого NETGEAR приобретал карты, и автор поддержки этих карт не знал на " +"тот момент, что Netgear использовал чужой идентификатор. Эти записи довольно " +"просты. Ключевое слово `vendor` обозначает тип строки, за которым следует " +"название производителя. Это название будет повторяться позже в " +"[.filename]#pccarddevs#, а также использоваться в таблицах соответствия " +"драйверов, поэтому оно должно быть коротким и допустимым идентификатором в " +"C. Числовой идентификатор в шестнадцатеричном формате указывает " +"производителя. Не добавляйте идентификаторы вида `0xffffffff` или `0xffff`, " +"так как они зарезервированы (первый означает \"идентификатор не " +"установлен\", а второй иногда встречается в крайне некачественных картах для " +"указания \"отсутствует\"). Наконец, следует строковое описание компании, " +"производящей карту. Эта строка в FreeBSD ни для чего не используется, кроме " +"как в комментариях." + +#. 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 "" +"/* Allied Telesis K.K. */\n" +"product ALLIEDTELESIS LA_PCM\t0x0002 Allied Telesis LA-PCM\n" + +#. 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 "" +"/* Archos */\n" +"product\tARCHOS ARC_ATAPI\t0x0043 MiniCD\n" + +#. 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 "" +"Ключевое слово `product` следует за именем производителя, повторяющимся " +"сверху. После него идет название продукта, которое используется драйвером и " +"должно быть допустимым идентификатором в C, но также может начинаться с " +"цифры. Как и в случае с производителями, шестнадцатеричный идентификатор " +"продукта для этой карты следует тем же соглашениям для `0xffffffff` и " +"`0xffff`. Наконец, идет строковое описание самого устройства. Эта строка " +"обычно не используется в FreeBSD, поскольку драйвер шины pccard в FreeBSD " +"формирует строку из читаемых человеком записей CIS, но она может быть " +"использована в редких случаях, когда этого недостаточно. Продукты " +"перечислены в алфавитном порядке по производителю, затем в числовом порядке " +"по идентификатору продукта. Перед записями каждого производителя есть " +"комментарий в C, а между записями — пустая строка." + +#. 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 "" +"Третий раздел аналогичен предыдущему разделу производителей, но все числовые " +"идентификаторы производителей установлены в `-1`, что означает \"совпадение " +"с любым найденным\" в коде шины pccard FreeBSD. Поскольку это идентификаторы " +"C, их имена должны быть уникальными. В остальном формат идентичен первому " +"разделу файла." + +#. 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 "" +"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" + +#. 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 "" +"Знакомое ключевое слово `product` сопровождается названием производителя и " +"именем карты, как и во втором разделе файла. Здесь формат отличается от " +"использованного ранее. Идёт группировка {}, за которой следует несколько " +"строк. Эти строки соответствуют производителю, продукту и дополнительной " +"информации, определённой в кортеже CIS_INFO. Эти строки фильтруются " +"программой, которая генерирует [.filename]#pccarddevs.h#, чтобы заменить &sp " +"на реальный пробел. Строки NULL означают, что соответствующую часть записи " +"следует игнорировать. В приведённом здесь примере есть некорректная запись. " +"Она не должна содержать номер версии, если только он не критичен для работы " +"карты. Иногда у производителей может быть множество различных версий карты в " +"обращении, которые все работают, и в таком случае эта информация только " +"затрудняет использование аналогичной карты с FreeBSD. Иногда это необходимо, " +"когда производитель хочет продавать множество различных компонентов под " +"одним брендом из-за рыночных соображений (доступность, цена и т. д.). Тогда " +"это может быть критично для различения карты в тех редких случаях, когда " +"производитель сохранил ту же пару производитель/продукт. На данный момент " +"использование регулярных выражений для сопоставления недоступно." + +#. 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 "" +"Чтобы понять, как добавить устройство в список поддерживаемых, необходимо " +"разобраться в процедурах `probe` (обнаружение) и/или `match` " +"(сопоставление), которые есть во многих драйверах. В FreeBSD 5.x это немного " +"сложнее из-за наличия слоя совместимости с OLDCARD. Поскольку различия лишь " +"косметические, здесь будет представлена идеализированная версия." + +#. 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 "" +"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" + +#. 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 "" +"static int\n" +"wi_pccard_probe(dev)\n" +"\tdevice_t\tdev;\n" +"{\n" +"\tconst struct pccard_product *pp;\n" + +#. 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 "" +"\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" + +#. 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 "" +"Вот простая процедура проверки pccard, которая соответствует нескольким " +"устройствам. Как упоминалось выше, название может отличаться (если это не " +"`foo_pccard_probe()`, то это будет `foo_pccard_match()`). Функция " +"`pccard_product_lookup()` является обобщенной функцией, которая проходит по " +"таблице и возвращает указатель на первую запись, которой соответствует. " +"Некоторые драйверы могут использовать этот механизм для передачи " +"дополнительной информации о некоторых картах остальной части драйвера, " +"поэтому в таблице могут быть вариации. Единственное требование — каждая " +"строка таблицы должна содержать `struct pccard_product` в качестве первого " +"элемента." + +#. 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 "" +"Рассматривая таблицу `wi_pccard_products`, можно заметить, что все записи " +"имеют вид `PCMCIA_CARD(_foo_, _bar_, _baz_)`. Часть _foo_ — это " +"идентификатор производителя из [.filename]#pccarddevs#. Часть _bar_ — это " +"идентификатор продукта. _baz_ — ожидаемый номер функции для этой карты. " +"Многие pccard-устройства могут иметь несколько функций, поэтому требуется " +"способ различать функцию 1 и функцию 0. Вы можете встретить `PCMCIA_CARD_D`, " +"который включает описание устройства из [.filename]#pccarddevs#. Также могут " +"встречаться `PCMCIA_CARD2` и `PCMCIA_CARD2_D`, которые используются, когда " +"необходимо сопоставить как строки CIS, так и номера производителей, в " +"вариантах «использовать описание по умолчанию» и «взять описание из " +"pccarddevs»." + +#. 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 "" +"Для добавления нового устройства необходимо сначала получить " +"идентификационную информацию от устройства. Проще всего это сделать, вставив " +"устройство в слот PC Card или CF и выполнив команду `devinfo -v`. Пример " +"вывода:" + +#. 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 "" +" 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" + +#. 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 "" +"`manufacturer` и `product` являются числовыми идентификаторами данного " +"продукта, в то время как `cisvendor` и `cisproduct` представляют собой " +"строки описания продукта из CIS." + +#. 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 "" +"Поскольку мы сначала хотим предпочесть числовой вариант, попробуем сначала " +"создать запись на его основе. Приведённая выше карта была слегка изменена " +"для целей данного примера. Производитель — BUFFALO, у которого, как мы " +"видим, уже есть запись:" + +#. 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 "vendor BUFFALO\t\t\t0x026f\tBUFFALO (Melco Corporation)\n" + +#. 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 "" +"/* 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" + +#. 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 "" +"Чтобы добавить устройство, мы можем просто добавить эту запись в " +"[.filename]#pccarddevs#:" + +#. 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 "product BUFFALO WLI2_CF_S11G\t0x030c\tBUFFALO AirStation ultra 802.11b CF\n" + +#. 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 "" +"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" + +#. 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 "" +"Если вы коммиттер исходного кода FreeBSD, и всё работает корректно, то " +"можете закоммитить изменения в дерево. Однако есть несколько небольших " +"нюансов, которые следует учесть. [.filename]#pccarddevs# должен быть " +"закоммичен в дерево первым. Затем [.filename]#pccarddevs.h# необходимо " +"перегенерировать и закоммитить вторым шагом, убедившись, что правильный тег " +"$FreeBSD$ присутствует в последнем файле. В конце закоммитьте добавления в " +"драйвер." + +#. 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 "" +"Пожалуйста, не отправляйте записи о новых устройствах автору напрямую. " +"Вместо этого оформите их как PR и сообщите автору номер PR для учета. Это " +"гарантирует, что записи не будут потеряны. При отправке PR нет необходимости " +"включать в патч diff-файлы [.filename]#pccardevs.h#, так как они будут " +"перегенерированы. Однако необходимо включить описание устройства, а также " +"патчи для клиентского драйвера. Если название устройства неизвестно, " +"используйте имя OEM99, и автор скорректирует OEM99 после изучения. Коммитеры " +"не должны коммитить OEM99, а вместо этого найти наибольший OEM-номер и " +"закоммитить на единицу больше." diff --git a/documentation/content/ru/books/arch-handbook/pci/_index.adoc b/documentation/content/ru/books/arch-handbook/pci/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/pci/_index.adoc @@ -0,0 +1,424 @@ +--- +description: 'Устройства PCI' +next: books/arch-handbook/scsi +params: + path: /books/arch-handbook/pci/ +prev: books/arch-handbook/isa +showBookMenu: true +tags: ["PCI", "Devices", "example", "guide"] +title: 'Глава 11. Устройства PCI' +weight: 13 +--- + +[[pci]] += Устройства PCI +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 11 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +Эта глава расскажет о механизмах FreeBSD для написания драйвера устройства на шине PCI. + +[[pci-probe]] +== Обнаружение и подключение + +Информация о том, как код шины PCI перебирает неприсоединённые устройства и проверяет, сможет ли только что загруженный kld присоединиться к любому из них. + +=== Пример исходного кода драйвера ([.filename]#mypci.c#) + +[.programlisting] +.... +/* + * Simple KLD to play with the PCI functions. + * + * Murray Stokely + */ + +#include /* defines used in kernel.h */ +#include +#include +#include +#include /* types used in module initialization */ +#include /* cdevsw struct */ +#include /* uio struct */ +#include +#include /* structs, prototypes for pci bus stuff and DEVMETHOD macros! */ + +#include +#include +#include + +#include /* For pci_get macros! */ +#include + +/* The softc holds our per-instance data. */ +struct mypci_softc { + device_t my_dev; + struct cdev *my_cdev; +}; + +/* Function prototypes */ +static d_open_t mypci_open; +static d_close_t mypci_close; +static d_read_t mypci_read; +static d_write_t mypci_write; + +/* Character device entry points */ + +static struct cdevsw mypci_cdevsw = { + .d_version = D_VERSION, + .d_open = mypci_open, + .d_close = mypci_close, + .d_read = mypci_read, + .d_write = mypci_write, + .d_name = "mypci", +}; + +/* + * In the cdevsw routines, we find our softc by using the si_drv1 member + * of struct cdev. We set this variable to point to our softc in our + * attach routine when we create the /dev entry. + */ + +int +mypci_open(struct cdev *dev, int oflags, int devtype, struct thread *td) +{ + struct mypci_softc *sc; + + /* Look up our softc. */ + sc = dev->si_drv1; + device_printf(sc->my_dev, "Opened successfully.\n"); + return (0); +} + +int +mypci_close(struct cdev *dev, int fflag, int devtype, struct thread *td) +{ + struct mypci_softc *sc; + + /* Look up our softc. */ + sc = dev->si_drv1; + device_printf(sc->my_dev, "Closed.\n"); + return (0); +} + +int +mypci_read(struct cdev *dev, struct uio *uio, int ioflag) +{ + struct mypci_softc *sc; + + /* Look up our softc. */ + sc = dev->si_drv1; + device_printf(sc->my_dev, "Asked to read %zd bytes.\n", uio->uio_resid); + return (0); +} + +int +mypci_write(struct cdev *dev, struct uio *uio, int ioflag) +{ + struct mypci_softc *sc; + + /* Look up our softc. */ + sc = dev->si_drv1; + device_printf(sc->my_dev, "Asked to write %zd bytes.\n", uio->uio_resid); + return (0); +} + +/* PCI Support Functions */ + +/* + * Compare the device ID of this device against the IDs that this driver + * supports. If there is a match, set the description and return success. + */ +static int +mypci_probe(device_t dev) +{ + + device_printf(dev, "MyPCI Probe\nVendor ID : 0x%x\nDevice ID : 0x%x\n", + pci_get_vendor(dev), pci_get_device(dev)); + + if (pci_get_vendor(dev) == 0x11c1) { + printf("We've got the Winmodem, probe successful!\n"); + device_set_desc(dev, "WinModem"); + return (BUS_PROBE_DEFAULT); + } + return (ENXIO); +} + +/* Attach function is only called if the probe is successful. */ + +static int +mypci_attach(device_t dev) +{ + struct mypci_softc *sc; + + printf("MyPCI Attach for : deviceID : 0x%x\n", pci_get_devid(dev)); + + /* Look up our softc and initialize its fields. */ + sc = device_get_softc(dev); + sc->my_dev = dev; + + /* + * Create a /dev entry for this device. The kernel will assign us + * a major number automatically. We use the unit number of this + * device as the minor number and name the character device + * "mypci". + */ + sc->my_cdev = make_dev(&mypci_cdevsw, device_get_unit(dev), + UID_ROOT, GID_WHEEL, 0600, "mypci%u", device_get_unit(dev)); + sc->my_cdev->si_drv1 = sc; + printf("Mypci device loaded.\n"); + return (0); +} + +/* Detach device. */ + +static int +mypci_detach(device_t dev) +{ + struct mypci_softc *sc; + + /* Teardown the state in our softc created in our attach routine. */ + sc = device_get_softc(dev); + destroy_dev(sc->my_cdev); + printf("Mypci detach!\n"); + return (0); +} + +/* Called during system shutdown after sync. */ + +static int +mypci_shutdown(device_t dev) +{ + + printf("Mypci shutdown!\n"); + return (0); +} + +/* + * Device suspend routine. + */ +static int +mypci_suspend(device_t dev) +{ + + printf("Mypci suspend!\n"); + return (0); +} + +/* + * Device resume routine. + */ +static int +mypci_resume(device_t dev) +{ + + printf("Mypci resume!\n"); + return (0); +} + +static device_method_t mypci_methods[] = { + /* Device interface */ + DEVMETHOD(device_probe, mypci_probe), + DEVMETHOD(device_attach, mypci_attach), + DEVMETHOD(device_detach, mypci_detach), + DEVMETHOD(device_shutdown, mypci_shutdown), + DEVMETHOD(device_suspend, mypci_suspend), + DEVMETHOD(device_resume, mypci_resume), + + DEVMETHOD_END +}; + +static devclass_t mypci_devclass; + +DEFINE_CLASS_0(mypci, mypci_driver, mypci_methods, sizeof(struct mypci_softc)); +DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0); +.... + +=== [.filename]#Makefile# для примера драйвера + +[.programlisting] +.... +# Makefile for mypci driver + +KMOD= mypci +SRCS= mypci.c +SRCS+= device_if.h bus_if.h pci_if.h + +.include +.... + +Если вы поместите исходный файл выше и [.filename]#Makefile# в каталог, вы можете запустить `make` для компиляции примера драйвера. Дополнительно можно выполнить `make load` для загрузки драйвера в текущее ядро и `make unload` для выгрузки драйвера после его загрузки. + +=== Дополнительные ресурсы + +* http://www.pcisig.org/[Группа по стандартам PCI] +* PCI System Architecture, Fourth Edition by Tom Shanley, et al. + +[[pci-bus]] +== Ресурсы шины + +FreeBSD предоставляет объектно-ориентированный механизм для запроса ресурсов от родительской шины. Почти все устройства будут дочерними элементами какого-либо типа шины (PCI, ISA, USB, SCSI и т.д.), и этим устройствам необходимо получать ресурсы от своей родительской шины (такие как сегменты памяти, линии прерываний или каналы DMA). + +=== Регистры базовых адресов + +Для выполнения каких-либо полезных действий с устройством PCI необходимо получить _регистры базовых адресов_ (BAR) из конфигурационного пространства PCI. Специфичные для PCI детали получения BAR абстрагированы в функции `bus_alloc_resource()`. + +Например, типичный драйвер может содержать что-то подобное в функции `attach()`: + +[.programlisting] +.... + sc->bar0id = PCIR_BAR(0); + sc->bar0res = bus_alloc_resource(dev, SYS_RES_MEMORY, &sc->bar0id, + 0, ~0, 1, RF_ACTIVE); + if (sc->bar0res == NULL) { + printf("Memory allocation of PCI base register 0 failed!\n"); + error = ENXIO; + goto fail1; + } + + sc->bar1id = PCIR_BAR(1); + sc->bar1res = bus_alloc_resource(dev, SYS_RES_MEMORY, &sc->bar1id, + 0, ~0, 1, RF_ACTIVE); + if (sc->bar1res == NULL) { + printf("Memory allocation of PCI base register 1 failed!\n"); + error = ENXIO; + goto fail2; + } + sc->bar0_bt = rman_get_bustag(sc->bar0res); + sc->bar0_bh = rman_get_bushandle(sc->bar0res); + sc->bar1_bt = rman_get_bustag(sc->bar1res); + sc->bar1_bh = rman_get_bushandle(sc->bar1res); +.... + +Дескрипторы для каждого регистра базовых адресов хранятся в структуре `softc`, чтобы их можно было использовать для записи на устройство в дальнейшем. + +Эти дескрипторы затем могут быть использованы для чтения или записи из регистров устройства с помощью функций `bus_space_*`. Например, драйвер может содержать сокращённую функцию для чтения из специфичного для платы регистра, как показано ниже: + +[.programlisting] +.... +uint16_t +board_read(struct ni_softc *sc, uint16_t address) +{ + return bus_space_read_2(sc->bar1_bt, sc->bar1_bh, address); +} +.... + +Аналогично, можно записать в регистры с помощью: + +[.programlisting] +.... +void +board_write(struct ni_softc *sc, uint16_t address, uint16_t value) +{ + bus_space_write_2(sc->bar1_bt, sc->bar1_bh, address, value); +} +.... + +Эти функции существуют в 8-битных, 16-битных и 32-битных версиях, и вам следует использовать `bus_space_{read|write}_{1|2|4}` соответственно. + +[NOTE] +==== +В FreeBSD 7.0 и более поздних версиях вы можете использовать функции `bus_*` вместо `bus_space_*`. Функции `bus_*` принимают указатель на структуру resource * вместо тега шины и дескриптора. Таким образом, вы можете удалить тег шины и дескриптор шины из `softc` и переписать функцию `board_read()` как: + +[.programlisting] +.... +uint16_t +board_read(struct ni_softc *sc, uint16_t address) +{ + return (bus_read(sc->bar1res, address)); +} +.... + +==== + +=== Прерывания + +Прерывания выделяются объектно-ориентированным кодом шины аналогично ресурсам памяти. Сначала ресурс IRQ должен быть выделен из родительской шины, а затем должен быть настроен обработчик прерывания для работы с этим IRQ. + +Вот пример из функции `attach()` устройства, который скажет больше, чем слова. + +[.programlisting] +.... +/* Get the IRQ resource */ + + sc->irqid = 0x0; + sc->irqres = bus_alloc_resource(dev, SYS_RES_IRQ, &(sc->irqid), + 0, ~0, 1, RF_SHAREABLE | RF_ACTIVE); + if (sc->irqres == NULL) { + printf("IRQ allocation failed!\n"); + error = ENXIO; + goto fail3; + } + + /* Now we should set up the interrupt handler */ + + error = bus_setup_intr(dev, sc->irqres, INTR_TYPE_MISC, + my_handler, sc, &(sc->handler)); + if (error) { + printf("Couldn't set up irq\n"); + goto fail4; + } +.... + +Некоторые меры предосторожности должны быть приняты в процедуре отключения драйвера. Необходимо остановить поток прерываний устройства и удалить обработчик прерываний. Как только `bus_teardown_intr()` завершится, можно быть уверенным, что обработчик прерываний больше не будет вызываться и все потоки, которые могли выполнять этот обработчик, завершили работу. Поскольку эта функция может засыпать, нельзя удерживать какие-либо мьютексы при её вызове. + +=== DMA + +Этот раздел устарел и приведён только в исторических целях. Правильный способ решения этих проблем — использование функций `bus_space_dma*()`. Этот абзац можно удалить, когда раздел будет обновлён с учётом данного подхода. Однако на данный момент API находится в состоянии изменения, поэтому, когда он стабилизируется, будет полезно обновить этот раздел соответствующим образом. + +На ПК периферийные устройства, которые хотят использовать DMA с управлением шиной, должны работать с физическими адресами. Это проблема, поскольку FreeBSD использует виртуальную память и работает почти исключительно с виртуальными адресами. К счастью, существует функция `vtophys()`, которая поможет. + +[.programlisting] +.... +#include +#include + +#define vtophys(virtual_address) (...) +.... + +Однако решение немного отличается на alpha, и на самом деле нам нужна функция под названием `vtobus()`. + +[.programlisting] +.... +#if defined(__alpha__) +#define vtobus(va) alpha_XXX_dmamap((vm_offset_t)va) +#else +#define vtobus(va) vtophys(va) +#endif +.... + +=== Освобождение ресурсов + +Очень важно освободить все ресурсы, которые были выделены во время `attach()`. Необходимо внимательно следить за освобождением правильных ресурсов даже в случае ошибки, чтобы система оставалась работоспособной при завершении работы вашего драйвера. diff --git a/documentation/content/ru/books/arch-handbook/pci/_index.po b/documentation/content/ru/books/arch-handbook/pci/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/pci/_index.po @@ -0,0 +1,1071 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-03 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 "Устройства PCI" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:1 +#, no-wrap +msgid "Chapter 11. PCI Devices" +msgstr "Глава 11. Устройства PCI" + +#. 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 "" +"Эта глава расскажет о механизмах FreeBSD для написания драйвера устройства " +"на шине PCI." + +#. 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 "" +"Информация о том, как код шины PCI перебирает неприсоединённые устройства и " +"проверяет, сможет ли только что загруженный kld присоединиться к любому из " +"них." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:58 +#, no-wrap +msgid "Sample Driver Source ([.filename]#mypci.c#)" +msgstr "Пример исходного кода драйвера ([.filename]#mypci.c#)" + +#. 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 "" +"/*\n" +" * Simple KLD to play with the PCI functions.\n" +" *\n" +" * Murray Stokely\n" +" */\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:77 +#, no-wrap +msgid "" +"#include \t\t/* defines used in kernel.h */\n" +"#include \n" +"#include \n" +"#include \n" +"#include \t\t/* types used in module initialization */\n" +"#include \t\t/* cdevsw struct */\n" +"#include \t\t/* uio struct */\n" +"#include \n" +"#include \t\t/* structs, prototypes for pci bus stuff and DEVMETHOD macros! */\n" +msgstr "" +"#include \t\t/* defines used in kernel.h */\n" +"#include \n" +"#include \n" +"#include \n" +"#include \t\t/* types used in module initialization */\n" +"#include \t\t/* cdevsw struct */\n" +"#include \t\t/* uio struct */\n" +"#include \n" +"#include \t\t/* structs, prototypes for pci bus stuff and DEVMETHOD macros! */\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:81 +#, no-wrap +msgid "" +"#include \n" +"#include \n" +"#include \n" +msgstr "" +"#include \n" +"#include \n" +"#include \n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:84 +#, no-wrap +msgid "" +"#include \t/* For pci_get macros! */\n" +"#include \n" +msgstr "" +"#include \t/* For pci_get macros! */\n" +"#include \n" + +#. 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 "" +"/* The softc holds our per-instance data. */\n" +"struct mypci_softc {\n" +"\tdevice_t\tmy_dev;\n" +"\tstruct cdev\t*my_cdev;\n" +"};\n" + +#. 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 "" +"/* 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" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:98 +#, no-wrap +msgid "/* Character device entry points */\n" +msgstr "/* Character device entry points */\n" + +#. 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 "" +"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" + +#. 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 "" +"/*\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" + +#. 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 "" +"int\n" +"mypci_open(struct cdev *dev, int oflags, int devtype, struct thread *td)\n" +"{\n" +"\tstruct mypci_softc *sc;\n" + +#. 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 "" +"\t/* Look up our softc. */\n" +"\tsc = dev->si_drv1;\n" +"\tdevice_printf(sc->my_dev, \"Opened successfully.\\n\");\n" +"\treturn (0);\n" +"}\n" + +#. 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 "" +"int\n" +"mypci_close(struct cdev *dev, int fflag, int devtype, struct thread *td)\n" +"{\n" +"\tstruct mypci_softc *sc;\n" + +#. 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 "" +"\t/* Look up our softc. */\n" +"\tsc = dev->si_drv1;\n" +"\tdevice_printf(sc->my_dev, \"Closed.\\n\");\n" +"\treturn (0);\n" +"}\n" + +#. 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 "" +"int\n" +"mypci_read(struct cdev *dev, struct uio *uio, int ioflag)\n" +"{\n" +"\tstruct mypci_softc *sc;\n" + +#. 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 "" +"\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" + +#. 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 "" +"int\n" +"mypci_write(struct cdev *dev, struct uio *uio, int ioflag)\n" +"{\n" +"\tstruct mypci_softc *sc;\n" + +#. 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 "" +"\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" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:159 +#, no-wrap +msgid "/* PCI Support Functions */\n" +msgstr "/* PCI Support Functions */\n" + +#. 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 "" +"/*\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" + +#. 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 "" +"\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" + +#. 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 "" +"\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" + +#. 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 "/* Attach function is only called if the probe is successful. */\n" + +#. 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 "" +"static int\n" +"mypci_attach(device_t dev)\n" +"{\n" +"\tstruct mypci_softc *sc;\n" + +#. 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 "\tprintf(\"MyPCI Attach for : deviceID : 0x%x\\n\", pci_get_devid(dev));\n" + +#. 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 "" +"\t/* Look up our softc and initialize its fields. */\n" +"\tsc = device_get_softc(dev);\n" +"\tsc->my_dev = dev;\n" + +#. 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\".\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 "" +"\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\".\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" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:206 +#, no-wrap +msgid "/* Detach device. */\n" +msgstr "/* Detach device. */\n" + +#. 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 "" +"static int\n" +"mypci_detach(device_t dev)\n" +"{\n" +"\tstruct mypci_softc *sc;\n" + +#. 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 "" +"\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" + +#. 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 "/* Called during system shutdown after sync. */\n" + +#. 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 "" +"static int\n" +"mypci_shutdown(device_t dev)\n" +"{\n" + +#. 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 "" +"\tprintf(\"Mypci shutdown!\\n\");\n" +"\treturn (0);\n" +"}\n" + +#. 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 "" +"/*\n" +" * Device suspend routine.\n" +" */\n" +"static int\n" +"mypci_suspend(device_t dev)\n" +"{\n" + +#. 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 "" +"\tprintf(\"Mypci suspend!\\n\");\n" +"\treturn (0);\n" +"}\n" + +#. 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 "" +"/*\n" +" * Device resume routine.\n" +" */\n" +"static int\n" +"mypci_resume(device_t dev)\n" +"{\n" + +#. 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 "" +"\tprintf(\"Mypci resume!\\n\");\n" +"\treturn (0);\n" +"}\n" + +#. 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 "" +"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" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:262 +#, no-wrap +msgid "" +"\tDEVMETHOD_END\n" +"};\n" +msgstr "" +"\tDEVMETHOD_END\n" +"};\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:264 +#, no-wrap +msgid "static devclass_t mypci_devclass;\n" +msgstr "static devclass_t mypci_devclass;\n" + +#. 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 "" +"DEFINE_CLASS_0(mypci, mypci_driver, mypci_methods, sizeof(struct mypci_softc));\n" +"DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0);\n" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:269 +#, no-wrap +msgid "[.filename]#Makefile# for Sample Driver" +msgstr "[.filename]#Makefile# для примера драйвера" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:274 +#, no-wrap +msgid "# Makefile for mypci driver\n" +msgstr "# Makefile for mypci driver\n" + +#. 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 "" +"KMOD=\tmypci\n" +"SRCS=\tmypci.c\n" +"SRCS+=\tdevice_if.h bus_if.h pci_if.h\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:280 +#, no-wrap +msgid ".include \n" +msgstr ".include \n" + +#. 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 "" +"Если вы поместите исходный файл выше и [.filename]#Makefile# в каталог, вы " +"можете запустить `make` для компиляции примера драйвера. Дополнительно можно " +"выполнить `make load` для загрузки драйвера в текущее ядро и `make unload` " +"для выгрузки драйвера после его загрузки." + +#. 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 "http://www.pcisig.org/[Группа по стандартам PCI]" + +#. 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 "PCI System Architecture, Fourth Edition by Tom Shanley, et al." + +#. 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 "" +"FreeBSD предоставляет объектно-ориентированный механизм для запроса ресурсов " +"от родительской шины. Почти все устройства будут дочерними элементами какого-" +"либо типа шины (PCI, ISA, USB, SCSI и т.д.), и этим устройствам необходимо " +"получать ресурсы от своей родительской шины (такие как сегменты памяти, " +"линии прерываний или каналы DMA)." + +#. 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 "" +"Для выполнения каких-либо полезных действий с устройством PCI необходимо " +"получить _регистры базовых адресов_ (BAR) из конфигурационного пространства " +"PCI. Специфичные для PCI детали получения BAR абстрагированы в функции " +"`bus_alloc_resource()`." + +#. 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 "" +"Например, типичный драйвер может содержать что-то подобное в функции " +"`attach()`:" + +#. 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 "" +" 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" + +#. 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 "" +" 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" + +#. 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 "" +"Дескрипторы для каждого регистра базовых адресов хранятся в структуре " +"`softc`, чтобы их можно было использовать для записи на устройство в " +"дальнейшем." + +#. 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 "" +"Эти дескрипторы затем могут быть использованы для чтения или записи из " +"регистров устройства с помощью функций `bus_space_*`. Например, драйвер " +"может содержать сокращённую функцию для чтения из специфичного для платы " +"регистра, как показано ниже:" + +#. 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 "" +"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" + +#. 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 "" +"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" + +#. 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 "" +"Эти функции существуют в 8-битных, 16-битных и 32-битных версиях, и вам " +"следует использовать `bus_space_{read|write}_{1|2|4}` соответственно." + +#. 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 "" +"В FreeBSD 7.0 и более поздних версиях вы можете использовать функции `bus_*` " +"вместо `bus_space_*`. Функции `bus_*` принимают указатель на структуру " +"resource * вместо тега шины и дескриптора. Таким образом, вы можете удалить " +"тег шины и дескриптор шины из `softc` и переписать функцию `board_read()` " +"как:" + +#. 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 "" +"uint16_t\n" +"board_read(struct ni_softc *sc, uint16_t address)\n" +"{\n" +"\treturn (bus_read(sc->bar1res, address));\n" +"}\n" + +#. 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 "" +"Прерывания выделяются объектно-ориентированным кодом шины аналогично " +"ресурсам памяти. Сначала ресурс IRQ должен быть выделен из родительской " +"шины, а затем должен быть настроен обработчик прерывания для работы с этим " +"IRQ." + +#. 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 "" +"Вот пример из функции `attach()` устройства, который скажет больше, чем " +"слова." + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:375 +#, no-wrap +msgid "/* Get the IRQ resource */\n" +msgstr "/* Get the IRQ resource */\n" + +#. 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 "" +" 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" + +#. 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 " /* Now we should set up the interrupt handler */\n" + +#. 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 "" +" 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" + +#. 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 "" +"Некоторые меры предосторожности должны быть приняты в процедуре отключения " +"драйвера. Необходимо остановить поток прерываний устройства и удалить " +"обработчик прерываний. Как только `bus_teardown_intr()` завершится, можно " +"быть уверенным, что обработчик прерываний больше не будет вызываться и все " +"потоки, которые могли выполнять этот обработчик, завершили работу. Поскольку " +"эта функция может засыпать, нельзя удерживать какие-либо мьютексы при её " +"вызове." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:397 +#, no-wrap +msgid "DMA" +msgstr "DMA" + +#. 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 "" +"Этот раздел устарел и приведён только в исторических целях. Правильный " +"способ решения этих проблем — использование функций `bus_space_dma*()`. Этот " +"абзац можно удалить, когда раздел будет обновлён с учётом данного подхода. " +"Однако на данный момент API находится в состоянии изменения, поэтому, когда " +"он стабилизируется, будет полезно обновить этот раздел соответствующим " +"образом." + +#. 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 "" +"На ПК периферийные устройства, которые хотят использовать DMA с управлением " +"шиной, должны работать с физическими адресами. Это проблема, поскольку " +"FreeBSD использует виртуальную память и работает почти исключительно с " +"виртуальными адресами. К счастью, существует функция `vtophys()`, которая " +"поможет." + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:407 +#, no-wrap +msgid "" +"#include \n" +"#include \n" +msgstr "" +"#include \n" +"#include \n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/pci/_index.adoc:409 +#, no-wrap +msgid "#define vtophys(virtual_address) (...)\n" +msgstr "#define vtophys(virtual_address) (...)\n" + +#. 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 "" +"Однако решение немного отличается на alpha, и на самом деле нам нужна " +"функция под названием `vtobus()`." + +#. 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 "" +"#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" + +#. 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 "" +"Очень важно освободить все ресурсы, которые были выделены во время " +"`attach()`. Необходимо внимательно следить за освобождением правильных " +"ресурсов даже в случае ошибки, чтобы система оставалась работоспособной при " +"завершении работы вашего драйвера." diff --git a/documentation/content/ru/books/arch-handbook/scsi/_index.adoc b/documentation/content/ru/books/arch-handbook/scsi/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/scsi/_index.adoc @@ -0,0 +1,1367 @@ +--- +description: 'Контроллеры SCSI с общим методом доступа (CAM)' +next: books/arch-handbook/usb +params: + path: /books/arch-handbook/scsi/ +prev: books/arch-handbook/pci +showBookMenu: true +tags: ["SCSI", "Controller", "Architecture"] +title: 'Глава 12. Контроллеры SCSI с общим методом доступа (CAM)' +weight: 14 +--- + +[[scsi]] += Контроллеры SCSI с общим методом доступа (CAM) +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 12 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[scsi-synopsis]] +== Обзор + +Этот документ предполагает, что читатель имеет общее представление о драйверах устройств в FreeBSD и о протоколе SCSI. Большая часть информации в этом документе была извлечена из драйверов: + +* ncr ([.filename]#/sys/pci/ncr.c#) от Wolfgang Stanglmeier и Stefan Esser +* sym ([.filename]#/sys/dev/sym/sym_hipd.c#) от Gerard Roudier +* aic7xxx ([.filename]#/sys/dev/aic7xxx/aic7xxx.c#) от Justin T. Gibbs + +и из самого кода CAM (автор Justin T. Gibbs, см. [.filename]#/sys/cam/*#). Когда какое-то решение выглядело наиболее логичным и было практически дословно взято из кода Justin T. Gibbs, я отмечал его как "рекомендуемое". + +Документ иллюстрирован примерами на псевдокоде. Хотя иногда примеры содержат много деталей и выглядят как настоящий код, это всё ещё псевдокод. Он был написан, чтобы продемонстрировать концепции в понятной форме. Для реального драйвера могут быть более модульные и эффективные подходы. Также он абстрагируется от деталей оборудования, а также от вопросов, которые могли бы затмить демонстрируемые концепции или которые предполагается описать в других главах руководства разработчика. Такие детали обычно показаны в виде вызовов функций с описательными именами, комментариев или псевдооператоров. К счастью, полные примеры из реальной жизни со всеми деталями можно найти в реальных драйверах. + +[[scsi-general]] +== Общая Архитектура + +CAM означает Common Access Method (Общий Метод Доступа). Это универсальный способ адресации шин ввода-вывода в стиле SCSI. Это позволяет отделить общие драйверы устройств от драйверов, управляющих шиной ввода-вывода: например, драйвер диска получает возможность управлять дисками как на SCSI, IDE, так и на любой другой шине, так что часть драйвера диска не нужно переписывать (или копировать и изменять) для каждой новой шины ввода-вывода. Таким образом, двумя наиболее важными активными сущностями являются: + +* _Модули периферийных устройств_ - драйвер для периферийных устройств (диски, ленты, CD-ROM и т.д.) +* _Модули интерфейса SCSI_ (SIM) - драйверы адаптеров шины для подключения к шине ввода-вывода, такой как SCSI или IDE. + +Периферийный драйвер получает запросы от ОС, преобразует их в последовательность команд SCSI и передает эти команды SCSI модулю интерфейса SCSI. Модуль интерфейса SCSI отвечает за передачу этих команд реальному оборудованию (или, если оборудование не поддерживает SCSI, а использует, например, IDE, также преобразует команды SCSI в собственные команды оборудования). + +Так как мы заинтересованы в написании драйвера адаптера SCSI, с этого момента мы будем рассматривать всё с точки зрения модуля SCSI-интерфейса (SIM). + +== Глобальные переменные и Шаблонный код + +Типичный драйвер SIM должен включать следующие заголовочные файлы, связанные с CAM: + +[.programlisting] +.... +#include +#include +#include +#include +#include +#include +.... + +== Конфигурация устройства: xxx_attach + +Первое, что должен сделать каждый драйвер SIM, — это зарегистрироваться в подсистеме CAM. Это выполняется в функции `xxx_attach()` драйвера (здесь и далее xxx_ используется для обозначения уникального префикса имени драйвера). Сама функция `xxx_attach()` вызывается кодом автонастройки системной шины, который мы здесь не описываем. + +Это достигается в несколько этапов: сначала необходимо выделить очередь запросов, связанных с этой SIM: + +[.programlisting] +.... + struct cam_devq *devq; + + if ((devq = cam_simq_alloc(SIZE)) == NULL) { + error; /* some code to handle the error */ + } +.... + +Вот `SIZE` — это размер выделяемой очереди, максимальное количество запросов, которые она может содержать. Это количество запросов, которые драйвер SIM может обрабатывать параллельно на одной SCSI-карте. Обычно его можно вычислить как: + +[.programlisting] +.... +SIZE = NUMBER_OF_SUPPORTED_TARGETS * MAX_SIMULTANEOUS_COMMANDS_PER_TARGET +.... + +Далее мы создаем описание нашего SIM: + +[.programlisting] +.... + struct cam_sim *sim; + + if ((sim = cam_sim_alloc(action_func, poll_func, driver_name, + softc, unit, mtx, max_dev_transactions, + max_tagged_dev_transactions, devq)) == NULL) { + cam_simq_free(devq); + error; /* some code to handle the error */ + } +.... + +Обратите внимание, что если мы не сможем создать дескриптор SIM, мы также освобождаем `devq`, потому что больше ничего не можем с ним сделать и хотим сэкономить память. + +Если SCSI-карта имеет несколько шин SCSI, то каждой шине требуется собственная структура `cam_sim`. + +Интересный вопрос: что делать, если SCSI-карта имеет более одной SCSI-шины, нужна ли одна структура `devq` на карту или на SCSI-шину? Ответ, приведённый в комментариях к коду CAM, таков: как угодно, на усмотрение автора драйвера. + +Аргументы: + +* `action_func` - указатель на функцию `xxx_action` драйвера. + +[.programlisting] +.... +static void xxx_action(struct cam_sim *, union ccb *); +.... +* `poll_func` - указатель на функцию `xxx_poll()` драйвера ++ +[.programlisting] +.... +static void xxx_poll(struct cam_sim *); +.... +* `driver_name` — имя фактического драйвера, например `ncr` или `wds`. +* `softc` — указатель на внутренний дескриптор драйвера для данной SCSI-карты. Этот указатель будет использоваться драйвером в дальнейшем для получения приватных данных. +* unit - номер управляющего устройства, например, для контроллера "mps0" это число будет 0 +* mtx - Блокировка, связанная с данной SIM. Для SIM, которые не поддерживают блокировку, передается Giant. Для SIM, которые поддерживают, передается блокировка, используемая для защиты структур данных этой SIM. Эта блокировка будет удерживаться при вызовах xxx_action и xxx_poll. +* max_dev_transactions - максимальное количество одновременных транзакций на целевом SCSI-устройстве в режиме без тегов. Это значение почти всегда равно 1, за исключением возможных исключений только для не-SCSI карт. Также драйверы, которые надеются получить преимущество, подготавливая одну транзакцию во время выполнения другой, могут установить его в 2, но это не кажется оправданным из-за сложности. +* max_tagged_dev_transactions - то же самое, но в режиме с тегами. Теги — это способ в SCSI инициировать несколько транзакций на устройстве: каждая транзакция получает уникальный тег и отправляется на устройство. Когда устройство завершает транзакцию, оно возвращает результат вместе с тегом, чтобы SCSI-адаптер (и драйвер) могли определить, какая транзакция была завершена. Этот аргумент также известен как максимальная глубина тега. Он зависит от возможностей SCSI-адаптера. + +Наконец, мы регистрируем шины SCSI, связанные с нашим SCSI-адаптером: + +[.programlisting] +.... + if (xpt_bus_register(sim, softc, bus_number) != CAM_SUCCESS) { + cam_sim_free(sim, /*free_devq*/ TRUE); + error; /* some code to handle the error */ + } +.... + +Если существует одна структура `devq` на каждую шину SCSI (т.е. мы рассматриваем карту с несколькими шинами как несколько карт с одной шиной каждая), то номер шины всегда будет 0, в противном случае каждая шина на SCSI-карте должна получить уникальный номер. Каждой шине требуется своя отдельная структура `cam_sim`. + +После этого наш контроллер полностью подключён к системе CAM. Значение `devq` теперь можно отбросить: sim будет передаваться в качестве аргумента во всех последующих вызовах из CAM, а devq можно получить из него. + +CAM предоставляет инфраструктуру для подобных асинхронных событий. Некоторые события возникают на нижних уровнях (драйверы SIM), некоторые — в драйверах периферийных устройств, а некоторые — в самой подсистеме CAM. Любой драйвер может зарегистрировать обработчики для определённых типов асинхронных событий, чтобы получать уведомления при их возникновении. + +Типичным примером такого события является сброс устройства. Каждая транзакция и событие идентифицируют устройства, к которым они применяются, с помощью "пути". Специфичные для целевого устройства события обычно происходят во время транзакции с этим устройством. Таким образом, путь из этой транзакции может быть повторно использован для сообщения о данном событии (это безопасно, потому что путь события копируется в процедуре сообщения о событии, но не освобождается и не передаётся дальше). Также безопасно динамически выделять пути в любое время, включая процедуры обработки прерываний, хотя это влечёт определённые накладные расходы, и возможная проблема такого подхода заключается в том, что в этот момент может не быть свободной памяти. Для события сброса шины нам необходимо определить путь-шаблон, включающий все устройства на шине. Поэтому мы можем заранее создать путь для будущих событий сброса шины и избежать проблем с возможной нехваткой памяти в будущем: + +[.programlisting] +.... + struct cam_path *path; + + if (xpt_create_path(&path, /*periph*/NULL, + cam_sim_path(sim), CAM_TARGET_WILDCARD, + CAM_LUN_WILDCARD) != CAM_REQ_CMP) { + xpt_bus_deregister(cam_sim_path(sim)); + cam_sim_free(sim, /*free_devq*/TRUE); + error; /* some code to handle the error */ + } + + softc->wpath = path; + softc->sim = sim; +.... + +Как вы можете видеть, путь включает: + +* Идентификатор драйвера периферийного устройства (NULL здесь, так как у нас его нет) +* Идентификатор драйвера SIM (`cam_sim_path(sim)`) +* Номер целевого устройства SCSI (CAM_TARGET_WILDCARD означает "все устройства") +* Номер SCSI LUN подустройства (CAM_LUN_WILDCARD означает "все LUN") + +Если драйвер не может выделить этот путь, он не сможет нормально работать, поэтому в таком случае мы демонтируем эту шину SCSI. + +И мы сохраняем указатель пути в структуре `softc` для дальнейшего использования. После этого сохраняем значение sim (или можем также отбросить его при выходе из `xxx_probe()`, если захотим). + +Вот и всё для минималистичной инициализации. Чтобы сделать всё правильно, остался ещё один вопрос. + +Для драйвера SIM есть одно особенно важное событие: когда целевое устройство считается потерянным. В этом случае может быть хорошей идеей сбросить SCSI-переговоры с этим устройством. Поэтому мы регистрируем обратный вызов для этого события в CAM. Запрос передаётся в CAM путём запроса действия CAM в блоке управления CAM для этого типа запроса: + +[.programlisting] +.... + struct ccb_setasync csa; + + xpt_setup_ccb(&csa.ccb_h, path, /*priority*/5); + csa.ccb_h.func_code = XPT_SASYNC_CB; + csa.event_enable = AC_LOST_DEVICE; + csa.callback = xxx_async; + csa.callback_arg = sim; + xpt_action((union ccb *)&csa); +.... + +== Обработка сообщений CAM: xxx_action + +[.programlisting] +.... +static void xxx_action(struct cam_sim *sim, union ccb *ccb); +.... + +Выполнить некоторое действие по запросу подсистемы CAM. Sim описывает SIM для запроса, CCB — это сам запрос. CCB расшифровывается как "CAM Control Block" (блок управления CAM). Это объединение множества конкретных экземпляров, каждый из которых описывает аргументы для определённого типа транзакций. Все эти экземпляры имеют общий заголовок CCB, в котором хранится общая часть аргументов. + +CAM поддерживает SCSI-контроллеры, работающие как в режиме инициатора («обычном»), так и в режиме цели (эмулирующем SCSI-устройство). Здесь мы рассматриваем только часть, относящуюся к режиму инициатора. + +Существует несколько функций и макросов (другими словами, методов), определённых для доступа к публичным данным в структуре sim: + +* `cam_sim_path(sim)` - идентификатор пути (см. выше) +* `cam_sim_name(sim)` — имя sim +* `cam_sim_softc(sim)` - указатель на структуру softc (приватные данные драйвера) +* `cam_sim_unit(sim)` - номер устройства +* `cam_sim_bus(sim)` - идентификатор шины + +Для идентификации устройства `xxx_action()` может получить номер устройства и указатель на его структуру softc, используя следующие функции. + +Тип запроса хранится в `ccb->ccb_h.func_code`. Поэтому, как правило, `xxx_action()` состоит из большого оператора switch: + +[.programlisting] +.... + struct xxx_softc *softc = (struct xxx_softc *) cam_sim_softc(sim); + struct ccb_hdr *ccb_h = &ccb->ccb_h; + int unit = cam_sim_unit(sim); + int bus = cam_sim_bus(sim); + + switch (ccb_h->func_code) { + case ...: + ... + default: + ccb_h->status = CAM_REQ_INVALID; + xpt_done(ccb); + break; + } +.... + +Как видно из случая по умолчанию (если получена неизвестная команда) код возврата команды устанавливается в `ccb->ccb_h.status`, а завершённый CCB возвращается обратно в CAM вызовом `xpt_done(ccb)`. + +`xpt_done()` не обязательно вызывать из `xxx_action()`: Например, запрос ввода-вывода может быть поставлен в очередь внутри драйвера SIM и/или его SCSI-контроллера. Затем, когда устройство пошлет прерывание, сигнализирующее о завершении обработки этого запроса, `xpt_done()` может быть вызван из процедуры обработки прерывания. + +На самом деле, статус CCB не только присваивается в качестве кода возврата, но и CCB всегда имеет какой-то статус. Перед тем как CCB передается в процедуру `xxx_action()`, он получает статус CCB_REQ_INPROG, означающий, что запрос находится в процессе выполнения. В [.filename]#/sys/cam/cam.h# определено удивительно большое количество значений статуса, которые должны детально отражать состояние запроса. Что еще интереснее, статус фактически представляет собой "побитовое ИЛИ" перечисленного значения статуса (младшие 6 бит) и возможных дополнительных флагов (старшие биты). Перечисленные значения будут подробно рассмотрены далее. Их краткое описание можно найти в разделе "Сводка ошибок". Возможные флаги статуса: + +* _CAM_DEV_QFRZN_ - если драйвер SIM получает серьёзную ошибку (например, устройство не отвечает на выборку или нарушает протокол SCSI) при обработке CCB, он должен заморозить очередь запросов, вызвав `xpt_freeze_simq()`, вернуть другие поставленные в очередь, но ещё не обработанные CCB для этого устройства обратно в очередь CAM, затем установить этот флаг для проблемного CCB и вызвать `xpt_done()`. Этот флаг заставляет подсистему CAM разморозить очередь после обработки ошибки. +* _CAM_AUTOSNS_VALID_ - если устройство вернуло состояние ошибки и флаг CAM_DIS_AUTOSENSE не установлен в CCB, драйвер SIM должен автоматически выполнить команду REQUEST SENSE, чтобы извлечь данные sense (расширенную информацию об ошибке) из устройства. Если попытка была успешной, данные sense должны быть сохранены в CCB, а этот флаг установлен. +* _CAM_RELEASE_SIMQ_ - аналогично CAM_DEV_QFRZN, но используется в случае возникновения проблем (или нехватки ресурсов) с самим SCSI-контроллером. В этом случае все последующие запросы к контроллеру должны быть остановлены с помощью `xpt_freeze_simq()`. Очередь контроллера будет возобновлена после того, как драйвер SIM устранит нехватку и уведомит CAM, вернув некоторый CCB с установленным этим флагом. +* _CAM_SIM_QUEUED_ - этот флаг должен быть установлен, когда SIM помещает CCB в свою очередь запросов (и снят, когда этот CCB извлекается из очереди перед возвратом в CAM). В настоящее время этот флаг нигде не используется в коде CAM, поэтому его назначение чисто диагностическое. +* _CAM_QOS_VALID_ - Данные QOS теперь действительны. + +Функция `xxx_action()` не может находиться в состоянии ожидания, поэтому вся синхронизация доступа к ресурсам должна выполняться с использованием SIM или заморозки очереди устройств. Помимо упомянутых флагов, подсистема CAM предоставляет функции `xpt_release_simq()` и `xpt_release_devq()` для разморозки очередей напрямую, без передачи CCB в CAM. + +Заголовок CCB содержит следующие поля: + +* _path_ - идентификатор пути для запроса +* _target_id_ - идентификатор целевого устройства для запроса +* _target_lun_ - идентификатор LUN целевого устройства +* _timeout_ - интервал таймаута для этой команды, в миллисекундах +* _timeout_ch_ - удобное место для драйвера SIM, чтобы хранить обработчик таймаута (сама подсистема CAM не делает никаких предположений о нём) +* _flags_ - различные биты информации о запросе spriv_ptr0, spriv_ptr1 — поля, зарезервированные для приватного использования драйвером SIM (например, для связи с очередями SIM или приватными блоками управления SIM); фактически они существуют как объединения: spriv_ptr0 и spriv_ptr1 имеют тип (void *), spriv_field0 и spriv_field1 имеют тип unsigned long, sim_priv.entries[0].bytes и sim_priv.entries[1].bytes - это байтовые массивы размера, согласованного с другими вариантами объединения, а sim_priv.bytes - это один массив, вдвое большего размера. + +Рекомендуемый способ использования приватных полей SIM в CCB — это определить для них осмысленные имена и использовать эти осмысленные имена в драйвере, например: + +[.programlisting] +.... +#define ccb_some_meaningful_name sim_priv.entries[0].bytes +#define ccb_hcb spriv_ptr1 /* for hardware control block */ +.... + +Наиболее распространенные запросы в режиме инициатора: + +=== _XPT_SCSI_IO_ - выполнить транзакцию ввода-вывода + +Экземпляр "struct ccb_scsiio csio" объединения ccb используется для передачи аргументов. Они включают: + +* _cdb_io_ - указатель на буфер команды SCSI или сам буфер +* _cdb_len_ - длина команды SCSI +* _data_ptr_ - указатель на буфер данных (усложняется, если используется scatter/gather) +* _dxfer_len_ - длина передаваемых данных +* _sglist_cnt_ - счетчик сегментов scatter/gather +* _scsi_status_ - место для возврата статуса SCSI +* _sense_data_ - буфер для информации SCSI sense, если команда возвращает ошибку (драйвер SIM должен автоматически выполнить команду REQUEST SENSE в этом случае, если флаг CCB CAM_DIS_AUTOSENSE не установлен) +* _sense_len_ - длина этого буфера (если она окажется больше размера sense_data, драйвер SIM должен без уведомления принять меньшее значение) +* _resid_, _sense_resid_ — если передача данных или SCSI sense вернула ошибку, это счётчики остаточных (не переданных) данных. Они не кажутся особенно значимыми, поэтому в случаях, когда их сложно вычислить (например, подсчёт байтов в FIFO-буфере SCSI-контроллера), подойдёт и приблизительное значение. Для успешно завершённой передачи они должны быть установлены в ноль. +* _tag_action_ - тип используемого тега: +** `CAM_TAG_ACTION_NONE` - не использовать теги для данной транзакции +** MSG_SIMPLE_Q_TAG, MSG_HEAD_OF_Q_TAG, MSG_ORDERED_Q_TAG — значение, соответствующее указанному теговому сообщению (см. /sys/cam/scsi/scsi_message.h); указывает только тип тега, значение тега должно быть назначено самим драйвером SIM + +Общая логика обработки этого запроса следующая: + +Первое, что нужно сделать, это проверить возможные состояния гонки, чтобы убедиться, что команда не была прервана, пока находилась в очереди: + +[.programlisting] +.... + struct ccb_scsiio *csio = &ccb->csio; + + if ((ccb_h->status & CAM_STATUS_MASK) != CAM_REQ_INPROG) { + xpt_done(ccb); + return; + } +.... + +Также мы проверяем, что устройство вообще поддерживается нашим контроллером: + +[.programlisting] +.... + if (ccb_h->target_id > OUR_MAX_SUPPORTED_TARGET_ID + || cch_h->target_id == OUR_SCSI_CONTROLLERS_OWN_ID) { + ccb_h->status = CAM_TID_INVALID; + xpt_done(ccb); + return; + } + if (ccb_h->target_lun > OUR_MAX_SUPPORTED_LUN) { + ccb_h->status = CAM_LUN_INVALID; + xpt_done(ccb); + return; + } +.... + +Затем выделяем все необходимые структуры данных (такие как зависящий от карты блок управления оборудованием), которые нам нужны для обработки этого запроса. Если мы не можем этого сделать, то замораживаем очередь SIM и запоминаем, что у нас есть отложенная операция, возвращаем CCB обратно и просим CAM поставить его в очередь снова. Позже, когда ресурсы станут доступны, очередь SIM должна быть разморожена путём возврата CCB с установленным битом `CAM_SIMQ_RELEASE` в его статусе. В противном случае, если всё прошло успешно, связываем CCB с блоком управления оборудованием (HCB) и помечаем его как поставленный в очередь. + +[.programlisting] +.... + struct xxx_hcb *hcb = allocate_hcb(softc, unit, bus); + + if (hcb == NULL) { + softc->flags |= RESOURCE_SHORTAGE; + xpt_freeze_simq(sim, /*count*/1); + ccb_h->status = CAM_REQUEUE_REQ; + xpt_done(ccb); + return; + } + + hcb->ccb = ccb; ccb_h->ccb_hcb = (void *)hcb; + ccb_h->status |= CAM_SIM_QUEUED; +.... + +Извлечь целевые данные из CCB в аппаратный блок управления. Проверить, запрошено ли назначение тега, и если да, то сгенерировать уникальный тег и построить сообщения тега SCSI. Драйвер SIM также отвечает за согласование с устройствами для установки максимальной взаимно поддерживаемой ширины шины, синхронной скорости и смещения. + +[.programlisting] +.... + hcb->target = ccb_h->target_id; hcb->lun = ccb_h->target_lun; + generate_identify_message(hcb); + if (ccb_h->tag_action != CAM_TAG_ACTION_NONE) + generate_unique_tag_message(hcb, ccb_h->tag_action); + if (!target_negotiated(hcb)) + generate_negotiation_messages(hcb); +.... + +Затем настройте команду SCSI. Хранилище команды может быть указано в CCB различными способами, определяемыми флагами CCB. Буфер команды может содержаться в CCB или указываться на него; в последнем случае указатель может быть физическим или виртуальным. Поскольку оборудованию обычно требуется физический адрес, мы всегда преобразуем адрес в физический, как правило, используя API busdma. + +В случае, если запрашивается физический адрес, допустимо вернуть CCB со статусом `CAM_REQ_INVALID`, текущие драйверы так и делают. При необходимости физический адрес также может быть преобразован или отображен обратно в виртуальный, но с большими трудностями, поэтому мы этого не делаем. + +[.programlisting] +.... + if (ccb_h->flags & CAM_CDB_POINTER) { + /* CDB is a pointer */ + if (!(ccb_h->flags & CAM_CDB_PHYS)) { + /* CDB pointer is virtual */ + hcb->cmd = vtobus(csio->cdb_io.cdb_ptr); + } else { + /* CDB pointer is physical */ + hcb->cmd = csio->cdb_io.cdb_ptr ; + } + } else { + /* CDB is in the ccb (buffer) */ + hcb->cmd = vtobus(csio->cdb_io.cdb_bytes); + } + hcb->cmdlen = csio->cdb_len; +.... + +Теперь настало время настроить данные. Опять же, хранилище данных может быть указано в CCB различными интересными способами, определяемыми флагами CCB. Сначала мы получаем направление передачи данных. Самый простой случай — если нет данных для передачи: + +[.programlisting] +.... + int dir = (ccb_h->flags & CAM_DIR_MASK); + + if (dir == CAM_DIR_NONE) + goto end_data; +.... + +Затем мы проверяем, находятся ли данные в одном фрагменте или в списке scatter-gather, а также являются ли адреса физическими или виртуальными. SCSI-контроллер может обрабатывать только ограниченное количество фрагментов ограниченной длины. Если запрос превышает это ограничение, мы возвращаем ошибку. Мы используем специальную функцию для возврата CCB, чтобы в одном месте обрабатывать нехватку ресурсов HCB. Функции для добавления фрагментов зависят от драйвера, и здесь мы оставляем их без детальной реализации. Подробности о проблемах трансляции адресов см. в описании обработки SCSI-команд (CDB). Если какая-то вариация слишком сложна или невозможна для реализации с конкретной картой, допустимо вернуть статус `CAM_REQ_INVALID`. На самом деле, похоже, что возможность scatter-gather нигде в коде CAM сейчас не используется. Но как минимум случай с единичным неразделённым виртуальным буфером должен быть реализован, так как он активно используется CAM. + +[.programlisting] +.... + int rv; + + initialize_hcb_for_data(hcb); + + if ((!(ccb_h->flags & CAM_SCATTER_VALID)) { + /* single buffer */ + if (!(ccb_h->flags & CAM_DATA_PHYS)) { + rv = add_virtual_chunk(hcb, csio->data_ptr, csio->dxfer_len, dir); + } + } else { + rv = add_physical_chunk(hcb, csio->data_ptr, csio->dxfer_len, dir); + } + } else { + int i; + struct bus_dma_segment *segs; + segs = (struct bus_dma_segment *)csio->data_ptr; + + if ((ccb_h->flags & CAM_SG_LIST_PHYS) != 0) { + /* The SG list pointer is physical */ + rv = setup_hcb_for_physical_sg_list(hcb, segs, csio->sglist_cnt); + } else if (!(ccb_h->flags & CAM_DATA_PHYS)) { + /* SG buffer pointers are virtual */ + for (i = 0; i < csio->sglist_cnt; i++) { + rv = add_virtual_chunk(hcb, segs[i].ds_addr, + segs[i].ds_len, dir); + if (rv != CAM_REQ_CMP) + break; + } + } else { + /* SG buffer pointers are physical */ + for (i = 0; i < csio->sglist_cnt; i++) { + rv = add_physical_chunk(hcb, segs[i].ds_addr, + segs[i].ds_len, dir); + if (rv != CAM_REQ_CMP) + break; + } + } + } + if (rv != CAM_REQ_CMP) { + /* we expect that add_*_chunk() functions return CAM_REQ_CMP + * if they added a chunk successfully, CAM_REQ_TOO_BIG if + * the request is too big (too many bytes or too many chunks), + * CAM_REQ_INVALID in case of other troubles + */ + free_hcb_and_ccb_done(hcb, ccb, rv); + return; + } + end_data: +.... + +Если отключение запрещено для этого CCB, мы передаем эту информацию в hcb: + +[.programlisting] +.... + if (ccb_h->flags & CAM_DIS_DISCONNECT) + hcb_disable_disconnect(hcb); +.... + +Если контроллер способен самостоятельно выполнять команду REQUEST SENSE, то ему также следует передать значение флага CAM_DIS_AUTOSENSE, чтобы предотвратить автоматическое выполнение REQUEST SENSE, если подсистема CAM этого не требует. + +Осталось только установить таймаут, передать наш hcb оборудованию и вернуться, остальное будет сделано обработчиком прерывания (или обработчиком таймаута). + +[.programlisting] +.... + ccb_h->timeout_ch = timeout(xxx_timeout, (caddr_t) hcb, + (ccb_h->timeout * hz) / 1000); /* convert milliseconds to ticks */ + put_hcb_into_hardware_queue(hcb); + return; +.... + +И вот возможная реализация функции, возвращающей CCB: + +[.programlisting] +.... + static void + free_hcb_and_ccb_done(struct xxx_hcb *hcb, union ccb *ccb, u_int32_t status) + { + struct xxx_softc *softc = hcb->softc; + + ccb->ccb_h.ccb_hcb = 0; + if (hcb != NULL) { + untimeout(xxx_timeout, (caddr_t) hcb, ccb->ccb_h.timeout_ch); + /* we're about to free a hcb, so the shortage has ended */ + if (softc->flags & RESOURCE_SHORTAGE) { + softc->flags &= ~RESOURCE_SHORTAGE; + status |= CAM_RELEASE_SIMQ; + } + free_hcb(hcb); /* also removes hcb from any internal lists */ + } + ccb->ccb_h.status = status | + (ccb->ccb_h.status & ~(CAM_STATUS_MASK|CAM_SIM_QUEUED)); + xpt_done(ccb); + } +.... + +=== _XPT_RESET_DEV_ - отправить устройству сообщение SCSI "BUS DEVICE RESET" + +В CCB не передаются данные, кроме заголовка, и наиболее интересным аргументом в нём является target_id. В зависимости от аппаратного обеспечения контроллера может быть создан аппаратный блок управления (как для запроса XPT_SCSI_IO, см. описание запроса XPT_SCSI_IO) и отправлен контроллеру, или SCSI-контроллер может быть немедленно запрограммирован на отправку этого сообщения RESET устройству, или этот запрос может просто не поддерживаться (и возвращать статус `CAM_REQ_INVALID`). Также при завершении запроса все отключенные транзакции для этого целевого устройства должны быть прерваны (вероятно, в процедуре прерывания). + +Кроме того, все текущие переговоры для цели теряются при сбросе, поэтому они также могут быть очищены. Или их очистка может быть отложена, так как в любом случае цель запросит повторные переговоры при следующей транзакции. + +=== _XPT_RESET_BUS_ - отправить сигнал RESET на шину SCSI + +В CCB не передаются аргументы, единственный интересный аргумент — это шина SCSI, указанная структурой sim. + +Минималистичная реализация могла бы пропустить SCSI-переговоры для всех устройств на шине и вернуть статус CAM_REQ_CMP. + +Правильная реализация дополнительно должна фактически сбросить шину SCSI (возможно, также сбросить контроллер SCSI) и пометить все обрабатываемые CCB, как находящиеся в аппаратной очереди, так и отключенные, как завершенные со статусом CAM_SCSI_BUS_RESET. Например: +[.programlisting] +.... + int targ, lun; + struct xxx_hcb *h, *hh; + struct ccb_trans_settings neg; + struct cam_path *path; + + /* The SCSI bus reset may take a long time, in this case its completion + * should be checked by interrupt or timeout. But for simplicity + * we assume here that it is really fast. + */ + reset_scsi_bus(softc); + + /* drop all enqueued CCBs */ + for (h = softc->first_queued_hcb; h != NULL; h = hh) { + hh = h->next; + free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET); + } + + /* the clean values of negotiations to report */ + neg.bus_width = 8; + neg.sync_period = neg.sync_offset = 0; + neg.valid = (CCB_TRANS_BUS_WIDTH_VALID + | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID); + + /* drop all disconnected CCBs and clean negotiations */ + for (targ=0; targ <= OUR_MAX_SUPPORTED_TARGET; targ++) { + clean_negotiations(softc, targ); + + /* report the event if possible */ + if (xpt_create_path(&path, /*periph*/NULL, + cam_sim_path(sim), targ, + CAM_LUN_WILDCARD) == CAM_REQ_CMP) { + xpt_async(AC_TRANSFER_NEG, path, &neg); + xpt_free_path(path); + } + + for (lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++) + for (h = softc->first_discon_hcb[targ][lun]; h != NULL; h = hh) { + hh=h->next; + free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET); + } + } + + ccb->ccb_h.status = CAM_REQ_CMP; + xpt_done(ccb); + + /* report the event */ + xpt_async(AC_BUS_RESET, softc->wpath, NULL); + return; +.... + +Реализация сброса шины SCSI в виде функции может быть хорошей идеей, так как она может быть повторно использована функцией таймаута в качестве последнего средства, если что-то пойдёт не так. + +=== _XPT_ABORT_ - прервать указанный CCB + +Аргументы передаются в экземпляре "struct ccb_abort cab" объединения ccb. Единственное поле аргумента в нём: + +* _abort_ccb_ — указатель на CCB, который необходимо прервать + +Если прерывание не поддерживается, просто верните статус CAM_UA_ABORT. Это также простой способ минимальной реализации этого вызова — в любом случае возвращать CAM_UA_ABORT. + +Трудный путь — честно реализовать этот запрос. Сначала проверьте, что прерывание применяется к SCSI-транзакции: + +[.programlisting] +.... + struct ccb *abort_ccb; + abort_ccb = ccb->cab.abort_ccb; + + if (abort_ccb->ccb_h.func_code != XPT_SCSI_IO) { + ccb->ccb_h.status = CAM_UA_ABORT; + xpt_done(ccb); + return; + } +.... + +Затем необходимо найти этот CCB в нашей очереди. Это можно сделать, пройдясь по списку всех наших блоков управления оборудованием в поисках связанного с этим CCB: + +[.programlisting] +.... + struct xxx_hcb *hcb, *h; + + hcb = NULL; + + /* We assume that softc->first_hcb is the head of the list of all + * HCBs associated with this bus, including those enqueued for + * processing, being processed by hardware and disconnected ones. + */ + for (h = softc->first_hcb; h != NULL; h = h->next) { + if (h->ccb == abort_ccb) { + hcb = h; + break; + } + } + + if (hcb == NULL) { + /* no such CCB in our queue */ + ccb->ccb_h.status = CAM_PATH_INVALID; + xpt_done(ccb); + return; + } + + hcb=found_hcb; +.... + +Теперь мы рассмотрим текущее состояние обработки HCB. Он может находиться в очереди, ожидая отправки на шину SCSI, передаваться в данный момент, быть отключенным и ожидать результата команды, или фактически завершённым с точки зрения аппаратуры, но ещё не отмеченным программным обеспечением, как выполненный. Чтобы избежать состояний гонки с аппаратурой, мы помечаем HCB как прерванный, так что если этот HCB вот-вот будет отправлен на шину SCSI, контроллер SCSI увидит этот флаг и пропустит его. + +[.programlisting] +.... + int hstatus; + + /* shown as a function, in case special action is needed to make + * this flag visible to hardware + */ + set_hcb_flags(hcb, HCB_BEING_ABORTED); + + abort_again: + + hstatus = get_hcb_status(hcb); + switch (hstatus) { + case HCB_SITTING_IN_QUEUE: + remove_hcb_from_hardware_queue(hcb); + /* FALLTHROUGH */ + case HCB_COMPLETED: + /* this is an easy case */ + free_hcb_and_ccb_done(hcb, abort_ccb, CAM_REQ_ABORTED); + break; +.... + +Если CCB передаётся в данный момент, мы хотели бы сигнализировать контроллеру SCSI аппаратно-зависимым способом, что хотим прервать текущую передачу. Контроллер SCSI установит сигнал SCSI ATTENTION, и когда целевое устройство ответит на него, отправит сообщение ABORT. Мы также сбрасываем таймаут, чтобы убедиться, что целевое устройство не засыпает навсегда. Если команда не будет прервана в разумное время, например, за 10 секунд, процедура таймаута продолжит работу и сбросит всю шину SCSI. Поскольку команда будет прервана в разумные сроки, мы можем просто вернуть запрос на прерывание как успешно выполненный и пометить прерванный CCB как прерванный (но пока не помечать его как завершённый). + +[.programlisting] +.... + case HCB_BEING_TRANSFERRED: + untimeout(xxx_timeout, (caddr_t) hcb, abort_ccb->ccb_h.timeout_ch); + abort_ccb->ccb_h.timeout_ch = + timeout(xxx_timeout, (caddr_t) hcb, 10 * hz); + abort_ccb->ccb_h.status = CAM_REQ_ABORTED; + /* ask the controller to abort that HCB, then generate + * an interrupt and stop + */ + if (signal_hardware_to_abort_hcb_and_stop(hcb) < 0) { + /* oops, we missed the race with hardware, this transaction + * got off the bus before we aborted it, try again */ + goto abort_again; + } + + break; +.... + +Если CCB находится в списке отключенных, то настроить его как запрос прерывания и повторно поставить в начало аппаратной очереди. Сбросить таймаут и сообщить о завершении запроса прерывания. + +[.programlisting] +.... + case HCB_DISCONNECTED: + untimeout(xxx_timeout, (caddr_t) hcb, abort_ccb->ccb_h.timeout_ch); + abort_ccb->ccb_h.timeout_ch = + timeout(xxx_timeout, (caddr_t) hcb, 10 * hz); + put_abort_message_into_hcb(hcb); + put_hcb_at_the_front_of_hardware_queue(hcb); + break; + } + ccb->ccb_h.status = CAM_REQ_CMP; + xpt_done(ccb); + return; +.... + +Вот и все, что касается запроса ABORT, хотя есть еще один момент. Поскольку сообщение ABORT очищает все текущие транзакции на LUN, нам необходимо пометить все остальные активные транзакции на этом LUN как прерванные. Это должно быть выполнено в процедуре аппаратного прерывания после того, как транзакция будет прервана. + +Реализация прерывания CCB в виде функции может быть довольно хорошей идеей, эта функция может быть повторно использована, если транзакция ввода-вывода превысит время ожидания. Единственное различие будет в том, что для транзакции с истекшим временем ожидания будет возвращён статус CAM_CMD_TIMEOUT. Тогда код в case XPT_ABORT будет небольшим, например: + +[.programlisting] +.... + case XPT_ABORT: + struct ccb *abort_ccb; + abort_ccb = ccb->cab.abort_ccb; + + if (abort_ccb->ccb_h.func_code != XPT_SCSI_IO) { + ccb->ccb_h.status = CAM_UA_ABORT; + xpt_done(ccb); + return; + } + if (xxx_abort_ccb(abort_ccb, CAM_REQ_ABORTED) < 0) + /* no such CCB in our queue */ + ccb->ccb_h.status = CAM_PATH_INVALID; + else + ccb->ccb_h.status = CAM_REQ_CMP; + xpt_done(ccb); + return; +.... + +=== _XPT_SET_TRAN_SETTINGS_ - явно установить значения настроек передачи SCSI + +Аргументы передаются в экземпляре "struct ccb_trans_setting cts" объединения ccb: + +* _valid_ - битовая маска, показывающая, какие настройки должны быть обновлены: +** _CCB_TRANS_SYNC_RATE_VALID_ - скорость синхронной передачи +** _CCB_TRANS_SYNC_OFFSET_VALID_ - синхронное смещение +** _CCB_TRANS_BUS_WIDTH_VALID_ - ширина шины +** _CCB_TRANS_DISC_VALID_ - установить разрешение/запрет отключения +** _CCB_TRANS_TQ_VALID_ - установить разрешение/запрет очередей с тегами +* _flags_ - состоит из двух частей: бинарных аргументов и идентификации подопераций. Бинарные аргументы: +** _CCB_TRANS_DISC_ENB_ - разрешить отключение +** _CCB_TRANS_TAG_ENB_ - разрешить тегированную очередь +* подоперации: +** _CCB_TRANS_CURRENT_SETTINGS_ - изменить текущие параметры согласования +** _CCB_TRANS_USER_SETTINGS_ - сохранять желаемые пользовательские значения sync_period, sync_offset - самоочевидные параметры; если sync_offset==0, то запрашивается асинхронный режим bus_width - ширина шины в битах (не в байтах) + +Поддерживаются два набора согласованных параметров: пользовательские настройки и текущие настройки. Пользовательские настройки не так часто используются в драйверах SIM, это в основном просто область памяти, где верхние уровни могут сохранять (и позже извлекать) свои представления о параметрах. Установка пользовательских параметров не вызывает повторного согласования скоростей передачи. Однако, когда SCSI-контроллер выполняет согласование, он никогда не должен устанавливать значения выше пользовательских параметров, так что они по сути являются верхней границей. + +Текущие настройки, как следует из названия, являются текущими. Их изменение означает, что параметры должны быть повторно согласованы при следующей передаче. Опять же, эти «новые текущие настройки» не предназначены для принудительного применения к устройству, они лишь используются в качестве начального шага переговоров. Кроме того, они должны быть ограничены реальными возможностями SCSI-контроллера: например, если SCSI-контроллер имеет 8-битную шину, а запрос требует установки 16-битных передач, этот параметр должен быть тихо усечён до 8-битных передач перед отправкой на устройство. + +Один нюанс заключается в том, что ширина шины и синхронные параметры относятся к цели, тогда как параметры отключения и включения тегов относятся к логическому устройству LUN. + +Рекомендуемая реализация заключается в хранении 3 наборов согласованных параметров (ширина шины и синхронная передача): + +* _user_ - пользовательский набор, как указано выше +* _current_ - тот, который фактически действуют +* _goal_ - тот набор, который запрошен для установки параметров в качестве "текущих" + +Код выглядит следующим образом: + +[.programlisting] +.... + struct ccb_trans_settings *cts; + int targ, lun; + int flags; + + cts = &ccb->cts; + targ = ccb_h->target_id; + lun = ccb_h->target_lun; + flags = cts->flags; + if (flags & CCB_TRANS_USER_SETTINGS) { + if (flags & CCB_TRANS_SYNC_RATE_VALID) + softc->user_sync_period[targ] = cts->sync_period; + if (flags & CCB_TRANS_SYNC_OFFSET_VALID) + softc->user_sync_offset[targ] = cts->sync_offset; + if (flags & CCB_TRANS_BUS_WIDTH_VALID) + softc->user_bus_width[targ] = cts->bus_width; + + if (flags & CCB_TRANS_DISC_VALID) { + softc->user_tflags[targ][lun] &= ~CCB_TRANS_DISC_ENB; + softc->user_tflags[targ][lun] |= flags & CCB_TRANS_DISC_ENB; + } + if (flags & CCB_TRANS_TQ_VALID) { + softc->user_tflags[targ][lun] &= ~CCB_TRANS_TQ_ENB; + softc->user_tflags[targ][lun] |= flags & CCB_TRANS_TQ_ENB; + } + } + if (flags & CCB_TRANS_CURRENT_SETTINGS) { + if (flags & CCB_TRANS_SYNC_RATE_VALID) + softc->goal_sync_period[targ] = + max(cts->sync_period, OUR_MIN_SUPPORTED_PERIOD); + if (flags & CCB_TRANS_SYNC_OFFSET_VALID) + softc->goal_sync_offset[targ] = + min(cts->sync_offset, OUR_MAX_SUPPORTED_OFFSET); + if (flags & CCB_TRANS_BUS_WIDTH_VALID) + softc->goal_bus_width[targ] = min(cts->bus_width, OUR_BUS_WIDTH); + + if (flags & CCB_TRANS_DISC_VALID) { + softc->current_tflags[targ][lun] &= ~CCB_TRANS_DISC_ENB; + softc->current_tflags[targ][lun] |= flags & CCB_TRANS_DISC_ENB; + } + if (flags & CCB_TRANS_TQ_VALID) { + softc->current_tflags[targ][lun] &= ~CCB_TRANS_TQ_ENB; + softc->current_tflags[targ][lun] |= flags & CCB_TRANS_TQ_ENB; + } + } + ccb->ccb_h.status = CAM_REQ_CMP; + xpt_done(ccb); + return; +.... + +Затем, когда следующий запрос ввода-вывода будет обработан, он проверит, нужно ли повторное согласование, например, вызовом функции target_negotiated(hcb). Это может быть реализовано следующим образом: + +[.programlisting] +.... + int + target_negotiated(struct xxx_hcb *hcb) + { + struct softc *softc = hcb->softc; + int targ = hcb->targ; + + if (softc->current_sync_period[targ] != softc->goal_sync_period[targ] + || softc->current_sync_offset[targ] != softc->goal_sync_offset[targ] + || softc->current_bus_width[targ] != softc->goal_bus_width[targ]) + return 0; /* FALSE */ + else + return 1; /* TRUE */ + } +.... + +После пересогласования значений полученные значения должны быть присвоены как текущим, так и целевым параметрам, чтобы для будущих операций ввода-вывода текущие и целевые параметры совпадали, и функция `target_negotiated()` возвращала TRUE. При инициализации карты (в `xxx_attach()`) текущие параметры согласования должны быть инициализированы узким асинхронным режимом, а целевые и текущие значения должны быть инициализированы максимальными значениями, поддерживаемыми контроллером. + +=== _XPT_GET_TRAN_SETTINGS_ - получить значения настроек передачи SCSI + +Эта операция является обратной XPT_SET_TRAN_SETTINGS. Заполните экземпляр CCB "struct ccb_trans_setting cts" данными, запрошенными флагами CCB_TRANS_CURRENT_SETTINGS или CCB_TRANS_USER_SETTINGS (если установлены оба, существующие драйверы возвращают текущие настройки). Установите все биты в поле valid. + +=== _XPT_CALC_GEOMETRY_ - вычислить логическую (BIOS) геометрию диска + +Аргументы передаются в экземпляре "struct ccb_calc_geometry ccg" объединения ccb: + +* _block_size_ - вход, размер блока (также известный как сектор) в байтах +* _volume_size_ - вход, размер тома в байтах +* _cylinders_ - выход, логические цилиндры +* _heads_ - выход, логические головки +* _secs_per_track_ - выход, логических секторов на дорожку + +Если возвращённая геометрия значительно отличается от той, которую предполагает BIOS SCSI-контроллера, и диск на этом SCSI-контроллере используется как загрузочный, система может не загрузиться. Типичный пример расчёта, взятый из драйвера `aic7xxx`, выглядит следующим образом: + +[.programlisting] +.... + struct ccb_calc_geometry *ccg; + u_int32_t size_mb; + u_int32_t secs_per_cylinder; + int extended; + + ccg = &ccb->ccg; + size_mb = ccg->volume_size + / ((1024L * 1024L) / ccg->block_size); + extended = check_cards_EEPROM_for_extended_geometry(softc); + + if (size_mb > 1024 && extended) { + ccg->heads = 255; + ccg->secs_per_track = 63; + } else { + ccg->heads = 64; + ccg->secs_per_track = 32; + } + secs_per_cylinder = ccg->heads * ccg->secs_per_track; + ccg->cylinders = ccg->volume_size / secs_per_cylinder; + ccb->ccb_h.status = CAM_REQ_CMP; + xpt_done(ccb); + return; +.... + +Это дает общее представление, точный расчет зависит от особенностей конкретной BIOS. Если BIOS не предоставляет возможности установить флаг "расширенной трансляции" в EEPROM, этот флаг обычно следует считать равным 1. Другие популярные геометрии: + +[.programlisting] +.... + 128 heads, 63 sectors - Symbios controllers + 16 heads, 63 sectors - old controllers +.... + +Некоторые системные BIOS и SCSI BIOS конфликтуют друг с другом с переменным успехом. Например, комбинация Symbios 875/895 SCSI и Phoenix BIOS может выдавать геометрию 128/63 после включения питания и 255/63 после жесткого сброса или мягкой перезагрузки. + +=== _XPT_PATH_INQ_ - запрос пути, другими словами, получение свойств драйвера SIM и контроллера SCSI (также известного как HBA - Host Bus Adapter) + +Свойства возвращаются в экземпляре "struct ccb_pathinq cpi" объединения ccb: + +* `version_num` - номер версии драйвера SIM, в настоящее время все драйверы используют 1 +* hba_inquiry - битовая маска функций, поддерживаемых контроллером: +** PI_MDP_ABLE - поддерживает сообщение MDP (что-то из SCSI3?) +** PI_WIDE_32 — поддерживает 32-битную широкую SCSI +** PI_WIDE_16 — поддерживает 16-битную широкую SCSI +** PI_SDTR_ABLE - может согласовать синхронную скорость передачи +** PI_LINKED_CDB - поддерживает связанные команды +** PI_TAG_ABLE - поддерживает помеченные команды +** PI_SOFT_RST — поддерживает альтернативу мягкого сброса (жесткий сброс и мягкий сброс являются взаимоисключающими в пределах шины SCSI) +* target_sprt - флаги поддержки целевого режима, 0 если не поддерживается +* hba_misc - различные функции контроллера: +** PIM_SCANHILO - сканирование шины от высокого ID к низкому ID +** PIM_NOREMOVE - съемные устройства не включены в сканирование +** PIM_NOINITIATOR - роль инициатора не поддерживается +** PIM_NOBUSRESET - пользователь отключил начальный BUS RESET +* hba_eng_cnt - загадочное количество движков HBA, что-то связанное со сжатием, в настоящее время всегда устанавливается в 0 +* vuhba_flags - уникальные флаги производителя, в настоящее время не используются +* max_target - максимальный поддерживаемый идентификатор целевого устройства (7 для 8-битной шины, 15 для 16-битной шины, 127 для Fibre Channel) +* max_lun - максимально поддерживаемый идентификатор LUN (7 для старых SCSI-контроллеров, 63 для новых) +* async_flags - битовая маска установленных обработчиков Async, в настоящее время не используется +* hpath_id - наивысший Path ID в подсистеме, в настоящее время не используется +* unit_number - номер контроллера, cam_sim_unit(sim) +* bus_id - номер шины, cam_sim_bus(sim) +* initiator_id - SCSI ID самого контроллера +* base_transfer_speed - номинальная скорость передачи в КБ/с для асинхронных узкополосных передач, равна 3300 для SCSI +* sim_vid - идентификатор производителя драйвера SIM, строка с нулевым окончанием максимальной длины SIM_IDLEN, включая завершающий ноль +* hba_vid - идентификатор производителя SCSI-контроллера, строка с нулевым окончанием максимальной длины HBA_IDLEN, включая завершающий ноль +* dev_name - имя драйвера устройства, строка с нулевым окончанием максимальной длины DEV_IDLEN, включая завершающий ноль, эквивалентно cam_sim_name(sim) + +Рекомендуемый способ установки строковых полей — использование strncpy, например: + +[.programlisting] +.... + strncpy(cpi->dev_name, cam_sim_name(sim), DEV_IDLEN); +.... + +После установки значений установите статус в CAM_REQ_CMP и пометьте CCB как завершённый. + +[[scsi-polling]] +== Опрос xxx_poll + +[.programlisting] +.... +static void xxx_poll(struct cam_sim *); +.... + +Функция poll используется для имитации прерываний, когда подсистема прерываний не функционирует (например, когда система аварийно завершила работу и создает дамп памяти). Подсистема CAM устанавливает соответствующий уровень прерывания перед вызовом процедуры poll. Таким образом, все, что ей нужно сделать, — это вызвать процедуру прерывания (или наоборот, процедура poll может выполнять реальные действия, а процедура прерывания просто вызывает процедуру poll). Зачем тогда нужна отдельная функция? Это связано с различными соглашениями о вызовах. Процедура `xxx_poll` получает указатель на структуру cam_sim в качестве аргумента, в то время как процедура прерывания PCI по общему соглашению получает указатель на структуру `xxx_softc`, а процедура прерывания ISA получает только номер устройства. Таким образом, процедура poll обычно выглядит следующим образом: + +[.programlisting] +.... +static void +xxx_poll(struct cam_sim *sim) +{ + xxx_intr((struct xxx_softc *)cam_sim_softc(sim)); /* for PCI device */ +} +.... + +или + +[.programlisting] +.... +static void +xxx_poll(struct cam_sim *sim) +{ + xxx_intr(cam_sim_unit(sim)); /* for ISA device */ +} +.... + +[[scsi-async]] +== Асинхронные события + +Если была настроена асинхронная callback-функция для события, то callback-функция должна быть определена. + +[.programlisting] +.... +static void +ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg) +.... + +* callback_arg - значение, переданное при регистрации callback +* code - определяет тип события +* path - определяет устройства, к которым применяется событие +* arg - аргумент, специфичный для события + +Реализация для одного типа события, AC_LOST_DEVICE, выглядит следующим образом: + +[.programlisting] +.... + struct xxx_softc *softc; + struct cam_sim *sim; + int targ; + struct ccb_trans_settings neg; + + sim = (struct cam_sim *)callback_arg; + softc = (struct xxx_softc *)cam_sim_softc(sim); + switch (code) { + case AC_LOST_DEVICE: + targ = xpt_path_target_id(path); + if (targ <= OUR_MAX_SUPPORTED_TARGET) { + clean_negotiations(softc, targ); + /* send indication to CAM */ + neg.bus_width = 8; + neg.sync_period = neg.sync_offset = 0; + neg.valid = (CCB_TRANS_BUS_WIDTH_VALID + | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID); + xpt_async(AC_TRANSFER_NEG, path, &neg); + } + break; + default: + break; + } +.... + +[[scsi-interrupts]] +== Прерывания + +Точный тип процедуры прерывания зависит от типа периферийной шины (PCI, ISA и так далее), к которой подключен SCSI-контроллер. + +Прерывания в драйверах SIM выполняются на уровне прерывания splcam. Поэтому в драйвере следует использовать `splcam()` для синхронизации между обработчиком прерывания и остальной частью драйвера (для драйверов, учитывающих многопроцессорность, ситуация становится ещё сложнее, но здесь мы этот случай не рассматриваем). Псевдокод в этом документе беззаботно игнорирует проблемы синхронизации. Реальный код так делать не должен. Простейший подход — установить `splcam()` при входе в другие функции и сбросить при выходе, защищая их одной большой критической секцией. Чтобы гарантировать восстановление уровня прерывания, можно определить обёрточную функцию, например: + +[.programlisting] +.... + static void + xxx_action(struct cam_sim *sim, union ccb *ccb) + { + int s; + s = splcam(); + xxx_action1(sim, ccb); + splx(s); + } + + static void + xxx_action1(struct cam_sim *sim, union ccb *ccb) + { + ... process the request ... + } +.... + +Этот подход прост и надежен, но проблема в том, что прерывания могут блокироваться на относительно долгое время, что негативно скажется на производительности системы. С другой стороны, функции семейства `spl()` имеют довольно высокие накладные расходы, поэтому большое количество мелких критических секций также может быть нежелательным. + +Условия, обрабатываемые процедурой прерывания, и детали сильно зависят от оборудования. Мы рассматриваем набор "типичных" условий. + +Сначала проверяем, было ли на шине событие SCSI сброса (вероятно, вызванное другим SCSI-контроллером на той же SCSI-шине). Если это так, мы отменяем все поставленные в очередь и отключенные запросы, сообщаем о событиях и повторно инициализируем наш SCSI-контроллер. Важно, чтобы во время этой инициализации контроллер не инициировал ещё один сброс, иначе два контроллера на одной SCSI-шине могут бесконечно обмениваться сбросами. Случай фатальной ошибки/зависания контроллера может быть обработан в том же месте, но, вероятно, также потребуется отправка сигнала RESET на SCSI-шину для сброса состояния соединений с SCSI-устройствами. + +[.programlisting] +.... + int fatal=0; + struct ccb_trans_settings neg; + struct cam_path *path; + + if (detected_scsi_reset(softc) + || (fatal = detected_fatal_controller_error(softc))) { + int targ, lun; + struct xxx_hcb *h, *hh; + + /* drop all enqueued CCBs */ + for(h = softc->first_queued_hcb; h != NULL; h = hh) { + hh = h->next; + free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET); + } + + /* the clean values of negotiations to report */ + neg.bus_width = 8; + neg.sync_period = neg.sync_offset = 0; + neg.valid = (CCB_TRANS_BUS_WIDTH_VALID + | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID); + + /* drop all disconnected CCBs and clean negotiations */ + for (targ=0; targ <= OUR_MAX_SUPPORTED_TARGET; targ++) { + clean_negotiations(softc, targ); + + /* report the event if possible */ + if (xpt_create_path(&path, /*periph*/NULL, + cam_sim_path(sim), targ, + CAM_LUN_WILDCARD) == CAM_REQ_CMP) { + xpt_async(AC_TRANSFER_NEG, path, &neg); + xpt_free_path(path); + } + + for (lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++) + for (h = softc->first_discon_hcb[targ][lun]; h != NULL; h = hh) { + hh=h->next; + if (fatal) + free_hcb_and_ccb_done(h, h->ccb, CAM_UNREC_HBA_ERROR); + else + free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET); + } + } + + /* report the event */ + xpt_async(AC_BUS_RESET, softc->wpath, NULL); + + /* re-initialization may take a lot of time, in such case + * its completion should be signaled by another interrupt or + * checked on timeout - but for simplicity we assume here that + * it is really fast + */ + if (!fatal) { + reinitialize_controller_without_scsi_reset(softc); + } else { + reinitialize_controller_with_scsi_reset(softc); + } + schedule_next_hcb(softc); + return; + } +.... + +Если прерывание не вызвано условием, общим для всего контроллера, то, вероятно, что-то произошло с текущим блоком управления аппаратным обеспечением. В зависимости от оборудования могут быть и другие события, не связанные с HCB, но мы их здесь не рассматриваем. Затем мы анализируем, что произошло с этим HCB: + +[.programlisting] +.... + struct xxx_hcb *hcb, *h, *hh; + int hcb_status, scsi_status; + int ccb_status; + int targ; + int lun_to_freeze; + + hcb = get_current_hcb(softc); + if (hcb == NULL) { + /* either stray interrupt or something went very wrong + * or this is something hardware-dependent + */ + handle as necessary; + return; + } + + targ = hcb->target; + hcb_status = get_status_of_current_hcb(softc); +.... + +Сначала мы проверяем, завершился ли HCB, и если да, то проверяем возвращённый статус SCSI. + +[.programlisting] +.... + if (hcb_status == COMPLETED) { + scsi_status = get_completion_status(hcb); +.... + +Затем проверьте, связан ли этот статус с командой REQUEST SENSE, и если да, обработайте его простым способом. + +[.programlisting] +.... + if (hcb->flags & DOING_AUTOSENSE) { + if (scsi_status == GOOD) { /* autosense was successful */ + hcb->ccb->ccb_h.status |= CAM_AUTOSNS_VALID; + free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_SCSI_STATUS_ERROR); + } else { + autosense_failed: + free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_AUTOSENSE_FAIL); + } + schedule_next_hcb(softc); + return; + } +.... + +Иначе сама команда завершена, уделяйте больше внимания деталям. Если автоопределение не отключено для этого CCB и команда завершилась неудачно с данными состояния, выполните команду REQUEST SENSE для получения этих данных. + +[.programlisting] +.... + hcb->ccb->csio.scsi_status = scsi_status; + calculate_residue(hcb); + + if ((hcb->ccb->ccb_h.flags & CAM_DIS_AUTOSENSE)==0 + && (scsi_status == CHECK_CONDITION + || scsi_status == COMMAND_TERMINATED)) { + /* start auto-SENSE */ + hcb->flags |= DOING_AUTOSENSE; + setup_autosense_command_in_hcb(hcb); + restart_current_hcb(softc); + return; + } + if (scsi_status == GOOD) + free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_REQ_CMP); + else + free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_SCSI_STATUS_ERROR); + schedule_next_hcb(softc); + return; + } +.... + +Типичным примером могут быть события согласования: сообщения согласования, полученные от цели SCSI (в ответ на нашу попытку согласования или по инициативе цели), или если цель не может согласовать (отклоняет наши сообщения согласования или не отвечает на них). + +[.programlisting] +.... + switch (hcb_status) { + case TARGET_REJECTED_WIDE_NEG: + /* revert to 8-bit bus */ + softc->current_bus_width[targ] = softc->goal_bus_width[targ] = 8; + /* report the event */ + neg.bus_width = 8; + neg.valid = CCB_TRANS_BUS_WIDTH_VALID; + xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &neg); + continue_current_hcb(softc); + return; + case TARGET_ANSWERED_WIDE_NEG: + { + int wd; + + wd = get_target_bus_width_request(softc); + if (wd <= softc->goal_bus_width[targ]) { + /* answer is acceptable */ + softc->current_bus_width[targ] = + softc->goal_bus_width[targ] = neg.bus_width = wd; + + /* report the event */ + neg.valid = CCB_TRANS_BUS_WIDTH_VALID; + xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &neg); + } else { + prepare_reject_message(hcb); + } + } + continue_current_hcb(softc); + return; + case TARGET_REQUESTED_WIDE_NEG: + { + int wd; + + wd = get_target_bus_width_request(softc); + wd = min (wd, OUR_BUS_WIDTH); + wd = min (wd, softc->user_bus_width[targ]); + + if (wd != softc->current_bus_width[targ]) { + /* the bus width has changed */ + softc->current_bus_width[targ] = + softc->goal_bus_width[targ] = neg.bus_width = wd; + + /* report the event */ + neg.valid = CCB_TRANS_BUS_WIDTH_VALID; + xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &neg); + } + prepare_width_nego_rsponse(hcb, wd); + } + continue_current_hcb(softc); + return; + } +.... + +Затем мы обрабатываем любые ошибки, которые могли произойти во время автоопределения, тем же простым способом, что и раньше. В противном случае мы снова внимательно изучаем детали. + +[.programlisting] +.... + if (hcb->flags & DOING_AUTOSENSE) + goto autosense_failed; + + switch (hcb_status) { +.... + +Следующее событие, которое мы рассматриваем, — это неожиданное отключение. Оно считается нормальным после сообщения ABORT или BUS DEVICE RESET и аномальным в остальных случаях. + +[.programlisting] +.... + case UNEXPECTED_DISCONNECT: + if (requested_abort(hcb)) { + /* abort affects all commands on that target+LUN, so + * mark all disconnected HCBs on that target+LUN as aborted too + */ + for (h = softc->first_discon_hcb[hcb->target][hcb->lun]; + h != NULL; h = hh) { + hh=h->next; + free_hcb_and_ccb_done(h, h->ccb, CAM_REQ_ABORTED); + } + ccb_status = CAM_REQ_ABORTED; + } else if (requested_bus_device_reset(hcb)) { + int lun; + + /* reset affects all commands on that target, so + * mark all disconnected HCBs on that target+LUN as reset + */ + + for (lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++) + for (h = softc->first_discon_hcb[hcb->target][lun]; + h != NULL; h = hh) { + hh=h->next; + free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET); + } + + /* send event */ + xpt_async(AC_SENT_BDR, hcb->ccb->ccb_h.path_id, NULL); + + /* this was the CAM_RESET_DEV request itself, it is completed */ + ccb_status = CAM_REQ_CMP; + } else { + calculate_residue(hcb); + ccb_status = CAM_UNEXP_BUSFREE; + /* request the further code to freeze the queue */ + hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN; + lun_to_freeze = hcb->lun; + } + break; +.... + +Если цель отказывается принимать теги, мы уведомляем CAM об этом и возвращаем все команды для этого LUN: + +[.programlisting] +.... + case TAGS_REJECTED: + /* report the event */ + neg.flags = 0 & ~CCB_TRANS_TAG_ENB; + neg.valid = CCB_TRANS_TQ_VALID; + xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &neg); + + ccb_status = CAM_MSG_REJECT_REC; + /* request the further code to freeze the queue */ + hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN; + lun_to_freeze = hcb->lun; + break; +.... + +Затем мы проверяем ряд других условий, при этом обработка в основном ограничивается установкой статуса CCB: + +[.programlisting] +.... + case SELECTION_TIMEOUT: + ccb_status = CAM_SEL_TIMEOUT; + /* request the further code to freeze the queue */ + hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN; + lun_to_freeze = CAM_LUN_WILDCARD; + break; + case PARITY_ERROR: + ccb_status = CAM_UNCOR_PARITY; + break; + case DATA_OVERRUN: + case ODD_WIDE_TRANSFER: + ccb_status = CAM_DATA_RUN_ERR; + break; + default: + /* all other errors are handled in a generic way */ + ccb_status = CAM_REQ_CMP_ERR; + /* request the further code to freeze the queue */ + hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN; + lun_to_freeze = CAM_LUN_WILDCARD; + break; + } +.... + +Затем мы проверяем, была ли ошибка достаточно серьёзной, чтобы заморозить очередь ввода до её обработки, и если да, то делаем это: + +[.programlisting] +.... + if (hcb->ccb->ccb_h.status & CAM_DEV_QFRZN) { + /* freeze the queue */ + xpt_freeze_devq(ccb->ccb_h.path, /*count*/1); + + /* re-queue all commands for this target/LUN back to CAM */ + + for (h = softc->first_queued_hcb; h != NULL; h = hh) { + hh = h->next; + + if (targ == h->targ + && (lun_to_freeze == CAM_LUN_WILDCARD || lun_to_freeze == h->lun)) + free_hcb_and_ccb_done(h, h->ccb, CAM_REQUEUE_REQ); + } + } + free_hcb_and_ccb_done(hcb, hcb->ccb, ccb_status); + schedule_next_hcb(softc); + return; +.... + +На этом общее описание обработки прерываний завершается, хотя для некоторых контроллеров могут потребоваться дополнительные действия. + +[[scsi-errors]] +== Ошибки (Сводка) + +При выполнении запроса ввода-вывода может произойти множество ошибок. Причина ошибки может быть указана в статусе CCB с большим количеством деталей. Примеры использования разбросаны по всему документу. Для полноты изложения приведём сводку рекомендуемых действий при типичных ошибках: + +* _CAM_RESRC_UNAVAIL_ — некоторый ресурс временно недоступен, и драйвер SIM не может сгенерировать событие, когда он станет доступен. Примером такого ресурса может быть некоторый внутренний аппаратный ресурс контроллера, для которого контроллер не генерирует прерывание при его доступности. +* _CAM_UNCOR_PARITY_ - произошла неисправимая ошибка четности +* _CAM_DATA_RUN_ERR_ - переполнение данных или неожиданная фаза данных (направление передачи не соответствует указанному в CAM_DIR_MASK) или нечётная длина передачи для широкой передачи +* _CAM_SEL_TIMEOUT_ - произошел таймаут выбора (цель не отвечает) +* _CAM_CMD_TIMEOUT_ - произошло превышение времени ожидания команды (сработала функция таймаута) +* _CAM_SCSI_STATUS_ERROR_ - устройство вернуло ошибку +* _CAM_AUTOSENSE_FAIL_ - устройство вернуло ошибку и команда REQUEST SENSE завершилась неудачно +* _CAM_MSG_REJECT_REC_ - получено сообщение MESSAGE REJECT +* _CAM_SCSI_BUS_RESET_ - получен сброс шины SCSI +* _CAM_REQ_CMP_ERR_ - произошла «невозможная» фаза SCSI или что-то столь же странное, либо это просто общая ошибка, если дополнительная информация недоступна +* _CAM_UNEXP_BUSFREE_ - произошло неожиданное отключение +* _CAM_BDR_SENT_ - Сообщение BUS DEVICE RESET было отправлено целевому устройству +* _CAM_UNREC_HBA_ERROR_ - невосстановимая ошибка адаптера шины хоста +* _CAM_REQ_TOO_BIG_ - запрос слишком велик для данного контроллера +* _CAM_REQUEUE_REQ_ - этот запрос должен быть повторно поставлен в очередь для сохранения порядка транзакций. Обычно это происходит, когда SIM обнаруживает ошибку, которая должна заморозить очередь, и необходимо поместить другие запросы в очереди для цели на уровне SIM обратно в очередь XPT. Типичными случаями таких ошибок являются тайм-ауты выбора, тайм-ауты команд и другие подобные условия. В таких случаях проблемная команда возвращает статус, указывающий на ошибку, а другие команды, которые ещё не были отправлены на шину, повторно ставятся в очередь. +* _CAM_LUN_INVALID_ - идентификатор LUN в запросе не поддерживается контроллером SCSI +* _CAM_TID_INVALID_ - идентификатор целевого устройства в запросе не поддерживается контроллером SCSI + +[[scsi-timeout]] +== Обработка таймаутов + +Когда время ожидания для HCB истекает, этот запрос должен быть прерван, как и в случае с запросом XPT_ABORT. Единственное отличие заключается в том, что возвращаемый статус прерванного запроса должен быть CAM_CMD_TIMEOUT вместо CAM_REQ_ABORTED (вот почему реализацию прерывания лучше сделать в виде функции). Но есть ещё одна возможная проблема: что если сам запрос на прерывание зависнет? В этом случае шина SCSI должна быть сброшена, как и при запросе XPT_RESET_BUS (и идея о реализации этого в виде функции, вызываемой из обоих мест, применима и здесь). Также мы должны сбросить всю шину SCSI, если запрос на сброс устройства завис. В итоге функция обработки таймаута будет выглядеть следующим образом: + +[.programlisting] +.... +static void +xxx_timeout(void *arg) +{ + struct xxx_hcb *hcb = (struct xxx_hcb *)arg; + struct xxx_softc *softc; + struct ccb_hdr *ccb_h; + + softc = hcb->softc; + ccb_h = &hcb->ccb->ccb_h; + + if (hcb->flags & HCB_BEING_ABORTED || ccb_h->func_code == XPT_RESET_DEV) { + xxx_reset_bus(softc); + } else { + xxx_abort_ccb(hcb->ccb, CAM_CMD_TIMEOUT); + } +} +.... + +Когда мы прерываем запрос, все остальные отключенные запросы к тому же целевому устройству/LUN также прерываются. Возникает вопрос: следует ли возвращать их со статусом CAM_REQ_ABORTED или CAM_CMD_TIMEOUT? Текущие драйверы используют CAM_CMD_TIMEOUT. Это кажется логичным, потому что если один запрос превысил время ожидания, то, вероятно, с устройством происходит что-то действительно плохое, и если их не трогать, они бы сами превысили время ожидания. diff --git a/documentation/content/ru/books/arch-handbook/scsi/_index.po b/documentation/content/ru/books/arch-handbook/scsi/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/scsi/_index.po @@ -0,0 +1,4280 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-05 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 "Контроллеры SCSI с общим методом доступа (CAM)" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1 +#, no-wrap +msgid "Chapter 12. Common Access Method SCSI Controllers" +msgstr "Глава 12. Контроллеры SCSI с общим методом доступа (CAM)" + +#. 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 "" +"Этот документ предполагает, что читатель имеет общее представление о " +"драйверах устройств в FreeBSD и о протоколе SCSI. Большая часть информации в " +"этом документе была извлечена из драйверов:" + +#. 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 "" +"ncr ([.filename]#/sys/pci/ncr.c#) от Wolfgang Stanglmeier и Stefan Esser" + +#. 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 "sym ([.filename]#/sys/dev/sym/sym_hipd.c#) от Gerard Roudier" + +#. 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 "aic7xxx ([.filename]#/sys/dev/aic7xxx/aic7xxx.c#) от Justin T. Gibbs" + +#. 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 "" +"и из самого кода CAM (автор Justin T. Gibbs, см. [.filename]#/sys/cam/*#). " +"Когда какое-то решение выглядело наиболее логичным и было практически " +"дословно взято из кода Justin T. Gibbs, я отмечал его как \"рекомендуемое\"." + +#. 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 "" +"CAM означает Common Access Method (Общий Метод Доступа). Это универсальный " +"способ адресации шин ввода-вывода в стиле SCSI. Это позволяет отделить общие " +"драйверы устройств от драйверов, управляющих шиной ввода-вывода: например, " +"драйвер диска получает возможность управлять дисками как на SCSI, IDE, так и " +"на любой другой шине, так что часть драйвера диска не нужно переписывать " +"(или копировать и изменять) для каждой новой шины ввода-вывода. Таким " +"образом, двумя наиболее важными активными сущностями являются:" + +#. 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 "" +"_Модули периферийных устройств_ - драйвер для периферийных устройств (диски, " +"ленты, CD-ROM и т.д.)" + +#. 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 "" +"_Модули интерфейса SCSI_ (SIM) - драйверы адаптеров шины для подключения к " +"шине ввода-вывода, такой как SCSI или IDE." + +#. 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 "" +"Периферийный драйвер получает запросы от ОС, преобразует их в " +"последовательность команд SCSI и передает эти команды SCSI модулю интерфейса " +"SCSI. Модуль интерфейса SCSI отвечает за передачу этих команд реальному " +"оборудованию (или, если оборудование не поддерживает SCSI, а использует, " +"например, IDE, также преобразует команды SCSI в собственные команды " +"оборудования)." + +#. 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 "" +"Так как мы заинтересованы в написании драйвера адаптера SCSI, с этого " +"момента мы будем рассматривать всё с точки зрения модуля SCSI-интерфейса " +"(SIM)." + +#. 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 "" +"Типичный драйвер SIM должен включать следующие заголовочные файлы, связанные " +"с CAM:" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:100 +#, no-wrap +msgid "" +"#include \n" +"#include \n" +"#include \n" +"#include \n" +"#include \n" +"#include \n" +msgstr "" +"#include \n" +"#include \n" +"#include \n" +"#include \n" +"#include \n" +"#include \n" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:102 +#, no-wrap +msgid "Device configuration: xxx_attach" +msgstr "Конфигурация устройства: xxx_attach" + +#. 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 "" +"Первое, что должен сделать каждый драйвер SIM, — это зарегистрироваться в " +"подсистеме CAM. Это выполняется в функции `xxx_attach()` драйвера (здесь и " +"далее xxx_ используется для обозначения уникального префикса имени " +"драйвера). Сама функция `xxx_attach()` вызывается кодом автонастройки " +"системной шины, который мы здесь не описываем." + +#. 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 "" +"Это достигается в несколько этапов: сначала необходимо выделить очередь " +"запросов, связанных с этой SIM:" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:113 +#, no-wrap +msgid " struct cam_devq *devq;\n" +msgstr " struct cam_devq *devq;\n" + +#. 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 "" +" if ((devq = cam_simq_alloc(SIZE)) == NULL) {\n" +" error; /* some code to handle the error */\n" +" }\n" + +#. 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 "" +"Вот `SIZE` — это размер выделяемой очереди, максимальное количество " +"запросов, которые она может содержать. Это количество запросов, которые " +"драйвер SIM может обрабатывать параллельно на одной SCSI-карте. Обычно его " +"можно вычислить как:" + +#. 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 "SIZE = NUMBER_OF_SUPPORTED_TARGETS * MAX_SIMULTANEOUS_COMMANDS_PER_TARGET\n" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:129 +msgid "Next we create a descriptor of our SIM:" +msgstr "Далее мы создаем описание нашего SIM:" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:133 +#, no-wrap +msgid " struct cam_sim *sim;\n" +msgstr " struct cam_sim *sim;\n" + +#. 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 "" +" 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" + +#. 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 "" +"Обратите внимание, что если мы не сможем создать дескриптор SIM, мы также " +"освобождаем `devq`, потому что больше ничего не можем с ним сделать и хотим " +"сэкономить память." + +#. 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 "" +"Если SCSI-карта имеет несколько шин SCSI, то каждой шине требуется " +"собственная структура `cam_sim`." + +#. 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 "" +"Интересный вопрос: что делать, если SCSI-карта имеет более одной SCSI-шины, " +"нужна ли одна структура `devq` на карту или на SCSI-шину? Ответ, приведённый " +"в комментариях к коду CAM, таков: как угодно, на усмотрение автора драйвера." + +#. 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 "`action_func` - указатель на функцию `xxx_action` драйвера." + +#. 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 "static void xxx_action(struct cam_sim *, union ccb *);\n" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:158 +msgid "`poll_func` - pointer to the driver's `xxx_poll()`" +msgstr "`poll_func` - указатель на функцию `xxx_poll()` драйвера" + +#. 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 "static void xxx_poll(struct cam_sim *);\n" + +#. 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 "`driver_name` — имя фактического драйвера, например `ncr` или `wds`." + +#. 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 "" +"`softc` — указатель на внутренний дескриптор драйвера для данной SCSI-карты. " +"Этот указатель будет использоваться драйвером в дальнейшем для получения " +"приватных данных." + +#. 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 "" +"unit - номер управляющего устройства, например, для контроллера \"mps0\" это " +"число будет 0" + +#. 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 "" +"mtx - Блокировка, связанная с данной SIM. Для SIM, которые не поддерживают " +"блокировку, передается Giant. Для SIM, которые поддерживают, передается " +"блокировка, используемая для защиты структур данных этой SIM. Эта блокировка " +"будет удерживаться при вызовах xxx_action и xxx_poll." + +#. 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 "" +"max_dev_transactions - максимальное количество одновременных транзакций на " +"целевом SCSI-устройстве в режиме без тегов. Это значение почти всегда равно " +"1, за исключением возможных исключений только для не-SCSI карт. Также " +"драйверы, которые надеются получить преимущество, подготавливая одну " +"транзакцию во время выполнения другой, могут установить его в 2, но это не " +"кажется оправданным из-за сложности." + +#. 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 "" +"max_tagged_dev_transactions - то же самое, но в режиме с тегами. Теги — это " +"способ в SCSI инициировать несколько транзакций на устройстве: каждая " +"транзакция получает уникальный тег и отправляется на устройство. Когда " +"устройство завершает транзакцию, оно возвращает результат вместе с тегом, " +"чтобы SCSI-адаптер (и драйвер) могли определить, какая транзакция была " +"завершена. Этот аргумент также известен как максимальная глубина тега. Он " +"зависит от возможностей SCSI-адаптера." + +#. 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 "Наконец, мы регистрируем шины SCSI, связанные с нашим SCSI-адаптером:" + +#. 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 "" +" 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" + +#. 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 "" +"Если существует одна структура `devq` на каждую шину SCSI (т.е. мы " +"рассматриваем карту с несколькими шинами как несколько карт с одной шиной " +"каждая), то номер шины всегда будет 0, в противном случае каждая шина на " +"SCSI-карте должна получить уникальный номер. Каждой шине требуется своя " +"отдельная структура `cam_sim`." + +#. 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 "" +"После этого наш контроллер полностью подключён к системе CAM. Значение " +"`devq` теперь можно отбросить: sim будет передаваться в качестве аргумента " +"во всех последующих вызовах из CAM, а devq можно получить из него." + +#. 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 "" +"CAM предоставляет инфраструктуру для подобных асинхронных событий. Некоторые " +"события возникают на нижних уровнях (драйверы SIM), некоторые — в драйверах " +"периферийных устройств, а некоторые — в самой подсистеме CAM. Любой драйвер " +"может зарегистрировать обработчики для определённых типов асинхронных " +"событий, чтобы получать уведомления при их возникновении." + +#. 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 " struct cam_path *path;\n" + +#. 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 "" +" 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" + +#. 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 "" +" softc->wpath = path;\n" +" softc->sim = sim;\n" + +#. 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 "" +"Идентификатор драйвера периферийного устройства (NULL здесь, так как у нас " +"его нет)" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:228 +msgid "ID of the SIM driver (`cam_sim_path(sim)`)" +msgstr "Идентификатор драйвера SIM (`cam_sim_path(sim)`)" + +#. 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 "" +"Номер целевого устройства SCSI (CAM_TARGET_WILDCARD означает \"все " +"устройства\")" + +#. 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 "Номер SCSI LUN подустройства (CAM_LUN_WILDCARD означает \"все LUN\")" + +#. 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 "" +"Если драйвер не может выделить этот путь, он не сможет нормально работать, " +"поэтому в таком случае мы демонтируем эту шину SCSI." + +#. 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 "" +"И мы сохраняем указатель пути в структуре `softc` для дальнейшего " +"использования. После этого сохраняем значение sim (или можем также отбросить " +"его при выходе из `xxx_probe()`, если захотим)." + +#. 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 "" +"Для драйвера SIM есть одно особенно важное событие: когда целевое устройство " +"считается потерянным. В этом случае может быть хорошей идеей сбросить SCSI-" +"переговоры с этим устройством. Поэтому мы регистрируем обратный вызов для " +"этого события в CAM. Запрос передаётся в CAM путём запроса действия CAM в " +"блоке управления CAM для этого типа запроса:" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:247 +#, no-wrap +msgid " struct ccb_setasync csa;\n" +msgstr " struct ccb_setasync csa;\n" + +#. 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 "" +" 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" + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:256 +#, no-wrap +msgid "Processing CAM messages: xxx_action" +msgstr "Обработка сообщений CAM: xxx_action" + +#. 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 "static void xxx_action(struct cam_sim *sim, union ccb *ccb);\n" + +#. 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 "" +"Выполнить некоторое действие по запросу подсистемы CAM. Sim описывает SIM " +"для запроса, CCB — это сам запрос. CCB расшифровывается как \"CAM Control " +"Block\" (блок управления CAM). Это объединение множества конкретных " +"экземпляров, каждый из которых описывает аргументы для определённого типа " +"транзакций. Все эти экземпляры имеют общий заголовок CCB, в котором " +"хранится общая часть аргументов." + +#. 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 "" +"CAM поддерживает SCSI-контроллеры, работающие как в режиме инициатора " +"(«обычном»), так и в режиме цели (эмулирующем SCSI-устройство). Здесь мы " +"рассматриваем только часть, относящуюся к режиму инициатора." + +#. 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 "" +"Существует несколько функций и макросов (другими словами, методов), " +"определённых для доступа к публичным данным в структуре sim:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:275 +msgid "`cam_sim_path(sim)` - the path ID (see above)" +msgstr "`cam_sim_path(sim)` - идентификатор пути (см. выше)" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:276 +msgid "`cam_sim_name(sim)` - the name of the sim" +msgstr "`cam_sim_name(sim)` — имя sim" + +#. 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 "" +"`cam_sim_softc(sim)` - указатель на структуру softc (приватные данные " +"драйвера)" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:278 +msgid "`cam_sim_unit(sim)` - the unit number" +msgstr "`cam_sim_unit(sim)` - номер устройства" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:279 +msgid "`cam_sim_bus(sim)` - the bus ID" +msgstr "`cam_sim_bus(sim)` - идентификатор шины" + +#. 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 "" +"Для идентификации устройства `xxx_action()` может получить номер устройства " +"и указатель на его структуру softc, используя следующие функции." + +#. 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 "" +"Тип запроса хранится в `ccb->ccb_h.func_code`. Поэтому, как правило, " +"`xxx_action()` состоит из большого оператора switch:" + +#. 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 "" +" 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" + +#. 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 "" +" 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" + +#. 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 "" +"Как видно из случая по умолчанию (если получена неизвестная команда) код " +"возврата команды устанавливается в `ccb->ccb_h.status`, а завершённый CCB " +"возвращается обратно в CAM вызовом `xpt_done(ccb)`." + +#. 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 "" +"`xpt_done()` не обязательно вызывать из `xxx_action()`: Например, запрос " +"ввода-вывода может быть поставлен в очередь внутри драйвера SIM и/или его " +"SCSI-контроллера. Затем, когда устройство пошлет прерывание, сигнализирующее " +"о завершении обработки этого запроса, `xpt_done()` может быть вызван из " +"процедуры обработки прерывания." + +#. 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 "" +"На самом деле, статус CCB не только присваивается в качестве кода возврата, " +"но и CCB всегда имеет какой-то статус. Перед тем как CCB передается в " +"процедуру `xxx_action()`, он получает статус CCB_REQ_INPROG, означающий, что " +"запрос находится в процессе выполнения. В [.filename]#/sys/cam/cam.h# " +"определено удивительно большое количество значений статуса, которые должны " +"детально отражать состояние запроса. Что еще интереснее, статус фактически " +"представляет собой \"побитовое ИЛИ\" перечисленного значения статуса " +"(младшие 6 бит) и возможных дополнительных флагов (старшие биты). " +"Перечисленные значения будут подробно рассмотрены далее. Их краткое описание " +"можно найти в разделе \"Сводка ошибок\". Возможные флаги статуса:" + +#. 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 "" +"_CAM_DEV_QFRZN_ - если драйвер SIM получает серьёзную ошибку (например, " +"устройство не отвечает на выборку или нарушает протокол SCSI) при обработке " +"CCB, он должен заморозить очередь запросов, вызвав `xpt_freeze_simq()`, " +"вернуть другие поставленные в очередь, но ещё не обработанные CCB для этого " +"устройства обратно в очередь CAM, затем установить этот флаг для проблемного " +"CCB и вызвать `xpt_done()`. Этот флаг заставляет подсистему CAM разморозить " +"очередь после обработки ошибки." + +#. 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 "" +"_CAM_AUTOSNS_VALID_ - если устройство вернуло состояние ошибки и флаг " +"CAM_DIS_AUTOSENSE не установлен в CCB, драйвер SIM должен автоматически " +"выполнить команду REQUEST SENSE, чтобы извлечь данные sense (расширенную " +"информацию об ошибке) из устройства. Если попытка была успешной, данные " +"sense должны быть сохранены в CCB, а этот флаг установлен." + +#. 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 "" +"_CAM_RELEASE_SIMQ_ - аналогично CAM_DEV_QFRZN, но используется в случае " +"возникновения проблем (или нехватки ресурсов) с самим SCSI-контроллером. В " +"этом случае все последующие запросы к контроллеру должны быть остановлены с " +"помощью `xpt_freeze_simq()`. Очередь контроллера будет возобновлена после " +"того, как драйвер SIM устранит нехватку и уведомит CAM, вернув некоторый CCB " +"с установленным этим флагом." + +#. 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 "" +"_CAM_SIM_QUEUED_ - этот флаг должен быть установлен, когда SIM помещает CCB " +"в свою очередь запросов (и снят, когда этот CCB извлекается из очереди перед " +"возвратом в CAM). В настоящее время этот флаг нигде не используется в коде " +"CAM, поэтому его назначение чисто диагностическое." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:325 +msgid "_CAM_QOS_VALID_ - The QOS data is now valid." +msgstr "_CAM_QOS_VALID_ - Данные QOS теперь действительны." + +#. 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 "" +"Функция `xxx_action()` не может находиться в состоянии ожидания, поэтому вся " +"синхронизация доступа к ресурсам должна выполняться с использованием SIM или " +"заморозки очереди устройств. Помимо упомянутых флагов, подсистема CAM " +"предоставляет функции `xpt_release_simq()` и `xpt_release_devq()` для " +"разморозки очередей напрямую, без передачи CCB в CAM." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:330 +msgid "The CCB header contains the following fields:" +msgstr "Заголовок CCB содержит следующие поля:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:332 +msgid "_path_ - path ID for the request" +msgstr "_path_ - идентификатор пути для запроса" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:333 +msgid "_target_id_ - target device ID for the request" +msgstr "_target_id_ - идентификатор целевого устройства для запроса" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:334 +msgid "_target_lun_ - LUN ID of the target device" +msgstr "_target_lun_ - идентификатор LUN целевого устройства" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:335 +msgid "_timeout_ - timeout interval for this command, in milliseconds" +msgstr "_timeout_ - интервал таймаута для этой команды, в миллисекундах" + +#. 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 "" +"_timeout_ch_ - удобное место для драйвера SIM, чтобы хранить обработчик " +"таймаута (сама подсистема CAM не делает никаких предположений о нём)" + +#. 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 "" +"_flags_ - различные биты информации о запросе spriv_ptr0, spriv_ptr1 — поля, " +"зарезервированные для приватного использования драйвером SIM (например, для " +"связи с очередями SIM или приватными блоками управления SIM); фактически они " +"существуют как объединения: spriv_ptr0 и spriv_ptr1 имеют тип (void *), " +"spriv_field0 и spriv_field1 имеют тип unsigned long, " +"sim_priv.entries[0].bytes и sim_priv.entries[1].bytes - это байтовые массивы " +"размера, согласованного с другими вариантами объединения, а sim_priv.bytes - " +"это один массив, вдвое большего размера." + +#. 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 "" +"Рекомендуемый способ использования приватных полей SIM в CCB — это " +"определить для них осмысленные имена и использовать эти осмысленные имена в " +"драйвере, например:" + +#. 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 "" +"#define ccb_some_meaningful_name sim_priv.entries[0].bytes\n" +"#define ccb_hcb spriv_ptr1 /* for hardware control block */\n" + +#. 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 "_XPT_SCSI_IO_ - выполнить транзакцию ввода-вывода" + +#. 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 "" +"Экземпляр \"struct ccb_scsiio csio\" объединения ccb используется для " +"передачи аргументов. Они включают:" + +#. 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 "_cdb_io_ - указатель на буфер команды SCSI или сам буфер" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:355 +msgid "_cdb_len_ - SCSI command length" +msgstr "_cdb_len_ - длина команды SCSI" + +#. 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 "" +"_data_ptr_ - указатель на буфер данных (усложняется, если используется " +"scatter/gather)" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:357 +msgid "_dxfer_len_ - length of the data to transfer" +msgstr "_dxfer_len_ - длина передаваемых данных" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:358 +msgid "_sglist_cnt_ - counter of the scatter/gather segments" +msgstr "_sglist_cnt_ - счетчик сегментов scatter/gather" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:359 +msgid "_scsi_status_ - place to return the SCSI status" +msgstr "_scsi_status_ - место для возврата статуса SCSI" + +#. 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 "" +"_sense_data_ - буфер для информации SCSI sense, если команда возвращает " +"ошибку (драйвер SIM должен автоматически выполнить команду REQUEST SENSE в " +"этом случае, если флаг CCB CAM_DIS_AUTOSENSE не установлен)" + +#. 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 "" +"_sense_len_ - длина этого буфера (если она окажется больше размера " +"sense_data, драйвер SIM должен без уведомления принять меньшее значение)" + +#. 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 "" +"_resid_, _sense_resid_ — если передача данных или SCSI sense вернула ошибку, " +"это счётчики остаточных (не переданных) данных. Они не кажутся особенно " +"значимыми, поэтому в случаях, когда их сложно вычислить (например, подсчёт " +"байтов в FIFO-буфере SCSI-контроллера), подойдёт и приблизительное значение. " +"Для успешно завершённой передачи они должны быть установлены в ноль." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:365 +msgid "_tag_action_ - the kind of tag to use:" +msgstr "_tag_action_ - тип используемого тега:" + +#. 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 "`CAM_TAG_ACTION_NONE` - не использовать теги для данной транзакции" + +#. 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 "" +"MSG_SIMPLE_Q_TAG, MSG_HEAD_OF_Q_TAG, MSG_ORDERED_Q_TAG — значение, " +"соответствующее указанному теговому сообщению (см. /sys/cam/scsi/" +"scsi_message.h); указывает только тип тега, значение тега должно быть " +"назначено самим драйвером SIM" + +#. 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 " struct ccb_scsiio *csio = &ccb->csio;\n" + +#. 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 "" +" if ((ccb_h->status & CAM_STATUS_MASK) != CAM_REQ_INPROG) {\n" +" xpt_done(ccb);\n" +" return;\n" +" }\n" + +#. 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 "" +" 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" + +#. 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 "" +"Затем выделяем все необходимые структуры данных (такие как зависящий от " +"карты блок управления оборудованием), которые нам нужны для обработки этого " +"запроса. Если мы не можем этого сделать, то замораживаем очередь SIM и " +"запоминаем, что у нас есть отложенная операция, возвращаем CCB обратно и " +"просим CAM поставить его в очередь снова. Позже, когда ресурсы станут " +"доступны, очередь SIM должна быть разморожена путём возврата CCB с " +"установленным битом `CAM_SIMQ_RELEASE` в его статусе. В противном случае, " +"если всё прошло успешно, связываем CCB с блоком управления оборудованием " +"(HCB) и помечаем его как поставленный в очередь." + +#. 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 " struct xxx_hcb *hcb = allocate_hcb(softc, unit, bus);\n" + +#. 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 "" +" 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" + +#. 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 "" +" hcb->ccb = ccb; ccb_h->ccb_hcb = (void *)hcb;\n" +" ccb_h->status |= CAM_SIM_QUEUED;\n" + +#. 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 "" +"Извлечь целевые данные из CCB в аппаратный блок управления. Проверить, " +"запрошено ли назначение тега, и если да, то сгенерировать уникальный тег и " +"построить сообщения тега SCSI. Драйвер SIM также отвечает за согласование с " +"устройствами для установки максимальной взаимно поддерживаемой ширины шины, " +"синхронной скорости и смещения." + +#. 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 "" +" 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" + +#. 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 "" +"Затем настройте команду SCSI. Хранилище команды может быть указано в CCB " +"различными способами, определяемыми флагами CCB. Буфер команды может " +"содержаться в CCB или указываться на него; в последнем случае указатель " +"может быть физическим или виртуальным. Поскольку оборудованию обычно " +"требуется физический адрес, мы всегда преобразуем адрес в физический, как " +"правило, используя API busdma." + +#. 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 "" +"В случае, если запрашивается физический адрес, допустимо вернуть CCB со " +"статусом `CAM_REQ_INVALID`, текущие драйверы так и делают. При необходимости " +"физический адрес также может быть преобразован или отображен обратно в " +"виртуальный, но с большими трудностями, поэтому мы этого не делаем." + +#. 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 "" +" 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" + +#. 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 "" +"Теперь настало время настроить данные. Опять же, хранилище данных может быть " +"указано в CCB различными интересными способами, определяемыми флагами CCB. " +"Сначала мы получаем направление передачи данных. Самый простой случай — если " +"нет данных для передачи:" + +#. 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 " int dir = (ccb_h->flags & CAM_DIR_MASK);\n" + +#. 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 "" +" if (dir == CAM_DIR_NONE)\n" +" goto end_data;\n" + +#. 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 "" +"Затем мы проверяем, находятся ли данные в одном фрагменте или в списке " +"scatter-gather, а также являются ли адреса физическими или виртуальными. " +"SCSI-контроллер может обрабатывать только ограниченное количество фрагментов " +"ограниченной длины. Если запрос превышает это ограничение, мы возвращаем " +"ошибку. Мы используем специальную функцию для возврата CCB, чтобы в одном " +"месте обрабатывать нехватку ресурсов HCB. Функции для добавления фрагментов " +"зависят от драйвера, и здесь мы оставляем их без детальной реализации. " +"Подробности о проблемах трансляции адресов см. в описании обработки SCSI-" +"команд (CDB). Если какая-то вариация слишком сложна или невозможна для " +"реализации с конкретной картой, допустимо вернуть статус `CAM_REQ_INVALID`. " +"На самом деле, похоже, что возможность scatter-gather нигде в коде CAM " +"сейчас не используется. Но как минимум случай с единичным неразделённым " +"виртуальным буфером должен быть реализован, так как он активно используется " +"CAM." + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:486 +#, no-wrap +msgid " int rv;\n" +msgstr " int rv;\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:488 +#, no-wrap +msgid " initialize_hcb_for_data(hcb);\n" +msgstr " initialize_hcb_for_data(hcb);\n" + +#. 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 "" +" 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" + +#. 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 "" +" 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" + +#. 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 "" +"Если отключение запрещено для этого CCB, мы передаем эту информацию в hcb:" + +#. 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 "" +" if (ccb_h->flags & CAM_DIS_DISCONNECT)\n" +" hcb_disable_disconnect(hcb);\n" + +#. 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 "" +"Если контроллер способен самостоятельно выполнять команду REQUEST SENSE, то " +"ему также следует передать значение флага CAM_DIS_AUTOSENSE, чтобы " +"предотвратить автоматическое выполнение REQUEST SENSE, если подсистема CAM " +"этого не требует." + +#. 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 "" +"Осталось только установить таймаут, передать наш hcb оборудованию и " +"вернуться, остальное будет сделано обработчиком прерывания (или обработчиком " +"таймаута)." + +#. 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 "" +" 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" + +#. 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 "И вот возможная реализация функции, возвращающей CCB:" + +#. 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 "" +" 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" + +#. 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 "" +" 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" + +#. 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 "_XPT_RESET_DEV_ - отправить устройству сообщение SCSI \"BUS DEVICE RESET\"" + +#. 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 "" +"В CCB не передаются данные, кроме заголовка, и наиболее интересным " +"аргументом в нём является target_id. В зависимости от аппаратного " +"обеспечения контроллера может быть создан аппаратный блок управления (как " +"для запроса XPT_SCSI_IO, см. описание запроса XPT_SCSI_IO) и отправлен " +"контроллеру, или SCSI-контроллер может быть немедленно запрограммирован на " +"отправку этого сообщения RESET устройству, или этот запрос может просто не " +"поддерживаться (и возвращать статус `CAM_REQ_INVALID`). Также при завершении " +"запроса все отключенные транзакции для этого целевого устройства должны быть " +"прерваны (вероятно, в процедуре прерывания)." + +#. 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 "_XPT_RESET_BUS_ - отправить сигнал RESET на шину SCSI" + +#. 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 "" +"В CCB не передаются аргументы, единственный интересный аргумент — это шина " +"SCSI, указанная структурой sim." + +#. 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 "" +"Минималистичная реализация могла бы пропустить SCSI-переговоры для всех " +"устройств на шине и вернуть статус CAM_REQ_CMP." + +#. 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 "" +"Правильная реализация дополнительно должна фактически сбросить шину SCSI " +"(возможно, также сбросить контроллер SCSI) и пометить все обрабатываемые " +"CCB, как находящиеся в аппаратной очереди, так и отключенные, как " +"завершенные со статусом CAM_SCSI_BUS_RESET. Например:" + +#. 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 "" +" int targ, lun;\n" +" struct xxx_hcb *h, *hh;\n" +" struct ccb_trans_settings neg;\n" +" struct cam_path *path;\n" + +#. 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 "" +" /* 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" + +#. 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 "" +" /* 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" + +#. 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 "" +" /* 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" + +#. 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 "" +" /* drop all disconnected CCBs and clean negotiations */\n" +" for (targ=0; targ <= OUR_MAX_SUPPORTED_TARGET; targ++) {\n" +" clean_negotiations(softc, targ);\n" + +#. 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 "" +" /* 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" + +#. 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 "" +" 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" + +#. 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 "" +" ccb->ccb_h.status = CAM_REQ_CMP;\n" +" xpt_done(ccb);\n" + +#. 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 "" +" /* report the event */\n" +" xpt_async(AC_BUS_RESET, softc->wpath, NULL);\n" +" return;\n" + +#. 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 "" +"Реализация сброса шины SCSI в виде функции может быть хорошей идеей, так как " +"она может быть повторно использована функцией таймаута в качестве последнего " +"средства, если что-то пойдёт не так." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:651 +#, no-wrap +msgid "_XPT_ABORT_ - abort the specified CCB" +msgstr "_XPT_ABORT_ - прервать указанный CCB" + +#. 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 "" +"Аргументы передаются в экземпляре \"struct ccb_abort cab\" объединения ccb. " +"Единственное поле аргумента в нём:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:657 +msgid "_abort_ccb_ - pointer to the CCB to be aborted" +msgstr "_abort_ccb_ — указатель на CCB, который необходимо прервать" + +#. 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 "" +"Если прерывание не поддерживается, просто верните статус CAM_UA_ABORT. Это " +"также простой способ минимальной реализации этого вызова — в любом случае " +"возвращать CAM_UA_ABORT." + +#. 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 "" +"Трудный путь — честно реализовать этот запрос. Сначала проверьте, что " +"прерывание применяется к SCSI-транзакции:" + +#. 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 "" +" struct ccb *abort_ccb;\n" +" abort_ccb = ccb->cab.abort_ccb;\n" + +#. 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 "" +" 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" + +#. 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 "" +"Затем необходимо найти этот CCB в нашей очереди. Это можно сделать, пройдясь " +"по списку всех наших блоков управления оборудованием в поисках связанного с " +"этим CCB:" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:682 +#, no-wrap +msgid " struct xxx_hcb *hcb, *h;\n" +msgstr " struct xxx_hcb *hcb, *h;\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:684 +#, no-wrap +msgid " hcb = NULL;\n" +msgstr " hcb = NULL;\n" + +#. 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 "" +" /* 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" + +#. 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 "" +" 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" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:704 +#, no-wrap +msgid " hcb=found_hcb;\n" +msgstr " hcb=found_hcb;\n" + +#. 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 "" +"Теперь мы рассмотрим текущее состояние обработки HCB. Он может находиться в " +"очереди, ожидая отправки на шину SCSI, передаваться в данный момент, быть " +"отключенным и ожидать результата команды, или фактически завершённым с точки " +"зрения аппаратуры, но ещё не отмеченным программным обеспечением, как " +"выполненный. Чтобы избежать состояний гонки с аппаратурой, мы помечаем HCB " +"как прерванный, так что если этот HCB вот-вот будет отправлен на шину SCSI, " +"контроллер SCSI увидит этот флаг и пропустит его." + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:713 +#, no-wrap +msgid " int hstatus;\n" +msgstr " int hstatus;\n" + +#. 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 "" +" /* 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" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:720 +#, no-wrap +msgid " abort_again:\n" +msgstr " abort_again:\n" + +#. 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 "" +" 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" + +#. 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 "" +"Если CCB передаётся в данный момент, мы хотели бы сигнализировать " +"контроллеру SCSI аппаратно-зависимым способом, что хотим прервать текущую " +"передачу. Контроллер SCSI установит сигнал SCSI ATTENTION, и когда целевое " +"устройство ответит на него, отправит сообщение ABORT. Мы также сбрасываем " +"таймаут, чтобы убедиться, что целевое устройство не засыпает навсегда. Если " +"команда не будет прервана в разумное время, например, за 10 секунд, " +"процедура таймаута продолжит работу и сбросит всю шину SCSI. Поскольку " +"команда будет прервана в разумные сроки, мы можем просто вернуть запрос на " +"прерывание как успешно выполненный и пометить прерванный CCB как прерванный " +"(но пока не помечать его как завершённый)." + +#. 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 "" +" 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" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:755 +#, no-wrap +msgid " break;\n" +msgstr " break;\n" + +#. 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 "" +"Если CCB находится в списке отключенных, то настроить его как запрос " +"прерывания и повторно поставить в начало аппаратной очереди. Сбросить " +"таймаут и сообщить о завершении запроса прерывания." + +#. 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 "" +" 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" + +#. 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 "" +"Вот и все, что касается запроса ABORT, хотя есть еще один момент. Поскольку " +"сообщение ABORT очищает все текущие транзакции на LUN, нам необходимо " +"пометить все остальные активные транзакции на этом LUN как прерванные. Это " +"должно быть выполнено в процедуре аппаратного прерывания после того, как " +"транзакция будет прервана." + +#. 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 "" +"Реализация прерывания CCB в виде функции может быть довольно хорошей идеей, " +"эта функция может быть повторно использована, если транзакция ввода-вывода " +"превысит время ожидания. Единственное различие будет в том, что для " +"транзакции с истекшим временем ожидания будет возвращён статус " +"CAM_CMD_TIMEOUT. Тогда код в case XPT_ABORT будет небольшим, например:" + +#. 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 "" +" case XPT_ABORT:\n" +" struct ccb *abort_ccb;\n" +" abort_ccb = ccb->cab.abort_ccb;\n" + +#. 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 "" +" 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" + +#. 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 "_XPT_SET_TRAN_SETTINGS_ - явно установить значения настроек передачи SCSI" + +#. 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 "" +"Аргументы передаются в экземпляре \"struct ccb_trans_setting cts\" " +"объединения ccb:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:808 +msgid "_valid_ - a bitmask showing which settings should be updated:" +msgstr "" +"_valid_ - битовая маска, показывающая, какие настройки должны быть обновлены:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:809 +msgid "_CCB_TRANS_SYNC_RATE_VALID_ - synchronous transfer rate" +msgstr "_CCB_TRANS_SYNC_RATE_VALID_ - скорость синхронной передачи" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:810 +msgid "_CCB_TRANS_SYNC_OFFSET_VALID_ - synchronous offset" +msgstr "_CCB_TRANS_SYNC_OFFSET_VALID_ - синхронное смещение" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:811 +msgid "_CCB_TRANS_BUS_WIDTH_VALID_ - bus width" +msgstr "_CCB_TRANS_BUS_WIDTH_VALID_ - ширина шины" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:812 +msgid "_CCB_TRANS_DISC_VALID_ - set enable/disable disconnection" +msgstr "_CCB_TRANS_DISC_VALID_ - установить разрешение/запрет отключения" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:813 +msgid "_CCB_TRANS_TQ_VALID_ - set enable/disable tagged queuing" +msgstr "_CCB_TRANS_TQ_VALID_ - установить разрешение/запрет очередей с тегами" + +#. 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 "" +"_flags_ - состоит из двух частей: бинарных аргументов и идентификации " +"подопераций. Бинарные аргументы:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:816 +msgid "_CCB_TRANS_DISC_ENB_ - enable disconnection" +msgstr "_CCB_TRANS_DISC_ENB_ - разрешить отключение" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:817 +msgid "_CCB_TRANS_TAG_ENB_ - enable tagged queuing" +msgstr "_CCB_TRANS_TAG_ENB_ - разрешить тегированную очередь" + +#. 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 "_CCB_TRANS_CURRENT_SETTINGS_ - изменить текущие параметры согласования" + +#. 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 "" +"_CCB_TRANS_USER_SETTINGS_ - сохранять желаемые пользовательские значения " +"sync_period, sync_offset - самоочевидные параметры; если sync_offset==0, то " +"запрашивается асинхронный режим bus_width - ширина шины в битах (не в байтах)" + +#. 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 "" +"Поддерживаются два набора согласованных параметров: пользовательские " +"настройки и текущие настройки. Пользовательские настройки не так часто " +"используются в драйверах SIM, это в основном просто область памяти, где " +"верхние уровни могут сохранять (и позже извлекать) свои представления о " +"параметрах. Установка пользовательских параметров не вызывает повторного " +"согласования скоростей передачи. Однако, когда SCSI-контроллер выполняет " +"согласование, он никогда не должен устанавливать значения выше " +"пользовательских параметров, так что они по сути являются верхней границей." + +#. 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 "" +"Текущие настройки, как следует из названия, являются текущими. Их изменение " +"означает, что параметры должны быть повторно согласованы при следующей " +"передаче. Опять же, эти «новые текущие настройки» не предназначены для " +"принудительного применения к устройству, они лишь используются в качестве " +"начального шага переговоров. Кроме того, они должны быть ограничены " +"реальными возможностями SCSI-контроллера: например, если SCSI-контроллер " +"имеет 8-битную шину, а запрос требует установки 16-битных передач, этот " +"параметр должен быть тихо усечён до 8-битных передач перед отправкой на " +"устройство." + +#. 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 "" +"Один нюанс заключается в том, что ширина шины и синхронные параметры " +"относятся к цели, тогда как параметры отключения и включения тегов относятся " +"к логическому устройству LUN." + +#. 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 "" +"Рекомендуемая реализация заключается в хранении 3 наборов согласованных " +"параметров (ширина шины и синхронная передача):" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:836 +msgid "_user_ - the user set, as above" +msgstr "_user_ - пользовательский набор, как указано выше" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:837 +msgid "_current_ - those actually in effect" +msgstr "_current_ - тот, который фактически действуют" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:838 +msgid "_goal_ - those requested by setting of the \"current\" parameters" +msgstr "" +"_goal_ - тот набор, который запрошен для установки параметров в качестве " +"\"текущих\"" + +#. 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 "" +" struct ccb_trans_settings *cts;\n" +" int targ, lun;\n" +" int flags;\n" + +#. 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 "" +" 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" + +#. 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 "" +" 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" + +#. 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 "" +" 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" + +#. 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 "" +"Затем, когда следующий запрос ввода-вывода будет обработан, он проверит, " +"нужно ли повторное согласование, например, вызовом функции " +"target_negotiated(hcb). Это может быть реализовано следующим образом:" + +#. 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 "" +" int\n" +" target_negotiated(struct xxx_hcb *hcb)\n" +" {\n" +" struct softc *softc = hcb->softc;\n" +" int targ = hcb->targ;\n" + +#. 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 "" +" 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" + +#. 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 "" +"После пересогласования значений полученные значения должны быть присвоены " +"как текущим, так и целевым параметрам, чтобы для будущих операций ввода-" +"вывода текущие и целевые параметры совпадали, и функция " +"`target_negotiated()` возвращала TRUE. При инициализации карты (в " +"`xxx_attach()`) текущие параметры согласования должны быть инициализированы " +"узким асинхронным режимом, а целевые и текущие значения должны быть " +"инициализированы максимальными значениями, поддерживаемыми контроллером." + +#. 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 "_XPT_GET_TRAN_SETTINGS_ - получить значения настроек передачи SCSI" + +#. 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 "" +"Эта операция является обратной XPT_SET_TRAN_SETTINGS. Заполните экземпляр " +"CCB \"struct ccb_trans_setting cts\" данными, запрошенными флагами " +"CCB_TRANS_CURRENT_SETTINGS или CCB_TRANS_USER_SETTINGS (если установлены " +"оба, существующие драйверы возвращают текущие настройки). Установите все " +"биты в поле valid." + +#. 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 "_XPT_CALC_GEOMETRY_ - вычислить логическую (BIOS) геометрию диска" + +#. 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 "" +"Аргументы передаются в экземпляре \"struct ccb_calc_geometry ccg\" " +"объединения ccb:" + +#. 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 "" +"_block_size_ - вход, размер блока (также известный как сектор) в байтах" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:927 +msgid "_volume_size_ - input, volume size in bytes" +msgstr "_volume_size_ - вход, размер тома в байтах" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:928 +msgid "_cylinders_ - output, logical cylinders" +msgstr "_cylinders_ - выход, логические цилиндры" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:929 +msgid "_heads_ - output, logical heads" +msgstr "_heads_ - выход, логические головки" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:930 +msgid "_secs_per_track_ - output, logical sectors per track" +msgstr "_secs_per_track_ - выход, логических секторов на дорожку" + +#. 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 "" +"Если возвращённая геометрия значительно отличается от той, которую " +"предполагает BIOS SCSI-контроллера, и диск на этом SCSI-контроллере " +"используется как загрузочный, система может не загрузиться. Типичный пример " +"расчёта, взятый из драйвера `aic7xxx`, выглядит следующим образом:" + +#. 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 "" +" struct ccb_calc_geometry *ccg;\n" +" u_int32_t size_mb;\n" +" u_int32_t secs_per_cylinder;\n" +" int extended;\n" + +#. 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 "" +" 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" + +#. 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 "" +" 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" + +#. 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 "" +"Это дает общее представление, точный расчет зависит от особенностей " +"конкретной BIOS. Если BIOS не предоставляет возможности установить флаг " +"\"расширенной трансляции\" в EEPROM, этот флаг обычно следует считать равным " +"1. Другие популярные геометрии:" + +#. 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 "" +" 128 heads, 63 sectors - Symbios controllers\n" +" 16 heads, 63 sectors - old controllers\n" + +#. 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 "" +"Некоторые системные BIOS и SCSI BIOS конфликтуют друг с другом с переменным " +"успехом. Например, комбинация Symbios 875/895 SCSI и Phoenix BIOS может " +"выдавать геометрию 128/63 после включения питания и 255/63 после жесткого " +"сброса или мягкой перезагрузки." + +#. 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 "_XPT_PATH_INQ_ - запрос пути, другими словами, получение свойств драйвера SIM и контроллера SCSI (также известного как HBA - Host Bus Adapter)" + +#. 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 "" +"Свойства возвращаются в экземпляре \"struct ccb_pathinq cpi\" объединения " +"ccb:" + +#. 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 "" +"`version_num` - номер версии драйвера SIM, в настоящее время все драйверы " +"используют 1" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:978 +msgid "hba_inquiry - bitmask of features supported by the controller:" +msgstr "hba_inquiry - битовая маска функций, поддерживаемых контроллером:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:979 +msgid "PI_MDP_ABLE - supports MDP message (something from SCSI3?)" +msgstr "PI_MDP_ABLE - поддерживает сообщение MDP (что-то из SCSI3?)" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:980 +msgid "PI_WIDE_32 - supports 32 bit wide SCSI" +msgstr "PI_WIDE_32 — поддерживает 32-битную широкую SCSI" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:981 +msgid "PI_WIDE_16 - supports 16 bit wide SCSI" +msgstr "PI_WIDE_16 — поддерживает 16-битную широкую SCSI" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:982 +msgid "PI_SDTR_ABLE - can negotiate synchronous transfer rate" +msgstr "PI_SDTR_ABLE - может согласовать синхронную скорость передачи" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:983 +msgid "PI_LINKED_CDB - supports linked commands" +msgstr "PI_LINKED_CDB - поддерживает связанные команды" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:984 +msgid "PI_TAG_ABLE - supports tagged commands" +msgstr "PI_TAG_ABLE - поддерживает помеченные команды" + +#. 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 "" +"PI_SOFT_RST — поддерживает альтернативу мягкого сброса (жесткий сброс и " +"мягкий сброс являются взаимоисключающими в пределах шины SCSI)" + +#. 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 "" +"target_sprt - флаги поддержки целевого режима, 0 если не поддерживается" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:987 +msgid "hba_misc - miscellaneous controller features:" +msgstr "hba_misc - различные функции контроллера:" + +#. 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 "PIM_SCANHILO - сканирование шины от высокого ID к низкому ID" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:989 +msgid "PIM_NOREMOVE - removable devices not included in scan" +msgstr "PIM_NOREMOVE - съемные устройства не включены в сканирование" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:990 +msgid "PIM_NOINITIATOR - initiator role not supported" +msgstr "PIM_NOINITIATOR - роль инициатора не поддерживается" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:991 +msgid "PIM_NOBUSRESET - user has disabled initial BUS RESET" +msgstr "PIM_NOBUSRESET - пользователь отключил начальный BUS RESET" + +#. 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 "" +"hba_eng_cnt - загадочное количество движков HBA, что-то связанное со " +"сжатием, в настоящее время всегда устанавливается в 0" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:993 +msgid "vuhba_flags - vendor-unique flags, unused now" +msgstr "" +"vuhba_flags - уникальные флаги производителя, в настоящее время не " +"используются" + +#. 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 "" +"max_target - максимальный поддерживаемый идентификатор целевого устройства " +"(7 для 8-битной шины, 15 для 16-битной шины, 127 для Fibre Channel)" + +#. 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 "" +"max_lun - максимально поддерживаемый идентификатор LUN (7 для старых SCSI-" +"контроллеров, 63 для новых)" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:996 +msgid "async_flags - bitmask of installed Async handler, unused now" +msgstr "" +"async_flags - битовая маска установленных обработчиков Async, в настоящее " +"время не используется" + +#. 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 "" +"hpath_id - наивысший Path ID в подсистеме, в настоящее время не используется" + +#. 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 "unit_number - номер контроллера, cam_sim_unit(sim)" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:999 +msgid "bus_id - the bus number, cam_sim_bus(sim)" +msgstr "bus_id - номер шины, cam_sim_bus(sim)" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1000 +msgid "initiator_id - the SCSI ID of the controller itself" +msgstr "initiator_id - SCSI ID самого контроллера" + +#. 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 "" +"base_transfer_speed - номинальная скорость передачи в КБ/с для асинхронных " +"узкополосных передач, равна 3300 для SCSI" + +#. 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 "" +"sim_vid - идентификатор производителя драйвера SIM, строка с нулевым " +"окончанием максимальной длины SIM_IDLEN, включая завершающий ноль" + +#. 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 "" +"hba_vid - идентификатор производителя SCSI-контроллера, строка с нулевым " +"окончанием максимальной длины HBA_IDLEN, включая завершающий ноль" + +#. 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 "" +"dev_name - имя драйвера устройства, строка с нулевым окончанием максимальной " +"длины DEV_IDLEN, включая завершающий ноль, эквивалентно cam_sim_name(sim)" + +#. 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 "" +"Рекомендуемый способ установки строковых полей — использование strncpy, " +"например:" + +#. 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 " strncpy(cpi->dev_name, cam_sim_name(sim), DEV_IDLEN);\n" + +#. 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 "" +"После установки значений установите статус в CAM_REQ_CMP и пометьте CCB как " +"завершённый." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1015 +#, no-wrap +msgid "Polling xxx_poll" +msgstr "Опрос xxx_poll" + +#. 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 "" +"Функция poll используется для имитации прерываний, когда подсистема " +"прерываний не функционирует (например, когда система аварийно завершила " +"работу и создает дамп памяти). Подсистема CAM устанавливает соответствующий " +"уровень прерывания перед вызовом процедуры poll. Таким образом, все, что ей " +"нужно сделать, — это вызвать процедуру прерывания (или наоборот, процедура " +"poll может выполнять реальные действия, а процедура прерывания просто " +"вызывает процедуру poll). Зачем тогда нужна отдельная функция? Это связано с " +"различными соглашениями о вызовах. Процедура `xxx_poll` получает указатель " +"на структуру cam_sim в качестве аргумента, в то время как процедура " +"прерывания PCI по общему соглашению получает указатель на структуру " +"`xxx_softc`, а процедура прерывания ISA получает только номер устройства. " +"Таким образом, процедура poll обычно выглядит следующим образом:" + +#. 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 "" +"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" + +#. 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 "" +"static void\n" +"xxx_poll(struct cam_sim *sim)\n" +"{\n" +" xxx_intr(cam_sim_unit(sim)); /* for ISA device */\n" +"}\n" + +#. 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 "" +"Если была настроена асинхронная callback-функция для события, то callback-" +"функция должна быть определена." + +#. 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 "" +"static void\n" +"ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)\n" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1062 +msgid "callback_arg - the value supplied when registering the callback" +msgstr "callback_arg - значение, переданное при регистрации callback" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1063 +msgid "code - identifies the type of event" +msgstr "code - определяет тип события" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1064 +msgid "path - identifies the devices to which the event applies" +msgstr "path - определяет устройства, к которым применяется событие" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1065 +msgid "arg - event-specific argument" +msgstr "arg - аргумент, специфичный для события" + +#. 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 "" +"Реализация для одного типа события, AC_LOST_DEVICE, выглядит следующим " +"образом:" + +#. 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 "" +" struct xxx_softc *softc;\n" +" struct cam_sim *sim;\n" +" int targ;\n" +" struct ccb_trans_settings neg;\n" + +#. 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 "" +" 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" + +#. 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 "" +"Точный тип процедуры прерывания зависит от типа периферийной шины (PCI, ISA " +"и так далее), к которой подключен SCSI-контроллер." + +#. 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 "" +"Прерывания в драйверах SIM выполняются на уровне прерывания splcam. Поэтому " +"в драйвере следует использовать `splcam()` для синхронизации между " +"обработчиком прерывания и остальной частью драйвера (для драйверов, " +"учитывающих многопроцессорность, ситуация становится ещё сложнее, но здесь " +"мы этот случай не рассматриваем). Псевдокод в этом документе беззаботно " +"игнорирует проблемы синхронизации. Реальный код так делать не должен. " +"Простейший подход — установить `splcam()` при входе в другие функции и " +"сбросить при выходе, защищая их одной большой критической секцией. Чтобы " +"гарантировать восстановление уровня прерывания, можно определить обёрточную " +"функцию, например:" + +#. 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 "" +" 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" + +#. 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 "" +" static void\n" +" xxx_action1(struct cam_sim *sim, union ccb *ccb)\n" +" {\n" +" ... process the request ...\n" +" }\n" + +#. 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 "" +"Этот подход прост и надежен, но проблема в том, что прерывания могут " +"блокироваться на относительно долгое время, что негативно скажется на " +"производительности системы. С другой стороны, функции семейства `spl()` " +"имеют довольно высокие накладные расходы, поэтому большое количество мелких " +"критических секций также может быть нежелательным." + +#. 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 "" +"Сначала проверяем, было ли на шине событие SCSI сброса (вероятно, вызванное " +"другим SCSI-контроллером на той же SCSI-шине). Если это так, мы отменяем все " +"поставленные в очередь и отключенные запросы, сообщаем о событиях и повторно " +"инициализируем наш SCSI-контроллер. Важно, чтобы во время этой инициализации " +"контроллер не инициировал ещё один сброс, иначе два контроллера на одной " +"SCSI-шине могут бесконечно обмениваться сбросами. Случай фатальной ошибки/" +"зависания контроллера может быть обработан в том же месте, но, вероятно, " +"также потребуется отправка сигнала RESET на SCSI-шину для сброса состояния " +"соединений с SCSI-устройствами." + +#. 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 "" +" int fatal=0;\n" +" struct ccb_trans_settings neg;\n" +" struct cam_path *path;\n" + +#. 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 "" +" if (detected_scsi_reset(softc)\n" +" || (fatal = detected_fatal_controller_error(softc))) {\n" +" int targ, lun;\n" +" struct xxx_hcb *h, *hh;\n" + +#. 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 "" +" /* 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" + +#. 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 "" +" /* 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" + +#. 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 "" +" /* drop all disconnected CCBs and clean negotiations */\n" +" for (targ=0; targ <= OUR_MAX_SUPPORTED_TARGET; targ++) {\n" +" clean_negotiations(softc, targ);\n" + +#. 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 "" +" /* 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" + +#. 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 "" +" 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" + +#. 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 "" +" /* report the event */\n" +" xpt_async(AC_BUS_RESET, softc->wpath, NULL);\n" + +#. 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 "" +" /* 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" + +#. 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 "" +"Если прерывание не вызвано условием, общим для всего контроллера, то, " +"вероятно, что-то произошло с текущим блоком управления аппаратным " +"обеспечением. В зависимости от оборудования могут быть и другие события, не " +"связанные с HCB, но мы их здесь не рассматриваем. Затем мы анализируем, что " +"произошло с этим HCB:" + +#. 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 "" +" 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" + +#. 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 "" +" 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" + +#. 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 "" +" targ = hcb->target;\n" +" hcb_status = get_status_of_current_hcb(softc);\n" + +#. 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 "" +"Сначала мы проверяем, завершился ли HCB, и если да, то проверяем " +"возвращённый статус SCSI." + +#. 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 "" +" if (hcb_status == COMPLETED) {\n" +" scsi_status = get_completion_status(hcb);\n" + +#. 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 "" +"Затем проверьте, связан ли этот статус с командой REQUEST SENSE, и если да, " +"обработайте его простым способом." + +#. 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 "" +" 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" + +#. 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 "" +"Иначе сама команда завершена, уделяйте больше внимания деталям. Если " +"автоопределение не отключено для этого CCB и команда завершилась неудачно с " +"данными состояния, выполните команду REQUEST SENSE для получения этих данных." + +#. 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 "" +" hcb->ccb->csio.scsi_status = scsi_status;\n" +" calculate_residue(hcb);\n" + +#. 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 "" +" 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" + +#. 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 "" +"Типичным примером могут быть события согласования: сообщения согласования, " +"полученные от цели SCSI (в ответ на нашу попытку согласования или по " +"инициативе цели), или если цель не может согласовать (отклоняет наши " +"сообщения согласования или не отвечает на них)." + +#. 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 "" +" 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" + +#. 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 "" +" 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" + +#. 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 "" +" /* 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" + +#. 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 "" +" wd = get_target_bus_width_request(softc);\n" +" wd = min (wd, OUR_BUS_WIDTH);\n" +" wd = min (wd, softc->user_bus_width[targ]);\n" + +#. 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 "" +" 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" + +#. 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 "" +" /* 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" + +#. 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 "" +" if (hcb->flags & DOING_AUTOSENSE)\n" +" goto autosense_failed;\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1341 +#, no-wrap +msgid " switch (hcb_status) {\n" +msgstr " switch (hcb_status) {\n" + +#. 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 "" +"Следующее событие, которое мы рассматриваем, — это неожиданное отключение. " +"Оно считается нормальным после сообщения ABORT или BUS DEVICE RESET и " +"аномальным в остальных случаях." + +#. 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 "" +" 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" + +#. 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 "" +" /* reset affects all commands on that target, so\n" +" * mark all disconnected HCBs on that target+LUN as reset\n" +" */\n" + +#. 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 "" +" 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" + +#. 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 "" +" /* send event */\n" +" xpt_async(AC_SENT_BDR, hcb->ccb->ccb_h.path_id, NULL);\n" + +#. 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 "" +" /* 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" + +#. 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 "" +"Если цель отказывается принимать теги, мы уведомляем CAM об этом и " +"возвращаем все команды для этого LUN:" + +#. 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 "" +" 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" + +#. 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 "" +" 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" + +#. 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 "" +"Затем мы проверяем ряд других условий, при этом обработка в основном " +"ограничивается установкой статуса CCB:" + +#. 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 "" +" 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" + +#. 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 "" +" if (hcb->ccb->ccb_h.status & CAM_DEV_QFRZN) {\n" +" /* freeze the queue */\n" +" xpt_freeze_devq(ccb->ccb_h.path, /*count*/1);\n" + +#. 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 " /* re-queue all commands for this target/LUN back to CAM */\n" + +#. 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 "" +" for (h = softc->first_queued_hcb; h != NULL; h = hh) {\n" +" hh = h->next;\n" + +#. 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 "" +" 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" + +#. 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 "" +"При выполнении запроса ввода-вывода может произойти множество ошибок. " +"Причина ошибки может быть указана в статусе CCB с большим количеством " +"деталей. Примеры использования разбросаны по всему документу. Для полноты " +"изложения приведём сводку рекомендуемых действий при типичных ошибках:" + +#. 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 "" +"_CAM_RESRC_UNAVAIL_ — некоторый ресурс временно недоступен, и драйвер SIM не " +"может сгенерировать событие, когда он станет доступен. Примером такого " +"ресурса может быть некоторый внутренний аппаратный ресурс контроллера, для " +"которого контроллер не генерирует прерывание при его доступности." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1468 +msgid "_CAM_UNCOR_PARITY_ - unrecovered parity error occurred" +msgstr "_CAM_UNCOR_PARITY_ - произошла неисправимая ошибка четности" + +#. 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 "" +"_CAM_DATA_RUN_ERR_ - переполнение данных или неожиданная фаза данных " +"(направление передачи не соответствует указанному в CAM_DIR_MASK) или " +"нечётная длина передачи для широкой передачи" + +#. 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 "_CAM_SEL_TIMEOUT_ - произошел таймаут выбора (цель не отвечает)" + +#. 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 "" +"_CAM_CMD_TIMEOUT_ - произошло превышение времени ожидания команды (сработала " +"функция таймаута)" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1472 +msgid "_CAM_SCSI_STATUS_ERROR_ - the device returned error" +msgstr "_CAM_SCSI_STATUS_ERROR_ - устройство вернуло ошибку" + +#. 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 "" +"_CAM_AUTOSENSE_FAIL_ - устройство вернуло ошибку и команда REQUEST SENSE " +"завершилась неудачно" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1474 +msgid "_CAM_MSG_REJECT_REC_ - MESSAGE REJECT message was received" +msgstr "_CAM_MSG_REJECT_REC_ - получено сообщение MESSAGE REJECT" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1475 +msgid "_CAM_SCSI_BUS_RESET_ - received SCSI bus reset" +msgstr "_CAM_SCSI_BUS_RESET_ - получен сброс шины SCSI" + +#. 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 "" +"_CAM_REQ_CMP_ERR_ - произошла «невозможная» фаза SCSI или что-то столь же " +"странное, либо это просто общая ошибка, если дополнительная информация " +"недоступна" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1477 +msgid "_CAM_UNEXP_BUSFREE_ - unexpected disconnect occurred" +msgstr "_CAM_UNEXP_BUSFREE_ - произошло неожиданное отключение" + +#. 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 "" +"_CAM_BDR_SENT_ - Сообщение BUS DEVICE RESET было отправлено целевому " +"устройству" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/scsi/_index.adoc:1479 +msgid "_CAM_UNREC_HBA_ERROR_ - unrecoverable Host Bus Adapter Error" +msgstr "_CAM_UNREC_HBA_ERROR_ - невосстановимая ошибка адаптера шины хоста" + +#. 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 "_CAM_REQ_TOO_BIG_ - запрос слишком велик для данного контроллера" + +#. 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 "" +"_CAM_REQUEUE_REQ_ - этот запрос должен быть повторно поставлен в очередь для " +"сохранения порядка транзакций. Обычно это происходит, когда SIM обнаруживает " +"ошибку, которая должна заморозить очередь, и необходимо поместить другие " +"запросы в очереди для цели на уровне SIM обратно в очередь XPT. Типичными " +"случаями таких ошибок являются тайм-ауты выбора, тайм-ауты команд и другие " +"подобные условия. В таких случаях проблемная команда возвращает статус, " +"указывающий на ошибку, а другие команды, которые ещё не были отправлены на " +"шину, повторно ставятся в очередь." + +#. 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 "" +"_CAM_LUN_INVALID_ - идентификатор LUN в запросе не поддерживается " +"контроллером SCSI" + +#. 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 "" +"_CAM_TID_INVALID_ - идентификатор целевого устройства в запросе не " +"поддерживается контроллером SCSI" + +#. 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 "" +"Когда время ожидания для HCB истекает, этот запрос должен быть прерван, как " +"и в случае с запросом XPT_ABORT. Единственное отличие заключается в том, что " +"возвращаемый статус прерванного запроса должен быть CAM_CMD_TIMEOUT вместо " +"CAM_REQ_ABORTED (вот почему реализацию прерывания лучше сделать в виде " +"функции). Но есть ещё одна возможная проблема: что если сам запрос на " +"прерывание зависнет? В этом случае шина SCSI должна быть сброшена, как и при " +"запросе XPT_RESET_BUS (и идея о реализации этого в виде функции, вызываемой " +"из обоих мест, применима и здесь). Также мы должны сбросить всю шину SCSI, " +"если запрос на сброс устройства завис. В итоге функция обработки таймаута " +"будет выглядеть следующим образом:" + +#. 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 "" +"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" + +#. 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 "" +" softc = hcb->softc;\n" +" ccb_h = &hcb->ccb->ccb_h;\n" + +#. 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 "" +" 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" + +#. 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 "" +"Когда мы прерываем запрос, все остальные отключенные запросы к тому же " +"целевому устройству/LUN также прерываются. Возникает вопрос: следует ли " +"возвращать их со статусом CAM_REQ_ABORTED или CAM_CMD_TIMEOUT? Текущие " +"драйверы используют CAM_CMD_TIMEOUT. Это кажется логичным, потому что если " +"один запрос превысил время ожидания, то, вероятно, с устройством происходит " +"что-то действительно плохое, и если их не трогать, они бы сами превысили " +"время ожидания." diff --git a/documentation/content/ru/books/arch-handbook/smp/_index.adoc b/documentation/content/ru/books/arch-handbook/smp/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/smp/_index.adoc @@ -0,0 +1,360 @@ +--- +description: 'Документ по архитектуре SMPng' +next: books/arch-handbook/partii +params: + path: /books/arch-handbook/smp/ +prev: books/arch-handbook/vm +showBookMenu: true +tags: ["SMPng", "introduction", "locks"] +title: 'Глава 8. Документ по архитектуре SMPng' +weight: 9 +--- + +[[smp]] += Документ по архитектуре SMPng +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 8 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[smp-intro]] +== Введение + +В этом документе представлены текущая архитектура и реализация SMPng. Сначала вводятся основные примитивы и инструменты. Затем излагается общая архитектура модели синхронизации и выполнения ядра FreeBSD. Далее обсуждаются стратегии блокировок для конкретных подсистем, описывающие подходы к внедрению детализированной синхронизации и параллелизма для каждой подсистемы. В заключение приводятся подробные заметки по реализации, объясняющие выбор проектных решений и информирующие читателя о важных последствиях использования конкретных примитивов. + +Этот документ находится в стадии разработки и будет обновляться в соответствии с текущими проектированием и реализацией, связанными с проектом SMPng. Многие разделы в настоящее время существуют только в виде набросков, но будут дополняться по мере продвижения работы. Обновления или предложения по документу могут быть направлены редакторам документа. + +Цель SMPng — обеспечить параллелизм в ядре. Ядро представляет собой одну довольно большую и сложную программу. Чтобы сделать ядро многопоточным, мы используем те же инструменты, что и для многопоточности других программ. К ним относятся мьютексы, разделяемые/монопольные блокировки, семафоры и условные переменные. Для определений этих и других терминов, связанных с SMP, см. раздел crossref:smp[smp-glossary, Глоссарий] в этой статье. + +[[smp-lock-fundamentals]] +== Основные инструменты и основы блокировки + +=== Атомарные инструкции и барьеры памяти + +Можно найти много описаний барьеров памяти и атомарных инструкций, поэтому в этом разделе не будет много деталей. Проще говоря, нельзя читать переменные без блокировки, если блокировка используется для защиты записи в эту переменную. Это становится очевидным, если учесть, что барьеры памяти лишь определяют относительный порядок операций с памятью; они не дают никаких гарантий относительно времени выполнения этих операций. То есть, барьер памяти не принуждает к сбросу содержимого локального кеша или буфера записи процессора. Вместо этого, барьер памяти при освобождении блокировки просто гарантирует, что все записи в защищённые данные будут видны другим процессорам или устройствам, если видна запись, освобождающая блокировку. Процессор может хранить эти данные в своём кеше или буфере записи сколько угодно долго. Однако, если другой процессор выполняет атомарную инструкцию над тем же данным, первый процессор должен гарантировать, что обновлённое значение будет видно второму процессору, наряду с любыми другими операциями, которые могут потребоваться согласно барьерам памяти. + +Например, предполагая простую модель, в которой данные считаются видимыми, когда они находятся в основной памяти (или в глобальном кеше), когда начинается выполнение атомарной инструкции на одном процессоре, буферы записи и кеши других процессоров должны выполнить все записи в ту же строку кеша вместе с любыми ожидающими операциями за барьером памяти. + +Это требует особой осторожности при использовании элемента, защищённого атомарными инструкциями. Например, в реализации мьютекса сна мы должны использовать `atomic_cmpset` вместо `atomic_set` для установки бита `MTX_CONTESTED`. Причина в том, что мы считываем значение `mtx_lock` в переменную и затем принимаем решение на основе этого чтения. Однако значение, которое мы ранее прочитали, может быть устаревшим или измениться, пока мы принимаем решение. Таким образом, когда выполняется `atomic_set`, это может привести к установке бита на другом значении, отличном от того, на котором мы основывали своё решение. Поэтому мы должны использовать `atomic_cmpset`, чтобы установить значение только в том случае, если значение, на котором мы приняли решение, актуально и действительно. + +Наконец, атомарные инструкции позволяют обновить или прочитать только один элемент. Если необходимо атомарно обновить несколько элементов, вместо этого следует использовать блокировку. Например, если требуется прочитать два счётчика и получить их значения, согласованные друг с другом, то эти счётчики должны быть защищены блокировкой, а не отдельными атомарными инструкциями. + +=== Блокировки на чтение и блокировки на запись + +Блокировки на чтение не требуют такой же строгости, как блокировки на запись. Оба типа блокировок должны гарантировать, что данные, к которым они обращаются, не устарели. Однако запись требует монопольного доступа. Несколько потоков могут безопасно читать значение. Использование разных типов блокировок для чтения и записи может быть реализовано несколькими способами. + +Во-первых, блокировки sx могут использоваться таким образом: монопольная блокировка при записи и разделяемая блокировка при чтении. Этот метод достаточно прост. + +Второй метод несколько менее очевиден. Вы можете защитить данные несколькими блокировками. Для чтения данных достаточно получить блокировку на чтение одной из блокировок. Однако для записи данных необходимо получить блокировку на запись всех блокировок. Это может сделать запись довольно затратной, но может быть полезно, когда данные доступны различными способами. Например, указатель на родительский процесс защищён как `proctree_lock` sx-блокировкой, так и мьютексом процесса. Иногда блокировка процесса удобнее, так как мы просто проверяем, кто является родителем уже заблокированного процесса. Однако в других случаях, таких как `inferior`, необходимо обходить дерево процессов через указатели на родителя, и блокировка каждого процесса была бы слишком затратной, а также сложной для гарантии того, что проверяемое условие остаётся верным как во время проверки, так и при выполнении действий, основанных на этой проверке. + +=== Условия и результаты блокировки + +Если вам нужна блокировка для проверки состояния переменной, чтобы можно было выполнить действие на основе прочитанного состояния, вы не можете просто удерживать блокировку во время чтения переменной, а затем снять блокировку перед выполнением действия на основе прочитанного значения. Как только вы снимаете блокировку, переменная может измениться, что сделает ваше решение недействительным. Таким образом, вы должны удерживать блокировку как во время чтения переменной, так и во время выполнения действия в результате проверки. + +[[smp-design]] +== Общая Архитектура и Дизайн + +=== Обработка прерываний + +Следуя примеру нескольких других многопоточных ядер UNIX(R), FreeBSD реализрвала обработчики прерываний, предоставив им собственный контекст потока. Предоставление контекста для обработчиков прерываний позволяет им блокироваться на блокировках. Однако, чтобы избежать задержек, потоки обработки прерываний выполняются с приоритетом реального времени в ядре. Таким образом, обработчики прерываний не должны выполняться слишком долго, чтобы не лишать ресурсов другие потоки ядра. Кроме того, поскольку несколько обработчиков могут использовать один поток прерываний, обработчики прерываний не должны переходить в режим сна или использовать блокировки, допускающие сон, чтобы не лишать ресурсов другие обработчики прерываний. + +Текущие потоки обработки прерываний в FreeBSD называются тяжеловесными потоками обработки прерываний. Они получили такое название, потому что переключение на поток обработки прерывания включает в себя полное переключение контекста. В первоначальной реализации ядро не было вытесняющим, поэтому прерывания, которые прерывали поток ядра, должны были ждать, пока поток ядра не заблокируется или не вернётся в пользовательское пространство, прежде чем у них появится возможность выполниться. + +Для решения проблем с задержками ядро FreeBSD стало вытесняющим. В настоящее время вытеснение потока ядра происходит только при освобождении мьютекса сна или при поступлении прерывания. Однако планируется сделать ядро FreeBSD полностью вытесняющим, как описано ниже. + +Не все обработчики прерываний выполняются в контексте потока. Вместо этого, некоторые обработчики выполняются непосредственно в основном контексте прерывания. Эти обработчики прерываний в настоящее время ошибочно называются "быстрыми" обработчиками прерываний, поскольку для их обозначения применяется флаг `INTR_FAST`, использовавшийся в более ранних версиях ядра. Единственные прерывания, которые в настоящее время используют такие обработчики прерываний, — это прерывания от часов и последовательных устройств ввода-вывода. Поскольку эти обработчики не имеют собственного контекста, они не могут захватывать блокирующие блокировки и, следовательно, могут использовать только спин-мьютексы. + +Наконец, существует одна дополнительная оптимизация, которую можно добавить в код MD, называемая легковесными переключениями контекста. Поскольку поток обработки прерывания выполняется в контексте ядра, он может заимствовать vmspace любого процесса. Таким образом, при легковесном переключении контекста переход к потоку обработки прерывания не меняет vmspace, а заимствует vmspace прерванного потока. Чтобы гарантировать, что vmspace прерванного потока не исчезнет во время работы, прерванному потоку запрещается выполнение до тех пор, пока поток обработки прерывания больше не использует его vmspace. Это может произойти, когда поток обработки прерывания либо блокируется, либо завершается. Если поток обработки прерывания блокируется, то при повторном запуске он будет использовать свой собственный контекст. Таким образом, он может освободить прерванный поток. + +Недостатки этой оптимизации заключаются в том, что они очень специфичны для конкретной машины и сложны, поэтому стоят усилий только в случае значительного улучшения производительности. На данный момент, вероятно, ещё рано делать выводы, и, фактически, это может даже ухудшить производительность, так как почти все обработчики прерываний будут немедленно блокироваться на Giant и потребуют исправления потока при блокировке. Кроме того, Майк Смит предложил альтернативный метод обработки прерываний, который работает следующим образом: + +. Каждый обработчик прерывания состоит из двух частей: предиката, который выполняется в основном контексте прерывания, и обработчика, который выполняется в контексте собственного потока. +. Если у обработчика прерывания есть предикат, то при срабатывании прерывания этот предикат выполняется. Если предикат возвращает значение `true`, прерывание считается полностью обработанным, и ядро возвращается из прерывания. Если предикат возвращает `false` или предиката нет, то запланированный обработчик запускается. + +Встраивание легковесных переключений контекста в эту схему может оказаться довольно сложным. Поскольку мы, возможно, захотим перейти на эту схему в будущем, вероятно, лучше отложить работу над легковесными переключениями контекста до тех пор, пока мы не определимся с окончательной архитектурой обработки прерываний и не выясним, как легковесные переключения контекста могут (или не могут) в неё вписаться. + +=== Ядро с вытеснением и критические секции + +==== Ядро и вытеснение вкратце + +Вытеснение ядра довольно просто. Основная идея заключается в том, что процессор всегда должен выполнять наиболее приоритетную доступную работу. Ну, это в идеале, по крайней мере. Есть несколько случаев, когда затраты на достижение идеала не стоят совершенства. + +Реализация полной вытесняющей многозадачности в ядре очень проста: когда вы планируете выполнение потока, помещая его в очередь выполнения, вы проверяете, является ли его приоритет выше, чем у текущего выполняемого потока. Если да, вы инициируете переключение контекста на этот поток. + +Хотя блокировки могут защитить большинство данных в случае вытеснения, не все части ядра безопасны для вытеснения. Например, если поток, удерживающий спин-блокировку, будет вытеснен, а новый поток попытается захватить ту же спин-блокировку, новый поток может вращаться вечно, так как прерванный поток может никогда не получить шанс на выполнение. Кроме того, некоторый код, такой как код для назначения номера адресного пространства процессу во время `exec` на Alpha, не должен быть вытеснен, так как он поддерживает фактический код переключения контекста. Для таких участков кода вытеснение отключается с использованием критической секции. + +==== Критические Секции + +Ответственность API критической секции заключается в предотвращении переключения контекста внутри критической секции. В полностью вытесняющем ядре каждый вызов `setrunqueue` для потока, отличного от текущего, является точкой вытеснения. Одна из реализаций заключается в том, что `critical_enter` устанавливает флаг для каждого потока, который сбрасывается его парной функцией. Если `setrunqueue` вызывается, когда этот флаг установлен, вытеснение не происходит, независимо от приоритета нового потока относительно текущего. Однако, поскольку критические секции используются в спин-блокировках для предотвращения переключения контекста и может быть захвачено несколько спин-блокировок, API критической секции должен поддерживать вложенность. По этой причине текущая реализация использует счетчик вложенности вместо одиночного флага для каждого потока. + +Для минимизации задержек прерывания внутри критической секции откладываются, а не отбрасываются. Если поток, который в обычных условиях должен быть вытеснен, становится готовым к выполнению, пока текущий поток находится в критической секции, то устанавливается флаг для данного потока, указывающий на ожидающее прерывание. При выходе из самой внешней критической секции флаг проверяется. Если флаг установлен, текущий поток вытесняется, чтобы позволить выполниться потоку с более высоким приоритетом. + +Прерывания создают проблему для спин-мьютексов. Если обработчик низкоуровневого прерывания требует блокировки, он не должен прерывать любой код, которому нужна эта блокировка, чтобы избежать возможного повреждения структур данных. В настоящее время этот механизм реализован через API критических секций с помощью функций `cpu_critical_enter` и `cpu_critical_exit`. Сейчас этот API отключает и снова включает прерывания на всех текущих платформах FreeBSD. Такой подход может быть не идеально оптимальным, но он прост для понимания и надежен в реализации. Теоретически, этот второй API нужен только для спин-мьютексов, используемых в основном контексте прерываний. Однако, для упрощения кода, он используется для всех спин-мьютексов и даже для всех критических секций. Возможно, стоит отделить MD API от MI API и использовать его только совместно с MI API в реализации спин-мьютексов. Если будет принят такой подход, то MD API, вероятно, потребуется переименовать, чтобы показать, что это отдельный API. + +==== Компромиссы проектирования + +Как упоминалось ранее, были сделаны некоторые компромиссы, чтобы пожертвовать случаями, когда идеальная вытесняющая многозадачность не всегда обеспечивает наилучшую производительность. + +Первый компромисс заключается в том, что код вытеснения не учитывает другие процессоры. Предположим, у нас есть два процессора A и B, где приоритет потока A равен 4, а приоритет потока B равен 2. Если процессор B делает поток с приоритетом 1 готовым к выполнению, то теоретически мы хотим, чтобы процессор A переключился на новый поток, чтобы выполнялись два потока с наивысшим приоритетом. Однако стоимость определения, на какой процессор нужно применить вытеснение, а также фактическая сигнализация этому процессору через IPI вместе с необходимой синхронизацией были бы огромными. Таким образом, текущий код вместо этого заставит процессор B переключиться на поток с более высоким приоритетом. Заметим, что это всё равно улучшает состояние системы, так как процессор B выполняет поток с приоритетом 1, а не поток с приоритетом 2. + +Второй компромисс ограничивает немедленное вытеснение ядра только потоками ядра с реальным временем. В простом случае вытеснения, описанном выше, поток всегда вытесняется немедленно (или как только будет покинута критическая секция), если становится доступным поток с более высоким приоритетом. Однако многие потоки, выполняющиеся в ядре, работают в контексте ядра лишь короткое время перед тем, как либо заблокироваться, либо вернуться в пользовательское пространство. Таким образом, если ядро вытеснит эти потоки для выполнения другого потока ядра без реального времени, оно может переключиться с выполняемого потока как раз перед тем, как тот собирается завершиться или перейти в режим ожидания. Кэш процессора должен затем адаптироваться к новому потоку. Когда ядро возвращается к вытесненному потоку, оно должно восстановить все потерянные кэшированные данные. Кроме того, выполняются два дополнительных переключения контекста, которых можно было бы избежать, если бы ядро отложило вытеснение до момента, пока первый поток не заблокируется или не вернётся в пользовательское пространство. Таким образом, по умолчанию код вытеснения будет немедленно вытеснять поток только в том случае, если поток с более высоким приоритетом имеет приоритет реального времени. + +Включение полной вытесняющей многозадачности для всех потоков ядра полезно в качестве средства отладки, так как позволяет выявить больше состояний гонки. Это особенно полезно на однопроцессорных системах (UP), где многие гонки сложно воспроизвести другими способами. Таким образом, существует опция ядра `FULL_PREEMPTION` для включения вытеснения для всех потоков ядра, которая может использоваться для целей отладки. + +=== Миграция потоков + +Простыми словами, поток мигрирует, когда переходит с одного CPU на другой. В неперемещаемом ядре это может происходить только в определённых точках, например, при вызове `msleep` или возврате в пользовательское пространство. Однако в перемещаемом ядре прерывание может вызвать вытеснение и возможную миграцию в любой момент. Это может негативно сказаться на данных, специфичных для CPU, поскольку, за исключением `curthread` и `curpcb`, данные могут изменяться при любой миграции. Поскольку потенциально миграция может произойти в любой момент, это делает незащищённый доступ к данным, специфичным для CPU, практически бесполезным. Поэтому желательно иметь возможность отключать миграцию для участков кода, где требуется стабильность данных, специфичных для CPU. + +Критические секции в настоящее время предотвращают миграцию, поскольку они не допускают переключения контекстов. Однако это может быть слишком строгим требованием в некоторых случаях, так как критическая секция также эффективно блокирует потоки прерываний на текущем процессоре. В результате был предоставлен другой API, позволяющий текущему потоку указать, что если он будет вытеснен, он не должен мигрировать на другой CPU. + +Этот API известен как закрепление потока и предоставляется планировщиком. API состоит из двух функций: `sched_pin` и `sched_unpin`. Эти функции управляют счетчиком вложенности `td_pinned` для каждого потока. Поток считается закрепленным, когда его счетчик вложенности больше нуля, и прекрашает быть закрепленным с нулевым счетчиком вложенности. Каждая реализация планировщика должна гарантировать, что закрепленные потоки выполняются только на том CPU, на котором они выполнялись при первом вызове `sched_pin`. Поскольку счетчик вложенности изменяется только самим потоком и читается другими потоками только тогда, когда закрепленный поток не выполняется, но удерживается `sched_lock`, то `td_pinned` не требует блокировки. Функция `sched_pin` увеличивает счетчик вложенности, а `sched_unpin` уменьшает его. Обратите внимание, что эти функции работают только с текущим потоком и привязывают текущий поток к CPU, на котором он выполняется в данный момент. Для привязки произвольного потока к определенному CPU следует использовать функции `sched_bind` и `sched_unbind`. + +=== Обратные вызовы + +Функция ядра `timeout` позволяет службам ядра регистрировать функции для выполнения в рамках программного прерывания `softclock`. События планируются на основе заданного количества тактов часов, и вызовы предоставленной потребителем функции будут происходить приблизительно в нужное время. + +Глобальный список ожидающих событий с таймаутом защищен глобальной спин-блокировкой `callout_lock`; любой доступ к списку таймаутов должен выполняться с удержанием этой блокировки. Когда `softclock` пробуждается, он сканирует список ожидающих таймаутов на предмет тех, которые должны сработать. Чтобы избежать инверсии блокировок, поток `softclock` освобождает блокировку `callout_lock` при вызове предоставленной функции обратного вызова `timeout`. Если флаг `CALLOUT_MPSAFE` не был установлен во время регистрации, то `Giant` будет захвачен перед вызовом обратного вызова, а затем освобожден после него. Блокировка `callout_lock` будет повторно захвачена перед продолжением работы. Код `softclock` аккуратно поддерживает список в согласованном состоянии во время освобождения блокировки. Если включен `DIAGNOSTIC`, то измеряется время выполнения каждой функции, и если оно превышает пороговое значение, генерируется предупреждение. + +[[smp-lock-strategies]] +== Конкретные стратегии блокировки + +=== Учетные данные + +`struct ucred` — это внутренняя структура учетных данных ядра, которая обычно используется в качестве основы для управления доступом на уровне процессов внутри ядра. Системы, производные от BSD, используют модель «копирования при записи» для учетных данных: могут существовать множественные ссылки на структуру учетных данных, и когда требуется внести изменение, структура дублируется, изменяется, а затем ссылка заменяется. Благодаря широко распространенному кэшированию учетных данных для реализации контроля доступа при открытии, это приводит к значительной экономии памяти. С переходом на детализированную SMP (симметричную многопроцессорность), эта модель также существенно экономит на операциях блокировки, требуя, чтобы модификации выполнялись только для неразделяемых учетных данных, избегая необходимости явной синхронизации при использовании известных разделяемых учетных данных. + +Структуры учетных данных с единственной ссылкой считаются изменяемыми; разделяемые структуры учетных данных не должны изменяться, иначе возникает риск состояния гонки. Мьютекс `cr_mtxp` защищает счетчик ссылок структуры `struct ucred` для поддержания согласованности. Любое использование структуры требует действительной ссылки на протяжении всего времени использования, иначе структура может быть освобождена из-под нелегитимного потребителя. + +Мьютекс `struct ucred` является листовым мьютексом и реализован через пул мьютексов по соображениям производительности. + +Обычно учетные данные используются в режиме только для чтения для принятия решений по контролю доступа, и в этом случае `td_ucred`, как правило, предпочтительнее, поскольку не требует блокировки. Когда учетные данные процесса обновляются, блокировка `proc` должна удерживаться на протяжении операций проверки и обновления, чтобы избежать состояний гонки. Учетные данные процесса `p_ucred` должны использоваться для операций проверки и обновления, чтобы предотвратить гонки между временем проверки и временем использования. + +Если при системных вызовах будет выполняться контроль доступа после обновления учетных данных процесса, значение `td_ucred` также должно быть обновлено до текущего значения процесса. Это предотвратит использование устаревших учетных данных после изменения. Ядро автоматически обновляет указатель `td_ucred` в структуре потока из `p_ucred` процесса всякий раз, когда процесс входит в ядро, что позволяет использовать свежие учетные данные для контроля доступа в ядре. + +=== Дескрипторы файлов и таблицы дескрипторов файлов + +Подробности будут позже. + +=== Структуры клеток + +`struct prison` хранит административные данные, связанные с обслуживанием клеток, созданных с использованием API man:jail[2]. Это включает имя хоста для каждой клетки, IP-адрес и связанные настройки. Эта структура имеет счетчик ссылок, так как указатели на её экземпляры разделяются многими структурами учётных данных. Один мьютекс, `pr_mtx`, защищает чтение и запись счётчика ссылок и всех изменяемых переменных внутри `struct jail`. Некоторые переменные устанавливаются только при создании клетки, и действительной ссылки на `struct prison` достаточно для чтения этих значений. Точная блокировка каждой записи документирована в комментариях файла [.filename]#sys/jail.h#. + +=== MAC Framework + +Фреймворк TrustedBSD MAC поддерживает данные в различных объектах ядра в виде `struct label`. Как правило, метки в объектах ядра защищаются тем же механизмом блокировки, что и остальная часть объекта ядра. Например, метка `v_label` в `struct vnode` защищается блокировкой vnode. + +В дополнение к меткам, поддерживаемым в стандартных объектах ядра, MAC Framework также поддерживает список зарегистрированных и активных политик. Список политик защищен глобальной мьютекс-блокировкой (`mac_policy_list_lock`) и счетчиком использования (также защищенным мьютексом). Поскольку множество проверок контроля доступа может выполняться параллельно, вход в framework для доступа только на чтение к списку политик требует удержания мьютекса во время увеличения (и последующего уменьшения) счетчика использования. Мьютекс не обязательно удерживать на протяжении всей операции входа в MAC — некоторые операции, такие как операции с метками на объектах файловой системы, выполняются длительное время. Для изменения списка политик, например во время регистрации и отмены регистрации политик, мьютекс должен быть удержан, а счетчик ссылок должен быть равен нулю, чтобы предотвратить изменение списка во время его использования. + +Условная переменная `mac_policy_list_not_busy` доступна для потоков, которым необходимо дождаться освобождения списка, но ожидание на этой условной переменной допустимо только если вызывающий поток не удерживает других блокировок, иначе может возникнуть нарушение порядка блокировок. Фактически, счетчик занятости действует как форма разделяемой/исключающей блокировки доступа к фреймворку: отличие в том, что, в отличие от sx-блокировки, потребители, ожидающие освобождения списка, могут подвергаться голоданию, вместо того чтобы допускать проблемы порядка блокировок в отношении счетчика занятости и других блокировок, которые могут удерживаться при входе в (или внутри) MAC Framework. + +=== Модули + +Для подсистемы модулей существует единая блокировка, которая используется для защиты общих данных. Эта блокировка является shared/exclusive (SX) и с высокой вероятностью потребует захвата (разделяемого или исключительного), поэтому были добавлены несколько макросов для упрощения работы с ней. Эти макросы можно найти в [.filename]#sys/module.h#, и их использование довольно простое. Основные структуры, защищаемые этой блокировкой, — это структуры `module_t` (при разделяемом доступе) и глобальная структура `modulelist_t` modules. Для более глубокого понимания стратегии блокировок рекомендуется изучить соответствующий исходный код в [.filename]#kern/kern_module.c#. + +=== Дерево устройств Newbus + +Система newbus будет использовать одну блокировку sx. Читатели будут удерживать разделяемую (read) блокировку (man:sx_slock[9]), а писатели — эксклюзивную (write) блокировку (man:sx_xlock[9]). Внутренние функции не будут выполнять блокировку вообще. Внешне видимые функции будут блокироваться по мере необходимости. Элементы, для которых не важно, выиграна гонка или проиграна, не будут блокироваться, так как они обычно читаются во многих местах (например, man:device_get_softc[9]). Изменения в структурах данных newbus будут относительно редкими, поэтому одной блокировки должно быть достаточно, и это не приведёт к снижению производительности. + +=== Каналы (pipe) + +... + +=== Процессы и потоки + +- иерархия процессов + +- блокировки и ссылки proc + +- потокоспецифичные копии записей proc для заморозки во время системных вызовов, включая td_ucred + +- межпроцессные операции + +- группы процессов и сеансы + +=== Планировщик + +Множество ссылок на `sched_lock` и примечания, указывающие на конкретные примитивы и связанные с ними особенности в других частях документа. + +=== Select и Poll + +Функции `select` и `poll` позволяют потокам блокироваться в ожидании событий на файловых дескрипторах — чаще всего, доступности файловых дескрипторов для чтения или записи. + +... + +=== SIGIO + +Служба SIGIO позволяет процессам запрашивать доставку сигнала SIGIO своей группе процессов при изменении статуса чтения/записи указанных файловых дескрипторов. Не более одного процесса или группы процессов может зарегистрироваться для получения SIGIO от любого заданного объекта ядра, и такой процесс или группа называется владельцем. Каждый объект, поддерживающий регистрацию SIGIO, содержит поле-указатель, которое имеет значение `NULL`, если объект не зарегистрирован, или указывает на структуру `struct sigio`, описывающую регистрацию. Это поле защищено глобальным мьютексом `sigio_lock`. Вызывающие функции обслуживания SIGIO должны передавать это поле «по ссылке», чтобы локальные копии регистра не создавались без защиты блокировкой. + +Один `struct sigio` выделяется для каждого зарегистрированного объекта, связанного с любым процессом или группой процессов, и содержит обратные ссылки на объект, владельца, информацию о сигнале, учетные данные и общее состояние регистрации. Каждый процесс или группа процессов содержит список зарегистрированных структур `struct sigio`: `p_sigiolst` для процессов и `pg_sigiolst` для групп процессов. Эти списки защищены блокировками процесса или группы процессов соответственно. Большинство полей в каждой `struct sigio` остаются постоянными на протяжении регистрации, за исключением поля `sio_pgsigio`, которое связывает `struct sigio` со списком процесса или группы процессов. Разработчикам, реализующим новые объекты ядра с поддержкой SIGIO, как правило, следует избегать удержания блокировок структур при вызове функций поддержки SIGIO, таких как `fsetown` или `funsetown`, чтобы не определять порядок блокировок между блокировками структур и глобальной блокировкой SIGIO. Обычно это возможно за счет использования повышенного счетчика ссылок на структуру, например, путем опоры на ссылку файлового дескриптора на канал во время операции с каналом. + +=== Sysctl + +Сервис `sysctl` MIB вызывается как из ядра, так и из пользовательских приложений с использованием системного вызова. По крайней мере, два вопроса возникают в отношении блокировок: во-первых, защита структур, поддерживающих пространство имен, и во-вторых, взаимодействие с переменными и функциями ядра, к которым обращается интерфейс `sysctl`. Поскольку `sysctl` позволяет прямое экспортирование (и изменение) статистики ядра и параметров конфигурации, механизм `sysctl` должен учитывать соответствующие семантики блокировок для этих переменных. В настоящее время `sysctl` использует единую глобальную sx-блокировку для сериализации использования `sysctl`; однако предполагается, что он работает под защитой Giant, и другие защиты не предоставляются. Оставшаяся часть этого раздела рассматривает возможные изменения в блокировках и семантике `sysctl`. + +- Необходимо изменить порядок операций для sysctl, которые обновляют значения из чтения старого, copyin и copyout, записи нового на copyin, блокировку, чтение старого и запись нового, разблокировку, copyout. Обычные sysctl, которые просто копируют старое значение и устанавливают новое, которое они копируют, могут по-прежнему следовать старой модели. Однако, возможно, будет чище использовать вторую модель для всех обработчиков sysctl, чтобы избежать операций блокировки. + +- Для упрощения распространённого случая, sysctl может включать указатель на мьютекс в макросах SYSCTL_FOO и в структуре. Это будет работать для большинства sysctl. Для значений, защищённых sx-блокировками, спин-мьютексами или другими стратегиями синхронизации, отличными от одиночного мьютекса сна, можно использовать узлы SYSCTL_PROC для обеспечения корректной блокировки. + +=== Очередь задач + +Интерфейс `taskqueue` имеет две основные блокировки, связанные с ним, для защиты соответствующих общих данных. Мьютекс `taskqueue_queues_mutex` предназначен для защиты TAILQ `taskqueue_queues`. Другая блокировка мьютекса, связанная с этой системой, находится в структуре данных `struct taskqueue`. Использование примитива синхронизации здесь необходимо для защиты целостности данных в `struct taskqueue`. Следует отметить, что нет отдельных макросов, помогающих пользователю заблокировать свою собственную работу, поскольку эти блокировки, скорее всего, не будут использоваться за пределами [.filename]#kern/subr_taskqueue.c#. + +[[smp-implementation-notes]] +== Заметки о реализации + +=== Очереди сна + +Очередь сна — это структура, которая содержит список потоков, ожидающих на канале ожидания. Каждый поток, который не находится в состоянии ожидания на канале ожидания, хранит структуру очереди сна при себе. Когда поток блокируется на канале ожидания, он передаёт свою структуру очереди сна этому каналу. Очереди сна, связанные с каналом ожидания, хранятся в хеш-таблице. + +Хеш-таблица очередей сна содержит очереди сна для каналов ожидания, у которых есть хотя бы один заблокированный поток. Каждая запись в хеш-таблице называется цепочкой очереди сна. Цепочка содержит связанный список очередей сна и спин-мьютекс. Спин-мьютекс защищает список очередей сна, а также содержимое структур очередей сна в списке. С каждым каналом ожидания связана только одна очередь сна. Если несколько потоков блокируются на одном канале ожидания, то очереди сна, связанные со всеми потоками, кроме первого, хранятся в списке свободных очередей сна в главной очереди сна. Когда поток удаляется из очереди сна, он получает одну из структур очереди сна из свободного списка главной очереди, если он не является единственным потоком в очереди. Последний поток получает главную очередь сна при возобновлении. Поскольку потоки могут удаляться из очереди сна в порядке, отличном от порядка добавления, поток может покинуть очередь сна с другой структурой очереди сна, чем та, с которой он в неё попал. + +Функция `sleepq_lock` блокирует спин-мьютес цепи очереди сна, соответствующей определённому каналу ожидания. Функция `sleepq_lookup` выполняет поиск в хеш-таблице главной очереди сна, связанной с заданным каналом ожидания. Если главная очередь сна не найдена, функция возвращает `NULL`. Функция `sleepq_release` разблокирует спин-мьютес, связанный с заданным каналом ожидания. + +Поток добавляется в очередь ожидания с помощью `sleepq_add`. Эта функция принимает канал ожидания, указатель на мьютекс, защищающий канал ожидания, строку описания сообщения ожидания и маску флагов. Цепь очереди ожидания должна быть заблокирована с помощью `sleepq_lock` перед вызовом этой функции. Если канал ожидания не защищен мьютексом (или защищен мьютексом Giant), то аргумент указателя на мьютекс должен быть `NULL`. Аргумент флагов содержит поле типа, указывающее на вид очереди ожидания, в которую добавляется поток, и флаг, указывающий, является ли ожидание прерываемым (`SLEEPQ_INTERRUPTIBLE`). В настоящее время существует только два типа очередей ожидания: традиционные очереди, управляемые через функции `msleep` и `wakeup` (`SLEEPQ_MSLEEP`), и очереди ожидания условных переменных (`SLEEPQ_CONDVAR`). Тип очереди ожидания и аргумент указателя на блокировку используются исключительно для внутренних проверок утверждений. Код, вызывающий `sleepq_add`, должен явно разблокировать любой блокировочный механизм, защищающий канал ожидания, после того как связанная цепь очереди ожидания будет заблокирована через `sleepq_lock` и перед блокировкой в очереди ожидания с помощью одной из функций ожидания. + +Таймаут для сна устанавливается вызовом `sleepq_set_timeout`. Функция принимает канал ожидания и время таймаута в виде относительного количества тиков в качестве аргументов. Если сон должен быть прерван поступающими сигналами, следует также вызвать функцию `sleepq_catch_signals`. Эта функция принимает канал ожидания в качестве единственного параметра. Если для данного потока уже есть ожидающий сигнал, то `sleepq_catch_signals` вернёт номер сигнала; в противном случае она вернёт 0. + +После добавления потока в очередь ожидания он блокируется с использованием одной из функций `sleepq_wait`. Существует четыре функции ожидания в зависимости от того, хочет ли вызывающий код использовать таймаут, прерывание сна перехваченными сигналами или прерывание от планировщика потоков пользовательского пространства. Функция `sleepq_wait` просто ожидает, пока текущий поток не будет явно возобновлён одной из функций пробуждения. Функция `sleepq_timedwait` ожидает, пока поток не будет явно возобновлён или пока не истечёт таймаут, установленный предыдущим вызовом `sleepq_set_timeout`. Функция `sleepq_wait_sig` ожидает, пока поток не будет явно возобновлён или его сон не будет прерван. Функция `sleepq_timedwait_sig` ожидает, пока поток не будет явно возобновлён, не истечёт таймаут, установленный предыдущим вызовом `sleepq_set_timeout`, или сон потока не будет прерван. Все функции ожидания принимают канал ожидания в качестве первого параметра. Кроме того, функция `sleepq_timedwait_sig` принимает второй логический параметр, указывающий, обнаружил ли предыдущий вызов `sleepq_catch_signals` ожидающий сигнал. + +Если поток явно возобновлен или прерван сигналом, функция ожидания возвращает ноль, указывая на успешное завершение сна. Если поток возобновлен по таймауту или прерыванию от планировщика потоков в пользовательском пространстве, вместо этого возвращается соответствующее значение errno. Обратите внимание, что поскольку `sleepq_wait` может возвращать только 0, она ничего не возвращает, и вызывающая сторона должна считать сон успешным. Также, если сон потока прерывается одновременно по таймауту и другим причинам, `sleepq_timedwait_sig` вернет ошибку, указывающую на срабатывание таймаута. Если возвращено значение ошибки 0 и для блокировки использовались `sleepq_wait_sig` или `sleepq_timedwait_sig`, следует вызвать функцию `sleepq_calc_signal_retval` для проверки ожидающих сигналов и вычисления соответствующего возвращаемого значения, если таковые обнаружены. Номер сигнала, полученный при предыдущем вызове `sleepq_catch_signals`, должен быть передан в качестве единственного аргумента в `sleepq_calc_signal_retval`. + +Потоки, находящиеся в состоянии ожидания на канале ожидания, явно возобновляются функциями `sleepq_broadcast` и `sleepq_signal`. Обе функции принимают канал ожидания, с которого нужно возобновить потоки, приоритет, на который нужно поднять возобновлённые потоки, и аргумент флагов, указывающий тип очереди ожидания, которую нужно возобновить. Аргумент приоритета трактуется как минимальный приоритет. Если у возобновляемого потока уже есть более высокий приоритет (численно меньший), чем указанный в аргументе, его приоритет не изменяется. Аргумент флагов используется для внутренних проверок, чтобы гарантировать, что очереди ожидания не обрабатываются как неправильный тип. Например, функции условных переменных не должны возобновлять потоки на традиционной очереди ожидания. Функция `sleepq_broadcast` возобновляет все потоки, заблокированные на указанном канале ожидания, тогда как `sleepq_signal` возобновляет только поток с наивысшим приоритетом, заблокированный на канале ожидания. Перед вызовом этих функций цепочка очереди ожидания должна быть заблокирована с помощью функции `sleepq_lock`. + +Спящий поток может быть прерван с помощью вызова функции `sleepq_abort`. Эта функция должна вызываться с удержанием `sched_lock`, а поток должен находиться в очереди сна. Поток также может быть удалён из определённой очереди сна с помощью функции `sleepq_remove`. Эта функция принимает как поток, так и канал ожидания в качестве аргументов и пробуждает поток только в том случае, если он находится в очереди сна для указанного канала ожидания. Если поток не находится в очереди сна или находится в очереди сна для другого канала ожидания, эта функция ничего не делает. + +=== Турникеты + +- Сравнение/сопоставление с очередями сна. + +- Поиск/ожидание/освобождение. - Описать состояние гонки TDF_TSNOBLOCK. + +- Приоритетное распространение. + +=== Подробности реализации мьютекса + +- Должны ли мы требовать владения мьютексами для `mtx_destroy()`, так как иначе мы не можем безопасно утверждать, что они не принадлежат кому-либо ещё? + +==== Вращающиеся мьютексы + +- Использование критической секции... + +==== Мьютексы сна (Sleep Mutexes) + +- Опишите гонки с оспариваемыми мьютексами + +- Почему безопасно читать mtx_lock оспариваемой мьютекса при удержании блокировки цепочки турникета. + +=== Witness + +- Что это делает + +- Как это работает + +[[smp-misc]] +== Разные темы + +=== Источники прерываний и абстракции ICU + +- struct isrc + +- pic драйверы + +=== Другие случайные вопросы/темы + +- Передавать ли блокировку в `sema_wait`? + +- Должны ли мы иметь sx блокировки без возможности сна? + +- Добавить некоторую информацию о правильном использовании счетчиков ссылок. + +:sectnums!: + +[glossary] +[[smp-glossary]] +== Глоссарий + +[.glosslist] +atomic (атомарный):: +Операция является атомарной, если все её эффекты видны другим процессорам одновременно при соблюдении соответствующего протокола доступа. В простейшем случае атомарные инструкции предоставляются непосредственно архитектурой процессора. На более высоком уровне, если несколько элементов структуры защищены блокировкой, то набор операций является атомарным, если все они выполняются при удержании блокировки без её освобождения между любыми из операций. ++ +См. также operation (операция). + +block (блокировать):: +Поток блокируется, когда он ожидает блокировку, ресурс или условие. К сожалению, этот термин в результате немного перегружен. ++ +См. также sleep (спать). + +critical section (критическая секция):: +Фрагмент кода, который не может быть вытеснен. Критическая секция начинается и завершается с использованием API man:critical_enter[9]. + +MD:: +Машинозависимый (machine dependent). ++ +Смотри также MI. + +memory operation (операция с памятью):: +Операция с памятью выполняет чтение и/или запись в ячейку памяти. + +MI:: +Машинно-независимый (machine independent). ++ +См. также MD. + +operation (операция):: +См. memory operation (операция с памятью). + +primary interrupt context (основной контекст прерывания):: +Основной контекст прерывания относится к коду, который выполняется при возникновении прерывания. Этот код может либо напрямую запускать обработчик прерывания, либо планировать выполнение асинхронного потока прерывания для обработчиков прерываний данного источника. + +realtime kernel thread (поток ядра реального времени):: +Высокоприоритетный поток ядра. В настоящее время единственными потоками ядра с реальным приоритетом являются потоки обработки прерываний. ++ +См. также thread (поток). + +sleep (спать):: +Поток находится в состоянии сна, когда он заблокирован на условной переменной или в очереди сна через `msleep` или `tsleep`. ++ +См. также block (блокировать). + +sleepable lock (блокировка с возможностью сна):: +блокировка с возможностью сна — это блокировка, которая может удерживаться потоком, находящимся в состоянии сна. В настоящее время в FreeBSD единственными блокировками с возможностью сна являются lockmgr и sx. В будущем некоторые sx-блокировки, такие как allproc и proctree, могут стать блокировками с возможностью сна. ++ +См. также sleep (спать). + +thread (поток):: +Поток ядра, представленный структурой `struct thread`. Потоки владеют блокировками и содержат единственный на поток контекст выполнения. + +wait channel (канал ожидания):: +Виртуальный адрес ядра, на котором потоки могут переходить в режим ожидания. + +:sectnums: diff --git a/documentation/content/ru/books/arch-handbook/smp/_index.po b/documentation/content/ru/books/arch-handbook/smp/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/smp/_index.po @@ -0,0 +1,1983 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-12 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 "Документ по архитектуре SMPng" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:1 +#, no-wrap +msgid "Chapter 8. SMPng Design Document" +msgstr "Глава 8. Документ по архитектуре SMPng" + +#. 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 "" +"В этом документе представлены текущая архитектура и реализация SMPng. " +"Сначала вводятся основные примитивы и инструменты. Затем излагается общая " +"архитектура модели синхронизации и выполнения ядра FreeBSD. Далее " +"обсуждаются стратегии блокировок для конкретных подсистем, описывающие " +"подходы к внедрению детализированной синхронизации и параллелизма для каждой " +"подсистемы. В заключение приводятся подробные заметки по реализации, " +"объясняющие выбор проектных решений и информирующие читателя о важных " +"последствиях использования конкретных примитивов." + +#. 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 "" +"Этот документ находится в стадии разработки и будет обновляться в " +"соответствии с текущими проектированием и реализацией, связанными с проектом " +"SMPng. Многие разделы в настоящее время существуют только в виде набросков, " +"но будут дополняться по мере продвижения работы. Обновления или предложения " +"по документу могут быть направлены редакторам документа." + +#. 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 "" +"Цель SMPng — обеспечить параллелизм в ядре. Ядро представляет собой одну " +"довольно большую и сложную программу. Чтобы сделать ядро многопоточным, мы " +"используем те же инструменты, что и для многопоточности других программ. К " +"ним относятся мьютексы, разделяемые/монопольные блокировки, семафоры и " +"условные переменные. Для определений этих и других терминов, связанных с " +"SMP, см. раздел crossref:smp[smp-glossary, Глоссарий] в этой статье." + +#. 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 "" +"Это требует особой осторожности при использовании элемента, защищённого " +"атомарными инструкциями. Например, в реализации мьютекса сна мы должны " +"использовать `atomic_cmpset` вместо `atomic_set` для установки бита " +"`MTX_CONTESTED`. Причина в том, что мы считываем значение `mtx_lock` в " +"переменную и затем принимаем решение на основе этого чтения. Однако " +"значение, которое мы ранее прочитали, может быть устаревшим или измениться, " +"пока мы принимаем решение. Таким образом, когда выполняется `atomic_set`, " +"это может привести к установке бита на другом значении, отличном от того, на " +"котором мы основывали своё решение. Поэтому мы должны использовать " +"`atomic_cmpset`, чтобы установить значение только в том случае, если " +"значение, на котором мы приняли решение, актуально и действительно." + +#. 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 "" +"Во-первых, блокировки sx могут использоваться таким образом: монопольная " +"блокировка при записи и разделяемая блокировка при чтении. Этот метод " +"достаточно прост." + +#. 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 "" +"Второй метод несколько менее очевиден. Вы можете защитить данные несколькими " +"блокировками. Для чтения данных достаточно получить блокировку на чтение " +"одной из блокировок. Однако для записи данных необходимо получить блокировку " +"на запись всех блокировок. Это может сделать запись довольно затратной, но " +"может быть полезно, когда данные доступны различными способами. Например, " +"указатель на родительский процесс защищён как `proctree_lock` sx-" +"блокировкой, так и мьютексом процесса. Иногда блокировка процесса удобнее, " +"так как мы просто проверяем, кто является родителем уже заблокированного " +"процесса. Однако в других случаях, таких как `inferior`, необходимо обходить " +"дерево процессов через указатели на родителя, и блокировка каждого процесса " +"была бы слишком затратной, а также сложной для гарантии того, что " +"проверяемое условие остаётся верным как во время проверки, так и при " +"выполнении действий, основанных на этой проверке." + +#. 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 "" +"Следуя примеру нескольких других многопоточных ядер UNIX(R), FreeBSD " +"реализрвала обработчики прерываний, предоставив им собственный контекст " +"потока. Предоставление контекста для обработчиков прерываний позволяет им " +"блокироваться на блокировках. Однако, чтобы избежать задержек, потоки " +"обработки прерываний выполняются с приоритетом реального времени в ядре. " +"Таким образом, обработчики прерываний не должны выполняться слишком долго, " +"чтобы не лишать ресурсов другие потоки ядра. Кроме того, поскольку несколько " +"обработчиков могут использовать один поток прерываний, обработчики " +"прерываний не должны переходить в режим сна или использовать блокировки, " +"допускающие сон, чтобы не лишать ресурсов другие обработчики прерываний." + +#. 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 "" +"Текущие потоки обработки прерываний в FreeBSD называются тяжеловесными " +"потоками обработки прерываний. Они получили такое название, потому что " +"переключение на поток обработки прерывания включает в себя полное " +"переключение контекста. В первоначальной реализации ядро не было " +"вытесняющим, поэтому прерывания, которые прерывали поток ядра, должны были " +"ждать, пока поток ядра не заблокируется или не вернётся в пользовательское " +"пространство, прежде чем у них появится возможность выполниться." + +#. 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 "" +"Для решения проблем с задержками ядро FreeBSD стало вытесняющим. В настоящее " +"время вытеснение потока ядра происходит только при освобождении мьютекса сна " +"или при поступлении прерывания. Однако планируется сделать ядро FreeBSD " +"полностью вытесняющим, как описано ниже." + +#. 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 "" +"Не все обработчики прерываний выполняются в контексте потока. Вместо этого, " +"некоторые обработчики выполняются непосредственно в основном контексте " +"прерывания. Эти обработчики прерываний в настоящее время ошибочно называются " +"\"быстрыми\" обработчиками прерываний, поскольку для их обозначения " +"применяется флаг `INTR_FAST`, использовавшийся в более ранних версиях ядра. " +"Единственные прерывания, которые в настоящее время используют такие " +"обработчики прерываний, — это прерывания от часов и последовательных " +"устройств ввода-вывода. Поскольку эти обработчики не имеют собственного " +"контекста, они не могут захватывать блокирующие блокировки и, следовательно, " +"могут использовать только спин-мьютексы." + +#. 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 "" +"Наконец, существует одна дополнительная оптимизация, которую можно добавить " +"в код MD, называемая легковесными переключениями контекста. Поскольку поток " +"обработки прерывания выполняется в контексте ядра, он может заимствовать " +"vmspace любого процесса. Таким образом, при легковесном переключении " +"контекста переход к потоку обработки прерывания не меняет vmspace, а " +"заимствует vmspace прерванного потока. Чтобы гарантировать, что vmspace " +"прерванного потока не исчезнет во время работы, прерванному потоку " +"запрещается выполнение до тех пор, пока поток обработки прерывания больше не " +"использует его vmspace. Это может произойти, когда поток обработки " +"прерывания либо блокируется, либо завершается. Если поток обработки " +"прерывания блокируется, то при повторном запуске он будет использовать свой " +"собственный контекст. Таким образом, он может освободить прерванный поток." + +#. 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 "" +"Недостатки этой оптимизации заключаются в том, что они очень специфичны для " +"конкретной машины и сложны, поэтому стоят усилий только в случае " +"значительного улучшения производительности. На данный момент, вероятно, ещё " +"рано делать выводы, и, фактически, это может даже ухудшить " +"производительность, так как почти все обработчики прерываний будут " +"немедленно блокироваться на Giant и потребуют исправления потока при " +"блокировке. Кроме того, Майк Смит предложил альтернативный метод обработки " +"прерываний, который работает следующим образом:" + +#. 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 "" +"Если у обработчика прерывания есть предикат, то при срабатывании прерывания " +"этот предикат выполняется. Если предикат возвращает значение `true`, " +"прерывание считается полностью обработанным, и ядро возвращается из " +"прерывания. Если предикат возвращает `false` или предиката нет, то " +"запланированный обработчик запускается." + +#. 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 "" +"Хотя блокировки могут защитить большинство данных в случае вытеснения, не " +"все части ядра безопасны для вытеснения. Например, если поток, удерживающий " +"спин-блокировку, будет вытеснен, а новый поток попытается захватить ту же " +"спин-блокировку, новый поток может вращаться вечно, так как прерванный поток " +"может никогда не получить шанс на выполнение. Кроме того, некоторый код, " +"такой как код для назначения номера адресного пространства процессу во время " +"`exec` на Alpha, не должен быть вытеснен, так как он поддерживает " +"фактический код переключения контекста. Для таких участков кода вытеснение " +"отключается с использованием критической секции." + +#. 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 "" +"Ответственность API критической секции заключается в предотвращении " +"переключения контекста внутри критической секции. В полностью вытесняющем " +"ядре каждый вызов `setrunqueue` для потока, отличного от текущего, является " +"точкой вытеснения. Одна из реализаций заключается в том, что " +"`critical_enter` устанавливает флаг для каждого потока, который сбрасывается " +"его парной функцией. Если `setrunqueue` вызывается, когда этот флаг " +"установлен, вытеснение не происходит, независимо от приоритета нового потока " +"относительно текущего. Однако, поскольку критические секции используются в " +"спин-блокировках для предотвращения переключения контекста и может быть " +"захвачено несколько спин-блокировок, API критической секции должен " +"поддерживать вложенность. По этой причине текущая реализация использует " +"счетчик вложенности вместо одиночного флага для каждого потока." + +#. 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 "" +"Прерывания создают проблему для спин-мьютексов. Если обработчик " +"низкоуровневого прерывания требует блокировки, он не должен прерывать любой " +"код, которому нужна эта блокировка, чтобы избежать возможного повреждения " +"структур данных. В настоящее время этот механизм реализован через API " +"критических секций с помощью функций `cpu_critical_enter` и " +"`cpu_critical_exit`. Сейчас этот API отключает и снова включает прерывания " +"на всех текущих платформах FreeBSD. Такой подход может быть не идеально " +"оптимальным, но он прост для понимания и надежен в реализации. Теоретически, " +"этот второй API нужен только для спин-мьютексов, используемых в основном " +"контексте прерываний. Однако, для упрощения кода, он используется для всех " +"спин-мьютексов и даже для всех критических секций. Возможно, стоит отделить " +"MD API от MI API и использовать его только совместно с MI API в реализации " +"спин-мьютексов. Если будет принят такой подход, то MD API, вероятно, " +"потребуется переименовать, чтобы показать, что это отдельный API." + +#. 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 "" +"Первый компромисс заключается в том, что код вытеснения не учитывает другие " +"процессоры. Предположим, у нас есть два процессора A и B, где приоритет " +"потока A равен 4, а приоритет потока B равен 2. Если процессор B делает " +"поток с приоритетом 1 готовым к выполнению, то теоретически мы хотим, чтобы " +"процессор A переключился на новый поток, чтобы выполнялись два потока с " +"наивысшим приоритетом. Однако стоимость определения, на какой процессор " +"нужно применить вытеснение, а также фактическая сигнализация этому " +"процессору через IPI вместе с необходимой синхронизацией были бы огромными. " +"Таким образом, текущий код вместо этого заставит процессор B переключиться " +"на поток с более высоким приоритетом. Заметим, что это всё равно улучшает " +"состояние системы, так как процессор B выполняет поток с приоритетом 1, а не " +"поток с приоритетом 2." + +#. 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 "" +"Включение полной вытесняющей многозадачности для всех потоков ядра полезно в " +"качестве средства отладки, так как позволяет выявить больше состояний гонки. " +"Это особенно полезно на однопроцессорных системах (UP), где многие гонки " +"сложно воспроизвести другими способами. Таким образом, существует опция ядра " +"`FULL_PREEMPTION` для включения вытеснения для всех потоков ядра, которая " +"может использоваться для целей отладки." + +#. 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 "" +"Простыми словами, поток мигрирует, когда переходит с одного CPU на другой. В " +"неперемещаемом ядре это может происходить только в определённых точках, " +"например, при вызове `msleep` или возврате в пользовательское пространство. " +"Однако в перемещаемом ядре прерывание может вызвать вытеснение и возможную " +"миграцию в любой момент. Это может негативно сказаться на данных, " +"специфичных для CPU, поскольку, за исключением `curthread` и `curpcb`, " +"данные могут изменяться при любой миграции. Поскольку потенциально миграция " +"может произойти в любой момент, это делает незащищённый доступ к данным, " +"специфичным для CPU, практически бесполезным. Поэтому желательно иметь " +"возможность отключать миграцию для участков кода, где требуется стабильность " +"данных, специфичных для CPU." + +#. 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 "" +"Критические секции в настоящее время предотвращают миграцию, поскольку они " +"не допускают переключения контекстов. Однако это может быть слишком строгим " +"требованием в некоторых случаях, так как критическая секция также эффективно " +"блокирует потоки прерываний на текущем процессоре. В результате был " +"предоставлен другой API, позволяющий текущему потоку указать, что если он " +"будет вытеснен, он не должен мигрировать на другой CPU." + +#. 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 "" +"Этот API известен как закрепление потока и предоставляется планировщиком. " +"API состоит из двух функций: `sched_pin` и `sched_unpin`. Эти функции " +"управляют счетчиком вложенности `td_pinned` для каждого потока. Поток " +"считается закрепленным, когда его счетчик вложенности больше нуля, и " +"прекрашает быть закрепленным с нулевым счетчиком вложенности. Каждая " +"реализация планировщика должна гарантировать, что закрепленные потоки " +"выполняются только на том CPU, на котором они выполнялись при первом вызове " +"`sched_pin`. Поскольку счетчик вложенности изменяется только самим потоком и " +"читается другими потоками только тогда, когда закрепленный поток не " +"выполняется, но удерживается `sched_lock`, то `td_pinned` не требует " +"блокировки. Функция `sched_pin` увеличивает счетчик вложенности, а " +"`sched_unpin` уменьшает его. Обратите внимание, что эти функции работают " +"только с текущим потоком и привязывают текущий поток к CPU, на котором он " +"выполняется в данный момент. Для привязки произвольного потока к " +"определенному CPU следует использовать функции `sched_bind` и `sched_unbind`." + +#. 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 "" +"Функция ядра `timeout` позволяет службам ядра регистрировать функции для " +"выполнения в рамках программного прерывания `softclock`. События планируются " +"на основе заданного количества тактов часов, и вызовы предоставленной " +"потребителем функции будут происходить приблизительно в нужное время." + +#. 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 "" +"Глобальный список ожидающих событий с таймаутом защищен глобальной спин-" +"блокировкой `callout_lock`; любой доступ к списку таймаутов должен " +"выполняться с удержанием этой блокировки. Когда `softclock` пробуждается, он " +"сканирует список ожидающих таймаутов на предмет тех, которые должны " +"сработать. Чтобы избежать инверсии блокировок, поток `softclock` освобождает " +"блокировку `callout_lock` при вызове предоставленной функции обратного " +"вызова `timeout`. Если флаг `CALLOUT_MPSAFE` не был установлен во время " +"регистрации, то `Giant` будет захвачен перед вызовом обратного вызова, а " +"затем освобожден после него. Блокировка `callout_lock` будет повторно " +"захвачена перед продолжением работы. Код `softclock` аккуратно поддерживает " +"список в согласованном состоянии во время освобождения блокировки. Если " +"включен `DIAGNOSTIC`, то измеряется время выполнения каждой функции, и если " +"оно превышает пороговое значение, генерируется предупреждение." + +#. 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 "" +"`struct ucred` — это внутренняя структура учетных данных ядра, которая " +"обычно используется в качестве основы для управления доступом на уровне " +"процессов внутри ядра. Системы, производные от BSD, используют модель " +"«копирования при записи» для учетных данных: могут существовать " +"множественные ссылки на структуру учетных данных, и когда требуется внести " +"изменение, структура дублируется, изменяется, а затем ссылка заменяется. " +"Благодаря широко распространенному кэшированию учетных данных для реализации " +"контроля доступа при открытии, это приводит к значительной экономии памяти. " +"С переходом на детализированную SMP (симметричную многопроцессорность), эта " +"модель также существенно экономит на операциях блокировки, требуя, чтобы " +"модификации выполнялись только для неразделяемых учетных данных, избегая " +"необходимости явной синхронизации при использовании известных разделяемых " +"учетных данных." + +#. 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 "" +"Структуры учетных данных с единственной ссылкой считаются изменяемыми; " +"разделяемые структуры учетных данных не должны изменяться, иначе возникает " +"риск состояния гонки. Мьютекс `cr_mtxp` защищает счетчик ссылок структуры " +"`struct ucred` для поддержания согласованности. Любое использование " +"структуры требует действительной ссылки на протяжении всего времени " +"использования, иначе структура может быть освобождена из-под нелегитимного " +"потребителя." + +#. 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 "" +"Мьютекс `struct ucred` является листовым мьютексом и реализован через пул " +"мьютексов по соображениям производительности." + +#. 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 "" +"Обычно учетные данные используются в режиме только для чтения для принятия " +"решений по контролю доступа, и в этом случае `td_ucred`, как правило, " +"предпочтительнее, поскольку не требует блокировки. Когда учетные данные " +"процесса обновляются, блокировка `proc` должна удерживаться на протяжении " +"операций проверки и обновления, чтобы избежать состояний гонки. Учетные " +"данные процесса `p_ucred` должны использоваться для операций проверки и " +"обновления, чтобы предотвратить гонки между временем проверки и временем " +"использования." + +#. 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 "" +"Если при системных вызовах будет выполняться контроль доступа после " +"обновления учетных данных процесса, значение `td_ucred` также должно быть " +"обновлено до текущего значения процесса. Это предотвратит использование " +"устаревших учетных данных после изменения. Ядро автоматически обновляет " +"указатель `td_ucred` в структуре потока из `p_ucred` процесса всякий раз, " +"когда процесс входит в ядро, что позволяет использовать свежие учетные " +"данные для контроля доступа в ядре." + +#. 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 "" +"`struct prison` хранит административные данные, связанные с обслуживанием " +"клеток, созданных с использованием API man:jail[2]. Это включает имя хоста " +"для каждой клетки, IP-адрес и связанные настройки. Эта структура имеет " +"счетчик ссылок, так как указатели на её экземпляры разделяются многими " +"структурами учётных данных. Один мьютекс, `pr_mtx`, защищает чтение и запись " +"счётчика ссылок и всех изменяемых переменных внутри `struct jail`. Некоторые " +"переменные устанавливаются только при создании клетки, и действительной " +"ссылки на `struct prison` достаточно для чтения этих значений. Точная " +"блокировка каждой записи документирована в комментариях файла " +"[.filename]#sys/jail.h#." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:176 +#, no-wrap +msgid "MAC Framework" +msgstr "MAC Framework" + +#. 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 "" +"Фреймворк TrustedBSD MAC поддерживает данные в различных объектах ядра в " +"виде `struct label`. Как правило, метки в объектах ядра защищаются тем же " +"механизмом блокировки, что и остальная часть объекта ядра. Например, метка " +"`v_label` в `struct vnode` защищается блокировкой vnode." + +#. 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 "" +"В дополнение к меткам, поддерживаемым в стандартных объектах ядра, MAC " +"Framework также поддерживает список зарегистрированных и активных политик. " +"Список политик защищен глобальной мьютекс-блокировкой " +"(`mac_policy_list_lock`) и счетчиком использования (также защищенным " +"мьютексом). Поскольку множество проверок контроля доступа может выполняться " +"параллельно, вход в framework для доступа только на чтение к списку политик " +"требует удержания мьютекса во время увеличения (и последующего уменьшения) " +"счетчика использования. Мьютекс не обязательно удерживать на протяжении всей " +"операции входа в MAC — некоторые операции, такие как операции с метками на " +"объектах файловой системы, выполняются длительное время. Для изменения " +"списка политик, например во время регистрации и отмены регистрации политик, " +"мьютекс должен быть удержан, а счетчик ссылок должен быть равен нулю, чтобы " +"предотвратить изменение списка во время его использования." + +#. 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 "" +"Условная переменная `mac_policy_list_not_busy` доступна для потоков, которым " +"необходимо дождаться освобождения списка, но ожидание на этой условной " +"переменной допустимо только если вызывающий поток не удерживает других " +"блокировок, иначе может возникнуть нарушение порядка блокировок. Фактически, " +"счетчик занятости действует как форма разделяемой/исключающей блокировки " +"доступа к фреймворку: отличие в том, что, в отличие от sx-блокировки, " +"потребители, ожидающие освобождения списка, могут подвергаться голоданию, " +"вместо того чтобы допускать проблемы порядка блокировок в отношении счетчика " +"занятости и других блокировок, которые могут удерживаться при входе в (или " +"внутри) MAC Framework." + +#. 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 "" +"Для подсистемы модулей существует единая блокировка, которая используется " +"для защиты общих данных. Эта блокировка является shared/exclusive (SX) и с " +"высокой вероятностью потребует захвата (разделяемого или исключительного), " +"поэтому были добавлены несколько макросов для упрощения работы с ней. Эти " +"макросы можно найти в [.filename]#sys/module.h#, и их использование довольно " +"простое. Основные структуры, защищаемые этой блокировкой, — это структуры " +"`module_t` (при разделяемом доступе) и глобальная структура `modulelist_t` " +"modules. Для более глубокого понимания стратегии блокировок рекомендуется " +"изучить соответствующий исходный код в [.filename]#kern/kern_module.c#." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:188 +#, no-wrap +msgid "Newbus Device Tree" +msgstr "Дерево устройств Newbus" + +#. 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 "" +"Система newbus будет использовать одну блокировку sx. Читатели будут " +"удерживать разделяемую (read) блокировку (man:sx_slock[9]), а писатели — " +"эксклюзивную (write) блокировку (man:sx_xlock[9]). Внутренние функции не " +"будут выполнять блокировку вообще. Внешне видимые функции будут " +"блокироваться по мере необходимости. Элементы, для которых не важно, " +"выиграна гонка или проиграна, не будут блокироваться, так как они обычно " +"читаются во многих местах (например, man:device_get_softc[9]). Изменения в " +"структурах данных newbus будут относительно редкими, поэтому одной " +"блокировки должно быть достаточно, и это не приведёт к снижению " +"производительности." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:192 +#, no-wrap +msgid "Pipes" +msgstr "Каналы (pipe)" + +#. 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 "блокировки и ссылки proc" + +#. 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 "" +"потокоспецифичные копии записей proc для заморозки во время системных " +"вызовов, включая td_ucred" + +#. 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 "" +"Множество ссылок на `sched_lock` и примечания, указывающие на конкретные " +"примитивы и связанные с ними особенности в других частях документа." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:212 +#, no-wrap +msgid "Select and Poll" +msgstr "Select и Poll" + +#. 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 "" +"Функции `select` и `poll` позволяют потокам блокироваться в ожидании событий " +"на файловых дескрипторах — чаще всего, доступности файловых дескрипторов для " +"чтения или записи." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:218 +#, no-wrap +msgid "SIGIO" +msgstr "SIGIO" + +#. 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 "" +"Служба SIGIO позволяет процессам запрашивать доставку сигнала SIGIO своей " +"группе процессов при изменении статуса чтения/записи указанных файловых " +"дескрипторов. Не более одного процесса или группы процессов может " +"зарегистрироваться для получения SIGIO от любого заданного объекта ядра, и " +"такой процесс или группа называется владельцем. Каждый объект, " +"поддерживающий регистрацию SIGIO, содержит поле-указатель, которое имеет " +"значение `NULL`, если объект не зарегистрирован, или указывает на структуру " +"`struct sigio`, описывающую регистрацию. Это поле защищено глобальным " +"мьютексом `sigio_lock`. Вызывающие функции обслуживания SIGIO должны " +"передавать это поле «по ссылке», чтобы локальные копии регистра не " +"создавались без защиты блокировкой." + +#. 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 "" +"Один `struct sigio` выделяется для каждого зарегистрированного объекта, " +"связанного с любым процессом или группой процессов, и содержит обратные " +"ссылки на объект, владельца, информацию о сигнале, учетные данные и общее " +"состояние регистрации. Каждый процесс или группа процессов содержит список " +"зарегистрированных структур `struct sigio`: `p_sigiolst` для процессов и " +"`pg_sigiolst` для групп процессов. Эти списки защищены блокировками процесса " +"или группы процессов соответственно. Большинство полей в каждой `struct " +"sigio` остаются постоянными на протяжении регистрации, за исключением поля " +"`sio_pgsigio`, которое связывает `struct sigio` со списком процесса или " +"группы процессов. Разработчикам, реализующим новые объекты ядра с поддержкой " +"SIGIO, как правило, следует избегать удержания блокировок структур при " +"вызове функций поддержки SIGIO, таких как `fsetown` или `funsetown`, чтобы " +"не определять порядок блокировок между блокировками структур и глобальной " +"блокировкой SIGIO. Обычно это возможно за счет использования повышенного " +"счетчика ссылок на структуру, например, путем опоры на ссылку файлового " +"дескриптора на канал во время операции с каналом." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:224 +#, no-wrap +msgid "Sysctl" +msgstr "Sysctl" + +#. 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 "" +"Сервис `sysctl` MIB вызывается как из ядра, так и из пользовательских " +"приложений с использованием системного вызова. По крайней мере, два вопроса " +"возникают в отношении блокировок: во-первых, защита структур, поддерживающих " +"пространство имен, и во-вторых, взаимодействие с переменными и функциями " +"ядра, к которым обращается интерфейс `sysctl`. Поскольку `sysctl` позволяет " +"прямое экспортирование (и изменение) статистики ядра и параметров " +"конфигурации, механизм `sysctl` должен учитывать соответствующие семантики " +"блокировок для этих переменных. В настоящее время `sysctl` использует единую " +"глобальную sx-блокировку для сериализации использования `sysctl`; однако " +"предполагается, что он работает под защитой Giant, и другие защиты не " +"предоставляются. Оставшаяся часть этого раздела рассматривает возможные " +"изменения в блокировках и семантике `sysctl`." + +#. 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 "" +"Необходимо изменить порядок операций для sysctl, которые обновляют значения " +"из чтения старого, copyin и copyout, записи нового на copyin, блокировку, " +"чтение старого и запись нового, разблокировку, copyout. Обычные sysctl, " +"которые просто копируют старое значение и устанавливают новое, которое они " +"копируют, могут по-прежнему следовать старой модели. Однако, возможно, будет " +"чище использовать вторую модель для всех обработчиков sysctl, чтобы избежать " +"операций блокировки." + +#. 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 "" +"Для упрощения распространённого случая, sysctl может включать указатель на " +"мьютекс в макросах SYSCTL_FOO и в структуре. Это будет работать для " +"большинства sysctl. Для значений, защищённых sx-блокировками, спин-" +"мьютексами или другими стратегиями синхронизации, отличными от одиночного " +"мьютекса сна, можно использовать узлы SYSCTL_PROC для обеспечения корректной " +"блокировки." + +#. 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 "" +"Интерфейс `taskqueue` имеет две основные блокировки, связанные с ним, для " +"защиты соответствующих общих данных. Мьютекс `taskqueue_queues_mutex` " +"предназначен для защиты TAILQ `taskqueue_queues`. Другая блокировка " +"мьютекса, связанная с этой системой, находится в структуре данных `struct " +"taskqueue`. Использование примитива синхронизации здесь необходимо для " +"защиты целостности данных в `struct taskqueue`. Следует отметить, что нет " +"отдельных макросов, помогающих пользователю заблокировать свою собственную " +"работу, поскольку эти блокировки, скорее всего, не будут использоваться за " +"пределами [.filename]#kern/subr_taskqueue.c#." + +#. 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 "" +"Функция `sleepq_lock` блокирует спин-мьютес цепи очереди сна, " +"соответствующей определённому каналу ожидания. Функция `sleepq_lookup` " +"выполняет поиск в хеш-таблице главной очереди сна, связанной с заданным " +"каналом ожидания. Если главная очередь сна не найдена, функция возвращает " +"`NULL`. Функция `sleepq_release` разблокирует спин-мьютес, связанный с " +"заданным каналом ожидания." + +#. 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 "" +"Поток добавляется в очередь ожидания с помощью `sleepq_add`. Эта функция " +"принимает канал ожидания, указатель на мьютекс, защищающий канал ожидания, " +"строку описания сообщения ожидания и маску флагов. Цепь очереди ожидания " +"должна быть заблокирована с помощью `sleepq_lock` перед вызовом этой " +"функции. Если канал ожидания не защищен мьютексом (или защищен мьютексом " +"Giant), то аргумент указателя на мьютекс должен быть `NULL`. Аргумент флагов " +"содержит поле типа, указывающее на вид очереди ожидания, в которую " +"добавляется поток, и флаг, указывающий, является ли ожидание прерываемым " +"(`SLEEPQ_INTERRUPTIBLE`). В настоящее время существует только два типа " +"очередей ожидания: традиционные очереди, управляемые через функции `msleep` " +"и `wakeup` (`SLEEPQ_MSLEEP`), и очереди ожидания условных переменных " +"(`SLEEPQ_CONDVAR`). Тип очереди ожидания и аргумент указателя на блокировку " +"используются исключительно для внутренних проверок утверждений. Код, " +"вызывающий `sleepq_add`, должен явно разблокировать любой блокировочный " +"механизм, защищающий канал ожидания, после того как связанная цепь очереди " +"ожидания будет заблокирована через `sleepq_lock` и перед блокировкой в " +"очереди ожидания с помощью одной из функций ожидания." + +#. 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 "" +"Таймаут для сна устанавливается вызовом `sleepq_set_timeout`. Функция " +"принимает канал ожидания и время таймаута в виде относительного количества " +"тиков в качестве аргументов. Если сон должен быть прерван поступающими " +"сигналами, следует также вызвать функцию `sleepq_catch_signals`. Эта функция " +"принимает канал ожидания в качестве единственного параметра. Если для " +"данного потока уже есть ожидающий сигнал, то `sleepq_catch_signals` вернёт " +"номер сигнала; в противном случае она вернёт 0." + +#. 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 "" +"После добавления потока в очередь ожидания он блокируется с использованием " +"одной из функций `sleepq_wait`. Существует четыре функции ожидания в " +"зависимости от того, хочет ли вызывающий код использовать таймаут, " +"прерывание сна перехваченными сигналами или прерывание от планировщика " +"потоков пользовательского пространства. Функция `sleepq_wait` просто " +"ожидает, пока текущий поток не будет явно возобновлён одной из функций " +"пробуждения. Функция `sleepq_timedwait` ожидает, пока поток не будет явно " +"возобновлён или пока не истечёт таймаут, установленный предыдущим вызовом " +"`sleepq_set_timeout`. Функция `sleepq_wait_sig` ожидает, пока поток не будет " +"явно возобновлён или его сон не будет прерван. Функция " +"`sleepq_timedwait_sig` ожидает, пока поток не будет явно возобновлён, не " +"истечёт таймаут, установленный предыдущим вызовом `sleepq_set_timeout`, или " +"сон потока не будет прерван. Все функции ожидания принимают канал ожидания в " +"качестве первого параметра. Кроме того, функция `sleepq_timedwait_sig` " +"принимает второй логический параметр, указывающий, обнаружил ли предыдущий " +"вызов `sleepq_catch_signals` ожидающий сигнал." + +#. 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 "" +"Если поток явно возобновлен или прерван сигналом, функция ожидания " +"возвращает ноль, указывая на успешное завершение сна. Если поток возобновлен " +"по таймауту или прерыванию от планировщика потоков в пользовательском " +"пространстве, вместо этого возвращается соответствующее значение errno. " +"Обратите внимание, что поскольку `sleepq_wait` может возвращать только 0, " +"она ничего не возвращает, и вызывающая сторона должна считать сон успешным. " +"Также, если сон потока прерывается одновременно по таймауту и другим " +"причинам, `sleepq_timedwait_sig` вернет ошибку, указывающую на срабатывание " +"таймаута. Если возвращено значение ошибки 0 и для блокировки использовались " +"`sleepq_wait_sig` или `sleepq_timedwait_sig`, следует вызвать функцию " +"`sleepq_calc_signal_retval` для проверки ожидающих сигналов и вычисления " +"соответствующего возвращаемого значения, если таковые обнаружены. Номер " +"сигнала, полученный при предыдущем вызове `sleepq_catch_signals`, должен " +"быть передан в качестве единственного аргумента в " +"`sleepq_calc_signal_retval`." + +#. 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 "" +"Потоки, находящиеся в состоянии ожидания на канале ожидания, явно " +"возобновляются функциями `sleepq_broadcast` и `sleepq_signal`. Обе функции " +"принимают канал ожидания, с которого нужно возобновить потоки, приоритет, на " +"который нужно поднять возобновлённые потоки, и аргумент флагов, указывающий " +"тип очереди ожидания, которую нужно возобновить. Аргумент приоритета " +"трактуется как минимальный приоритет. Если у возобновляемого потока уже есть " +"более высокий приоритет (численно меньший), чем указанный в аргументе, его " +"приоритет не изменяется. Аргумент флагов используется для внутренних " +"проверок, чтобы гарантировать, что очереди ожидания не обрабатываются как " +"неправильный тип. Например, функции условных переменных не должны " +"возобновлять потоки на традиционной очереди ожидания. Функция " +"`sleepq_broadcast` возобновляет все потоки, заблокированные на указанном " +"канале ожидания, тогда как `sleepq_signal` возобновляет только поток с " +"наивысшим приоритетом, заблокированный на канале ожидания. Перед вызовом " +"этих функций цепочка очереди ожидания должна быть заблокирована с помощью " +"функции `sleepq_lock`." + +#. 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 "" +"Спящий поток может быть прерван с помощью вызова функции `sleepq_abort`. Эта " +"функция должна вызываться с удержанием `sched_lock`, а поток должен " +"находиться в очереди сна. Поток также может быть удалён из определённой " +"очереди сна с помощью функции `sleepq_remove`. Эта функция принимает как " +"поток, так и канал ожидания в качестве аргументов и пробуждает поток только " +"в том случае, если он находится в очереди сна для указанного канала " +"ожидания. Если поток не находится в очереди сна или находится в очереди сна " +"для другого канала ожидания, эта функция ничего не делает." + +#. 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 "Поиск/ожидание/освобождение. - Описать состояние гонки TDF_TSNOBLOCK." + +#. 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 "" +"Должны ли мы требовать владения мьютексами для `mtx_destroy()`, так как " +"иначе мы не можем безопасно утверждать, что они не принадлежат кому-либо ещё?" + +#. 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 "Мьютексы сна (Sleep Mutexes)" + +#. 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 "" +"Почему безопасно читать mtx_lock оспариваемой мьютекса при удержании " +"блокировки цепочки турникета." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:281 +#, no-wrap +msgid "Witness" +msgstr "Witness" + +#. 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 "Источники прерываний и абстракции ICU" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:293 +msgid "struct isrc" +msgstr "struct isrc" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:295 +msgid "pic drivers" +msgstr "pic драйверы" + +#. 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 "Передавать ли блокировку в `sema_wait`?" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:301 +msgid "Should we have non-sleepable sx locks?" +msgstr "Должны ли мы иметь sx блокировки без возможности сна?" + +#. 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 "atomic (атомарный)" + +#. 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 "См. также operation (операция)." + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:316 +#, no-wrap +msgid "block" +msgstr "block (блокировать)" + +#. 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 "См. также sleep (спать)." + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:321 +#, no-wrap +msgid "critical section" +msgstr "critical section (критическая секция)" + +#. 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 "" +"Фрагмент кода, который не может быть вытеснен. Критическая секция начинается " +"и завершается с использованием API man:critical_enter[9]." + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:324 +#, no-wrap +msgid "MD" +msgstr "MD" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:326 +msgid "Machine dependent." +msgstr "Машинозависимый (machine dependent)." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:328 +msgid "See Also MI." +msgstr "Смотри также MI." + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:329 +#, no-wrap +msgid "memory operation" +msgstr "memory operation (операция с памятью)" + +#. 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 "MI" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:334 +msgid "Machine independent." +msgstr "Машинно-независимый (machine independent)." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:336 +msgid "See Also MD." +msgstr "См. также MD." + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:337 +#, no-wrap +msgid "operation" +msgstr "operation (операция)" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:339 +msgid "See memory operation." +msgstr "См. memory operation (операция с памятью)." + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:340 +#, no-wrap +msgid "primary interrupt context" +msgstr "primary interrupt context (основной контекст прерывания)" + +#. 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 "realtime kernel thread (поток ядра реального времени)" + +#. 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 "См. также thread (поток)." + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:348 +#, no-wrap +msgid "sleep" +msgstr "sleep (спать)" + +#. 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 "" +"Поток находится в состоянии сна, когда он заблокирован на условной " +"переменной или в очереди сна через `msleep` или `tsleep`." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:352 +msgid "See Also block." +msgstr "См. также block (блокировать)." + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:353 +#, no-wrap +msgid "sleepable lock" +msgstr "sleepable lock (блокировка с возможностью сна)" + +#. 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 "" +"блокировка с возможностью сна — это блокировка, которая может удерживаться " +"потоком, находящимся в состоянии сна. В настоящее время в FreeBSD " +"единственными блокировками с возможностью сна являются lockmgr и sx. В " +"будущем некоторые sx-блокировки, такие как allproc и proctree, могут стать " +"блокировками с возможностью сна." + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:358 +#, no-wrap +msgid "thread" +msgstr "thread (поток)" + +#. 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 "" +"Поток ядра, представленный структурой `struct thread`. Потоки владеют " +"блокировками и содержат единственный на поток контекст выполнения." + +#. type: Labeled list +#: documentation/content/en/books/arch-handbook/smp/_index.adoc:361 +#, no-wrap +msgid "wait channel" +msgstr "wait channel (канал ожидания)" + +#. 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/ru/books/arch-handbook/sound/_index.adoc b/documentation/content/ru/books/arch-handbook/sound/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/sound/_index.adoc @@ -0,0 +1,351 @@ +--- +description: 'Звуковая подсистема FreeBSD' +next: books/arch-handbook/pccard +params: + path: /books/arch-handbook/sound/ +prev: books/arch-handbook/newbus +showBookMenu: true +tags: ["Sound", "OSS", "pcm", "mixer"] +title: 'Глава 15. Звуковая подсистема' +weight: 17 +--- + +[[oss]] += Звуковая подсистема +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 15 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[oss-intro]] +== Введение + +Подсистема звука FreeBSD чётко разделяет общие вопросы обработки звука и детали, специфичные для устройств. Это упрощает добавление поддержки нового оборудования. + +man:pcm[4] — это центральный компонент подсистемы звука. В основном он реализует следующие элементы: + +* Интерфейс системных вызовов (read, write, ioctls) для работы с оцифрованным звуком и функциями микшера. Набор команд ioctl совместим с устаревшим интерфейсом _OSS_ или _Voxware_, что позволяет портировать распространённые мультимедийные приложения без изменений. +* Общий код для обработки звуковых данных (преобразование форматов, виртуальные каналы). +* Единый программный интерфейс к аппаратно-зависимым модулям аудиоинтерфейсов. +* Дополнительная поддержка некоторых распространённых аппаратных интерфейсов (ac97) или общий код для специфичного оборудования (например: подпрограммы ISA DMA). + +Поддержка конкретных звуковых карт реализована аппаратно-специфичными драйверами, которые предоставляют интерфейсы каналов и микшера для подключения к общему коду [.filename]#pcm#. + +В этой главе термин [.filename]#pcm# будет относиться к центральной, общей части звукового драйвера, в отличие от аппаратно-зависимых модулей. + +Разработчик драйверов, только начинающий свою разработку, конечно, захочет начать с существующего модуля и использовать его код в качестве основного источника информации. Однако, хотя код подсистемы звука чист и аккуратен, он в основном лишён комментариев. Этот документ пытается дать обзор интерфейса фреймворка и ответить на некоторые вопросы, которые могут возникнуть при адаптации существующего кода. + +В качестве альтернативы или в дополнение к началу разработки с примера драйвера из кода системы, вы можете найти шаблон драйвера с комментариями по адресу https://people.FreeBSD.org/~cg/template.c[ https://people.FreeBSD.org/~cg/template.c] + +[[oss-files]] +== Файлы + +Весь соответствующий код находится в [.filename]#/usr/src/sys/dev/sound/#, за исключением определений публичного интерфейса ioctl, которые можно найти в [.filename]#/usr/src/sys/sys/soundcard.h# + +В каталоге [.filename]#/usr/src/sys/dev/sound/#, папка [.filename]#pcm/# содержит основной код, тогда как каталоги [.filename]#pci/#, [.filename]#isa/# и [.filename]#usb/# содержат драйверы для плат PCI и ISA, а также для USB-аудиоустройств. + +[[pcm-probe-and-attach]] +== Обнаружение, присоединение и т.д. + +Драйверы звуковых устройств выполняют обнаружение и подключение почти так же, как и любой модуль драйвера оборудования. Возможно, вам будет полезно ознакомиться с разделами руководства, посвящёнными crossref:isa-driver[isa-driver,ISA] или crossref:pci[pci,PCI], для получения дополнительной информации. + +Однако драйверы звука отличаются в некоторых аспектах: + +* Они объявляют себя как устройства класса [.filename]#pcm#, с приватной структурой устройства `struct snddev_info`: ++ +[.programlisting] +.... + static driver_t xxx_driver = { + "pcm", + xxx_methods, + sizeof(struct snddev_info) + }; + + DRIVER_MODULE(snd_xxxpci, pci, xxx_driver, pcm_devclass, 0, 0); + MODULE_DEPEND(snd_xxxpci, snd_pcm, PCM_MINVER, PCM_PREFVER,PCM_MAXVER); +.... ++ +Большинству звуковых драйверов необходимо хранить дополнительную приватную информацию о своём устройстве. Приватная структура данных обычно выделяется в процедуре attach. Её адрес передаётся в [.filename]#pcm# через вызовы `pcm_register()` и `mixer_init()`. [.filename]#pcm# позже передаёт обратно этот адрес в качестве параметра при вызовах интерфейсов звукового драйвера. +* Подпрограмма подключения звукового драйвера должна объявить свой интерфейс MIXER или AC97 для [.filename]#pcm#, вызвав `mixer_init()`. Для интерфейса MIXER это, в свою очередь, приводит к вызову crossref:sound[xxxmixer-init,`xxxmixer_init()`]. +* Функция подключения драйвера звука объявляет свою общую конфигурацию CHANNEL для [.filename]#pcm#, вызывая `pcm_register(dev, sc, nplay, nrec)`, где `sc` — это адрес структуры данных устройства, используемый при последующих вызовах из [.filename]#pcm#, а `nplay` и `nrec` — количество каналов воспроизведения и записи. +* Подпрограмма подключения звукового драйвера объявляет каждый из своих каналов вызовами `pcm_addchan()`. Это настраивает связующий слой канала в [.filename]#pcm# и, в свою очередь, вызывает вызов crossref:sound[xxxchannel-init,`xxxchannel_init()`]. +* Драйвер звука должен вызвать `pcm_unregister()` в процедуре отключения перед освобождением своих ресурсов. + +Существует два возможных способа работы с устройствами, не поддерживающими PnP: + +* Используйте метод `device_identify()` (пример: [.filename]#sound/isa/es1888.c#). Метод `device_identify()` проверяет наличие оборудования по известным адресам и, если находит поддерживаемое устройство, создает новое pcm-устройство, которое затем передается для probe/attach. +* Используйте пользовательскую конфигурацию ядра с соответствующими подсказками для устройств pcm (пример: [.filename]#sound/isa/mss.c#). + +[.filename]#pcm# драйверы должны реализовывать подпрограммы `device_suspend`, `device_resume` и `device_shutdown`, чтобы управление питанием и выгрузка модулей работали корректно. + +[[oss-interfaces]] +== Interfaces + +Интерфейс между ядром [.filename]#pcm# и звуковыми драйверами определяется в терминах crossref:kobj[kernel-objects,объектов ядра Kobj]. + +Существует два основных интерфейса, которые обычно предоставляет драйвер звука: _CHANNEL_ и либо _MIXER_, либо _AC97_. + +Интерфейс _AC97_ — это очень небольшой интерфейс доступа к оборудованию (чтение/запись регистров), реализованный драйверами для устройств с кодеком AC97. В этом случае фактический интерфейс MIXER предоставляется общим кодом AC97 в [.filename]#pcm#. + +=== Интерфейс CHANNEL + +==== Общие примечания для параметров функций + +Драйверы звука обычно имеют приватную структуру данных для описания своего устройства и по одной структуре для каждого канала воспроизведения и записи, который они поддерживают. + +Для всех функций интерфейса CHANNEL первый параметр — это непрозрачный указатель. + +Второй параметр представляет собой указатель на приватную структуру данных канала, за исключением `channel_init()`, где передается указатель на приватную структуру устройства (и возвращается указатель на канал для дальнейшего использования [.filename]#pcm#). + +==== Обзор операций передачи данных + +Для надежной передачи звуковых данных ядро [.filename]#pcm# и драйверы звука взаимодействуют через общую область памяти, описываемую структурой `struct snd_dbuf`. + +`struct snd_dbuf` является приватной для [.filename]#pcm#, и драйверы звука получают нужные значения через вызовы функций доступа (`sndbuf_getxxx()`). + +Область разделяемой памяти имеет размер `sndbuf_getsize()` и разделена на блоки фиксированного размера по `sndbuf_getblksz()` байт. + +При воспроизведении общий механизм передачи выглядит следующим образом (для записи идея обратная): + +* [.filename]#pcm# сначала заполняет буфер, затем вызывает функцию crossref:sound[channel-trigger,`xxxchannel_trigger()`] драйвера звука с параметром PCMTRIG_START. +* Звуковой драйвер затем организует повторяющуюся передачу всей области памяти (`sndbuf_getbuf()`, `sndbuf_getsize()`) на устройство блоками по `sndbuf_getblksz()` байт. Для каждого переданного блока он вызывает функцию `chn_intr()`[.filename]#pcm# (обычно это происходит во время прерывания). +* `chn_intr()` организует копирование новых данных в область, которая была передана устройству (теперь свободна), и вносит соответствующие обновления в структуру `snd_dbuf`. + +[[xxxchannel-init]] +==== channel_init + +`xxxchannel_init()` вызывается для инициализации каждого из каналов воспроизведения или записи. Вызовы инициируются из процедуры присоединения драйвера звука. (См. раздел crossref:sound[pcm-probe-and-attach,зондирование и присоединение]). + +[.programlisting] +.... + static void * + xxxchannel_init(kobj_t obj, void *data, + struct snd_dbuf *b, struct pcm_channel *c, int dir) <.> + { + struct xxx_info *sc = data; + struct xxx_chinfo *ch; + ... + return ch; <.> + } +.... + +<.> `b` — это адрес для канала `struct snd_dbuf`. Он должен быть инициализирован в функции вызовом `sndbuf_alloc()`. Размер буфера, который следует использовать, обычно представляет собой небольшое кратное от 'типичного' размера единицы передачи данных для вашего устройства. `c` — это указатель на структуру управления каналом [.filename]#pcm#. Это непрозрачный объект. Функция должна сохранить его в локальной структуре канала для использования в последующих вызовах [.filename]#pcm# (например: `chn_intr(c)`). `dir` указывает направление канала (`PCMDIR_PLAY` или `PCMDIR_REC`). + +<.> Функция должна возвращать указатель на приватную область, используемую для управления этим каналом. Этот указатель будет передаваться в качестве параметра при других вызовах интерфейса канала. + +==== channel_setformat + +`xxxchannel_setformat()` должен настроить оборудование для указанного канала под указанный звуковой формат. + +[.programlisting] +.... + static int + xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format) <.> + { + struct xxx_chinfo *ch = data; + ... + return 0; + } +.... + +<.> `format` указывается как значение `AFMT_XXX` ([.filename]#soundcard.h#). + +==== channel_setspeed + +`xxxchannel_setspeed()` настраивает оборудование канала для указанной скорости дискретизации и возвращает возможно скорректированную скорость. + +[.programlisting] +.... + static int + xxxchannel_setspeed(kobj_t obj, void *data, u_int32_t speed) + { + struct xxx_chinfo *ch = data; + ... + return speed; + } +.... + +==== channel_setblocksize + +`xxxchannel_setblocksize()` устанавливает размер блока, который является размером единичных транзакций между [.filename]#pcm# и звуковым драйвером, а также между звуковым драйвером и устройством. Обычно это количество байт, передаваемых до возникновения прерывания. Во время передачи звуковой драйвер должен вызывать `chn_intr()` из [.filename]#pcm# каждый раз, когда передается данный размер. + +Большинство драйверов звука здесь учитывают только размер блока, который будет использоваться при начале фактической передачи. + +[.programlisting] +.... + static int + xxxchannel_setblocksize(kobj_t obj, void *data, u_int32_t blocksize) + { + struct xxx_chinfo *ch = data; + ... + return blocksize; <.> + } +.... + +<.> Функция возвращает, возможно, скорректированный размер блока. Если размер блока действительно изменён, следует вызвать `sndbuf_resize()` для корректировки буфера. + +[[channel-trigger]] +==== channel_trigger + +`xxxchannel_trigger()` вызывается [.filename]#pcm# для управления операциями передачи данных в драйвере. + +[.programlisting] +.... + static int + xxxchannel_trigger(kobj_t obj, void *data, int go) <.> + { + struct xxx_chinfo *ch = data; + ... + return 0; + } +.... + +<.> `go` определяет действие для текущего вызова. Возможные значения: + +[NOTE] +==== +Если драйвер использует ISA DMA, перед выполнением действий с устройством следует вызвать `sndbuf_isadma()`, которая позаботится о том, что делает DMA-чип. +==== + +==== channel_getptr + +`xxxchannel_getptr()` возвращает текущее смещение в буфере передачи. Обычно этот вызов выполняется функцией `chn_intr()`, и именно так [.filename]#pcm# узнаёт, куда можно передавать новые данные. + +==== channel_free + +`xxxchannel_free()` вызывается для освобождения ресурсов канала, например, при выгрузке драйвера, и должна быть реализована, если структуры данных канала динамически выделены или если `sndbuf_alloc()` не использовалась для выделения буфера. + +==== channel_getcaps + +[.programlisting] +.... + struct pcmchan_caps * + xxxchannel_getcaps(kobj_t obj, void *data) + { + return &xxx_caps; <.> + } +.... + +<.> Подпрограмма возвращает указатель на (обычно статически определённую) структуру `pcmchan_caps` (определена в [.filename]#sound/pcm/channel.h#). Эта структура содержит минимальную и максимальную частоты дискретизации, а также поддерживаемые звуковые форматы. Пример можно найти в любом драйвере звукового устройства. + +==== Дополнительные Функции + +`channel_reset()`, `channel_resetdone()` и `channel_notify()` предназначены для специальных целей и не должны реализовываться в драйвере без обсуждения на {freebsd-multimedia}. + +`channel_setdir()` устарела. + +=== Интерфейс MIXER + +[[xxxmixer-init]] +==== mixer_init + +`xxxmixer_init()` инициализирует оборудование и сообщает [.filename]#pcm#, какие устройства микшера доступны для воспроизведения и записи + +[.programlisting] +.... + static int + xxxmixer_init(struct snd_mixer *m) + { + struct xxx_info *sc = mix_getdevinfo(m); + u_int32_t v; + + [Initialize hardware] + + [Set appropriate bits in v for play mixers] <.> + mix_setdevs(m, v); + [Set appropriate bits in v for record mixers] + mix_setrecdevs(m, v) + + return 0; + } +.... + +<.> Установите биты в целочисленном значении и вызовите `mix_setdevs()` и `mix_setrecdevs()`, чтобы сообщить [.filename]#pcm#, какие устройства существуют. + +Определения битов микшера можно найти в [.filename]#soundcard.h# (значения `SOUND_MASK_XXX` и сдвиги битов `SOUND_MIXER_XXX`). + +==== mixer_set + +`xxxmixer_set()` устанавливает уровень громкости для одного устройства микшера. + +[.programlisting] +.... + static int + xxxmixer_set(struct snd_mixer *m, unsigned dev, + unsigned left, unsigned right) <.> + { + struct sc_info *sc = mix_getdevinfo(m); + [set volume level] + return left | (right << 8); <.> + } +.... + +<.> Устройство указывается как значение `SOUND_MIXER_XXX`. Значения громкости задаются в диапазоне [0-100]. Значение ноль должно отключать звук устройства. +<.> Поскольку уровни оборудования, вероятно, не совпадут с входной шкалой и будет происходить округление, процедура возвращает фактические значения уровней (в диапазоне 0-100), как показано. + +==== mixer_setrecsrc + +`xxxmixer_setrecsrc()` устанавливает устройство источника записи. + +[.programlisting] +.... + static int + xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src) <.> + { + struct xxx_info *sc = mix_getdevinfo(m); + + [look for non zero bit(s) in src, set up hardware] + + [update src to reflect actual action] + return src; <.> + } +.... + +<.> Желаемые устройства записи указываются в виде битового поля +<.> Возвращаются фактические устройства, настроенные для записи. Некоторые драйверы могут настраивать только одно устройство для записи. Функция должна возвращать -1 в случае ошибки. + +==== mixer_uninit, mixer_reinit + +`xxxmixer_uninit()` должен гарантировать, что весь звук отключен, и, если возможно, аппаратный микшер должен быть переведен в режим пониженного энергопотребления. + +`xxxmixer_reinit()` должна гарантировать, что аппаратура микшера включена и все настройки, не управляемые `mixer_set()` или `mixer_setrecsrc()`, восстановлены. + +=== Интерфейс AC97 + +Интерфейс _AC97_ реализован драйверами с кодеком AC97. У него есть только три метода: + +* `xxxac97_init()` возвращает количество найденных кодеков ac97. +* `ac97_read()` и `ac97_write()` читают или записывают указанный регистр. + +Интерфейс _AC97_ используется кодом AC97 в [.filename]#pcm# для выполнения операций более высокого уровня. В качестве примера можно посмотреть [.filename]#sound/pci/maestro3.c# или другие файлы в [.filename]#sound/pci/#. diff --git a/documentation/content/ru/books/arch-handbook/sound/_index.po b/documentation/content/ru/books/arch-handbook/sound/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/sound/_index.po @@ -0,0 +1,1125 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-12 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\n" + +#. type: Yaml Front Matter Hash Value: description +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:1 +#, no-wrap +msgid "FreeBSD Sound Subsystem" +msgstr "Звуковая подсистема FreeBSD" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:1 +#, no-wrap +msgid "Chapter 15. Sound Subsystem" +msgstr "Глава 15. Звуковая подсистема" + +#. 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 "" +"Подсистема звука FreeBSD чётко разделяет общие вопросы обработки звука и " +"детали, специфичные для устройств. Это упрощает добавление поддержки нового " +"оборудования." + +#. 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 "" +"man:pcm[4] — это центральный компонент подсистемы звука. В основном он " +"реализует следующие элементы:" + +#. 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 "" +"Интерфейс системных вызовов (read, write, ioctls) для работы с оцифрованным " +"звуком и функциями микшера. Набор команд ioctl совместим с устаревшим " +"интерфейсом _OSS_ или _Voxware_, что позволяет портировать распространённые " +"мультимедийные приложения без изменений." + +#. 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 "" +"Дополнительная поддержка некоторых распространённых аппаратных интерфейсов " +"(ac97) или общий код для специфичного оборудования (например: подпрограммы " +"ISA DMA)." + +#. 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 "" +"Поддержка конкретных звуковых карт реализована аппаратно-специфичными " +"драйверами, которые предоставляют интерфейсы каналов и микшера для " +"подключения к общему коду [.filename]#pcm#." + +#. 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 "" +"В этой главе термин [.filename]#pcm# будет относиться к центральной, общей " +"части звукового драйвера, в отличие от аппаратно-зависимых модулей." + +#. 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 "" +"В качестве альтернативы или в дополнение к началу разработки с примера " +"драйвера из кода системы, вы можете найти шаблон драйвера с комментариями по " +"адресу https://people.FreeBSD.org/~cg/template.c[ https://people.FreeBSD.org/" +"~cg/template.c]" + +#. 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 "" +"Весь соответствующий код находится в [.filename]#/usr/src/sys/dev/sound/#, " +"за исключением определений публичного интерфейса ioctl, которые можно найти " +"в [.filename]#/usr/src/sys/sys/soundcard.h#" + +#. 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 "" +"В каталоге [.filename]#/usr/src/sys/dev/sound/#, папка [.filename]#pcm/# " +"содержит основной код, тогда как каталоги [.filename]#pci/#, [.filename]#isa/" +"# и [.filename]#usb/# содержат драйверы для плат PCI и ISA, а также для USB-" +"аудиоустройств." + +#. 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 "" +"Драйверы звуковых устройств выполняют обнаружение и подключение почти так " +"же, как и любой модуль драйвера оборудования. Возможно, вам будет полезно " +"ознакомиться с разделами руководства, посвящёнными crossref:isa-driver[isa-" +"driver,ISA] или crossref:pci[pci,PCI], для получения дополнительной " +"информации." + +#. 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 "" +"Они объявляют себя как устройства класса [.filename]#pcm#, с приватной " +"структурой устройства `struct snddev_info`:" + +#. 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 "" +" static driver_t xxx_driver = {\n" +" \"pcm\",\n" +" xxx_methods,\n" +" sizeof(struct snddev_info)\n" +" };\n" + +#. 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 "" +" 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" + +#. 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 "" +"Большинству звуковых драйверов необходимо хранить дополнительную приватную " +"информацию о своём устройстве. Приватная структура данных обычно выделяется " +"в процедуре attach. Её адрес передаётся в [.filename]#pcm# через вызовы " +"`pcm_register()` и `mixer_init()`. [.filename]#pcm# позже передаёт обратно " +"этот адрес в качестве параметра при вызовах интерфейсов звукового драйвера." + +#. 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 "" +"Подпрограмма подключения звукового драйвера должна объявить свой интерфейс " +"MIXER или AC97 для [.filename]#pcm#, вызвав `mixer_init()`. Для интерфейса " +"MIXER это, в свою очередь, приводит к вызову crossref:sound[xxxmixer-" +"init,`xxxmixer_init()`]." + +#. 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 "" +"Функция подключения драйвера звука объявляет свою общую конфигурацию CHANNEL " +"для [.filename]#pcm#, вызывая `pcm_register(dev, sc, nplay, nrec)`, где `sc` " +"— это адрес структуры данных устройства, используемый при последующих " +"вызовах из [.filename]#pcm#, а `nplay` и `nrec` — количество каналов " +"воспроизведения и записи." + +#. 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 "" +"Подпрограмма подключения звукового драйвера объявляет каждый из своих " +"каналов вызовами `pcm_addchan()`. Это настраивает связующий слой канала в " +"[.filename]#pcm# и, в свою очередь, вызывает вызов crossref:sound[xxxchannel-" +"init,`xxxchannel_init()`]." + +#. 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 "" +"Драйвер звука должен вызвать `pcm_unregister()` в процедуре отключения перед " +"освобождением своих ресурсов." + +#. 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 "" +"Существует два возможных способа работы с устройствами, не поддерживающими " +"PnP:" + +#. 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 "" +"Используйте метод `device_identify()` (пример: [.filename]#sound/isa/" +"es1888.c#). Метод `device_identify()` проверяет наличие оборудования по " +"известным адресам и, если находит поддерживаемое устройство, создает новое " +"pcm-устройство, которое затем передается для probe/attach." + +#. 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 "" +"Используйте пользовательскую конфигурацию ядра с соответствующими " +"подсказками для устройств pcm (пример: [.filename]#sound/isa/mss.c#)." + +#. 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 "" +"[.filename]#pcm# драйверы должны реализовывать подпрограммы " +"`device_suspend`, `device_resume` и `device_shutdown`, чтобы управление " +"питанием и выгрузка модулей работали корректно." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:117 +#, no-wrap +msgid "Interfaces" +msgstr "Interfaces" + +#. 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 "" +"Интерфейс между ядром [.filename]#pcm# и звуковыми драйверами определяется в " +"терминах crossref:kobj[kernel-objects,объектов ядра Kobj]." + +#. 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 "" +"Существует два основных интерфейса, которые обычно предоставляет драйвер " +"звука: _CHANNEL_ и либо _MIXER_, либо _AC97_." + +#. 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 "" +"Интерфейс _AC97_ — это очень небольшой интерфейс доступа к оборудованию " +"(чтение/запись регистров), реализованный драйверами для устройств с кодеком " +"AC97. В этом случае фактический интерфейс MIXER предоставляется общим кодом " +"AC97 в [.filename]#pcm#." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:126 +#, no-wrap +msgid "The CHANNEL Interface" +msgstr "Интерфейс CHANNEL" + +#. 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 "" +"Для всех функций интерфейса CHANNEL первый параметр — это непрозрачный " +"указатель." + +#. 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 "" +"Второй параметр представляет собой указатель на приватную структуру данных " +"канала, за исключением `channel_init()`, где передается указатель на " +"приватную структуру устройства (и возвращается указатель на канал для " +"дальнейшего использования [.filename]#pcm#)." + +#. 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 "" +"Для надежной передачи звуковых данных ядро [.filename]#pcm# и драйверы звука " +"взаимодействуют через общую область памяти, описываемую структурой `struct " +"snd_dbuf`." + +#. 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 "" +"`struct snd_dbuf` является приватной для [.filename]#pcm#, и драйверы звука " +"получают нужные значения через вызовы функций доступа (`sndbuf_getxxx()`)." + +#. 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 "" +"Область разделяемой памяти имеет размер `sndbuf_getsize()` и разделена на " +"блоки фиксированного размера по `sndbuf_getblksz()` байт." + +#. 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 "" +"[.filename]#pcm# сначала заполняет буфер, затем вызывает функцию " +"crossref:sound[channel-trigger,`xxxchannel_trigger()`] драйвера звука с " +"параметром PCMTRIG_START." + +#. 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 "" +"Звуковой драйвер затем организует повторяющуюся передачу всей области памяти " +"(`sndbuf_getbuf()`, `sndbuf_getsize()`) на устройство блоками по " +"`sndbuf_getblksz()` байт. Для каждого переданного блока он вызывает функцию " +"`chn_intr()`[.filename]#pcm# (обычно это происходит во время прерывания)." + +#. 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 "" +"`chn_intr()` организует копирование новых данных в область, которая была " +"передана устройству (теперь свободна), и вносит соответствующие обновления в " +"структуру `snd_dbuf`." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:152 +#, no-wrap +msgid "channel_init" +msgstr "channel_init" + +#. 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 "" +"`xxxchannel_init()` вызывается для инициализации каждого из каналов " +"воспроизведения или записи. Вызовы инициируются из процедуры присоединения " +"драйвера звука. (См. раздел crossref:sound[pcm-probe-and-attach,зондирование " +"и присоединение])." + +#. 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 "" +" 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" + +#. 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 "" +"`b` — это адрес для канала `struct snd_dbuf`. Он должен быть инициализирован " +"в функции вызовом `sndbuf_alloc()`. Размер буфера, который следует " +"использовать, обычно представляет собой небольшое кратное от 'типичного' " +"размера единицы передачи данных для вашего устройства. `c` — это указатель " +"на структуру управления каналом [.filename]#pcm#. Это непрозрачный объект. " +"Функция должна сохранить его в локальной структуре канала для использования " +"в последующих вызовах [.filename]#pcm# (например: `chn_intr(c)`). `dir` " +"указывает направление канала (`PCMDIR_PLAY` или `PCMDIR_REC`)." + +#. 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 "channel_setformat" + +#. 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 "" +"`xxxchannel_setformat()` должен настроить оборудование для указанного канала " +"под указанный звуковой формат." + +#. 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 "" +" 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" + +#. 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 "" +"`format` указывается как значение `AFMT_XXX` ([.filename]#soundcard.h#)." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:191 +#, no-wrap +msgid "channel_setspeed" +msgstr "channel_setspeed" + +#. 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 "" +"`xxxchannel_setspeed()` настраивает оборудование канала для указанной " +"скорости дискретизации и возвращает возможно скорректированную скорость." + +#. 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 "" +" 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" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:206 +#, no-wrap +msgid "channel_setblocksize" +msgstr "channel_setblocksize" + +#. 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 "" +"`xxxchannel_setblocksize()` устанавливает размер блока, который является " +"размером единичных транзакций между [.filename]#pcm# и звуковым драйвером, а " +"также между звуковым драйвером и устройством. Обычно это количество байт, " +"передаваемых до возникновения прерывания. Во время передачи звуковой драйвер " +"должен вызывать `chn_intr()` из [.filename]#pcm# каждый раз, когда " +"передается данный размер." + +#. 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 "" +" 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" + +#. 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 "" +"Функция возвращает, возможно, скорректированный размер блока. Если размер " +"блока действительно изменён, следует вызвать `sndbuf_resize()` для " +"корректировки буфера." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:226 +#, no-wrap +msgid "channel_trigger" +msgstr "channel_trigger" + +#. 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 "" +"`xxxchannel_trigger()` вызывается [.filename]#pcm# для управления операциями " +"передачи данных в драйвере." + +#. 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 "" +" 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" + +#. 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 "`go` определяет действие для текущего вызова. Возможные значения:" + +#. 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 "" +"Если драйвер использует ISA DMA, перед выполнением действий с устройством " +"следует вызвать `sndbuf_isadma()`, которая позаботится о том, что делает DMA-" +"чип." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:248 +#, no-wrap +msgid "channel_getptr" +msgstr "channel_getptr" + +#. 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 "" +"`xxxchannel_getptr()` возвращает текущее смещение в буфере передачи. Обычно " +"этот вызов выполняется функцией `chn_intr()`, и именно так [.filename]#pcm# " +"узнаёт, куда можно передавать новые данные." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:252 +#, no-wrap +msgid "channel_free" +msgstr "channel_free" + +#. 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 "" +"`xxxchannel_free()` вызывается для освобождения ресурсов канала, например, " +"при выгрузке драйвера, и должна быть реализована, если структуры данных " +"канала динамически выделены или если `sndbuf_alloc()` не использовалась для " +"выделения буфера." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:256 +#, no-wrap +msgid "channel_getcaps" +msgstr "channel_getcaps" + +#. 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 "" +" struct pcmchan_caps *\n" +" xxxchannel_getcaps(kobj_t obj, void *data)\n" +" {\n" +" return &xxx_caps; <.>\n" +" }\n" + +#. 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 "" +"Подпрограмма возвращает указатель на (обычно статически определённую) " +"структуру `pcmchan_caps` (определена в [.filename]#sound/pcm/channel.h#). " +"Эта структура содержит минимальную и максимальную частоты дискретизации, а " +"также поддерживаемые звуковые форматы. Пример можно найти в любом драйвере " +"звукового устройства." + +#. 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 "" +"`channel_reset()`, `channel_resetdone()` и `channel_notify()` предназначены " +"для специальных целей и не должны реализовываться в драйвере без обсуждения " +"на {freebsd-multimedia}." + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:274 +msgid "`channel_setdir()` is deprecated." +msgstr "`channel_setdir()` устарела." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:275 +#, no-wrap +msgid "The MIXER Interface" +msgstr "Интерфейс MIXER" + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:278 +#, no-wrap +msgid "mixer_init" +msgstr "mixer_init" + +#. 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 "" +"`xxxmixer_init()` инициализирует оборудование и сообщает [.filename]#pcm#, " +"какие устройства микшера доступны для воспроизведения и записи" + +#. 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 "" +" static int\n" +" xxxmixer_init(struct snd_mixer *m)\n" +" {\n" +" struct xxx_info *sc = mix_getdevinfo(m);\n" +" u_int32_t v;\n" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:291 +#, no-wrap +msgid " [Initialize hardware]\n" +msgstr " [Initialize hardware]\n" + +#. 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 "" +" [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" + +#. type: delimited block . 4 +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:299 +#, no-wrap +msgid "" +" return 0;\n" +" }\n" +msgstr "" +" return 0;\n" +" }\n" + +#. 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 "" +"Установите биты в целочисленном значении и вызовите `mix_setdevs()` и " +"`mix_setrecdevs()`, чтобы сообщить [.filename]#pcm#, какие устройства " +"существуют." + +#. 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 "" +"Определения битов микшера можно найти в [.filename]#soundcard.h# (значения " +"`SOUND_MASK_XXX` и сдвиги битов `SOUND_MIXER_XXX`)." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:305 +#, no-wrap +msgid "mixer_set" +msgstr "mixer_set" + +#. 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 "" +"`xxxmixer_set()` устанавливает уровень громкости для одного устройства " +"микшера." + +#. 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 "" +" 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" + +#. 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 "" +"Устройство указывается как значение `SOUND_MIXER_XXX`. Значения громкости " +"задаются в диапазоне [0-100]. Значение ноль должно отключать звук устройства." + +#. 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 "" +"Поскольку уровни оборудования, вероятно, не совпадут с входной шкалой и " +"будет происходить округление, процедура возвращает фактические значения " +"уровней (в диапазоне 0-100), как показано." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:324 +#, no-wrap +msgid "mixer_setrecsrc" +msgstr "mixer_setrecsrc" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:327 +msgid "`xxxmixer_setrecsrc()` sets the recording source device." +msgstr "`xxxmixer_setrecsrc()` устанавливает устройство источника записи." + +#. 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 "" +" static int\n" +" xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src) <.>\n" +" {\n" +" struct xxx_info *sc = mix_getdevinfo(m);\n" + +#. 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 " [look for non zero bit(s) in src, set up hardware]\n" + +#. 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 "" +" [update src to reflect actual action]\n" +" return src; <.>\n" +" }\n" + +#. 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 "" +"Возвращаются фактические устройства, настроенные для записи. Некоторые " +"драйверы могут настраивать только одно устройство для записи. Функция должна " +"возвращать -1 в случае ошибки." + +#. type: Title ==== +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:345 +#, no-wrap +msgid "mixer_uninit, mixer_reinit" +msgstr "mixer_uninit, mixer_reinit" + +#. 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 "" +"`xxxmixer_uninit()` должен гарантировать, что весь звук отключен, и, если " +"возможно, аппаратный микшер должен быть переведен в режим пониженного " +"энергопотребления." + +#. 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 "" +"`xxxmixer_reinit()` должна гарантировать, что аппаратура микшера включена и " +"все настройки, не управляемые `mixer_set()` или `mixer_setrecsrc()`, " +"восстановлены." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:351 +#, no-wrap +msgid "The AC97 Interface" +msgstr "Интерфейс AC97" + +#. 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 "" +"Интерфейс _AC97_ реализован драйверами с кодеком AC97. У него есть только " +"три метода:" + +#. type: Plain text +#: documentation/content/en/books/arch-handbook/sound/_index.adoc:356 +msgid "`xxxac97_init()` returns the number of ac97 codecs found." +msgstr "`xxxac97_init()` возвращает количество найденных кодеков ac97." + +#. 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 "" +"`ac97_read()` и `ac97_write()` читают или записывают указанный регистр." + +#. 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 "" +"Интерфейс _AC97_ используется кодом AC97 в [.filename]#pcm# для выполнения " +"операций более высокого уровня. В качестве примера можно посмотреть " +"[.filename]#sound/pci/maestro3.c# или другие файлы в [.filename]#sound/pci/#." diff --git a/documentation/content/ru/books/arch-handbook/sysinit/_index.adoc b/documentation/content/ru/books/arch-handbook/sysinit/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/sysinit/_index.adoc @@ -0,0 +1,165 @@ +--- +description: 'Фреймворк SYSINIT' +next: books/arch-handbook/mac +params: + path: /books/arch-handbook/sysinit/ +prev: books/arch-handbook/jail +showBookMenu: true +tags: ["SYSINIT", "framework", "Terminology"] +title: 'Глава 5. Фреймворк SYSINIT' +weight: 6 +--- + +[[sysinit]] += Фреймворк SYSINIT +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 5 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +SYSINIT — это фреймворк для общего механизма сортировки и диспетчеризации вызовов. В настоящее время FreeBSD использует его для динамической инициализации ядра. SYSINIT позволяет изменять порядок, добавлять, удалять и заменять подсистемы ядра FreeBSD во время линковки ядра при загрузке ядра или его модулей, без необходимости редактировать статически упорядоченные маршруты инициализации и перекомпилировать ядро. Эта система также позволяет модулям ядра (в настоящее время называемым _KLD_) компилироваться, линковаться и инициализироваться отдельно во время загрузки, а также загружаться позже, когда система уже работает. Это достигается с помощью «компоновщика ядра» (kernel linker) и «наборов компоновщика» (linker sets). + +[[sysinit-term]] +== Терминология + +Набор компоновщика (Linker Set):: +Техника компоновщика, при которой компоновщик собирает статически объявленные данные из всех исходных файлов программы в единый непрерывно адресуемый блок данных. + +[[sysinit-operation]] +== Работа механизма SYSINIT + +SYSINIT полагается на способность компоновщика объединять статические данные, объявленные в нескольких местах исходного кода программы, в единый непрерывный блок данных. Этот метод компоновщика называется "набором компоновщика" (linker set). SYSINIT использует два набора компоновщика для поддержки двух наборов данных, содержащих порядок вызова, функцию и указатель на данные, передаваемые этой функции для каждого члена этих наборов данных. + +SYSINIT использует два приоритета для упорядочивания функций при выполнении. Первый приоритет — это идентификатор подсистемы, задающий общий порядок вызова функций SYSINIT. Предварительно объявленные идентификаторы находятся в [.filename]## в перечислении `sysinit_sub_id`. Второй используемый приоритет — это порядок элементов внутри подсистемы. Предварительно объявленные порядки элементов подсистемы находятся в [.filename]## в перечислении `sysinit_elem_order`. + +В настоящее время существует два варианта использования `SYSINIT`: вызов функций при загрузке системы и загрузке модулей ядра, а также вызов функций при завершении работы системы и выгрузке модулей ядра. Подсистемы ядра часто используют `SYSINIT` при старте системы для инициализации структур данных. Например, подсистема планирования процессов использует `SYSINIT` для инициализации структуры данных очереди выполнения. Драйверы устройств должны избегать прямого использования `SYSINIT()`. Вместо этого драйверы реальных устройств, входящих в структуру шины, должны использовать `DRIVER_MODULE()`, который предоставляет функцию для обнаружения устройства и, если оно присутствует, его инициализации. Этот макрос выполняет несколько действий, специфичных для устройств, а затем вызывает `SYSINIT()` самостоятельно. Для псевдоустройств, которые не входят в структуру шины, следует использовать `DEV_MODULE()`. + +[[sysinit-using]] +== Использование SYSINIT + +=== Интерфейс + +==== Заголовки + +[.programlisting] +.... + +.... + +==== Макросы + +[.programlisting] +.... +SYSINIT(uniquifier, subsystem, order, func, ident) +SYSUNINIT(uniquifier, subsystem, order, func, ident) +.... + +=== Запуск + +Макрос `SYSINIT()` создает необходимые данные SYSINIT в наборе данных инициализации системы, чтобы SYSINIT мог отсортировать и выполнить функцию при запуске системы и загрузке модуля. `SYSINIT()` принимает уникальный идентификатор, который SYSINIT использует для идентификации конкретных данных вызова функции, порядок подсистемы, порядок элемента подсистемы, функцию для вызова и данные для передачи в функцию. Все функции должны принимать аргумент в виде константного указателя. + +.Пример `SYSINIT()` +[example] +==== +[.programlisting] +.... +#include + +void foo_null(void *unused) +{ + foo_doo(); +} +SYSINIT(foo, SI_SUB_FOO, SI_ORDER_FOO, foo_null, NULL); + +struct foo foo_voodoo = { + FOO_VOODOO; +} + +void foo_arg(void *vdata) +{ + struct foo *foo = (struct foo *)vdata; + foo_data(foo); +} +SYSINIT(bar, SI_SUB_FOO, SI_ORDER_FOO, foo_arg, &foo_voodoo); +.... +==== + +Обратите внимание, что `SI_SUB_FOO` и `SI_ORDER_FOO` должны быть в перечислениях `sysinit_sub_id` и `sysinit_elem_order`, как упоминалось выше. Можно использовать существующие значения или добавить свои в эти перечисления. Также можно использовать математические операции для точной настройки порядка выполнения SYSINIT. В этом примере показан SYSINIT, который должен выполняться непосредственно перед SYSINIT, обрабатывающими настройку параметров ядра. + +.Пример настройки порядка `SYSINIT()` +[example] +==== +[.programlisting] +.... +static void +mptable_register(void *dummy __unused) +{ + + apic_register_enumerator(&mptable_enumerator); +} + +SYSINIT(mptable_register, SI_SUB_TUNABLES - 1, SI_ORDER_FIRST, + mptable_register, NULL); +.... + +==== + +=== Выключение системы + +Макрос `SYSUNINIT()` ведет себя аналогично макросу `SYSINIT()`, за исключением того, что добавляет данные SYSINIT в набор данных завершения работы SYSINIT. + +.Пример `SYSUNINIT()` +[example] +==== +[.programlisting] +.... +#include + +void foo_cleanup(void *unused) +{ + foo_kill(); +} +SYSUNINIT(foobar, SI_SUB_FOO, SI_ORDER_FOO, foo_cleanup, NULL); + +struct foo_stack foo_stack = { + FOO_STACK_VOODOO; +} + +void foo_flush(void *vdata) +{ +} +SYSUNINIT(barfoo, SI_SUB_FOO, SI_ORDER_FOO, foo_flush, &foo_stack); +.... + +==== diff --git a/documentation/content/ru/books/arch-handbook/sysinit/_index.po b/documentation/content/ru/books/arch-handbook/sysinit/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/sysinit/_index.po @@ -0,0 +1,393 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-02 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\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 "Фреймворк SYSINIT" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:1 +#, no-wrap +msgid "Chapter 5. The SYSINIT Framework" +msgstr "Глава 5. Фреймворк SYSINIT" + +#. 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 "" +"SYSINIT — это фреймворк для общего механизма сортировки и диспетчеризации " +"вызовов. В настоящее время FreeBSD использует его для динамической " +"инициализации ядра. SYSINIT позволяет изменять порядок, добавлять, удалять и " +"заменять подсистемы ядра FreeBSD во время линковки ядра при загрузке ядра " +"или его модулей, без необходимости редактировать статически упорядоченные " +"маршруты инициализации и перекомпилировать ядро. Эта система также позволяет " +"модулям ядра (в настоящее время называемым _KLD_) компилироваться, " +"линковаться и инициализироваться отдельно во время загрузки, а также " +"загружаться позже, когда система уже работает. Это достигается с помощью " +"«компоновщика ядра» (kernel linker) и «наборов компоновщика» (linker sets)." + +#. 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 "Набор компоновщика (Linker Set)" + +#. 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 "Работа механизма SYSINIT" + +#. 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 "" +"SYSINIT полагается на способность компоновщика объединять статические " +"данные, объявленные в нескольких местах исходного кода программы, в единый " +"непрерывный блок данных. Этот метод компоновщика называется \"набором " +"компоновщика\" (linker set). SYSINIT использует два набора компоновщика для " +"поддержки двух наборов данных, содержащих порядок вызова, функцию и " +"указатель на данные, передаваемые этой функции для каждого члена этих " +"наборов данных." + +#. 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]## 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]## in the enum list " +"`sysinit_elem_order`." +msgstr "" +"SYSINIT использует два приоритета для упорядочивания функций при выполнении. " +"Первый приоритет — это идентификатор подсистемы, задающий общий порядок " +"вызова функций SYSINIT. Предварительно объявленные идентификаторы находятся " +"в [.filename]## в перечислении `sysinit_sub_id`. Второй " +"используемый приоритет — это порядок элементов внутри подсистемы. " +"Предварительно объявленные порядки элементов подсистемы находятся в " +"[.filename]## в перечислении `sysinit_elem_order`." + +#. 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 "" +"В настоящее время существует два варианта использования `SYSINIT`: вызов " +"функций при загрузке системы и загрузке модулей ядра, а также вызов функций " +"при завершении работы системы и выгрузке модулей ядра. Подсистемы ядра часто " +"используют `SYSINIT` при старте системы для инициализации структур данных. " +"Например, подсистема планирования процессов использует `SYSINIT` для " +"инициализации структуры данных очереди выполнения. Драйверы устройств должны " +"избегать прямого использования `SYSINIT()`. Вместо этого драйверы реальных " +"устройств, входящих в структуру шины, должны использовать `DRIVER_MODULE()`, " +"который предоставляет функцию для обнаружения устройства и, если оно " +"присутствует, его инициализации. Этот макрос выполняет несколько действий, " +"специфичных для устройств, а затем вызывает `SYSINIT()` самостоятельно. Для " +"псевдоустройств, которые не входят в структуру шины, следует использовать " +"`DEV_MODULE()`." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:69 +#, no-wrap +msgid "Using SYSINIT" +msgstr "Использование SYSINIT" + +#. 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 "\n" +msgstr "\n" + +#. 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 "" +"SYSINIT(uniquifier, subsystem, order, func, ident)\n" +"SYSUNINIT(uniquifier, subsystem, order, func, ident)\n" + +#. 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 "" +"Макрос `SYSINIT()` создает необходимые данные SYSINIT в наборе данных " +"инициализации системы, чтобы SYSINIT мог отсортировать и выполнить функцию " +"при запуске системы и загрузке модуля. `SYSINIT()` принимает уникальный " +"идентификатор, который SYSINIT использует для идентификации конкретных " +"данных вызова функции, порядок подсистемы, порядок элемента подсистемы, " +"функцию для вызова и данные для передачи в функцию. Все функции должны " +"принимать аргумент в виде константного указателя." + +#. type: Block title +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:92 +#, no-wrap +msgid "Example of a `SYSINIT()`" +msgstr "Пример `SYSINIT()`" + +#. 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 \n" +msgstr "#include \n" + +#. 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 "" +"void foo_null(void *unused)\n" +"{\n" +" foo_doo();\n" +"}\n" +"SYSINIT(foo, SI_SUB_FOO, SI_ORDER_FOO, foo_null, NULL);\n" + +#. 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 "" +"struct foo foo_voodoo = {\n" +" FOO_VOODOO;\n" +"}\n" + +#. 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 "" +"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" + +#. 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 "" +"Обратите внимание, что `SI_SUB_FOO` и `SI_ORDER_FOO` должны быть в " +"перечислениях `sysinit_sub_id` и `sysinit_elem_order`, как упоминалось выше. " +"Можно использовать существующие значения или добавить свои в эти " +"перечисления. Также можно использовать математические операции для точной " +"настройки порядка выполнения SYSINIT. В этом примере показан SYSINIT, " +"который должен выполняться непосредственно перед SYSINIT, обрабатывающими " +"настройку параметров ядра." + +#. type: Block title +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:120 +#, no-wrap +msgid "Example of Adjusting `SYSINIT()` Order" +msgstr "Пример настройки порядка `SYSINIT()`" + +#. 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 "" +"static void\n" +"mptable_register(void *dummy __unused)\n" +"{\n" + +#. 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 "" +"\tapic_register_enumerator(&mptable_enumerator);\n" +"}\n" + +#. 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 "" +"SYSINIT(mptable_register, SI_SUB_TUNABLES - 1, SI_ORDER_FIRST,\n" +" mptable_register, NULL);\n" + +#. 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 "" +"Макрос `SYSUNINIT()` ведет себя аналогично макросу `SYSINIT()`, за " +"исключением того, что добавляет данные SYSINIT в набор данных завершения " +"работы SYSINIT." + +#. type: Block title +#: documentation/content/en/books/arch-handbook/sysinit/_index.adoc:142 +#, no-wrap +msgid "Example of a `SYSUNINIT()`" +msgstr "Пример `SYSUNINIT()`" + +#. 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 "" +"void foo_cleanup(void *unused)\n" +"{\n" +" foo_kill();\n" +"}\n" +"SYSUNINIT(foobar, SI_SUB_FOO, SI_ORDER_FOO, foo_cleanup, NULL);\n" + +#. 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 "" +"struct foo_stack foo_stack = {\n" +" FOO_STACK_VOODOO;\n" +"}\n" + +#. 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 "" +"void foo_flush(void *vdata)\n" +"{\n" +"}\n" +"SYSUNINIT(barfoo, SI_SUB_FOO, SI_ORDER_FOO, foo_flush, &foo_stack);\n" diff --git a/documentation/content/ru/books/arch-handbook/usb/_index.adoc b/documentation/content/ru/books/arch-handbook/usb/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/usb/_index.adoc @@ -0,0 +1,186 @@ +--- +description: 'Устройства USB в FreeBSD' +next: books/arch-handbook/newbus +params: + path: /books/arch-handbook/usb/ +prev: books/arch-handbook/scsi +showBookMenu: true +tags: ["USB", "Structure", "UHCI", "OHCI"] +title: 'Глава 13. USB-устройства' +weight: 15 +--- + +[[usb]] += Устройства USB +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 13 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[usb-intro]] +== Введение + +Универсальная последовательная шина (USB) — это новый способ подключения устройств к персональным компьютерам. Архитектура шины поддерживает двустороннюю связь и была разработана в ответ на усложнение устройств, требующих большего взаимодействия с хостом. Поддержка USB включена во все современные чипсеты ПК и, следовательно, доступна во всех недавно собранных компьютерах. Выпуск Apple iMac только с USB стал серьёзным стимулом для производителей оборудования выпускать USB-версии своих устройств. Согласно будущим спецификациям ПК, все устаревшие разъёмы должны быть заменены одним или несколькими USB-разъёмами, обеспечивающими универсальные возможности plug and play. Поддержка USB-оборудования появилась в NetBSD на очень раннем этапе и была разработана Леннартом Аугустссоном для проекта NetBSD. Код был портирован в FreeBSD, и в настоящее время мы поддерживаем общую кодовая базу. Для реализации подсистемы USB важны некоторые особенности USB. + +_Леннарт Аугустссон выполнил большую часть работы по реализации поддержки USB для проекта NetBSD. Огромная благодарность за этот невероятный объем работы. Также большое спасибо Арди и Дирку за их комментарии и вычитку этой статьи._ + +* Устройства подключаются к портам компьютера напрямую или через устройства, называемые концентраторами, образуя древовидную структуру устройств. +* Устройства можно подключать и отключать во время работы. +* Устройства могут приостанавливать свою работу и инициировать возобновление работы основной системы +* Поскольку устройства могут получать питание от шины, программное обеспечение хоста должно отслеживать энергопотребление для каждого концентратора. +* Различные требования к качеству обслуживания для разных типов устройств, а также максимум в 126 устройств, которые могут быть подключены к одной шине, требуют правильного планирования передач по общей шине, чтобы полностью использовать доступную пропускную способность в 12 Мбит/с (более 400 Мбит/с для USB 2.0) +* Устройства являются интеллектуальными и содержат легко доступную информацию о себе + +Разработка драйверов для подсистемы USB и подключенных к ней устройств поддерживается спецификациями, которые были разработаны и будут разрабатываться. Эти спецификации общедоступны на домашних страницах USB. Apple активно продвигает стандартизированные драйверы, предоставляя драйверы для универсальных классов в своей операционной системе MacOS и не поощряя использование отдельных драйверов для каждого нового устройства. Эта глава пытается собрать основную информацию для базового понимания реализации стека USB 2.0 в FreeBSD/NetBSD. Однако рекомендуется читать её вместе с соответствующими спецификациями 2.0 и другими ресурсами для разработчиков: + +* Спецификация USB 2.0 (http://www.usb.org/developers/docs/usb20_docs/[http://www.usb.org/developers/docs/usb20_docs/]) +* Универсальный интерфейс хост-контроллера (UHCI) Спецификация (link:ftp://ftp.netbsd.org/pub/NetBSD/misc/blymn/uhci11d.pdf[ftp://ftp.netbsd.org/pub/NetBSD/misc/blymn/uhci11d.pdf]) +* Спецификация интерфейса Open Host Controller (OHCI)(link:ftp://ftp.compaq.com/pub/supportinformation/papers/hcir1_0a.pdf[ftp://ftp.compaq.com/pub/supportinformation/papers/hcir1_0a.pdf]) +* Раздел для разработчиков на домашней странице USB (http://www.usb.org/developers/[http://www.usb.org/developers/]) + +=== Структура стека USB + +Поддержка USB в FreeBSD может быть разделена на три уровня. Самый нижний уровень содержит драйвер контроллера хоста, предоставляющий универсальный интерфейс к оборудованию и его механизмам планирования. Он поддерживает инициализацию оборудования, планирование передач и обработку завершённых и/или неудачных передач. Каждый драйвер контроллера хоста реализует виртуальный концентратор, обеспечивающий независимый от оборудования доступ к регистрам, управляющим корневыми портами на задней панели машины. + +Средний уровень обрабатывает подключение и отключение устройства, базовую инициализацию устройства, выбор драйвера, каналы связи (pipe) и управляет ресурсами. Этот сервисный уровень также контролирует стандартные каналы и запросы устройств, передаваемые через них. + +Верхний уровень содержит отдельные драйверы, поддерживающие конкретные (классы) устройств. Эти драйверы реализуют протокол, используемый в каналах, отличных от стандартного. Они также реализуют дополнительную функциональность для обеспечения доступа к устройству другим частям ядра или пользовательского пространства. Они используют интерфейс драйвера USB (USBDI), предоставляемый уровнем сервисов. + +[[usb-hc]] +== Контроллеры хоста + +Хост-контроллер (HC) управляет передачей пакетов на шине. Используются кадры длительностью 1 миллисекунда. В начале каждого кадра хост-контроллер генерирует пакет Start of Frame (SOF). + +Пакет SOF используется для синхронизации начала кадра и отслеживания номера кадра. Внутри каждого кадра передаются пакеты, либо от хоста к устройству (исходящие), либо от устройства к хосту (входящие). Передачи всегда инициируются хостом (опросные передачи). Поэтому на каждой шине USB может быть только один хост. Каждая передача пакета имеет стадию статуса, в которой получатель данных может вернуть либо ACK (подтверждение приема), NAK (повторить), STALL (ошибка) либо ничего (искаженная стадия данных, устройство недоступно или отключено). В разделе 8.5 спецификации USB 2.0 подробно объясняются детали пакетов. На шине USB могут происходить четыре различных типа передач: управляющие, массовые, прерывания и изохронные. Типы передач и их характеристики описаны ниже. + +Крупные передачи между устройством на шине USB и драйвером устройства разделяются на несколько пакетов хост-контроллером или драйвером HC. + +Запросы устройств (управляющие передачи) к конечным точкам по умолчанию являются особыми. Они состоят из двух или трёх фаз: SETUP, DATA (опционально) и STATUS. Пакет настройки отправляется на устройство. Если присутствует фаза данных, направление пакета(ов) данных указывается в пакете настройки. Направление в фазе статуса противоположно направлению во время фазы данных или IN, если фазы данных не было. Аппаратное обеспечение хост-контроллера также предоставляет регистры с текущим состоянием корневых портов и изменениями, произошедшими с момента последнего сброса регистра изменений статуса. Доступ к этим регистрам предоставляется через виртуализированный концентратор, как предложено в спецификации USB. Виртуальный концентратор должен соответствовать классу устройств концентратора, указанному в главе 11 этой спецификации. Он должен предоставлять канал по умолчанию, через который можно отправлять запросы устройств. Он возвращает стандартные и специфичные для класса концентратора наборы дескрипторов. Также он должен предоставлять прерывающий канал, сообщающий об изменениях, происходящих на его портах. В настоящее время доступны две спецификации для хост-контроллеров: - Universal Host Controller Interface (UHCI) от Intel и Open Host Controller Interface (OHCI) от Compaq, Microsoft и National Semiconductor. Спецификация UHCI разработана для уменьшения аппаратной сложности, требуя от драйвера хост-контроллера предоставления полного расписания передач для каждого кадра. Контроллеры типа OHCI гораздо более независимы, предоставляя более абстрактный интерфейс и выполняя большую часть работы самостоятельно. + +=== UHCI + +Контроллер UHCI поддерживает список кадров (framelist) с 1024 указателями на структуры данных для каждого кадра. Он распознаёт два типа данных: дескрипторы передачи (TD) и головы очередей (QH). Каждый TD представляет пакет для передачи в конечную точку устройства или из неё. QH служат для группировки TD (и других QH) вместе. + +Каждая передача состоит из одного или нескольких пакетов. Драйвер UHCI разделяет большие передачи на несколько пакетов. Для каждой передачи, за исключением изохронных, выделяется QH. Для каждого типа передачи эти QH собираются в QH для соответствующего типа. Изохронные передачи должны выполняться первыми из-за требования фиксированной задержки и непосредственно указываются указателем в списке кадров. Последний изохронный TD ссылается на QH для прерывающих передач для этого кадра. Все QH для прерывающих передач указывают на QH для управляющих передач, который, в свою очередь, указывает на QH для массовых передач. Следующая диаграмма дает графическое представление этого: + +В результате выполняется следующее расписание в каждом кадре. После получения указателя на текущий кадр из списка кадров контроллер сначала выполняет TDs для всех изохронных пакетов в этом кадре. Последний из этих TDs ссылается на QH для прерывающих передач этого кадра. Хост-контроллер затем переходит от этого QH к QHs для отдельных прерывающих передач. После завершения этой очереди, QH для прерывающих передач ссылается на QH для всех управляющих передач. Он выполняет все подочереди, запланированные там, а затем все передачи, поставленные в очередь в QH для массовых передач. Для упрощения обработки завершенных или неудачных передач аппаратное обеспечение генерирует различные типы прерываний в конце каждого кадра. В последнем TD для передачи бит *Interrupt-On Completion* устанавливается драйвером HC, чтобы вызвать прерывание по завершении передачи. Прерывание ошибки возникает, если TD достигает максимального количества ошибок. Если в TD установлен бит *short packet detect* и передано меньше установленной длины пакета, это прерывание уведомляет драйвер контроллера о завершении передачи. Задача драйвера хост-контроллера — определить, какая передача завершилась или вызвала ошибку. При вызове процедура обслуживания прерывания находит все завершенные передачи и вызывает их callback-функции. + +Обратитесь к спецификации UHCI для более подробного описания. + +=== OHCI + +Программирование OHCI-контроллера значительно проще. Контроллер предполагает, что доступен набор конечных точек, и учитывает приоритеты планирования и порядок типов передач в кадре. Основная структура данных, используемая хост-контроллером, — это дескриптор конечной точки (ED), к которому присоединена очередь дескрипторов передачи (TD). ED содержит максимальный размер пакета, разрешенный для конечной точки, а аппаратное обеспечение контроллера выполняет разделение на пакеты. Указатели на буферы данных обновляются после каждой передачи, и когда начальный и конечный указатели становятся равны, TD перемещается в очередь завершенных (done-queue). Четыре типа конечных точек (прерывание, изохронная, управление и массовая) имеют свои собственные очереди. Управляющие и массовые конечные точки помещаются каждая в свою очередь. ED прерываний организуются в дерево, где уровень в дереве определяет частоту их выполнения. + +Порядок действий, выполняемых хост-контроллером в каждом кадре, выглядит следующим образом. Контроллер сначала запускает непериодические очереди управления и массовых передач, вплоть до ограничения времени, установленного драйвером HC. Затем выполняются прерывающие передачи для данного номера кадра, используя младшие пять битов номера кадра в качестве индекса уровня 0 дерева ED прерываний. В конце этого дерева подключены изохронные ED, которые затем обходятся. Изохронные TD содержат номер кадра, в котором должна быть запущена первая передача. После выполнения всех периодических передач очереди управления и массовых передач обходятся снова. Периодически вызывается процедура обслуживания прерывания для обработки очереди завершенных операций и вызова обратных вызовов для каждой передачи, а также для перепланирования прерывающих и изохронных конечных точек. + +См. UHCI Specification для более подробного описания. Средний уровень обеспечивает контролируемый доступ к устройству и управляет ресурсами, используемыми различными драйверами и уровнем сервисов. Этот уровень отвечает за следующие аспекты: + +* Информация о конфигурации устройства +* Каналы для взаимодействия с устройством +* Обнаружение, подключение и отключение от устройства. + +[[usb-dev]] +== Информация об устройстве USB + +=== Информация о конфигурации устройства + +Каждое устройство предоставляет различные уровни информации о конфигурации. У каждого устройства есть одна или несколько конфигураций, из которых одна выбирается во время обнаружения/подключения. Конфигурация определяет требования к питанию и пропускной способности. В каждой конфигурации может быть несколько интерфейсов. Интерфейс устройства — это набор конечных точек. Например, USB-колонки могут иметь интерфейс для аудиоданных (Audio Class) и интерфейс для регуляторов, ручек и кнопок (HID Class). Все интерфейсы в конфигурации активны одновременно и могут быть подключены разными драйверами. Каждый интерфейс может иметь альтернативные варианты, предоставляющие различные параметры качества обслуживания. Например, в камерах это используется для поддержки разных размеров кадра и количества кадров в секунду. + +В каждом интерфейсе может быть указано 0 или более конечных точек. Конечные точки — это однонаправленные точки доступа для связи с устройством. Они предоставляют буферы для временного хранения входящих или исходящих данных устройства. Каждая конечная точка имеет уникальный адрес в конфигурации — номер конечной точки плюс её направление. Конечная точка по умолчанию, конечная точка 0, не является частью какого-либо интерфейса и доступна во всех конфигурациях. Она управляется уровнем сервисов и не доступна напрямую драйверам устройств. + +Эта иерархическая конфигурационная информация описывается в устройстве стандартным набором дескрипторов (см. раздел 9.6 спецификации USB). Они могут быть запрошены через Get Descriptor Request. Сервисный уровень кэширует эти дескрипторы, чтобы избежать ненужных передач по шине USB. Доступ к дескрипторам предоставляется через вызовы функций. + +* Дескрипторы устройств: Общая информация об устройстве, такая как Vendor (производитель), Product (продукт) и Revision Id (идентификатор ревизии), поддерживаемый класс устройства, подкласс и протокол, если применимо, максимальный размер пакета для конечной точки по умолчанию и т. д. +* Дескрипторы конфигурации: количество интерфейсов в данной конфигурации, поддержка функций приостановки и возобновления работы, а также требования к питанию. +* Дескрипторы интерфейса: класс интерфейса, подкласс и протокол (если применимо), количество альтернативных настроек интерфейса и количество конечных точек. +* Дескрипторы конечных точек: Адрес конечной точки, направление и тип, максимальный поддерживаемый размер пакета и частота опроса, если тип является конечной точкой прерывания. Для конечной точки по умолчанию (конечная точка 0) дескриптора не существует, и она никогда не учитывается в дескрипторе интерфейса. +* Дескрипторы строк: В остальных дескрипторах для некоторых полей указываются индексы строк. Эти индексы могут использоваться для получения описательных строк, возможно, на нескольких языках. + +Спецификации классов могут добавлять свои собственные типы дескрипторов, которые доступны через запрос GetDescriptor. + +Канальный обмен данными с конечными точками устройства осуществляется через так называемые *каналы*. Драйверы передают данные конечным точкам через канал и предоставляют функцию обратного вызова, которая вызывается при завершении или сбое передачи (асинхронные передачи) или ожидают завершения (синхронная передача). Передачи данных в конечную точку сериализуются в канале. Передача может завершиться успешно, завершиться с ошибкой или превысить время ожидания (если оно было задано). Существует два типа таймаутов для передач. Таймауты могут происходить из-за истечения времени на шине USB (миллисекунды). Эти таймауты рассматриваются как сбои и могут быть вызваны отключением устройства. Вторая форма таймаута реализована на уровне программного обеспечения и срабатывает, если передача не завершается в течение заданного времени (секунды). Это происходит, когда устройство отрицательно подтверждает (NAK) переданные пакеты. Причинами могут быть неготовность устройства к приему данных, переполнение буфера или пустой буфер, либо ошибки протокола. + +Если передача через канал превышает максимальный размер пакета, указанный в соответствующем дескрипторе конечной точки, хост-контроллер (OHCI) или драйвер HC (UHCI) разделит передачу на пакеты максимального размера, при этом последний пакет может быть меньше максимального размера. + +Иногда для устройства не является проблемой вернуть меньше данных, чем запрошено. Например, при передаче данных в режиме bulk-in на модем может быть запрошено 200 байт данных, но у модема в данный момент доступно только 5 байт. Драйвер может установить флаг короткого пакета (SPD). Это позволяет хост-контроллеру принять пакет, даже если объем переданных данных меньше запрошенного. Этот флаг действителен только для in-передач, так как объем данных, отправляемых на устройство, всегда известен заранее. Если во время передачи в устройстве происходит неустранимая ошибка, канал останавливается (stalled). Прежде чем принимать или отправлять дополнительные данные, драйвер должен устранить причину остановки и сбросить условие остановки конечной точки, отправив запрос `clear endpoint halt` через канал по умолчанию. Конечная точка по умолчанию никогда не должна останавливаться. + +Существует четыре различных типа конечных точек и соответствующих каналов: - Управляющий канал / канал по умолчанию: На каждое устройство приходится один управляющий канал, подключенный к конечной точке по умолчанию (конечная точка 0). Этот канал передает запросы устройства и связанные с ними данные. Разница между передачами через канал по умолчанию и другими каналами заключается в том, что протокол для этих передач описан в спецификации USB. Эти запросы используются для сброса и настройки устройства. Базовый набор команд, который должен поддерживаться каждым устройством, приведен в главе 9 спецификации USB. Команды, поддерживаемые на этом канале, могут быть расширены спецификацией класса устройства для обеспечения дополнительной функциональности. + +* Массовый канал: Это USB-эквивалент среды передачи данных в сыром виде. +* Прерывающий канал: Хост отправляет запрос данных на устройство, и если устройству нечего отправлять, оно отвечает NAK на пакет данных. Прерывающие передачи планируются с частотой, указанной при создании канала. +* Изохронный канал: Эти каналы предназначены для изохронных данных, например, видео- или аудиопотоков, с фиксированной задержкой, но без гарантированной доставки. В текущей реализации доступна некоторая поддержка каналов этого типа. Пакеты в управляющих, массовых и прерывающих передачах повторяются, если во время передачи возникает ошибка или устройство отрицательно подтверждает пакет (NAK) из-за, например, нехватки буферного пространства для хранения входящих данных. Однако изохронные пакеты не повторяются в случае неудачной доставки или NAK пакета, так как это может нарушить временные ограничения. + +Доступность необходимой полосы пропускания рассчитывается во время создания канала. Передачи планируются в рамках интервалов в 1 миллисекунду. Распределение полосы пропускания внутри интервала регламентируется спецификацией USB, раздел 5.6 [2]. Изохронные и прерывающие передачи могут использовать до 90% полосы пропускания в рамках интервала. Пакеты для управляющих и массовых передач планируются после всех изохронных и прерывающих пакетов и используют всю оставшуюся полосу пропускания. + +Дополнительная информация о планировании передач и освобождении пропускной способности доступна в главе 5 спецификации USB, разделе 1.3 спецификации UHCI и разделе 3.4.2 спецификации OHCI. + +[[usb-devprobe]] +== Обнаружение устройства и подключение + +После уведомления от концентратора о подключении нового устройства сервисный уровень включает порт, предоставляя устройству ток 100 мА. На этом этапе устройство находится в своём исходном состоянии и прослушивает адрес устройства 0. Сервисный уровень продолжит получение различных дескрипторов через стандартный канал. После этого он отправит запрос Set Address, чтобы переместить устройство с исходного адреса (адрес 0). Несколько драйверов устройств могут поддерживать данное устройство. Например, драйвер модема может поддерживать ISDN TA через интерфейс совместимости AT. Однако драйвер, предназначенный для конкретной модели ISDN-адаптера, может обеспечить гораздо лучшую поддержку этого устройства. Для обеспечения такой гибкости пробы возвращают приоритеты, указывающие уровень их поддержки. Поддержка конкретной версии продукта имеет наивысший приоритет, а универсальный драйвер — самый низкий. Также возможно, что несколько драйверов могут быть подключены к одному устройству, если в одной конфигурации присутствует несколько интерфейсов. Каждому драйверу требуется поддерживать только подмножество интерфейсов. + +Поиск драйвера для нового подключенного устройства сначала проверяет наличие специфичных для устройства драйверов. Если они не найдены, код проверки перебирает все поддерживаемые конфигурации, пока драйвер не будет подключен в одной из них. Для поддержки устройств с несколькими драйверами на разных интерфейсах проверка перебирает все интерфейсы в конфигурации, которые ещё не были заняты драйвером. Конфигурации, превышающие выделенный бюджет мощности для концентратора, игнорируются. Во время подключения драйвер должен инициализировать устройство в его рабочее состояние, но не сбрасывать его, так как это приведёт к отключению устройства от шины и перезапуску процесса проверки. Чтобы избежать излишнего потребления пропускной способности, не следует запрашивать канал прерывания во время подключения, а отложить его выделение до момента открытия файла и фактического использования данных. При закрытии файла канал следует снова закрыть, даже если устройство остаётся подключенным. + +=== Отключение и извлечение устройства + +Драйвер устройства должен ожидать получения ошибок во время любой транзакции с устройством. Дизайн USB поддерживает и поощряет отключение устройств в любой момент времени. Драйверы должны гарантировать корректную обработку ситуаций, когда устройство исчезает. + +Кроме того, устройство, которое было отключено и снова подключено, не будет повторно присоединено к тому же экземпляру устройства. Это может измениться в будущем, когда больше устройств будут поддерживать серийные номера (см. дескриптор устройства) или будут разработаны другие способы определения идентификатора устройства. + +Отключение устройства сигнализируется концентратором в пакете прерывания, передаваемом драйверу концентратора. Информация об изменении состояния указывает, на каком порту произошло изменение подключения. Метод отключения устройства для всех драйверов устройств, подключенных к этому порту, вызывается, и структуры очищаются. Если состояние порта указывает, что за это время к порту было подключено устройство, начнется процедура обнаружения и подключения устройства. Сброс устройства вызовет последовательность отключения-подключения на концентраторе и будет обработан, как описано выше. + +[[usb-protocol]] +== Информация о протоколе драйверов USB + +Используемый протокол для каналов, отличных от стандартного, не определен спецификацией USB. Информацию об этом можно найти из различных источников. Наиболее точный источник — раздел для разработчиков на домашних страницах USB. На этих страницах доступно растущее количество спецификаций классов устройств. Эти спецификации определяют, каким должно быть совместимое устройство с точки зрения драйвера, базовую функциональность, которую оно должно предоставлять, и протокол, используемый на каналах связи. Спецификация USB включает описание класса концентраторов (Hub Class). Спецификация класса устройств человеко-машинного интерфейса (HID) была создана для поддержки клавиатур, планшетов, сканеров штрих-кодов, кнопок, регуляторов, переключателей и т. д. Третий пример — спецификация класса устройств хранения данных (Mass Storage). Полный список классов устройств можно найти в разделе для разработчиков на домашних страницах USB. + +Для многих устройств информация о протоколе ещё не опубликована. Сведения об используемом протоколе могут быть доступны у компании-производителя устройства. Некоторые компании потребуют подписания соглашения о неразглашении (NDA), прежде чем предоставить спецификации. В большинстве случаев это исключает возможность сделать драйвер открытым. + +Еще один хороший источник информации — исходные коды драйверов Linux, так как ряд компаний начал предоставлять драйверы для Linux для своих устройств. Всегда полезно связаться с авторами этих драйверов для получения информации. + +Пример: Устройства интерфейса пользователя (HID) — Спецификация для устройств интерфейса пользователя, таких как клавиатуры, мыши, планшеты, кнопки, регуляторы и т.д., упоминается в других спецификациях классов устройств и используется во многих устройствах. + +Например, аудиоколонки предоставляют конечные точки для цифро-аналоговых преобразователей и, возможно, дополнительный канал для микрофона. Они также предоставляют конечную точку HID в отдельном интерфейсе для кнопок и регуляторов на передней панели устройства. То же самое справедливо для класса управления монитором. Реализовать поддержку этих интерфейсов достаточно просто с помощью доступных библиотек ядра и пользовательского пространства, а также драйвера класса HID или универсального драйвера. Другим примером устройства с несколькими интерфейсами в одной конфигурации, управляемыми разными драйверами, является недорогая клавиатура со встроенным устаревшим портом для мыши. Чтобы избежать затрат на включение аппаратного обеспечения USB-концентратора в устройство, производители объединили данные мыши, полученные с порта PS/2 на задней панели клавиатуры, и нажатия клавиш в два отдельных интерфейса в одной конфигурации. Драйверы мыши и клавиатуры подключаются к соответствующему интерфейсу и выделяют каналы для двух независимых конечных точек. + +Пример: Загрузка микропрограммы — многие разработанные устройства основаны на процессоре общего назначения с добавленным USB-ядром. Поскольку разработка драйверов и микропрограмм для USB-устройств всё ещё очень нова, многие устройства требуют загрузки микропрограммы после подключения. + +Процедура выполняется следующим образом. Устройство идентифицирует себя через идентификаторы производителя и продукта. Первый драйвер проверяет его и подключается к нему, затем загружает в него микропрограмму. После этого устройство выполняет мягкую перезагрузку, и драйвер отключается. После небольшой паузы устройство снова появляется на шине. При этом идентификаторы производителя, продукта и версии устройства изменятся, что отражает факт загрузки микропрограммы, и в результате второй драйвер проверит его и подключится к нему. + +Примером таких устройств является плата ввода-вывода ActiveWire, основанная на чипе EZ-USB. Для этого чипа доступен универсальный загрузчик микропрограмм. Микропрограмма, загруженная в плату ActiveWire, изменяет идентификатор ревизии. Затем выполняется мягкий сброс USB-части чипа EZ-USB для отключения от USB-шины и повторного подключения. + +Пример: Поддержка устройств хранения данных в основном построена на существующих протоколах. Устройство Iomega USB Zipdrive основано на SCSI-версии их накопителя. SCSI-команды и статусные сообщения упаковываются в блоки и передаются через массовые каналы к устройству и от него, эмулируя SCSI-контроллер через USB-соединение. ATAPI и UFI команды поддерживаются аналогичным образом. + +Спецификация Mass Storage поддерживает 2 различных типа обёртки командного блока. Первоначальная попытка была основана на отправке команды и состояния через канал по умолчанию с использованием массовых передач для данных, перемещаемых между хостом и устройством. На основе опыта был разработан второй подход, основанный на обёртке командных и статусных блоков и их отправке через конечные точки массовой передачи (bulk out и bulk in). Спецификация точно определяет, что должно происходить и когда, а также что необходимо делать в случае возникновения ошибки. Наибольшую сложность при написании драйверов для таких устройств представляет встраивание USB-ориентированного протокола в существующую поддержку устройств хранения данных. CAM предоставляет механизмы для этого достаточно прямолинейным способом. С ATAPI всё менее просто, так как исторически интерфейс IDE никогда не имел множества различных вариантов реализации. + +Поддержка USB-дисковода от Y-E Data также не прямолинейна, так как был разработан новый набор команд. diff --git a/documentation/content/ru/books/arch-handbook/usb/_index.po b/documentation/content/ru/books/arch-handbook/usb/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/usb/_index.po @@ -0,0 +1,1200 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-07-12 04:45+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\n" + +#. type: Yaml Front Matter Hash Value: description +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:1 +#, no-wrap +msgid "USB Devices in FreeBSD" +msgstr "Устройства USB в FreeBSD" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:1 +#, no-wrap +msgid "Chapter 13. USB Devices" +msgstr "Глава 13. USB-устройства" + +#. type: Title = +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:14 +#, no-wrap +msgid "USB Devices" +msgstr "Устройства USB" + +#. 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 "" +"Универсальная последовательная шина (USB) — это новый способ подключения " +"устройств к персональным компьютерам. Архитектура шины поддерживает " +"двустороннюю связь и была разработана в ответ на усложнение устройств, " +"требующих большего взаимодействия с хостом. Поддержка USB включена во все " +"современные чипсеты ПК и, следовательно, доступна во всех недавно собранных " +"компьютерах. Выпуск Apple iMac только с USB стал серьёзным стимулом для " +"производителей оборудования выпускать USB-версии своих устройств. Согласно " +"будущим спецификациям ПК, все устаревшие разъёмы должны быть заменены одним " +"или несколькими USB-разъёмами, обеспечивающими универсальные возможности " +"plug and play. Поддержка USB-оборудования появилась в NetBSD на очень раннем " +"этапе и была разработана Леннартом Аугустссоном для проекта NetBSD. Код был " +"портирован в FreeBSD, и в настоящее время мы поддерживаем общую кодовая " +"базу. Для реализации подсистемы USB важны некоторые особенности USB." + +#. 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 "" +"_Леннарт Аугустссон выполнил большую часть работы по реализации поддержки " +"USB для проекта NetBSD. Огромная благодарность за этот невероятный объем " +"работы. Также большое спасибо Арди и Дирку за их комментарии и вычитку этой " +"статьи._" + +#. 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 "" +"Различные требования к качеству обслуживания для разных типов устройств, а " +"также максимум в 126 устройств, которые могут быть подключены к одной шине, " +"требуют правильного планирования передач по общей шине, чтобы полностью " +"использовать доступную пропускную способность в 12 Мбит/с (более 400 Мбит/с " +"для USB 2.0)" + +#. 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 "" +"Разработка драйверов для подсистемы USB и подключенных к ней устройств " +"поддерживается спецификациями, которые были разработаны и будут " +"разрабатываться. Эти спецификации общедоступны на домашних страницах USB. " +"Apple активно продвигает стандартизированные драйверы, предоставляя драйверы " +"для универсальных классов в своей операционной системе MacOS и не поощряя " +"использование отдельных драйверов для каждого нового устройства. Эта глава " +"пытается собрать основную информацию для базового понимания реализации стека " +"USB 2.0 в FreeBSD/NetBSD. Однако рекомендуется читать её вместе с " +"соответствующими спецификациями 2.0 и другими ресурсами для разработчиков:" + +#. 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 "" +"Спецификация USB 2.0 (http://www.usb.org/developers/docs/usb20_docs/[http://" +"www.usb.org/developers/docs/usb20_docs/])" + +#. 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 "" +"Универсальный интерфейс хост-контроллера (UHCI) Спецификация (link:ftp://" +"ftp.netbsd.org/pub/NetBSD/misc/blymn/uhci11d.pdf[ftp://ftp.netbsd.org/pub/" +"NetBSD/misc/blymn/uhci11d.pdf])" + +#. 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 "" +"Спецификация интерфейса Open Host Controller (OHCI)(link:ftp://" +"ftp.compaq.com/pub/supportinformation/papers/hcir1_0a.pdf[ftp://" +"ftp.compaq.com/pub/supportinformation/papers/hcir1_0a.pdf])" + +#. 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 "" +"Раздел для разработчиков на домашней странице USB (http://www.usb.org/" +"developers/[http://www.usb.org/developers/])" + +#. type: Title === +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:72 +#, no-wrap +msgid "Structure of the USB Stack" +msgstr "Структура стека USB" + +#. 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 "" +"Поддержка USB в FreeBSD может быть разделена на три уровня. Самый нижний " +"уровень содержит драйвер контроллера хоста, предоставляющий универсальный " +"интерфейс к оборудованию и его механизмам планирования. Он поддерживает " +"инициализацию оборудования, планирование передач и обработку завершённых и/" +"или неудачных передач. Каждый драйвер контроллера хоста реализует " +"виртуальный концентратор, обеспечивающий независимый от оборудования доступ " +"к регистрам, управляющим корневыми портами на задней панели машины." + +#. 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 "" +"Средний уровень обрабатывает подключение и отключение устройства, базовую " +"инициализацию устройства, выбор драйвера, каналы связи (pipe) и управляет " +"ресурсами. Этот сервисный уровень также контролирует стандартные каналы и " +"запросы устройств, передаваемые через них." + +#. 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 "" +"Верхний уровень содержит отдельные драйверы, поддерживающие конкретные " +"(классы) устройств. Эти драйверы реализуют протокол, используемый в каналах, " +"отличных от стандартного. Они также реализуют дополнительную " +"функциональность для обеспечения доступа к устройству другим частям ядра или " +"пользовательского пространства. Они используют интерфейс драйвера USB " +"(USBDI), предоставляемый уровнем сервисов." + +#. 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 "" +"Хост-контроллер (HC) управляет передачей пакетов на шине. Используются кадры " +"длительностью 1 миллисекунда. В начале каждого кадра хост-контроллер " +"генерирует пакет Start of Frame (SOF)." + +#. 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 "" +"Пакет SOF используется для синхронизации начала кадра и отслеживания номера " +"кадра. Внутри каждого кадра передаются пакеты, либо от хоста к устройству " +"(исходящие), либо от устройства к хосту (входящие). Передачи всегда " +"инициируются хостом (опросные передачи). Поэтому на каждой шине USB может " +"быть только один хост. Каждая передача пакета имеет стадию статуса, в " +"которой получатель данных может вернуть либо ACK (подтверждение приема), NAK " +"(повторить), STALL (ошибка) либо ничего (искаженная стадия данных, " +"устройство недоступно или отключено). В разделе 8.5 спецификации USB 2.0 " +"подробно объясняются детали пакетов. На шине USB могут происходить четыре " +"различных типа передач: управляющие, массовые, прерывания и изохронные. Типы " +"передач и их характеристики описаны ниже." + +#. 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 "" +"Крупные передачи между устройством на шине USB и драйвером устройства " +"разделяются на несколько пакетов хост-контроллером или драйвером HC." + +#. 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 "" +"Запросы устройств (управляющие передачи) к конечным точкам по умолчанию " +"являются особыми. Они состоят из двух или трёх фаз: SETUP, DATA " +"(опционально) и STATUS. Пакет настройки отправляется на устройство. Если " +"присутствует фаза данных, направление пакета(ов) данных указывается в пакете " +"настройки. Направление в фазе статуса противоположно направлению во время " +"фазы данных или IN, если фазы данных не было. Аппаратное обеспечение хост-" +"контроллера также предоставляет регистры с текущим состоянием корневых " +"портов и изменениями, произошедшими с момента последнего сброса регистра " +"изменений статуса. Доступ к этим регистрам предоставляется через " +"виртуализированный концентратор, как предложено в спецификации USB. " +"Виртуальный концентратор должен соответствовать классу устройств " +"концентратора, указанному в главе 11 этой спецификации. Он должен " +"предоставлять канал по умолчанию, через который можно отправлять запросы " +"устройств. Он возвращает стандартные и специфичные для класса концентратора " +"наборы дескрипторов. Также он должен предоставлять прерывающий канал, " +"сообщающий об изменениях, происходящих на его портах. В настоящее время " +"доступны две спецификации для хост-контроллеров: - Universal Host Controller " +"Interface (UHCI) от Intel и Open Host Controller Interface (OHCI) от Compaq, " +"Microsoft и National Semiconductor. Спецификация UHCI разработана для " +"уменьшения аппаратной сложности, требуя от драйвера хост-контроллера " +"предоставления полного расписания передач для каждого кадра. Контроллеры " +"типа OHCI гораздо более независимы, предоставляя более абстрактный интерфейс " +"и выполняя большую часть работы самостоятельно." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:91 +#, no-wrap +msgid "UHCI" +msgstr "UHCI" + +#. 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 "" +"Контроллер UHCI поддерживает список кадров (framelist) с 1024 указателями на " +"структуры данных для каждого кадра. Он распознаёт два типа данных: " +"дескрипторы передачи (TD) и головы очередей (QH). Каждый TD представляет " +"пакет для передачи в конечную точку устройства или из неё. QH служат для " +"группировки TD (и других QH) вместе." + +#. 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 "" +"Каждая передача состоит из одного или нескольких пакетов. Драйвер UHCI " +"разделяет большие передачи на несколько пакетов. Для каждой передачи, за " +"исключением изохронных, выделяется QH. Для каждого типа передачи эти QH " +"собираются в QH для соответствующего типа. Изохронные передачи должны " +"выполняться первыми из-за требования фиксированной задержки и " +"непосредственно указываются указателем в списке кадров. Последний изохронный " +"TD ссылается на QH для прерывающих передач для этого кадра. Все QH для " +"прерывающих передач указывают на QH для управляющих передач, который, в свою " +"очередь, указывает на QH для массовых передач. Следующая диаграмма дает " +"графическое представление этого:" + +#. 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 "" +"В результате выполняется следующее расписание в каждом кадре. После " +"получения указателя на текущий кадр из списка кадров контроллер сначала " +"выполняет TDs для всех изохронных пакетов в этом кадре. Последний из этих " +"TDs ссылается на QH для прерывающих передач этого кадра. Хост-контроллер " +"затем переходит от этого QH к QHs для отдельных прерывающих передач. После " +"завершения этой очереди, QH для прерывающих передач ссылается на QH для всех " +"управляющих передач. Он выполняет все подочереди, запланированные там, а " +"затем все передачи, поставленные в очередь в QH для массовых передач. Для " +"упрощения обработки завершенных или неудачных передач аппаратное обеспечение " +"генерирует различные типы прерываний в конце каждого кадра. В последнем TD " +"для передачи бит *Interrupt-On Completion* устанавливается драйвером HC, " +"чтобы вызвать прерывание по завершении передачи. Прерывание ошибки " +"возникает, если TD достигает максимального количества ошибок. Если в TD " +"установлен бит *short packet detect* и передано меньше установленной длины " +"пакета, это прерывание уведомляет драйвер контроллера о завершении передачи. " +"Задача драйвера хост-контроллера — определить, какая передача завершилась " +"или вызвала ошибку. При вызове процедура обслуживания прерывания находит все " +"завершенные передачи и вызывает их callback-функции." + +#. 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 "Обратитесь к спецификации UHCI для более подробного описания." + +#. type: Title === +#: documentation/content/en/books/arch-handbook/usb/_index.adoc:101 +#, no-wrap +msgid "OHCI" +msgstr "OHCI" + +#. 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 "" +"Программирование OHCI-контроллера значительно проще. Контроллер " +"предполагает, что доступен набор конечных точек, и учитывает приоритеты " +"планирования и порядок типов передач в кадре. Основная структура данных, " +"используемая хост-контроллером, — это дескриптор конечной точки (ED), к " +"которому присоединена очередь дескрипторов передачи (TD). ED содержит " +"максимальный размер пакета, разрешенный для конечной точки, а аппаратное " +"обеспечение контроллера выполняет разделение на пакеты. Указатели на буферы " +"данных обновляются после каждой передачи, и когда начальный и конечный " +"указатели становятся равны, TD перемещается в очередь завершенных (done-" +"queue). Четыре типа конечных точек (прерывание, изохронная, управление и " +"массовая) имеют свои собственные очереди. Управляющие и массовые конечные " +"точки помещаются каждая в свою очередь. ED прерываний организуются в дерево, " +"где уровень в дереве определяет частоту их выполнения." + +#. 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 "" +"Порядок действий, выполняемых хост-контроллером в каждом кадре, выглядит " +"следующим образом. Контроллер сначала запускает непериодические очереди " +"управления и массовых передач, вплоть до ограничения времени, установленного " +"драйвером HC. Затем выполняются прерывающие передачи для данного номера " +"кадра, используя младшие пять битов номера кадра в качестве индекса уровня 0 " +"дерева ED прерываний. В конце этого дерева подключены изохронные ED, которые " +"затем обходятся. Изохронные TD содержат номер кадра, в котором должна быть " +"запущена первая передача. После выполнения всех периодических передач " +"очереди управления и массовых передач обходятся снова. Периодически " +"вызывается процедура обслуживания прерывания для обработки очереди " +"завершенных операций и вызова обратных вызовов для каждой передачи, а также " +"для перепланирования прерывающих и изохронных конечных точек." + +#. 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 "" +"См. UHCI Specification для более подробного описания. Средний уровень " +"обеспечивает контролируемый доступ к устройству и управляет ресурсами, " +"используемыми различными драйверами и уровнем сервисов. Этот уровень " +"отвечает за следующие аспекты:" + +#. 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 "Информация об устройстве USB" + +#. 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 "" +"Каждое устройство предоставляет различные уровни информации о конфигурации. " +"У каждого устройства есть одна или несколько конфигураций, из которых одна " +"выбирается во время обнаружения/подключения. Конфигурация определяет " +"требования к питанию и пропускной способности. В каждой конфигурации может " +"быть несколько интерфейсов. Интерфейс устройства — это набор конечных точек. " +"Например, USB-колонки могут иметь интерфейс для аудиоданных (Audio Class) и " +"интерфейс для регуляторов, ручек и кнопок (HID Class). Все интерфейсы в " +"конфигурации активны одновременно и могут быть подключены разными " +"драйверами. Каждый интерфейс может иметь альтернативные варианты, " +"предоставляющие различные параметры качества обслуживания. Например, в " +"камерах это используется для поддержки разных размеров кадра и количества " +"кадров в секунду." + +#. 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 "" +"В каждом интерфейсе может быть указано 0 или более конечных точек. Конечные " +"точки — это однонаправленные точки доступа для связи с устройством. Они " +"предоставляют буферы для временного хранения входящих или исходящих данных " +"устройства. Каждая конечная точка имеет уникальный адрес в конфигурации — " +"номер конечной точки плюс её направление. Конечная точка по умолчанию, " +"конечная точка 0, не является частью какого-либо интерфейса и доступна во " +"всех конфигурациях. Она управляется уровнем сервисов и не доступна напрямую " +"драйверам устройств." + +#. 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 "" +"Эта иерархическая конфигурационная информация описывается в устройстве " +"стандартным набором дескрипторов (см. раздел 9.6 спецификации USB). Они " +"могут быть запрошены через Get Descriptor Request. Сервисный уровень " +"кэширует эти дескрипторы, чтобы избежать ненужных передач по шине USB. " +"Доступ к дескрипторам предоставляется через вызовы функций." + +#. 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 "" +"Дескрипторы устройств: Общая информация об устройстве, такая как Vendor " +"(производитель), Product (продукт) и Revision Id (идентификатор ревизии), " +"поддерживаемый класс устройства, подкласс и протокол, если применимо, " +"максимальный размер пакета для конечной точки по умолчанию и т. д." + +#. 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 "" +"Дескрипторы конечных точек: Адрес конечной точки, направление и тип, " +"максимальный поддерживаемый размер пакета и частота опроса, если тип " +"является конечной точкой прерывания. Для конечной точки по умолчанию " +"(конечная точка 0) дескриптора не существует, и она никогда не учитывается в " +"дескрипторе интерфейса." + +#. 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 "" +"Спецификации классов могут добавлять свои собственные типы дескрипторов, " +"которые доступны через запрос GetDescriptor." + +#. 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 "" +"Канальный обмен данными с конечными точками устройства осуществляется через " +"так называемые *каналы*. Драйверы передают данные конечным точкам через " +"канал и предоставляют функцию обратного вызова, которая вызывается при " +"завершении или сбое передачи (асинхронные передачи) или ожидают завершения " +"(синхронная передача). Передачи данных в конечную точку сериализуются в " +"канале. Передача может завершиться успешно, завершиться с ошибкой или " +"превысить время ожидания (если оно было задано). Существует два типа " +"таймаутов для передач. Таймауты могут происходить из-за истечения времени на " +"шине USB (миллисекунды). Эти таймауты рассматриваются как сбои и могут быть " +"вызваны отключением устройства. Вторая форма таймаута реализована на уровне " +"программного обеспечения и срабатывает, если передача не завершается в " +"течение заданного времени (секунды). Это происходит, когда устройство " +"отрицательно подтверждает (NAK) переданные пакеты. Причинами могут быть " +"неготовность устройства к приему данных, переполнение буфера или пустой " +"буфер, либо ошибки протокола." + +#. 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 "" +"Если передача через канал превышает максимальный размер пакета, указанный в " +"соответствующем дескрипторе конечной точки, хост-контроллер (OHCI) или " +"драйвер HC (UHCI) разделит передачу на пакеты максимального размера, при " +"этом последний пакет может быть меньше максимального размера." + +#. 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 "" +"Иногда для устройства не является проблемой вернуть меньше данных, чем " +"запрошено. Например, при передаче данных в режиме bulk-in на модем может " +"быть запрошено 200 байт данных, но у модема в данный момент доступно только " +"5 байт. Драйвер может установить флаг короткого пакета (SPD). Это позволяет " +"хост-контроллеру принять пакет, даже если объем переданных данных меньше " +"запрошенного. Этот флаг действителен только для in-передач, так как объем " +"данных, отправляемых на устройство, всегда известен заранее. Если во время " +"передачи в устройстве происходит неустранимая ошибка, канал останавливается " +"(stalled). Прежде чем принимать или отправлять дополнительные данные, " +"драйвер должен устранить причину остановки и сбросить условие остановки " +"конечной точки, отправив запрос `clear endpoint halt` через канал по " +"умолчанию. Конечная точка по умолчанию никогда не должна останавливаться." + +#. 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 "" +"Существует четыре различных типа конечных точек и соответствующих каналов: - " +"Управляющий канал / канал по умолчанию: На каждое устройство приходится один " +"управляющий канал, подключенный к конечной точке по умолчанию (конечная " +"точка 0). Этот канал передает запросы устройства и связанные с ними данные. " +"Разница между передачами через канал по умолчанию и другими каналами " +"заключается в том, что протокол для этих передач описан в спецификации USB. " +"Эти запросы используются для сброса и настройки устройства. Базовый набор " +"команд, который должен поддерживаться каждым устройством, приведен в главе 9 " +"спецификации USB. Команды, поддерживаемые на этом канале, могут быть " +"расширены спецификацией класса устройства для обеспечения дополнительной " +"функциональности." + +#. 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 "Массовый канал: Это USB-эквивалент среды передачи данных в сыром виде." + +#. 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 "" +"Прерывающий канал: Хост отправляет запрос данных на устройство, и если " +"устройству нечего отправлять, оно отвечает NAK на пакет данных. Прерывающие " +"передачи планируются с частотой, указанной при создании канала." + +#. 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 "" +"Изохронный канал: Эти каналы предназначены для изохронных данных, например, " +"видео- или аудиопотоков, с фиксированной задержкой, но без гарантированной " +"доставки. В текущей реализации доступна некоторая поддержка каналов этого " +"типа. Пакеты в управляющих, массовых и прерывающих передачах повторяются, " +"если во время передачи возникает ошибка или устройство отрицательно " +"подтверждает пакет (NAK) из-за, например, нехватки буферного пространства " +"для хранения входящих данных. Однако изохронные пакеты не повторяются в " +"случае неудачной доставки или NAK пакета, так как это может нарушить " +"временные ограничения." + +#. 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 "" +"Доступность необходимой полосы пропускания рассчитывается во время создания " +"канала. Передачи планируются в рамках интервалов в 1 миллисекунду. " +"Распределение полосы пропускания внутри интервала регламентируется " +"спецификацией USB, раздел 5.6 [2]. Изохронные и прерывающие передачи могут " +"использовать до 90% полосы пропускания в рамках интервала. Пакеты для " +"управляющих и массовых передач планируются после всех изохронных и " +"прерывающих пакетов и используют всю оставшуюся полосу пропускания." + +#. 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 "" +"Дополнительная информация о планировании передач и освобождении пропускной " +"способности доступна в главе 5 спецификации USB, разделе 1.3 спецификации " +"UHCI и разделе 3.4.2 спецификации OHCI." + +#. 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 "" +"После уведомления от концентратора о подключении нового устройства сервисный " +"уровень включает порт, предоставляя устройству ток 100 мА. На этом этапе " +"устройство находится в своём исходном состоянии и прослушивает адрес " +"устройства 0. Сервисный уровень продолжит получение различных дескрипторов " +"через стандартный канал. После этого он отправит запрос Set Address, чтобы " +"переместить устройство с исходного адреса (адрес 0). Несколько драйверов " +"устройств могут поддерживать данное устройство. Например, драйвер модема " +"может поддерживать ISDN TA через интерфейс совместимости AT. Однако драйвер, " +"предназначенный для конкретной модели ISDN-адаптера, может обеспечить " +"гораздо лучшую поддержку этого устройства. Для обеспечения такой гибкости " +"пробы возвращают приоритеты, указывающие уровень их поддержки. Поддержка " +"конкретной версии продукта имеет наивысший приоритет, а универсальный " +"драйвер — самый низкий. Также возможно, что несколько драйверов могут быть " +"подключены к одному устройству, если в одной конфигурации присутствует " +"несколько интерфейсов. Каждому драйверу требуется поддерживать только " +"подмножество интерфейсов." + +#. 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 "" +"Драйвер устройства должен ожидать получения ошибок во время любой транзакции " +"с устройством. Дизайн USB поддерживает и поощряет отключение устройств в " +"любой момент времени. Драйверы должны гарантировать корректную обработку " +"ситуаций, когда устройство исчезает." + +#. 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 "Информация о протоколе драйверов USB" + +#. 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 "" +"Используемый протокол для каналов, отличных от стандартного, не определен " +"спецификацией USB. Информацию об этом можно найти из различных источников. " +"Наиболее точный источник — раздел для разработчиков на домашних страницах " +"USB. На этих страницах доступно растущее количество спецификаций классов " +"устройств. Эти спецификации определяют, каким должно быть совместимое " +"устройство с точки зрения драйвера, базовую функциональность, которую оно " +"должно предоставлять, и протокол, используемый на каналах связи. " +"Спецификация USB включает описание класса концентраторов (Hub Class). " +"Спецификация класса устройств человеко-машинного интерфейса (HID) была " +"создана для поддержки клавиатур, планшетов, сканеров штрих-кодов, кнопок, " +"регуляторов, переключателей и т. д. Третий пример — спецификация класса " +"устройств хранения данных (Mass Storage). Полный список классов устройств " +"можно найти в разделе для разработчиков на домашних страницах USB." + +#. 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 "" +"Для многих устройств информация о протоколе ещё не опубликована. Сведения об " +"используемом протоколе могут быть доступны у компании-производителя " +"устройства. Некоторые компании потребуют подписания соглашения о " +"неразглашении (NDA), прежде чем предоставить спецификации. В большинстве " +"случаев это исключает возможность сделать драйвер открытым." + +#. 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 "" +"Еще один хороший источник информации — исходные коды драйверов Linux, так " +"как ряд компаний начал предоставлять драйверы для Linux для своих устройств. " +"Всегда полезно связаться с авторами этих драйверов для получения информации." + +#. 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 "" +"Пример: Устройства интерфейса пользователя (HID) — Спецификация для " +"устройств интерфейса пользователя, таких как клавиатуры, мыши, планшеты, " +"кнопки, регуляторы и т.д., упоминается в других спецификациях классов " +"устройств и используется во многих устройствах." + +#. 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 "" +"Например, аудиоколонки предоставляют конечные точки для цифро-аналоговых " +"преобразователей и, возможно, дополнительный канал для микрофона. Они также " +"предоставляют конечную точку HID в отдельном интерфейсе для кнопок и " +"регуляторов на передней панели устройства. То же самое справедливо для " +"класса управления монитором. Реализовать поддержку этих интерфейсов " +"достаточно просто с помощью доступных библиотек ядра и пользовательского " +"пространства, а также драйвера класса HID или универсального драйвера. " +"Другим примером устройства с несколькими интерфейсами в одной конфигурации, " +"управляемыми разными драйверами, является недорогая клавиатура со встроенным " +"устаревшим портом для мыши. Чтобы избежать затрат на включение аппаратного " +"обеспечения USB-концентратора в устройство, производители объединили данные " +"мыши, полученные с порта PS/2 на задней панели клавиатуры, и нажатия клавиш " +"в два отдельных интерфейса в одной конфигурации. Драйверы мыши и клавиатуры " +"подключаются к соответствующему интерфейсу и выделяют каналы для двух " +"независимых конечных точек." + +#. 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 "" +"Пример: Загрузка микропрограммы — многие разработанные устройства основаны " +"на процессоре общего назначения с добавленным USB-ядром. Поскольку " +"разработка драйверов и микропрограмм для USB-устройств всё ещё очень нова, " +"многие устройства требуют загрузки микропрограммы после подключения." + +#. 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 "" +"Примером таких устройств является плата ввода-вывода ActiveWire, основанная " +"на чипе EZ-USB. Для этого чипа доступен универсальный загрузчик " +"микропрограмм. Микропрограмма, загруженная в плату ActiveWire, изменяет " +"идентификатор ревизии. Затем выполняется мягкий сброс USB-части чипа EZ-USB " +"для отключения от USB-шины и повторного подключения." + +#. 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 "" +"Пример: Поддержка устройств хранения данных в основном построена на " +"существующих протоколах. Устройство Iomega USB Zipdrive основано на SCSI-" +"версии их накопителя. SCSI-команды и статусные сообщения упаковываются в " +"блоки и передаются через массовые каналы к устройству и от него, эмулируя " +"SCSI-контроллер через USB-соединение. ATAPI и UFI команды поддерживаются " +"аналогичным образом." + +#. 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 "" +"Спецификация Mass Storage поддерживает 2 различных типа обёртки командного " +"блока. Первоначальная попытка была основана на отправке команды и состояния " +"через канал по умолчанию с использованием массовых передач для данных, " +"перемещаемых между хостом и устройством. На основе опыта был разработан " +"второй подход, основанный на обёртке командных и статусных блоков и их " +"отправке через конечные точки массовой передачи (bulk out и bulk in). " +"Спецификация точно определяет, что должно происходить и когда, а также что " +"необходимо делать в случае возникновения ошибки. Наибольшую сложность при " +"написании драйверов для таких устройств представляет встраивание USB-" +"ориентированного протокола в существующую поддержку устройств хранения " +"данных. CAM предоставляет механизмы для этого достаточно прямолинейным " +"способом. С ATAPI всё менее просто, так как исторически интерфейс IDE " +"никогда не имел множества различных вариантов реализации." + +#. 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 "" +"Поддержка USB-дисковода от Y-E Data также не прямолинейна, так как был " +"разработан новый набор команд." diff --git a/documentation/content/ru/books/arch-handbook/vm/_index.adoc b/documentation/content/ru/books/arch-handbook/vm/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/vm/_index.adoc @@ -0,0 +1,127 @@ +--- +description: 'Система управления виртуальной памятью во FreeBSD' +next: books/arch-handbook/smp +params: + path: /books/arch-handbook/vm/ +prev: books/arch-handbook/mac +showBookMenu: true +tags: ["Virtual memory", "vm_page_t", "vm_object_t", "I/O", "KVM"] +title: 'Глава 7. Система управления виртуальной памятью' +weight: 8 +--- + +[[vm]] += Система управления виртуальной памятью +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 7 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/arch-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[vm-physmem]] +== Управление физической памятью `vm_page_t` + +Физическая память управляется постранично с использованием структуры `vm_page_t`. Страницы физической памяти классифицируются посредством размещения соответствующих структур `vm_page_t` в одной из нескольких очередей подкачки. + +Страница может находиться в одном из следующих состояний: зафиксированном (Wired), активном (Active), неактивном (Inactive), кэшированном (Cache) или свободном (Free). За исключением зафиксированного состояния, страница обычно помещается в двусвязный список, представляющий её текущее состояние. Зафиксированные страницы не помещаются ни в одну из очередей. + +FreeBSD реализует более сложную очередь подкачки для кэшированных и свободных страниц с целью реализации раскраски страниц. Каждое из этих состояний включает несколько очередей, организованных в соответствии с размерами кэшей L1 и L2 процессора. Когда требуется выделить новую страницу, FreeBSD пытается получить такую, которая будет достаточно хорошо выровнена с точки зрения кэшей L1 и L2 относительно объекта виртуальной памяти, для которого выделяется страница. + +Кроме того, страница может удерживаться с помощью счётчика ссылок или быть заблокированной с помощью счётчика занятости. Система виртуальной памяти также реализует состояние «абсолютной блокировки» страницы с использованием бита PG_BUSY в флагах страницы. + +В общем случае каждая из очередей подкачки работает по принципу LRU (наименее недавно использованная). Обычно страница изначально помещается в зафиксированное или активное состояние. В зафиксированном состоянии страница, как правило, ассоциирована с какой-либо таблицей страниц. Система виртуальной памяти «состаривает» страницу, просматривая страницы в более активной очереди страниц (LRU), чтобы переместить их в менее активную очередь. Страницы, перемещённые в кэш, всё ещё связаны с объектом виртуальной памяти, но могут быть немедленно повторно использованы. Страницы в очереди свободных действительно являются полностью свободными. FreeBSD стремится минимизировать количество страниц в очереди свободных, но определённый минимальный объём таких страниц должен поддерживаться для обеспечения возможности выделения памяти во время обработки прерываний. + +Если процесс пытается обратиться к странице, которой нет в его таблице страниц, но которая присутствует в одной из очередей подкачки (например, в неактивной или кэшированной), происходит относительно недорогой сбой повторной активации страницы, в результате которого страница повторно активируется. Если же страницы вообще нет в памяти системы, процесс вынужден блокироваться до тех пор, пока страница не будет загружена с диска. + +FreeBSD динамически настраивает свои очереди страниц и старается поддерживать разумные пропорции количества страниц в различных очередях, а также сбалансированное соотношение чистых и грязных страниц. Объём перераспределения зависит от текущей нагрузки на память системы. Это перераспределение выполняется демоном выгрузки страниц (pageout daemon) и включает в себя очистку (laundering) грязных страниц (синхронизацию их с резервным хранилищем), отслеживание активности страниц по ссылкам на них (сброс их положения в очередях LRU или перемещение между очередями), миграцию страниц между очередями при разбалансировке очередей и другие действия. Система виртуальной памяти FreeBSD допускает определённое количество сбоев повторной активации страниц, чтобы точнее определить, насколько страница фактически активна или неактивна. Это позволяет принимать более обоснованные решения о том, когда очищать или выгружать страницу в файл подкачки. + +[[vm-cache]] +== Унифицированный буферный кеш `vm_object_t` + +FreeBSD реализует концепцию универсального «объекта виртуальной памяти» (VM-объекта). VM-объекты могут быть связаны с резервным хранилищем различных типов: без резервного хранилища, с подкачкой, с физическим устройством или с файловым хранилищем. Поскольку файловая система использует те же VM-объекты для управления данными в оперативной памяти, связанными с файлами, в результате получается унифицированный буферный кэш. + +Объекты виртуальной памяти могут быть _затемнены_ (shadowed), то есть размещены друг над другом в виде стека. Например, объект виртуальной памяти с подкачкой может быть размещён поверх объекта, связанного с файловым хранилищем, для реализации отображения mmap() с флагом MAP_PRIVATE. Такое стековое размещение также используется для реализации различных общих свойств, включая копирование при записи (copy-on-write), для адресных пространств созданных при форке процесса. + +Следует отметить, что структура `vm_page_t` может быть связана только с одним объектом виртуальной памяти (VM-объектом) в данный момент времени. Механизм затемнения VM-объектов реализует кажущееся совместное использование одной и той же страницы между несколькими экземплярами. + +[[vm-fileio]] +== Ввод-вывод файловой системы `struct buf` + +VM-объекты, поддерживаемые vnode, такие как объекты, связанные с файловым хранилищем, обычно должны поддерживать собственную информацию о чистоте/грязности, независимую от представления о чистоте/грязности в системе виртуальной памяти. Например, когда система виртуальной памяти решает синхронизировать физическую страницу с её резервным хранилищем, система виртуальной памяти должна отметить страницу как чистую до того, как она будет фактически записана в резервное хранилище. Кроме того, файловые системы должны иметь возможность отображать части файла или метаданных файла в KVM для выполнения операций с ними. + +Сущности, используемые для управления этим процессом, известны как файловые буферы, структуры ``struct buf`` или ``bp``. Когда файловая система должна работать с частью объекта виртуальной памяти, она обычно отображает часть объекта в структуру struct buf, а затем отображает страницы из этой структуры в KVM. Точно так же операции с дисковым вводом-выводом обычно выполняются путём отображения частей объектов в структуры буферов и последующего выполнения ввода-вывода на этих структурах. Соответствующие им страницы vm_page_t обычно блокируются на время выполнения операции ввода-вывода. Файловые буферы также имеют собственное представление о состоянии занятости, что полезно для кода драйвера файловой системы, который предпочитает работать с файловыми буферами, а не с обычными страницами виртуальной памяти. + +FreeBSD резервирует ограниченный объем виртуальной памяти ядра для хранения отображений из структур struct buf на физические страницы памяти, но следует подчеркнуть, что эта память используется исключительно для хранения отображений и не ограничивает возможность кэширования данных. Кэширование физических данных строго связано с ``vm_page_t``, а не с файловыми буферами. Однако, поскольку файловые буферы используются для операций ввода-вывода, они ограничивают количество возможных параллельных операций ввода-вывода. Тем не менее, поскольку обычно доступно несколько тысяч файловых буферов, это редко становится проблемой. + +[[vm-pagetables]] +== Отображение таблиц страниц `vm_map_t, vm_entry_t` + +FreeBSD разделяет топологию физических таблиц страниц от системы виртуальной памяти. Все основные таблицы страниц, связанные с каждым процессом, могут быть восстановлены динамически и обычно считаются временными (throwaway). Специальные таблицы страниц, такие как те, которые управляют KVM (виртуальной памятью ядра), обычно предварительно выделяются навсегда. Эти таблицы страниц не являются временными. + +FreeBSD связывает части vm_object с диапазонами адресов в виртуальной памяти через структуры `vm_map_t` и `vm_entry_t`. Таблицы страниц напрямую создаются из иерархии `vm_map_t` / `vm_entry_t`/ `vm_object_t`. Напоминаем, что физические страницы непосредственно связаны только с `vm_object`, однако это не совсем так. Структуры ``vm_page_t`` также привязаны к таблицами страниц, с которыми они активно ассоциированы. Одна структура `vm_page_t` может быть привязана к нескольким _pmaps_ (так называют таблицы страниц). Тем не менее, иерархическая ассоциация сохраняется, и все ссылки на одну и ту же страницу в одном объекте ссылаются на один и тот же `vm_page_t`, что, в свою очередь, обеспечивает унификацию буферного кэша. + +[[vm-kvm]] +== Отображение виртуальной памяти ядра + +FreeBSD использует KVM для хранения различных структур ядра. Самой крупной сущностью, хранящейся в KVM, является кэш файловых буферов. То есть, отображения, связанные с сущностями `struct buf`. + +В отличие от Linux, FreeBSD _не_ отображает всю физическую память в KVM. Это означает, что FreeBSD может обрабатывать конфигурации памяти до 4 ГБ на 32-битных платформах. На самом деле, если бы MMU это позволял, FreeBSD теоретически могла бы обрабатывать конфигурации памяти до 8 ТБ на 32-битной платформе. Однако, поскольку большинство 32-битных платформ способны отображать только 4 ГБ оперативной памяти, этот вопрос не имеет практического значения. + +KVM управляется через несколько механизмов. Основным механизмом для управления KVM является _аллокатор зон_. Аллокатор зон берет блок KVM и делит его на блоки памяти постоянного размера для выделения структур определённого типа. Вы можете использовать команду `vmstat -m`, чтобы получить обзор текущего использования KVM, разбитого по зонам. + +[[vm-tuning]] +== Настройка системы виртуальной памяти во FreeBSD + +Были преложены значительные усилия сделать ядро FreeBSD динамически настраиваемым. Обычно вам не нужно вмешиваться в настройки, за исключением параметров конфигурации ядра `maxusers` и `NMBCLUSTERS`. Параметры компиляции ядра указанны (обычно) в файле [.filename]#/usr/src/sys/i386/conf/CONFIG_FILE#. Описание всех доступных параметров конфигурации ядра можно найти в файле [.filename]#/usr/src/sys/i386/conf/LINT#. + +В большой системе конфигурации, возможно, вам потребуется увеличить значение `maxusers`. Обычно значения варьируются от 10 до 128. Обратите внимание, что слишком большое значение для `maxusers` может привести к переполнению доступной KVM, что вызовет непредсказуемую работу системы. Лучше оставить `maxusers` на разумном уровне и добавлять другие параметры, такие как `NMBCLUSTERS`, для увеличения конкретных ресурсов. + +Если ваша система будет активно использовать сеть, возможно, вам захочется увеличить значение `NMBCLUSTERS`. Типичные значения варьируются от 1024 до 4096. + +Параметр `NBUF` также традиционно используется для масштабирования системы. Этот параметр определяет объем виртуальной памяти ядра, который система может использовать для отображения файловых буферов для ввода-вывода. Обратите внимание, что этот параметр никак не связан с унифицированным буферным кэшем! В ядрах 3.0-CURRENT и позднее этот параметр динамически настраивается, и в целом не следует настраивать его вручную. Мы рекомендуем вам _не_ пытаться задавать параметр NBUF. Позвольте системе выбрать его автоматически. Слишком малое значение может привести к крайне неэффективной работе файловой системы, в то время как слишком большое значение может привести к истощению очередей страниц из-за того, что слишком много страниц будет закреплено в памяти. + +По умолчанию ядра FreeBSD не оптимизированы. Вы можете установить флаги отладки и оптимизации с помощью директивы `makeoptions` в конфигурации ядра. Обратите внимание, что не следует использовать флаг `-g`, если вы не можете разместить в системе большие ядра (обычно более 7 МБ), которые получаются в результате. + +[.programlisting] +.... +makeoptions DEBUG="-g" +makeoptions COPTFLAGS="-O -pipe" +.... + +Sysctl предоставляет способ настройки параметров ядра во время работы системы. Обычно вам не нужно изменять какие-либо переменные sysctl, особенно те, что связаны с виртуальной памятью. + +Настройка виртуальной памяти (VM) и системы во время работы относительно проста. Во-первых, используйте Soft Updates на ваших файловых системах UFS/FFS, когда это возможно. Файл [.filename]#/usr/src/sys/ufs/ffs/README.softupdates# содержит инструкции (и ограничения) по конфигурации этой функции. + +Во-вторых, настройте достаточный объем подкачки (swap). Вы должны создать раздел подкачки на каждом физическом диске, до четырёх, даже на "рабочих" дисках. Объём подкачки должен быть как минимум в 2 раза больше объёма основной памяти, а возможно — и больше, если у вас немного ОЗУ. Размер раздела подкачки следует выбирать с учётом максимальной конфигурации памяти, которую вы когда-либо планируете установить на эту машину, чтобы в будущем не пришлось переразбивать диски. Если вы хотите иметь возможность сохранять дампы при сбое, ваш первый swap-раздел должен быть не меньше объёма основной памяти, а каталог [.filename]#/var/crash# должен иметь достаточно свободного места для хранения дампа. + +Подкачка на базе NFS вполне допустима в системах версии 4.X и новее, однако необходимо учитывать, что основная нагрузка на подкачку ляжет на NFS-сервер. diff --git a/documentation/content/ru/books/arch-handbook/vm/_index.po b/documentation/content/ru/books/arch-handbook/vm/_index.po new file mode 100644 --- /dev/null +++ b/documentation/content/ru/books/arch-handbook/vm/_index.po @@ -0,0 +1,551 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov , 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-19 19:03+0300\n" +"PO-Revision-Date: 2025-05-26 08:57+0000\n" +"Last-Translator: Vladlen Popolitov \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +"X-Generator: Weblate 4.17\n" + +#. type: Yaml Front Matter Hash Value: description +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:1 +#, no-wrap +msgid "Virtual Memory System in FreeBSD" +msgstr "Система управления виртуальной памятью во FreeBSD" + +#. type: Yaml Front Matter Hash Value: title +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:1 +#, no-wrap +msgid "Chapter 7. Virtual Memory System" +msgstr "Глава 7. Система управления виртуальной памятью" + +#. 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 "Управление физической памятью `vm_page_t`" + +#. 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 "" +"Физическая память управляется постранично с использованием структуры " +"`vm_page_t`. Страницы физической памяти классифицируются посредством " +"размещения соответствующих структур `vm_page_t` в одной из нескольких " +"очередей подкачки." + +#. 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 "" +"Страница может находиться в одном из следующих состояний: зафиксированном " +"(Wired), активном (Active), неактивном (Inactive), кэшированном (Cache) или " +"свободном (Free). За исключением зафиксированного состояния, страница обычно " +"помещается в двусвязный список, представляющий её текущее состояние. " +"Зафиксированные страницы не помещаются ни в одну из очередей." + +#. 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 "" +"FreeBSD реализует более сложную очередь подкачки для кэшированных и " +"свободных страниц с целью реализации раскраски страниц. Каждое из этих " +"состояний включает несколько очередей, организованных в соответствии с " +"размерами кэшей L1 и L2 процессора. Когда требуется выделить новую страницу, " +"FreeBSD пытается получить такую, которая будет достаточно хорошо выровнена с " +"точки зрения кэшей L1 и L2 относительно объекта виртуальной памяти, для " +"которого выделяется страница." + +#. 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 "" +"Кроме того, страница может удерживаться с помощью счётчика ссылок или быть " +"заблокированной с помощью счётчика занятости. Система виртуальной памяти " +"также реализует состояние «абсолютной блокировки» страницы с использованием " +"бита PG_BUSY в флагах страницы." + +#. 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 "" +"В общем случае каждая из очередей подкачки работает по принципу LRU " +"(наименее недавно использованная). Обычно страница изначально помещается в " +"зафиксированное или активное состояние. В зафиксированном состоянии " +"страница, как правило, ассоциирована с какой-либо таблицей страниц. Система " +"виртуальной памяти «состаривает» страницу, просматривая страницы в более " +"активной очереди страниц (LRU), чтобы переместить их в менее активную " +"очередь. Страницы, перемещённые в кэш, всё ещё связаны с объектом " +"виртуальной памяти, но могут быть немедленно повторно использованы. Страницы " +"в очереди свободных действительно являются полностью свободными. FreeBSD " +"стремится минимизировать количество страниц в очереди свободных, но " +"определённый минимальный объём таких страниц должен поддерживаться для " +"обеспечения возможности выделения памяти во время обработки прерываний." + +#. 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 "" +"FreeBSD динамически настраивает свои очереди страниц и старается " +"поддерживать разумные пропорции количества страниц в различных очередях, а " +"также сбалансированное соотношение чистых и грязных страниц. Объём " +"перераспределения зависит от текущей нагрузки на память системы. Это " +"перераспределение выполняется демоном выгрузки страниц (pageout daemon) и " +"включает в себя очистку (laundering) грязных страниц (синхронизацию их с " +"резервным хранилищем), отслеживание активности страниц по ссылкам на них " +"(сброс их положения в очередях LRU или перемещение между очередями), " +"миграцию страниц между очередями при разбалансировке очередей и другие " +"действия. Система виртуальной памяти FreeBSD допускает определённое " +"количество сбоев повторной активации страниц, чтобы точнее определить, " +"насколько страница фактически активна или неактивна. Это позволяет принимать " +"более обоснованные решения о том, когда очищать или выгружать страницу в " +"файл подкачки." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:69 +#, no-wrap +msgid "The Unified Buffer Cache `vm_object_t`" +msgstr "Унифицированный буферный кеш `vm_object_t`" + +#. 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 "" +"FreeBSD реализует концепцию универсального «объекта виртуальной памяти» (VM-" +"объекта). VM-объекты могут быть связаны с резервным хранилищем различных " +"типов: без резервного хранилища, с подкачкой, с физическим устройством или с " +"файловым хранилищем. Поскольку файловая система использует те же VM-объекты " +"для управления данными в оперативной памяти, связанными с файлами, в " +"результате получается унифицированный буферный кэш." + +#. 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 "" +"Объекты виртуальной памяти могут быть _затемнены_ (shadowed), то есть " +"размещены друг над другом в виде стека. Например, объект виртуальной памяти " +"с подкачкой может быть размещён поверх объекта, связанного с файловым " +"хранилищем, для реализации отображения mmap() с флагом MAP_PRIVATE. Такое " +"стековое размещение также используется для реализации различных общих " +"свойств, включая копирование при записи (copy-on-write), для адресных " +"пространств созданных при форке процесса." + +#. 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 "" +"Следует отметить, что структура `vm_page_t` может быть связана только с " +"одним объектом виртуальной памяти (VM-объектом) в данный момент времени. " +"Механизм затемнения VM-объектов реализует кажущееся совместное использование " +"одной и той же страницы между несколькими экземплярами." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:78 +#, no-wrap +msgid "Filesystem I/O `struct buf`" +msgstr "Ввод-вывод файловой системы `struct buf`" + +#. 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 "" +"VM-объекты, поддерживаемые vnode, такие как объекты, связанные с файловым " +"хранилищем, обычно должны поддерживать собственную информацию о чистоте/" +"грязности, независимую от представления о чистоте/грязности в системе " +"виртуальной памяти. Например, когда система виртуальной памяти решает " +"синхронизировать физическую страницу с её резервным хранилищем, система " +"виртуальной памяти должна отметить страницу как чистую до того, как она " +"будет фактически записана в резервное хранилище. Кроме того, файловые " +"системы должны иметь возможность отображать части файла или метаданных файла " +"в KVM для выполнения операций с ними." + +#. 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 "" +"Сущности, используемые для управления этим процессом, известны как файловые " +"буферы, структуры ``struct buf`` или ``bp``. Когда файловая система должна " +"работать с частью объекта виртуальной памяти, она обычно отображает часть " +"объекта в структуру struct buf, а затем отображает страницы из этой " +"структуры в KVM. Точно так же операции с дисковым вводом-выводом обычно " +"выполняются путём отображения частей объектов в структуры буферов и " +"последующего выполнения ввода-вывода на этих структурах. Соответствующие им " +"страницы vm_page_t обычно блокируются на время выполнения операции ввода-" +"вывода. Файловые буферы также имеют собственное представление о состоянии " +"занятости, что полезно для кода драйвера файловой системы, который " +"предпочитает работать с файловыми буферами, а не с обычными страницами " +"виртуальной памяти." + +#. 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 "" +"FreeBSD резервирует ограниченный объем виртуальной памяти ядра для хранения " +"отображений из структур struct buf на физические страницы памяти, но следует " +"подчеркнуть, что эта память используется исключительно для хранения " +"отображений и не ограничивает возможность кэширования данных. Кэширование " +"физических данных строго связано с ``vm_page_t``, а не с файловыми буферами. " +"Однако, поскольку файловые буферы используются для операций ввода-вывода, " +"они ограничивают количество возможных параллельных операций ввода-вывода. " +"Тем не менее, поскольку обычно доступно несколько тысяч файловых буферов, " +"это редко становится проблемой." + +#. 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 "Отображение таблиц страниц `vm_map_t, vm_entry_t`" + +#. 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 "" +"FreeBSD разделяет топологию физических таблиц страниц от системы виртуальной " +"памяти. Все основные таблицы страниц, связанные с каждым процессом, могут " +"быть восстановлены динамически и обычно считаются временными (throwaway). " +"Специальные таблицы страниц, такие как те, которые управляют KVM " +"(виртуальной памятью ядра), обычно предварительно выделяются навсегда. Эти " +"таблицы страниц не являются временными." + +#. 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 "" +"FreeBSD связывает части vm_object с диапазонами адресов в виртуальной памяти " +"через структуры `vm_map_t` и `vm_entry_t`. Таблицы страниц напрямую " +"создаются из иерархии `vm_map_t` / `vm_entry_t`/ `vm_object_t`. Напоминаем, " +"что физические страницы непосредственно связаны только с `vm_object`, однако " +"это не совсем так. Структуры ``vm_page_t`` также привязаны к таблицами " +"страниц, с которыми они активно ассоциированы. Одна структура `vm_page_t` " +"может быть привязана к нескольким _pmaps_ (так называют таблицы страниц). " +"Тем не менее, иерархическая ассоциация сохраняется, и все ссылки на одну и " +"ту же страницу в одном объекте ссылаются на один и тот же `vm_page_t`, что, " +"в свою очередь, обеспечивает унификацию буферного кэша." + +#. 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 "" +"FreeBSD использует KVM для хранения различных структур ядра. Самой крупной " +"сущностью, хранящейся в KVM, является кэш файловых буферов. То есть, " +"отображения, связанные с сущностями `struct buf`." + +#. 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 "" +"В отличие от Linux, FreeBSD _не_ отображает всю физическую память в KVM. Это " +"означает, что FreeBSD может обрабатывать конфигурации памяти до 4 ГБ на 32-" +"битных платформах. На самом деле, если бы MMU это позволял, FreeBSD " +"теоретически могла бы обрабатывать конфигурации памяти до 8 ТБ на 32-битной " +"платформе. Однако, поскольку большинство 32-битных платформ способны " +"отображать только 4 ГБ оперативной памяти, этот вопрос не имеет " +"практического значения." + +#. 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 "" +"KVM управляется через несколько механизмов. Основным механизмом для " +"управления KVM является _аллокатор зон_. Аллокатор зон берет блок KVM и " +"делит его на блоки памяти постоянного размера для выделения структур " +"определённого типа. Вы можете использовать команду `vmstat -m`, чтобы " +"получить обзор текущего использования KVM, разбитого по зонам." + +#. type: Title == +#: documentation/content/en/books/arch-handbook/vm/_index.adoc:103 +#, no-wrap +msgid "Tuning the FreeBSD VM System" +msgstr "Настройка системы виртуальной памяти во FreeBSD" + +#. 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 "" +"Были преложены значительные усилия сделать ядро FreeBSD динамически " +"настраиваемым. Обычно вам не нужно вмешиваться в настройки, за исключением " +"параметров конфигурации ядра `maxusers` и `NMBCLUSTERS`. Параметры " +"компиляции ядра указанны (обычно) в файле [.filename]#/usr/src/sys/i386/conf/" +"CONFIG_FILE#. Описание всех доступных параметров конфигурации ядра можно " +"найти в файле [.filename]#/usr/src/sys/i386/conf/LINT#." + +#. 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 "" +"В большой системе конфигурации, возможно, вам потребуется увеличить значение " +"`maxusers`. Обычно значения варьируются от 10 до 128. Обратите внимание, что " +"слишком большое значение для `maxusers` может привести к переполнению " +"доступной KVM, что вызовет непредсказуемую работу системы. Лучше оставить " +"`maxusers` на разумном уровне и добавлять другие параметры, такие как " +"`NMBCLUSTERS`, для увеличения конкретных ресурсов." + +#. 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 "" +"Если ваша система будет активно использовать сеть, возможно, вам захочется " +"увеличить значение `NMBCLUSTERS`. Типичные значения варьируются от 1024 до " +"4096." + +#. 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 "" +"Параметр `NBUF` также традиционно используется для масштабирования системы. " +"Этот параметр определяет объем виртуальной памяти ядра, который система " +"может использовать для отображения файловых буферов для ввода-вывода. " +"Обратите внимание, что этот параметр никак не связан с унифицированным " +"буферным кэшем! В ядрах 3.0-CURRENT и позднее этот параметр динамически " +"настраивается, и в целом не следует настраивать его вручную. Мы рекомендуем " +"вам _не_ пытаться задавать параметр NBUF. Позвольте системе выбрать его " +"автоматически. Слишком малое значение может привести к крайне неэффективной " +"работе файловой системы, в то время как слишком большое значение может " +"привести к истощению очередей страниц из-за того, что слишком много страниц " +"будет закреплено в памяти." + +#. 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 "" +"По умолчанию ядра FreeBSD не оптимизированы. Вы можете установить флаги " +"отладки и оптимизации с помощью директивы `makeoptions` в конфигурации ядра. " +"Обратите внимание, что не следует использовать флаг `-g`, если вы не можете " +"разместить в системе большие ядра (обычно более 7 МБ), которые получаются в " +"результате." + +#. 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 "" +"makeoptions DEBUG=\"-g\" \n" +"makeoptions COPTFLAGS=\"-O -pipe\"\n" + +#. 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 "" +"Sysctl предоставляет способ настройки параметров ядра во время работы " +"системы. Обычно вам не нужно изменять какие-либо переменные sysctl, особенно " +"те, что связаны с виртуальной памятью." + +#. 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 "" +"Настройка виртуальной памяти (VM) и системы во время работы относительно " +"проста. Во-первых, используйте Soft Updates на ваших файловых системах UFS/" +"FFS, когда это возможно. Файл [.filename]#/usr/src/sys/ufs/ffs/" +"README.softupdates# содержит инструкции (и ограничения) по конфигурации этой " +"функции." + +#. 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 "" +"Во-вторых, настройте достаточный объем подкачки (swap). Вы должны создать " +"раздел подкачки на каждом физическом диске, до четырёх, даже на \"рабочих\" " +"дисках. Объём подкачки должен быть как минимум в 2 раза больше объёма " +"основной памяти, а возможно — и больше, если у вас немного ОЗУ. Размер " +"раздела подкачки следует выбирать с учётом максимальной конфигурации памяти, " +"которую вы когда-либо планируете установить на эту машину, чтобы в будущем " +"не пришлось переразбивать диски. Если вы хотите иметь возможность сохранять " +"дампы при сбое, ваш первый swap-раздел должен быть не меньше объёма основной " +"памяти, а каталог [.filename]#/var/crash# должен иметь достаточно свободного " +"места для хранения дампа." + +#. 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 "" +"Подкачка на базе NFS вполне допустима в системах версии 4.X и новее, однако " +"необходимо учитывать, что основная нагрузка на подкачку ляжет на NFS-сервер."