diff options
Diffstat (limited to 'documentation/content/ru/articles/geom-class')
| -rw-r--r-- | documentation/content/ru/articles/geom-class/_index.adoc | 43 | ||||
| -rw-r--r-- | documentation/content/ru/articles/geom-class/_index.po | 1388 |
2 files changed, 1411 insertions, 20 deletions
diff --git a/documentation/content/ru/articles/geom-class/_index.adoc b/documentation/content/ru/articles/geom-class/_index.adoc index 9ec0e0c6e2..a7940ade06 100644 --- a/documentation/content/ru/articles/geom-class/_index.adoc +++ b/documentation/content/ru/articles/geom-class/_index.adoc @@ -1,8 +1,11 @@ --- -title: Создание класса GEOM authors: - - author: Ivan Voras + - + author: 'Ivan Voras' email: ivoras@FreeBSD.org +description: 'Руководство по внутреннему устройству GEOM и созданию собственного класса GEOM' +tags: ["GEOM", "kernel", "modules", "FreeBSD"] +title: 'Создание класса GEOM' trademarks: ["freebsd", "intel", "general"] --- @@ -47,10 +50,10 @@ endif::[] toc::[] [[intro]] -== Вступление +== Введение [[intro-docs]] -=== Документация +=== Documentation Документация по программированию для ядра скудная, это одна из немногих областей программирования, где почти нет хороших учебных пособий, и совет "читай исходники!" - сохраняет свою справедливость. Однако, существует несколько статей и книг разной актуальности, которые рекомендуются к изучению перед тем, как начать программировать: @@ -88,7 +91,7 @@ options WITNESS_SUPPORT options WITNESS .... -Также включите отладочные символы, если планируете выполнять отладку по дампам аварийных отказов +Также включите отладочные символы, если планируете выполнять отладку по дампам аварийных отказов: [.programlisting] .... @@ -129,7 +132,7 @@ kern.metadelay=3 [.programlisting] .... dumpdev="/dev/ad0s4b" -dumpdir="/usr/core" +dumpdir="/usr/core .... Переменная `dumpdev` указывает на раздел подкачки, а `dumpdir` сообщает системе куда перемещать дамп ядра при следующей загрузке. @@ -170,7 +173,7 @@ KMOD=geom_journal .include <bsd.kmod.mk> .... -Этот [.filename]#Makefile# (с измененными именами файлов) подойдет к любому модулю ядра. Класс GEOM может размещаться в одном единственном модуле ядра. Если для сборки вашего модуля требуется больше, чем один файл, то перечислите их имена, разделенные пробельными символами, в переменной `SRCS`. +Этот [.filename]#Makefile# (с измененными именами файлов) подойдет к любому модулю ядра. Класс GEOM может размещаться в одном единственном модуле ядра. Если для сборки вашего модуля требуется больше, чем один файл, то перечислите их имена, разделенные пробельными символами, в переменной `SRCS`. [[kernelprog]] == Программирование в ядре FreeBSD @@ -187,7 +190,7 @@ KMOD=geom_journal static MALLOC_DEFINE(M_GJOURNAL, "gjournal data", "GEOM_JOURNAL Data"); .... -Для того, чтобы можно было использовать этот макрос, необходимо включить следующие заголовочные файлы: [.filename]#sys/param.h#, [.filename]#sys/kernel.h# и [.filename]#sys/malloc.h# +Для того, чтобы можно было использовать этот макрос, необходимо включить следующие заголовочные файлы: [.filename]#sys/param.h#, [.filename]#sys/kernel.h# и [.filename]#sys/malloc.h#. Существует еще один механизм выделения памяти - UMA (Universal Memory Allocator), описанный в man:uma[9]. Это специфический метод, преимущественно предназначенный для быстрого выделения памяти под списки, состоящие из элементов одинакового размера (например, динамические массивы структур). @@ -201,7 +204,7 @@ KMOD=geom_journal [[kernelprog-bios]] === BIOs -Структура `bio` используется для всех операций ввода/вывода, касающихся GEOM. Она содержит информацию о том, какое устройство ('поставщик geom') должно ответить на запрос, тип запроса, смещение, длину и указатель на буфер, а также набор "определенных пользователем" флагов и полей . +Структура `bio` используется для всех операций ввода/вывода, касающихся GEOM. Она содержит информацию о том, какое устройство ('поставщик geom') должно ответить на запрос, тип запроса, смещение, длину и указатель на буфер, а также набор "определенных пользователем" флагов и полей . Важным моментом является то, что `bio` обрабатываются асинхронно. Это значит, что во многих частях кода нет аналога к man:read[2] и man:write[2] функциям из пространства пользовательских процессов, которые не возвращают управление пока не выполнится системный вызов. Скорее, по завершении обработки запроса (или в случае ошибки при обработке) как извещение вызывается определенная пользователем функция. @@ -220,12 +223,12 @@ KMOD=geom_journal Класс GEOM выполняет преобразования данных. Эти преобразования могут быть скомпонованы друг с другом в виде дерева. Экземпляр класса GEOM называют __geom__. -В каждом классе GEOM есть несколько "методов класса", которые вызываются когда экземпляра класса нет в наличии (или же они не привязаны к конкретному экземпляру класса). +В каждом классе GEOM есть несколько "методов класса", которые вызываются когда экземпляра класса нет в наличии (или же они не привязаны к конкретному экземпляру класса): * `.init` вызывается тогда, когда системе GEOM становится известно о классе GEOM (например, когда загружается модуль ядра). -* `.fini` будет вызван в случае отказа GEOM системы от класса (например, при выгрузке модуля). +* `.fini` будет вызван в случае отказа GEOM системы от класса (например, при выгрузке модуля) * `.taste` вызывается, когда в системе появляется новый класс или поставщик geom ("provider"). Если соответствие найдено, то эта функция обычно создает и запускает экземпляр geom. -* `.destroy_geom` вызывается при необходимости разрушить экземпляр geom. +* `.destroy_geom` вызывается при необходимости разрушить экземпляр geom * `.ctlconf` будет вызван, когда пользователь запросит изменение конфигурации существующего экземпляра geom Также определены функции событий GEOM, которые копируются в экземпляр geom. @@ -241,7 +244,7 @@ KMOD=geom_journal * `struct g_provider *provider` : "поставщик geom" предоставляемый данным экземпляром geom * `uint16_t n_disks` : Количество потребителей geom ("consumer"), обслуживаемых данным экземпляром geom -* `struct g_consumer \**disks` : Массив `struct g_consumer*`. (Невозможно обойтись одинарным указателем, потому что система GEOM создает для нас структуры struct g_consumer) +* `struct g_consumer \**disks` : Массив `struct g_consumer*`. (Невозможно обойтись одинарным указателем, потому что система GEOM создает для нас структуры struct g_consumer). Структура `softc` содержит состояние экземпляра geom. У каждого экземпляра есть свой softc. @@ -283,7 +286,7 @@ KMOD=geom_journal [.programlisting] .... - команда [-опции] имя_geom [другие] + verb [-options] geomname [other] .... Общими командами являются: @@ -329,18 +332,18 @@ KMOD=geom_journal * Файловая система преобразует запрос в экземпляр структуры bio и передает его системе GEOM. Файловая система "знает", что экземпляр geom должен обработать запрос, так как файловые системы размещаются непосредственно над экземпляром geom. * Запрос завершается вызовом функции `.start`() в потоке g_down и достигает верхнего экземпляра geom. * Верхний экземпляр geom (например, это секционировщик разделов (partition slicer)) определяет, что запрос должен быть переадресован нижестоящему экземпляру geom (к примеру, драйверу диска). Вышестоящий экземпляр geom создает копию запроса bio (запросы bio _ВСЕГДА_ копируются при передаче между экземплярами geom при помощи `g_clone_bio`()!), изменяет поля смещения и целевого поставщика geom и запускает на обработку копию при помощи функции `g_io_request`() -* Драйвер диска также получает запрос bio, как вызов функции `.start`() в потоке `g_down`. Драйвер обращается к контроллеру диска, получает блок данных и вызывает функцию `g_io_deliver`() используя копию запроса bio -* Теперь, извещение о завершении bio "всплывает" в потоке `g_up`. Сначала в потоке `g_up` вызывается функция `.done`() секционировщика разделов, последний использует полученную информацию, разрушает клонированный экземпляр структуры bio посредством `g_destroy_bio`() и вызывает `g_io_deliver`() используя первоначальный запрос -* Файловая система получает данные и передает их пользовательскому процессу +* Драйвер диска также получает запрос bio, как вызов функции `.start`() в потоке `g_down`. Драйвер обращается к контроллеру диска, получает блок данных и вызывает функцию `g_io_deliver`() используя копию запроса bio. +* Теперь, извещение о завершении bio "всплывает" в потоке `g_up`. Сначала в потоке `g_up` вызывается функция `.done`() секционировщика разделов, последний использует полученную информацию, разрушает клонированный экземпляр структуры bio посредством `g_destroy_bio`() и вызывает `g_io_deliver`() используя первоначальный запрос. +* Файловая система получает данные и передает их пользовательскому процессу. -За информацией о том, как данные передаются в структуре `bio` между экземплярами geom, смотрите man:g_bio[9] (обратите внимание на использование полей `bio_parent` и `bio_children`). +За информацией о том, как данные передаются в структуре `bio` между экземплярами geom, смотрите man:g_bio[9] (обратите внимание на использование полей `bio_parent` и `bio_children`). Важный момент в том, что __НЕЛЬЗЯ ДОПУСКАТЬ БЛОКИРОВОК В ПОТОКАХ G_UP И G_DOWN__. Вот неполный перечень того, что нельзя делать в этих потоках: * Вызывать функции `msleep`() или `tsleep`(). * Использовать функции `g_write_data`() и `g_read_data`(), так как они блокируются в момент обмена данными с потребителями geom. * Ожидать ввод/вывод. -* Вызывать man:malloc[9] и `uma_zalloc`() с установленным флагом `M_WAITOK`. +* Вызывать man:malloc[9] и `uma_zalloc`() с установленным флагом `M_WAITOK` * Использовать man:sx[9] Это ограничение на код GEOM призвано избежать от "засорения" пути запроса ввода/вывода, так как блокировки обычно не имеют четких временных границ, и нет гарантий на занимаемое время (также на то есть и другие технические причины). Это также значит, что в вышеупомянутых потоках сколь-нибудь сложные операции выполнить нельзя, например: любое сложное преобразование требует выделения памяти. К счастью решение есть: создание дополнительных ядерных потоков. @@ -348,7 +351,7 @@ KMOD=geom_journal [[geom-kernelthreads]] === Ядерные потоки выполнения, предназначенные для использования в коде geom -Ядерные потоки выполнения создаются функцией man:kthread_create[9], в своем поведении они схожи с потоками, созданными в пространстве пользовательских процессов, но есть одно отличие: они не могут известить вызвавший их поток о своем завершении; по завершению - необходимо вызывать man:kthread_exit[9] +Ядерные потоки выполнения создаются функцией man:kthread_create[9], в своем поведении они схожи с потоками, созданными в пространстве пользовательских процессов, но есть одно отличие: они не могут известить вызвавший их поток о своем завершении; по завершению - необходимо вызывать man:kthread_exit[9]. В коде GEOM обычное назначение этих потоков - разгрузить поток `g_down` (функцию `.start`() ) от обработки запросов. Эти потоки подобны "обработчикам событий" ("event handlers"): у них есть очередь событий (которая наполняется событиями от разных функций из разных потоков; очередь необходимо защищать мьютексом), события из очереди выбираются одно за другим и обрабатываются в большом блоке `switch`(). diff --git a/documentation/content/ru/articles/geom-class/_index.po b/documentation/content/ru/articles/geom-class/_index.po new file mode 100644 index 0000000000..0fd7cf563b --- /dev/null +++ b/documentation/content/ru/articles/geom-class/_index.po @@ -0,0 +1,1388 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# Vladlen Popolitov <vladlenpopolitov@list.ru>, 2025. +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-09-20 13:16+0300\n" +"PO-Revision-Date: 2025-07-05 04:45+0000\n" +"Last-Translator: Vladlen Popolitov <vladlenpopolitov@list.ru>\n" +"Language-Team: Russian <https://translate-dev.freebsd.org/projects/" +"documentation/articlesgeom-class_index/ru/>\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/articles/geom-class/_index.adoc:1 +#, no-wrap +msgid "A guide to GEOM internals, and writing your own GEOM class" +msgstr "Руководство по внутреннему устройству GEOM и созданию собственного класса GEOM" + +#. type: Title = +#: documentation/content/en/articles/geom-class/_index.adoc:1 +#: documentation/content/en/articles/geom-class/_index.adoc:11 +#, no-wrap +msgid "Writing a GEOM Class" +msgstr "Создание класса GEOM" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:44 +msgid "Abstract" +msgstr "Аннотация" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:47 +msgid "" +"This text documents some starting points in developing GEOM classes, and " +"kernel modules in general. It is assumed that the reader is familiar with C " +"userland programming." +msgstr "" +"Эта статья документирует некоторые начальные выкладки в разработке GEOM-" +"классов, а также модулей ядра в общем. Предполагается, что читатель близко " +"знаком с программированием на Си в контексте пространства пользовательских " +"процессов (userland)." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:49 +msgid "'''" +msgstr "'''" + +#. type: Title == +#: documentation/content/en/articles/geom-class/_index.adoc:53 +#, no-wrap +msgid "Introduction" +msgstr "Введение" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:56 +#, no-wrap +msgid "Documentation" +msgstr "Documentation" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:60 +msgid "" +"Documentation on kernel programming is scarce - it is one of few areas where " +"there is nearly nothing in the way of friendly tutorials, and the phrase " +"\"use the source!\" really holds true. However, there are some bits and " +"pieces (some of them seriously outdated) floating around that should be " +"studied before beginning to code:" +msgstr "" +"Документация по программированию для ядра скудная, это одна из немногих " +"областей программирования, где почти нет хороших учебных пособий, и совет " +"\"читай исходники!\" - сохраняет свою справедливость. Однако, существует " +"несколько статей и книг разной актуальности, которые рекомендуются к " +"изучению перед тем, как начать программировать:" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:62 +msgid "" +"The extref:{developers-handbook}[FreeBSD Developer's Handbook] - part of the " +"documentation project, it does not contain anything specific to kernel " +"programming, but rather some general useful information." +msgstr "" +"extref:{developers-handbook}[Руководство FreeBSD для разработчиков] - часть " +"Проекта Документации FreeBSD, ничего специфичного о программировании ядра в " +"нем нет, зато есть немного общей полезной информации." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:63 +msgid "" +"The extref:{arch-handbook}[FreeBSD Architecture Handbook] - also from the " +"documentation project, contains descriptions of several low-level facilities " +"and procedures. The most important chapter is 13, extref:{arch-handbook}" +"[Writing FreeBSD device drivers, driverbasics]." +msgstr "" +"extref:{arch-handbook}[Руководство по Архитектуре FreeBSD] - также является " +"частью Проекта Документации FreeBSD, содержит описания некоторых " +"низкоуровневых средств и процедур. Уделите внимание разделу номер 13 - " +"extref:{arch-handbook}[Написание драйверов устройств для FreeBSD, " +"driverbasics]." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:64 +msgid "" +"The Blueprints section of http://www.freebsddiary.org[FreeBSD Diary] web " +"site - contains several interesting articles on kernel facilities." +msgstr "" +"Несколько интересных статей об устройстве ядра можно найти на сайте http://" +"www.freebsddiary.com[FreeBSD Diary]." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:65 +msgid "" +"The man pages in section 9 - for important documentation on kernel functions." +msgstr "" +"Страницы из раздела номер 9 системного справочника, содержат важную " +"документацию по функциям ядра." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:66 +msgid "" +"The man:geom[4] man page and http://phk.freebsd.dk/pubs/[PHK's GEOM slides] " +"- for general introduction of the GEOM subsystem." +msgstr "" +"Страница справочника man:geom[4], а также http://phk.freebsd.dk/pubs/[слайды " +"Пола-Хеннинга Кампа ] - общее представление о подсистеме GEOM." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:67 +msgid "" +"Man pages man:g_bio[9], man:g_event[9], man:g_data[9], man:g_geom[9], " +"man:g_provider[9], man:g_consumer[9], man:g_access[9] & others linked from " +"those, for documentation on specific functionalities." +msgstr "" +"Страницы справочника man:g_bio[9], man:g_event[9], man:g_data[9], " +"man:g_geom[9], man:g_provider[9], man:g_consumer[9], man:g_access[9], а " +"также другие, связанные с вышеупомянутыми и раскрывающие специфический " +"функционал подсистемы GEOM." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:68 +msgid "" +"The man:style[9] man page - for documentation on the coding-style " +"conventions which must be followed for any code which is to be committed to " +"the FreeBSD tree." +msgstr "" +"Страница справочника man:style[9] - документирует соглашения о стиле " +"оформления кода, которые обязаны быть соблюдены если вы планируете передать " +"ваш код в Subversion репозиторий FreeBSD." + +#. type: Title == +#: documentation/content/en/articles/geom-class/_index.adoc:70 +#, no-wrap +msgid "Preliminaries" +msgstr "Подготовка" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:77 +msgid "" +"The best way to do kernel development is to have (at least) two separate " +"computers. One of these would contain the development environment and " +"sources, and the other would be used to test the newly written code by " +"network-booting and network-mounting filesystems from the first one. This " +"way if the new code contains bugs and crashes the machine, it will not mess " +"up the sources (and other \"live\" data). The second system does not even " +"require a proper display. Instead, it could be connected with a serial " +"cable or KVM to the first one." +msgstr "" +"Для того, чтоб заниматься разработками для ядра, желательно иметь два " +"отдельных компьютера. Один из них предназначен для среды разработки и " +"исходных кодов, а второй - для запуска тестов отлаживаемого кода. Второму " +"компьютеру для работы достаточно иметь возможность выполнять начальную " +"загрузку по сети и монтирование файловых систем по сети. В этой ситуации, " +"если отлаживаемый код содержит ошибки и вызовет аварийную остановку системы, " +"то это не повлечет порчу или утерю исходного кода . Второму компьютеру даже " +"не потребуется иметь свой монитор, достаточно будет соединения асинхронных " +"портов кабелем RS-232 или соединения при помощи KVM-устройства." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:80 +msgid "" +"But, since not everybody has two or more computers handy, there are a few " +"things that can be done to prepare an otherwise \"live\" system for " +"developing kernel code. This setup is also applicable for developing in a " +"http://www.vmware.com/[VMWare] or http://www.qemu.org/[QEmu] virtual machine " +"(the next best thing after a dedicated development machine)." +msgstr "" +"Но так как далеко не у каждого есть два или более компьютеров под рукой, " +"есть пара способов подготовить иную \"живую\" систему для разработки кода " +"для ядра. Один из них - это разработка в http://www.vmware.com/[VMWare] или " +"http://www.qemu.org/[QEmu] виртуальной машине (это лучшее из доступного, " +"после, конечно-же, выделенного для тестов компьютера)." + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:82 +#, no-wrap +msgid "Modifying a System for Development" +msgstr "Настройка системы для разработки" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:85 +msgid "" +"For any kernel programming a kernel with `INVARIANTS` enabled is a must-" +"have. So enter these in your kernel configuration file:" +msgstr "" +"Прежде всего необходимо иметь в ядре поддержку `INVARIANTS`. Добавьте " +"следующие строки в файл конфигурации ядра:" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:90 +#, no-wrap +msgid "" +"options INVARIANT_SUPPORT\n" +"options INVARIANTS\n" +msgstr "" +"options INVARIANT_SUPPORT\n" +"options INVARIANTS\n" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:93 +msgid "" +"For more debugging you should also include WITNESS support, which will alert " +"you of mistakes in locking:" +msgstr "" +"Для большей информативности при отладке включите поддержку WITNESS, которая " +"будет предупреждать вас в случае возникновения взаимоблокировок:" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:98 +#, no-wrap +msgid "" +"options WITNESS_SUPPORT\n" +"options WITNESS\n" +msgstr "" +"options WITNESS_SUPPORT\n" +"options WITNESS\n" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:101 +msgid "For debugging crash dumps, a kernel with debug symbols is needed:" +msgstr "" +"Также включите отладочные символы, если планируете выполнять отладку по " +"дампам аварийных отказов:" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:105 +#, no-wrap +msgid " makeoptions DEBUG=-g\n" +msgstr " makeoptions DEBUG=-g\n" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:110 +msgid "" +"With the usual way of installing the kernel (`make installkernel`) the debug " +"kernel will not be automatically installed. It is called " +"[.filename]#kernel.debug# and located in [.filename]#/usr/obj/usr/src/sys/" +"KERNELNAME/#. For convenience it should be copied to [.filename]#/boot/" +"kernel/#." +msgstr "" +"Установка отладочного ядра обычным способом (`make installkernel`) не даст " +"привычного результата: файл ядра будет называться [.filename]#kernel.debug# " +"и будет находиться в [.filename]#/usr/obj/usr/src/sys/KERNELNAME/#. Для " +"удобства, отладочное ядро необходимо скопировать в [.filename]#/boot/kernel/" +"#." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:113 +msgid "" +"Another convenience is enabling the kernel debugger so you can examine a " +"kernel panic when it happens. For this, enter the following lines in your " +"kernel configuration file:" +msgstr "" +"Также удобно иметь включенный отладчик ядра, так вы сможете исследовать " +"паники сразу-же после их возникновения. Для включения отладчика добавьте " +"следующие строки в файл конфигурации ядра:" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:119 +#, no-wrap +msgid "" +"options KDB\n" +"options DDB\n" +"options KDB_TRACE\n" +msgstr "" +"options KDB\n" +"options DDB\n" +"options KDB_TRACE\n" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:122 +msgid "" +"For this to work you might need to set a sysctl (if it is not on by default):" +msgstr "" +"Для автоматического запуска отладчика ядра после возникновения паники может " +"понадобиться установить переменную sysctl:" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:126 +#, no-wrap +msgid " debug.debugger_on_panic=1\n" +msgstr " debug.debugger_on_panic=1\n" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:134 +msgid "" +"Kernel panics will happen, so care should be taken with the filesystem " +"cache. In particular, having softupdates might mean the latest file version " +"could be lost if a panic occurs before it is committed to storage. " +"Disabling softupdates yields a great performance hit, and still does not " +"guarantee data consistency. Mounting filesystem with the \"sync\" option is " +"needed for that. For a compromise, the softupdates cache delays can be " +"shortened. There are three sysctl's that are useful for this (best to be " +"set in [.filename]#/etc/sysctl.conf#):" +msgstr "" +"Паники системы будут происходить, поэтому уделите внимание кэшу файловой " +"системы. Обычно, при включенном механизме softupdates, последняя версия " +"файла может быть утеряна если паника произошла раньше сбрасывания кэша на " +"устройство хранения. Выключение механизма softupdates (посредством " +"монтирования файловой системы с опцией \"sync\") значительно сказывается на " +"производительности и, опять-же, не гарантирует целостности данных. Как " +"компромисс, можно сократить задержки сбрасывания кэша механизма softupdates. " +"Есть три переменных sysctl, значения которых необходимо изменить (лучше " +"всего - прописав их в [.filename]#/etc/sysctl.conf#):" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:140 +#, no-wrap +msgid "" +"kern.filedelay=5\n" +"kern.dirdelay=4\n" +"kern.metadelay=3\n" +msgstr "" +"kern.filedelay=5\n" +"kern.dirdelay=4\n" +"kern.metadelay=3\n" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:143 +msgid "The numbers represent seconds." +msgstr "Значения этих переменных - секунды." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:151 +msgid "" +"For debugging kernel panics, kernel core dumps are required. Since a kernel " +"panic might make filesystems unusable, this crash dump is first written to a " +"raw partition. Usually, this is the swap partition. This partition must be " +"at least as large as the physical RAM in the machine. On the next boot, the " +"dump is copied to a regular file. This happens after filesystems are " +"checked and mounted, and before swap is enabled. This is controlled with " +"two [.filename]#/etc/rc.conf# variables:" +msgstr "" +"Для отладки паник ядра необходимы дампы памяти. Так как паника ядра может " +"\"сломать\" файловую систему, дамп сначала сохраняется в \"сырой\" раздел. " +"Обычно, это своп-раздел. Поэтому, размер своп-раздела должен быть не меньше " +"размера ОЗУ компьютера. При последующей загрузке дамп копируется в обычный " +"файл. Это происходит сразу-же после проверки и монтирования файловых систем, " +"но перед активированием раздела свопа. Такое поведение контролируется " +"следующими переменными [.filename]#/etc/rc.conf#:" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:156 +#, no-wrap +msgid "" +"dumpdev=\"/dev/ad0s4b\"\n" +"dumpdir=\"/usr/core\n" +msgstr "" +"dumpdev=\"/dev/ad0s4b\"\n" +"dumpdir=\"/usr/core\n" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:159 +msgid "" +"The `dumpdev` variable specifies the swap partition and `dumpdir` tells the " +"system where in the filesystem to relocate the core dump on reboot." +msgstr "" +"Переменная `dumpdev` указывает на раздел подкачки, а `dumpdir` сообщает " +"системе куда перемещать дамп ядра при следующей загрузке." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:162 +msgid "" +"Writing kernel core dumps is slow and takes a long time so if you have lots " +"of memory (>256M) and lots of panics it could be frustrating to sit and wait " +"while it is done (twice - first to write it to swap, then to relocate it to " +"filesystem). It is convenient then to limit the amount of RAM the system " +"will use via a [.filename]#/boot/loader.conf# tunable:" +msgstr "" +"Сохранение дампа ядра - процесс медленный, и, если у вашего компьютера много " +"оперативной памяти (>256M) и если паники случаются часто, то ожидание " +"сохранения дампов может начать раздражать (вспомним, что над дампом " +"происходит две операции: сохранение в своп-файл и перемещение на файловую " +"систему). В таком случае может оказаться удобным ограничивание объема " +"используемой системой памяти путем установки переменной в [.filename]#/boot/" +"loader.conf#:" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:166 +#, no-wrap +msgid " hw.physmem=\"256M\"\n" +msgstr " hw.physmem=\"256M\"\n" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:169 +msgid "" +"If the panics are frequent and filesystems large (or you simply do not trust " +"softupdates+background fsck) it is advisable to turn background fsck off via " +"[.filename]#/etc/rc.conf# variable:" +msgstr "" +"Если паники случаются часто и размер файловых систем большой (или же вы " +"просто не доверяете softupdates и фоновой проверке файловых систем), " +"рекомендуется отключить фоновую проверку файловых систем посредством " +"установки переменной в [.filename]#/etc/rc.conf#:" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:173 +#, no-wrap +msgid " background_fsck=\"NO\"\n" +msgstr " background_fsck=\"NO\"\n" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:178 +msgid "" +"This way, the filesystems will always get checked when needed. Note that " +"with background fsck, a new panic could happen while it is checking the " +"disks. Again, the safest way is not to have many local filesystems by using " +"another computer as an NFS server." +msgstr "" +"В этом случае файловые системы будут проверяться только при необходимости. " +"Также заметьте, что в случае использования фоновой проверки, новая паника " +"может случиться в то время, когда проверяются диски. Другими словами, " +"наиболее безопасный способ - не иметь много локальных файловых систем, а " +"использовать второй компьютер в качестве NFS-сервера." + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:180 +#, no-wrap +msgid "Starting the Project" +msgstr "Начало проекта" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:184 +msgid "" +"For the purpose of creating a new GEOM class, an empty subdirectory has to " +"be created under an arbitrary user-accessible directory. You do not have to " +"create the module directory under [.filename]#/usr/src#." +msgstr "" +"Для написания нового класса GEOM необходимо создать поддиректорию в любой " +"доступной пользователю директории. Совсем не обязательно, чтоб ваш модуль " +"изначально размещался в [.filename]#/usr/src#." + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:186 +#, no-wrap +msgid "The Makefile" +msgstr "Makefile" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:189 +msgid "" +"It is good practice to create [.filename]#Makefiles# for every nontrivial " +"coding project, which of course includes kernel modules." +msgstr "" +"Правилом хорошего тона является создание [.filename]#Makefile#-ов для " +"каждого нетривиального проекта, примером которого конечно-же является " +"создание модулей ядра." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:192 +msgid "" +"Creating the [.filename]#Makefile# is simple thanks to an extensive set of " +"helper routines provided by the system. In short, here is how a minimal " +"[.filename]#Makefile# looks for a kernel module:" +msgstr "" +"Создание [.filename]#Makefile# - дело не сложное благодаря исчерпывающему " +"набору вспомогательных средств, предоставляемых системой. В вкратце, вот как " +"должен выглядеть [.filename]#Makefile# для модуля ядра:" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:197 +#, no-wrap +msgid "" +"SRCS=g_journal.c\n" +"KMOD=geom_journal\n" +msgstr "" +"SRCS=g_journal.c\n" +"KMOD=geom_journal\n" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:199 +#, no-wrap +msgid ".include <bsd.kmod.mk>\n" +msgstr ".include <bsd.kmod.mk>\n" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:203 +msgid "" +"This [.filename]#Makefile# (with changed filenames) will do for any kernel " +"module, and a GEOM class can reside in just one kernel module. If more than " +"one file is required, list it in the `SRCS` variable, separated with " +"whitespace from other filenames." +msgstr "" +"Этот [.filename]#Makefile# (с измененными именами файлов) подойдет к любому " +"модулю ядра. Класс GEOM может размещаться в одном единственном модуле ядра. " +"Если для сборки вашего модуля требуется больше, чем один файл, то " +"перечислите их имена, разделенные пробельными символами, в переменной `SRCS`." + +#. type: Title == +#: documentation/content/en/articles/geom-class/_index.adoc:205 +#, no-wrap +msgid "On FreeBSD Kernel Programming" +msgstr "Программирование в ядре FreeBSD" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:208 +#, no-wrap +msgid "Memory Allocation" +msgstr "Выделение памяти" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:213 +msgid "" +"See man:malloc[9]. Basic memory allocation is only slightly different than " +"its userland equivalent. Most notably, `malloc`() and `free`() accept " +"additional parameters as is described in the man page." +msgstr "" +"Прочитайте man:malloc[9] - выделение памяти лишь немного отличается от " +"своего эквивалента, используемого в пространстве пользовательских процессов " +"(userland). Наиболее приметно то, что `malloc`() и `free`() принимают " +"дополнительные параметры, которые описаны в странице справочника." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:215 +msgid "" +"A \"malloc type\" must be declared in the declaration section of a source " +"file, like this:" +msgstr "" +"Тип \"malloc_type\" необходимо объявить в секции деклараций файла с исходным " +"кодом, например:" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:219 +#, no-wrap +msgid " static MALLOC_DEFINE(M_GJOURNAL, \"gjournal data\", \"GEOM_JOURNAL Data\");\n" +msgstr " static MALLOC_DEFINE(M_GJOURNAL, \"gjournal data\", \"GEOM_JOURNAL Data\");\n" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:222 +msgid "" +"To use this macro, [.filename]#sys/param.h#, [.filename]#sys/kernel.h# and " +"[.filename]#sys/malloc.h# headers must be included." +msgstr "" +"Для того, чтобы можно было использовать этот макрос, необходимо включить " +"следующие заголовочные файлы: [.filename]#sys/param.h#, [.filename]#sys/" +"kernel.h# и [.filename]#sys/malloc.h#." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:225 +msgid "" +"There is another mechanism for allocating memory, the UMA (Universal Memory " +"Allocator). See man:uma[9] for details, but it is a special type of " +"allocator mainly used for speedy allocation of lists comprised of same-sized " +"items (for example, dynamic arrays of structs)." +msgstr "" +"Существует еще один механизм выделения памяти - UMA (Universal Memory " +"Allocator), описанный в man:uma[9]. Это специфический метод, преимущественно " +"предназначенный для быстрого выделения памяти под списки, состоящие из " +"элементов одинакового размера (например, динамические массивы структур)." + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:227 +#, no-wrap +msgid "Lists and Queues" +msgstr "Очереди и списки" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:234 +msgid "" +"See man:queue[3]. There are a LOT of cases when a list of things needs to " +"be maintained. Fortunately, this data structure is implemented (in several " +"ways) by C macros included in the system. The most used list type is TAILQ " +"because it is the most flexible. It is also the one with largest memory " +"requirements (its elements are doubly-linked) and also the slowest (although " +"the speed variation is on the order of several CPU instructions more, so it " +"should not be taken seriously)." +msgstr "" +"Ознакомьтесь с man:queue[3] Во множестве случаев вам необходимо будет " +"организовывать и управлять такой структурой данных, как списки. К счастью, " +"эта структура данных реализована несколькими способами в виде макросов на " +"Си, а также включена в систему. Наиболее гибкий и часто употребляемый тип " +"списка - TAILQ. Этот тип списка также один из наиболее требовательных к " +"памяти (его элементы - с двойными связями), а также - наиболее медленный " +"(однако счет идет на несколько инструкций ЦПУ, поэтому последнее утверждение " +"не следует воспринимать в всерьез)." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:236 +msgid "" +"If data retrieval speed is very important, see man:tree[3] and " +"man:hashinit[9]." +msgstr "" +"Если важна скорость получения данных, то возьмите на вооружение man:tree[3] " +"и man:hashinit[9]." + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:238 +#, no-wrap +msgid "BIOs" +msgstr "BIOs" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:242 +msgid "" +"Structure `bio` is used for any and all Input/Output operations concerning " +"GEOM. It basically contains information about what device ('provider') " +"should satisfy the request, request type, offset, length, pointer to a " +"buffer, and a bunch of \"user-specific\" flags and fields that can help " +"implement various hacks." +msgstr "" +"Структура `bio` используется для всех операций ввода/вывода, касающихся " +"GEOM. Она содержит информацию о том, какое устройство ('поставщик geom') " +"должно ответить на запрос, тип запроса, смещение, длину и указатель на " +"буфер, а также набор \"определенных пользователем\" флагов и полей ." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:246 +msgid "" +"The important thing here is that ``bio``s are handled asynchronously. That " +"means that, in most parts of the code, there is no analogue to userland's " +"man:read[2] and man:write[2] calls that do not return until a request is " +"done. Rather, a developer-supplied function is called as a notification " +"when the request gets completed (or results in error)." +msgstr "" +"Важным моментом является то, что `bio` обрабатываются асинхронно. Это " +"значит, что во многих частях кода нет аналога к man:read[2] и man:write[2] " +"функциям из пространства пользовательских процессов, которые не возвращают " +"управление пока не выполнится системный вызов. Скорее, по завершении " +"обработки запроса (или в случае ошибки при обработке) как извещение " +"вызывается определенная пользователем функция." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:250 +msgid "" +"The asynchronous programming model (also called \"event-driven\") is " +"somewhat harder than the much more used imperative one used in userland (at " +"least it takes a while to get used to it). In some cases the helper " +"routines `g_write_data`() and `g_read_data`() can be used, but __not " +"always__. In particular, they cannot be used when a mutex is held; for " +"example, the GEOM topology mutex or the internal mutex held during the " +"`.start`() and `.stop`() functions." +msgstr "" +"Асинхронная модель программирования в чем-то сложней, нежели чаще " +"используемая императивная модель, используемая в пространстве " +"пользовательских процессов; в любом случае, привыкание займет некоторое " +"время. В некоторых случаях могут быть использованы вспомогательные функции " +"`g_write_data`() и `g_read_data`(), но __далеко не всегда__. В частности, " +"эти функции не могут использоваться когда захвачен мьютекс; например, " +"мьютекс GEOM-топологии или внутренний мьютекс, удерживаемый в ходе " +"выполнения `.start`() или `.stop`()." + +#. type: Title == +#: documentation/content/en/articles/geom-class/_index.adoc:252 +#, no-wrap +msgid "On GEOM Programming" +msgstr "Программирование в системе GEOM" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:255 +#, no-wrap +msgid "Ggate" +msgstr "Ggate" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:259 +msgid "" +"If maximum performance is not needed, a much simpler way of making a data " +"transformation is to implement it in userland via the ggate (GEOM gate) " +"facility. Unfortunately, there is no easy way to convert between, or even " +"share code between the two approaches." +msgstr "" +"Если максимальная производительность не требуется, то более простой способ " +"совершать преобразования данных - это выполнять их в пространстве " +"пользовательских процессов посредством ggate (GEOM gate). К недостаткам " +"следует отнести невозможность простого переноса кода в ядро." + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:261 +#, no-wrap +msgid "GEOM Class" +msgstr "Класс GEOM" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:266 +msgid "" +"GEOM classes are transformations on the data. These transformations can be " +"combined in a tree-like fashion. Instances of GEOM classes are called " +"__geoms__." +msgstr "" +"Класс GEOM выполняет преобразования данных. Эти преобразования могут быть " +"скомпонованы друг с другом в виде дерева. Экземпляр класса GEOM называют " +"__geom__." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:268 +msgid "" +"Each GEOM class has several \"class methods\" that get called when there is " +"no geom instance available (or they are simply not bound to a single " +"instance):" +msgstr "" +"В каждом классе GEOM есть несколько \"методов класса\", которые вызываются " +"когда экземпляра класса нет в наличии (или же они не привязаны к конкретному " +"экземпляру класса):" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:270 +msgid "" +"`.init` is called when GEOM becomes aware of a GEOM class (when the kernel " +"module gets loaded.)" +msgstr "" +"`.init` вызывается тогда, когда системе GEOM становится известно о классе " +"GEOM (например, когда загружается модуль ядра)." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:271 +msgid "" +"`.fini` gets called when GEOM abandons the class (when the module gets " +"unloaded)" +msgstr "" +"`.fini` будет вызван в случае отказа GEOM системы от класса (например, при " +"выгрузке модуля)" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:272 +msgid "" +"`.taste` is called next, once for each provider the system has available. If " +"applicable, this function will usually create and start a geom instance." +msgstr "" +"`.taste` вызывается, когда в системе появляется новый класс или поставщик " +"geom (\"provider\"). Если соответствие найдено, то эта функция обычно " +"создает и запускает экземпляр geom." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:273 +msgid "`.destroy_geom` is called when the geom should be disbanded" +msgstr "`.destroy_geom` вызывается при необходимости разрушить экземпляр geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:274 +msgid "" +"`.ctlconf` is called when user requests reconfiguration of existing geom" +msgstr "" +"`.ctlconf` будет вызван, когда пользователь запросит изменение конфигурации " +"существующего экземпляра geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:276 +msgid "" +"Also defined are the GEOM event functions, which will get copied to the geom " +"instance." +msgstr "" +"Также определены функции событий GEOM, которые копируются в экземпляр geom." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:278 +msgid "" +"Field `.geom` in the `g_class` structure is a LIST of geoms instantiated " +"from the class." +msgstr "" +"Поле `.geom` в структуре `g_class` - это список (LIST) экземпляров geom, " +"реализованных из класса." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:280 +msgid "These functions are called from the g_event kernel thread." +msgstr "Эти функции вызываются из g_event потока ядра." + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:282 +#, no-wrap +msgid "Softc" +msgstr "Softc" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:288 +msgid "" +"The name \"softc\" is a legacy term for \"driver private data\". The name " +"most probably comes from the archaic term \"software control block\". In " +"GEOM, it is a structure (more precise: pointer to a structure) that can be " +"attached to a geom instance to hold whatever data is private to the geom " +"instance. Most GEOM classes have the following members:" +msgstr "" +"\"softc\" - это устаревший термин для \"приватных данных драйвера\" " +"(\"driver private data\"). Название вероятней всего происходит от " +"устаревшего термина \"software control block\". В системе GEOM softc это " +"структура (точнее: указатель на структуру) которая может быть присоединена к " +"экземпляру geom и может содержать приватные данные экземпляра. У большинства " +"классов GEOM есть следующие члены:" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:290 +msgid "`struct g_provider *provider` : The \"provider\" this geom instantiates" +msgstr "" +"`struct g_provider *provider` : \"поставщик geom\" предоставляемый данным " +"экземпляром geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:291 +msgid "`uint16_t n_disks` : Number of consumer this geom consumes" +msgstr "" +"`uint16_t n_disks` : Количество потребителей geom (\"consumer\"), " +"обслуживаемых данным экземпляром geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:292 +msgid "" +"`struct g_consumer \\**disks` : Array of `struct g_consumer*`. (It is not " +"possible to use just single indirection because struct g_consumer* are " +"created on our behalf by GEOM)." +msgstr "" +"`struct g_consumer \\**disks` : Массив `struct g_consumer*`. (Невозможно " +"обойтись одинарным указателем, потому что система GEOM создает для нас " +"структуры struct g_consumer)." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:295 +msgid "" +"The `softc` structure contains all the state of geom instance. Every geom " +"instance has its own softc." +msgstr "" +"Структура `softc` содержит состояние экземпляра geom. У каждого экземпляра " +"есть свой softc." + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:297 +#, no-wrap +msgid "Metadata" +msgstr "Метаданные" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:300 +msgid "" +"Format of metadata is more-or-less class-dependent, but MUST start with:" +msgstr "" +"Формат метаданных в той или иной мере зависит от конкретного класса, но " +"_обязан_ начинаться с:" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:302 +msgid "16 byte buffer for null-terminated signature (usually the class name)" +msgstr "" +"16-байтного буфера для подписи - строки с завершающим нулем (обычно это имя " +"класса)" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:303 +msgid "uint32 version ID" +msgstr "uint32 идентификатора версии" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:305 +msgid "" +"It is assumed that geom classes know how to handle metadata with version " +"ID's lower than theirs." +msgstr "" +"Подразумевается, что классы geom знают как обращаться с метаданными с " +"идентификаторами версий ниже, чем их собственные." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:307 +msgid "" +"Metadata is located in the last sector of the provider (and thus must fit in " +"it)." +msgstr "" +"Метаданные размещаются в последнем секторе поставщика geom (поэтому обязаны " +"целиком умещаться в нем)." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:309 +msgid "" +"(All this is implementation-dependent but all existing code works like that, " +"and it is supported by libraries.)" +msgstr "" +"(Все это зависит от реализации, но весь существующий код работает подобно " +"описанному и поддерживается библиотеками.)" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:311 +#, no-wrap +msgid "Labeling/creating a GEOM" +msgstr "Маркирование/создание экземпляра geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:314 +msgid "The sequence of events is:" +msgstr "Последовательность событий следующая:" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:316 +msgid "user calls man:geom[8] utility (or one of its hardlinked friends)" +msgstr "пользователь запускает служебную программу man:geom[8]" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:317 +msgid "" +"the utility figures out which geom class it is supposed to handle and " +"searches for [.filename]#geom_CLASSNAME.so# library (usually in [.filename]#/" +"lib/geom#)." +msgstr "" +"программа решает каким классом geom ей придется управлять и ищет библиотеку " +"[.filename]#geom_CLASSNAME.so# (которая обычно находится в [.filename]#/lib/" +"geom#)." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:318 +msgid "" +"it man:dlopen[3]-s the library, extracts the definitions of command-line " +"parameters and helper functions." +msgstr "" +"она открывает библиотеку при помощи man:dlopen[3], извлекает вспомогательные " +"функции и определения параметров командной строки." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:320 +msgid "In the case of creating/labeling a new geom, this is what happens:" +msgstr "Вот так происходит создание/маркирование нового экземпляра geom:" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:322 +msgid "" +"man:geom[8] looks in the command-line argument for the command (usually " +"`label`), and calls a helper function." +msgstr "" +"man:geom[8] ищет команду в аргументах командной строки (обычно это `label`) " +"и вызывает вспомогательную функцию." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:323 +msgid "" +"The helper function checks parameters and gathers metadata, which it " +"proceeds to write to all concerned providers." +msgstr "" +"Вспомогательная функция проверяет параметры и собирает метаданные, которые " +"записываются во все вовлеченные поставщики geom." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:324 +msgid "" +"This \"spoils\" existing geoms (if any) and initializes a new round of " +"\"tasting\" of the providers. The intended geom class recognizes the " +"metadata and brings the geom up." +msgstr "" +"Это \"повреждает (spoil)\" существующие экземпляры geom (если они были) и " +"порождает новый виток \"тестирования\" поставщиков geom. Целевой класс geom " +"опознает метаданные и активирует экземпляр geom." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:326 +msgid "" +"(The above sequence of events is implementation-dependent but all existing " +"code works like that, and it is supported by libraries.)" +msgstr "" +"(Приведенная выше последовательность событий зависит от конкретной " +"реализации, но весь существующий код работает подобно описанному и " +"поддерживается библиотеками.)" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:328 +#, no-wrap +msgid "GEOM Command Structure" +msgstr "Структура команд geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:332 +msgid "" +"The helper [.filename]#geom_CLASSNAME.so# library exports `class_commands` " +"structure, which is an array of `struct g_command` elements. Commands are " +"of uniform format and look like:" +msgstr "" +"Вспомогательная библиотека [.filename]#geom_CLASSNAME.so# экспортирует " +"структуру `class_commands`, которая является массивом элементов `struct " +"g_command`. Эти команды одинакового формата и выглядят следующим образом:" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:336 +#, no-wrap +msgid " verb [-options] geomname [other]\n" +msgstr " verb [-options] geomname [other]\n" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:339 +msgid "Common verbs are:" +msgstr "Общими командами являются:" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:341 +msgid "" +"label - to write metadata to devices so they can be recognized at tasting " +"and brought up in geoms" +msgstr "" +"label - записать метаданные в устройства, чтобы они могли быть опознаны в " +"процессе тестирования и использованы в соответствующих экземплярах geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:342 +msgid "destroy - to destroy metadata, so the geoms get destroyed" +msgstr "" +"destroy - разрушить метаданные, за которым последует разрушение экземпляров " +"geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:344 +msgid "Common options are:" +msgstr "Общие опции:" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:346 +msgid "`-v` : be verbose" +msgstr "`-v` : детальный вывод" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:347 +msgid "`-f` : force" +msgstr "`-f` : принудить" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:351 +msgid "" +"Many actions, such as labeling and destroying metadata can be performed in " +"userland. For this, `struct g_command` provides field `gc_func` that can be " +"set to a function (in the same [.filename]#.so#) that will be called to " +"process a verb. If `gc_func` is NULL, the command will be passed to kernel " +"module, to `.ctlreq` function of the geom class." +msgstr "" +"Некоторые операции, к примеру маркирование метаданными и разрушение " +"метаданных могут быть выполнены из пространства пользовательских процессов. " +"Для этого, структура `g_command` содержит поле `gc_func`, которое может быть " +"установлено на функцию (в том-же [.filename]#.so#), которая будет вызвана " +"для обработки команды. В случае, когда `gc_func` равно NULL, команда будет " +"передана модулю ядра: функции `.ctlreq` класса GEOM." + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:353 +#, no-wrap +msgid "Geoms" +msgstr "Экземпляры geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:357 +msgid "" +"Geoms are instances of GEOM classes. They have internal data (a softc " +"structure) and some functions with which they respond to external events." +msgstr "" +"У экземпляров классов GEOM есть внутренние данные, которые хранятся в " +"структурах softc, а также есть некоторые функции, посредством которых они " +"реагируют на внешние события." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:359 +msgid "The event functions are:" +msgstr "Функции событий:" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:361 +msgid "`.access` : calculates permissions (read/write/exclusive)" +msgstr "" +"`.access` : просчитывает права доступа (чтение/запись/исключительный доступ)" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:362 +msgid "`.dumpconf` : returns XML-formatted information about the geom" +msgstr "`.dumpconf` : возвращает информацию о экземпляре geom; формат XML" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:363 +msgid "`.orphan` : called when some underlying provider gets disconnected" +msgstr "" +"`.orphan` : вызывается, когда отсоединяется любой из низлежащих поставщиков " +"geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:364 +msgid "`.spoiled` : called when some underlying provider gets written to" +msgstr "" +"`.spoiled` : вызывается, когда производится запись в низлежащий поставщик " +"geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:365 +msgid "`.start` : handles I/O" +msgstr "`.start` : обрабатывает ввод/вывод" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:367 +msgid "" +"These functions are called from the `g_down` kernel thread and there can be " +"no sleeping in this context, (see definition of sleeping elsewhere) which " +"limits what can be done quite a bit, but forces the handling to be fast." +msgstr "" +"Эти функции вызываются из ядерного потока `g_down` и в этом контексте не " +"может быть блокировок (поищите определение \"блокировка\" в других " +"источниках), что немного ограничивает свободу действий, но способствует " +"быстроте обработки." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:369 +msgid "" +"Of these, the most important function for doing actual useful work is the " +"`.start`() function, which is called when a BIO request arrives for a " +"provider managed by a instance of geom class." +msgstr "" +"Из вышеупомянутых, наиболее важной и выполняющей полезную работу функцией " +"является `.start`(), которая вызывается всякий раз, когда поставщику geom, " +"управляемому экземпляром класса, приходит запрос BIO." + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:371 +#, no-wrap +msgid "GEOM Threads" +msgstr "Потоки выполнения системы geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:374 +msgid "There are three kernel threads created and run by the GEOM framework:" +msgstr "" +"Системой GEOM в ядре ОС создаются и используются три потока выполнения " +"(kernel threads):" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:376 +msgid "" +"`g_down` : Handles requests coming from high-level entities (such as a " +"userland request) on the way to physical devices" +msgstr "" +"`g_down` : Обрабатывает запросы, приходящие от высокоуровневых сущностей " +"(таких, как запросы из пространства пользовательских процессов) на пути к " +"физическим устройствам" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:377 +msgid "" +"`g_up` : Handles responses from device drivers to requests made by higher-" +"level entities" +msgstr "" +"`g_up` : Обрабатывает ответы от драйверов устройств на запросы, выполненные " +"высокоуровневыми сущностями" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:378 +msgid "" +"`g_event` : Handles all other cases: creation of geom instances, access " +"counting, \"spoil\" events, etc." +msgstr "" +"`g_event` : Отрабатывает в остальных случаях, как-то создание экземпляра " +"geom, просчитывание прав доступа, события \"повреждения\" и т.п." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:380 +msgid "" +"When a user process issues \"read data X at offset Y of a file\" request, " +"this is what happens:" +msgstr "" +"Когда пользовательский процесс запрашивает \"прочитать данные X по смещению " +"Y файла\", происходит следующее:" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:382 +msgid "" +"The filesystem converts the request into a struct bio instance and passes it " +"to the GEOM subsystem. It knows what geom instance should handle it because " +"filesystems are hosted directly on a geom instance." +msgstr "" +"Файловая система преобразует запрос в экземпляр структуры bio и передает его " +"системе GEOM. Файловая система \"знает\", что экземпляр geom должен " +"обработать запрос, так как файловые системы размещаются непосредственно над " +"экземпляром geom." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:383 +msgid "" +"The request ends up as a call to the `.start`() function made on the g_down " +"thread and reaches the top-level geom instance." +msgstr "" +"Запрос завершается вызовом функции `.start`() в потоке g_down и достигает " +"верхнего экземпляра geom." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:384 +msgid "" +"This top-level geom instance (for example the partition slicer) determines " +"that the request should be routed to a lower-level instance (for example the " +"disk driver). It makes a copy of the bio request (bio requests _ALWAYS_ need " +"to be copied between instances, with `g_clone_bio`()!), modifies the data " +"offset and target provider fields and executes the copy with `g_io_request`()" +msgstr "" +"Верхний экземпляр geom (например, это секционировщик разделов (partition " +"slicer)) определяет, что запрос должен быть переадресован нижестоящему " +"экземпляру geom (к примеру, драйверу диска). Вышестоящий экземпляр geom " +"создает копию запроса bio (запросы bio _ВСЕГДА_ копируются при передаче " +"между экземплярами geom при помощи `g_clone_bio`()!), изменяет поля смещения " +"и целевого поставщика geom и запускает на обработку копию при помощи функции " +"`g_io_request`()" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:385 +msgid "" +"The disk driver gets the bio request also as a call to `.start`() on the " +"`g_down` thread. It talks to hardware, gets the data back, and calls " +"`g_io_deliver`() on the bio." +msgstr "" +"Драйвер диска также получает запрос bio, как вызов функции `.start`() в " +"потоке `g_down`. Драйвер обращается к контроллеру диска, получает блок " +"данных и вызывает функцию `g_io_deliver`() используя копию запроса bio." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:386 +msgid "" +"Now, the notification of bio completion \"bubbles up\" in the `g_up` thread. " +"First the partition slicer gets `.done`() called in the `g_up` thread, it " +"uses information stored in the bio to free the cloned `bio` structure (with " +"`g_destroy_bio`()) and calls `g_io_deliver`() on the original request." +msgstr "" +"Теперь, извещение о завершении bio \"всплывает\" в потоке `g_up`. Сначала в " +"потоке `g_up` вызывается функция `.done`() секционировщика разделов, " +"последний использует полученную информацию, разрушает клонированный " +"экземпляр структуры bio посредством `g_destroy_bio`() и вызывает " +"`g_io_deliver`() используя первоначальный запрос." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:387 +msgid "The filesystem gets the data and transfers it to userland." +msgstr "" +"Файловая система получает данные и передает их пользовательскому процессу." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:389 +msgid "" +"See man:g_bio[9] man page for information how the data is passed back and " +"forth in the `bio` structure (note in particular the `bio_parent` and " +"`bio_children` fields and how they are handled)." +msgstr "" +"За информацией о том, как данные передаются в структуре `bio` между " +"экземплярами geom, смотрите man:g_bio[9] (обратите внимание на использование " +"полей `bio_parent` и `bio_children`)." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:392 +msgid "" +"One important feature is: __THERE CAN BE NO SLEEPING IN G_UP AND G_DOWN " +"THREADS__. This means that none of the following things can be done in " +"those threads (the list is of course not complete, but only informative):" +msgstr "" +"Важный момент в том, что __НЕЛЬЗЯ ДОПУСКАТЬ БЛОКИРОВОК В ПОТОКАХ G_UP И " +"G_DOWN__. Вот неполный перечень того, что нельзя делать в этих потоках:" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:394 +msgid "Calls to `msleep`() and `tsleep`(), obviously." +msgstr "Вызывать функции `msleep`() или `tsleep`()." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:395 +msgid "" +"Calls to `g_write_data`() and `g_read_data`(), because these sleep between " +"passing the data to consumers and returning." +msgstr "" +"Использовать функции `g_write_data`() и `g_read_data`(), так как они " +"блокируются в момент обмена данными с потребителями geom." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:396 +msgid "Waiting for I/O." +msgstr "Ожидать ввод/вывод." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:397 +msgid "Calls to man:malloc[9] and `uma_zalloc`() with `M_WAITOK` flag set" +msgstr "" +"Вызывать man:malloc[9] и `uma_zalloc`() с установленным флагом `M_WAITOK`" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:398 +msgid "sx and other sleepable locks" +msgstr "Использовать man:sx[9]" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:402 +msgid "" +"This restriction is here to stop GEOM code clogging the I/O request path, " +"since sleeping is usually not time-bound and there can be no guarantees on " +"how long will it take (there are some other, more technical reasons also). " +"It also means that there is not much that can be done in those threads; for " +"example, almost any complex thing requires memory allocation. Fortunately, " +"there is a way out: creating additional kernel threads." +msgstr "" +"Это ограничение на код GEOM призвано избежать от \"засорения\" пути запроса " +"ввода/вывода, так как блокировки обычно не имеют четких временных границ, и " +"нет гарантий на занимаемое время (также на то есть и другие технические " +"причины). Это также значит, что в вышеупомянутых потоках сколь-нибудь " +"сложные операции выполнить нельзя, например: любое сложное преобразование " +"требует выделения памяти. К счастью решение есть: создание дополнительных " +"ядерных потоков." + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:404 +#, no-wrap +msgid "Kernel Threads for Use in GEOM Code" +msgstr "Ядерные потоки выполнения, предназначенные для использования в коде geom" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:407 +msgid "" +"Kernel threads are created with man:kthread_create[9] function, and they are " +"sort of similar to userland threads in behavior, only they cannot return to " +"caller to signify termination, but must call man:kthread_exit[9]." +msgstr "" +"Ядерные потоки выполнения создаются функцией man:kthread_create[9], в своем " +"поведении они схожи с потоками, созданными в пространстве пользовательских " +"процессов, но есть одно отличие: они не могут известить вызвавший их поток о " +"своем завершении; по завершению - необходимо вызывать man:kthread_exit[9]." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:410 +msgid "" +"In GEOM code, the usual use of threads is to offload processing of requests " +"from `g_down` thread (the `.start`() function). These threads look like " +"\"event handlers\": they have a linked list of event associated with them " +"(on which events can be posted by various functions in various threads so it " +"must be protected by a mutex), take the events from the list one by one and " +"process them in a big `switch`() statement." +msgstr "" +"В коде GEOM обычное назначение этих потоков - разгрузить поток `g_down` " +"(функцию `.start`() ) от обработки запросов. Эти потоки подобны " +"\"обработчикам событий\" (\"event handlers\"): у них есть очередь событий " +"(которая наполняется событиями от разных функций из разных потоков; очередь " +"необходимо защищать мьютексом), события из очереди выбираются одно за другим " +"и обрабатываются в большом блоке `switch`()." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:415 +msgid "" +"The main benefit of using a thread to handle I/O requests is that it can " +"sleep when needed. Now, this sounds good, but should be carefully thought " +"out. Sleeping is well and very convenient but can very effectively destroy " +"performance of the geom transformation. Extremely performance-sensitive " +"classes probably should do all the work in `.start`() function call, taking " +"great care to handle out-of-memory and similar errors." +msgstr "" +"Основное преимущество использования отдельного потока, который обрабатывает " +"запросы ввода/вывода, то, что он может блокироваться по мере необходимости. " +"Это, несомненно, привлекательно, но должно быть хорошо обдумано. " +"Блокирование - хорошо и удобно, но может существенно снизить " +"производительность преобразований данных в системе GEOM. Особо " +"требовательные к производительности классы могут делать всю работу в функции " +"`.start`(), уделяя особое внимание ошибкам при работе с памятью." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:419 +msgid "" +"The other benefit of having a event-handler thread like that is to serialize " +"all the requests and responses coming from different geom threads into one " +"thread. This is also very convenient but can be slow. In most cases, " +"handling of `.done`() requests can be left to the `g_up` thread." +msgstr "" +"Еще одно преимущество потока \"обработчика событий\" это сериализация всех " +"запросов и ответов, приходящих с разных потоков geom в один поток. Это также " +"удобно, но может быть медленным. В большинстве случаев, обработка запросов " +"функцией `.done`() может быть оставлена потоку `g_up`." + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:422 +msgid "" +"Mutexes in FreeBSD kernel (see man:mutex[9]) have one distinction from their " +"more common userland cousins - the code cannot sleep while holding a " +"mutex). If the code needs to sleep a lot, man:sx[9] locks may be more " +"appropriate. On the other hand, if you do almost everything in a single " +"thread, you may get away with no mutexes at all." +msgstr "" +"У мьютексов в ядре FreeBSD (man:mutex[9]) есть одно различие с их аналогами " +"из пространства пользовательских процессов - во время удержания мьютекса в " +"коде не должно быть блокировки. Если в коде необходимо блокирование, то " +"лучше использовать man:sx[9]. С другой стороны, если вся ваша работа " +"выполняется в одном потоке, вы можете обойтись вообще без мьютексов." |