Date: Wed, 29 Oct 2025 16:24:39 GMT From: Vladlen Popolitov <vladlen@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: 64e4abb4e0 - main - Remove obsolete Russian documentation files Message-ID: <202510291624.59TGOdgX025765@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by vladlen: URL: https://cgit.FreeBSD.org/doc/commit/?id=64e4abb4e0dba3613d9bb9da7810bccc785b438f commit 64e4abb4e0dba3613d9bb9da7810bccc785b438f Author: Vladlen Popolitov <vladlen@FreeBSD.org> AuthorDate: 2025-10-29 16:24:22 +0000 Commit: Vladlen Popolitov <vladlen@FreeBSD.org> CommitDate: 2025-10-29 16:24:22 +0000 Remove obsolete Russian documentation files Delete ru/book/*/chapter.adoc files that are no longer required. Reviewed by: carlavilla Differential Revision: https://reviews.freebsd.org/D53435 --- .../books/arch-handbook/driverbasics/chapter.adoc | 512 ---------------- .../ru/books/arch-handbook/locking/chapter.adoc | 137 ----- .../ru/books/arch-handbook/sound/chapter.adoc | 432 ------------- .../developers-handbook/introduction/chapter.adoc | 140 ----- .../developers-handbook/kerneldebug/chapter.adoc | 678 --------------------- .../developers-handbook/policies/chapter.adoc | 196 ------ .../books/developers-handbook/secure/chapter.adoc | 190 ------ 7 files changed, 2285 deletions(-) diff --git a/documentation/content/ru/books/arch-handbook/driverbasics/chapter.adoc b/documentation/content/ru/books/arch-handbook/driverbasics/chapter.adoc deleted file mode 100644 index d845e849be..0000000000 --- a/documentation/content/ru/books/arch-handbook/driverbasics/chapter.adoc +++ /dev/null @@ -1,512 +0,0 @@ ---- -title: Глава 9. Написание драйверов устройств для FreeBSD -authors: ---- - -[[driverbasics]] -= Написание драйверов устройств для FreeBSD -:doctype: book -:toc: macro -:toclevels: 1 -:icons: font -:sectnums: -:sectnumlevels: 6 -:sectnumoffset: 9 -:partnums: -:source-highlighter: rouge -:experimental: - -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::[] - -Эту главу написал {murray} на основе множества источников, включая справочную страницу intro(4), которую создал {joerg}. - -[[driverbasics-intro]] -== Введение - -Эта глава является кратким введением в процесс написания драйверов устройств для FreeBSD. В этом контексте термин устройство используется в основном для вещей, связанных с оборудованием, относящимся к системе, таких, как диски, печатающие устройства или графические дисплеи с клавиатурами. Драйвер устройства является программной компонентой операционной системы, управляющей некоторым устройством. Имеются также так называемые псевдо-устройства, в случае которых драйвер устройства эмулирует поведение устройства программно, без наличия ка кой-либо соответствующей аппаратуры. Драйверы устройств могут быть вкомпилированы в систему статически или могут загружаться по требованию при помощи механизма динамического компоновщика ядра `kld`. - -Большинство устройств в Unix-подобной операционной системе доступны через файлы устройств (device-nodes), иногда также называемые специальными файлами. В иерархии файловой системы эти файлы обычно находятся в каталоге [.filename]#/dev#. В версиях FreeBSD, более старых, чем 5.0-RELEASE, в которых поддержка man:devfs[5] не интегрирована в систему, каждый файл устройства должен создаваться статически и вне зависимости от наличия соответствующего драйвера устройства. Большинство файлов устройств в системе создаются при помощи команды `MAKEDEV`. - -Драйверы устройств могут быть условно разделены на две категории; драйверы символьных и сетевых устройств. - -[[driverbasics-kld]] -== Механизм динамического компоновщика ядра - KLD - -Интерфейс kld позволяет системным администраторам динамически добавлять и убирать функциональность из работающей системы. Это позволяет разработчикам драйверов устройств загружать собственные изменения в работающее ядро без постоянных перезагрузок для тестирования изменений. - -Для работы с интерфейсом kld используются следующие команды привилегированного режима: - -* `kldload` - загружает новый модуль ядра -* `kldunload` - выгружает модуль ядра -* `kldstat` - выводит список загруженных в данный момент модулей - -Скелет модуля ядра - -[.programlisting] -.... -/* - * KLD Skeleton - * Inspired by Andrew Reiter's Daemonnews article - */ - -#include <sys/types.h> -#include <sys/module.h> -#include <sys/systm.h> /* uprintf */ -#include <sys/errno.h> -#include <sys/param.h> /* defines used in kernel.h */ -#include <sys/kernel.h> /* 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 = EINVAL; - 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 имеются заготовки для включения в make-файлы, которые вы можете использовать для быстрой компиляции собственных дополнений к ядру. - -[.programlisting] -.... -SRCS=skeleton.c -KMOD=skeleton - -.include <bsd.kmod.mk> -.... - -Простой запуск команды `make` с этим make-файлом приведет к созданию файла [.filename]#skeleton.ko#, который можно загрузить в вашу систему, набрав: - -[source,shell] -.... -# kldload -v ./skeleton.ko -.... - -[[driverbasics-access]] -== Обращение к драйверу устройства - -Unix дает некоторый общий набор системных вызовов для использования в пользовательских приложениях. Когда пользователь обращается к файлу устройства, высокие уровни ядра перенаправляют эти обращения к соответствующему драйверу устройства. Скрипт `/dev/MAKEDEV` создает большинство файлов устройств в вашей системе, однако если вы ведете разработку своего собственного драйвера, то может появиться необходимость в создании собственных файлов устройств при помощи команды `mknod`. - -=== Создание статических файлов устройств - -Для создания файла устройства команде `mknod` требуется указать четыре аргумента. Вы должны указать имя файла устройства, тип устройства, старшее число устройства и младшее число устройства. - -=== Динамические файлы устройств - -Файловая система устройств, devfs, предоставляет доступ к пространству имен устройств ядра из глобального пространства имен файловой системы. Это устраняет потенциальную проблемы наличия драйвера без статического файла устройства или файла устройства без установленного драйвера устройства. Devfs все еще находится в разработке, однако она уже достаточно хорошо работает. - -[[driverbasics-char]] -== Символьные устройства - -Драйвер символьного устройства передает данные непосредственно в или из процесса пользователя. Это самый распространенный тип драйвера устройства и в дереве исходных текстов имеется достаточно простых примеров таких драйверов. - -В этом простом примере псевдо-устройство запоминает какие угодно значения, которые вы в него записываете, и затем может выдавать их назад при чтении из этого устройства. Приведены две версии, одна для FreeBSD 4.X, а другая для FreeBSD 5.X. - -.Пример драйвера псевдо-устройства Echo для FreeBSD 4.X -[example] -==== -[.programlisting] -.... -/* - * Simple `echo' pseudo-device KLD - * - * Murray Stokely - */ - -#define MIN(a,b) (((a) (b)) ? (a) : (b)) - -#include sys/types.h -#include sys/module.h -#include sys/systm.h /* uprintf */ -#include sys/errno.h -#include sys/param.h /* defines used in kernel.h */ -#include sys/kernel.h /* types used in module initialization */ -#include sys/conf.h /* cdevsw struct */ -#include sys/uio.h /* uio struct */ -#include sys/malloc.h - -#define BUFFERSIZE 256 - -/* Function prototypes */ -d_open_t echo_open; -d_close_t echo_close; -d_read_t echo_read; -d_write_t echo_write; - -/* Character device entry points */ -static struct cdevsw echo_cdevsw = { - echo_open, - echo_close, - echo_read, - echo_write, - noioctl, - nopoll, - nommap, - nostrategy, - "echo", - 33, /* reserved for lkms - /usr/src/sys/conf/majors */ - nodump, - nopsize, - D_TTY, - -1 -}; - -struct s_echo { - char msg[BUFFERSIZE]; - int len; -} t_echo; - -/* vars */ -static dev_t sdev; -static int len; -static int count; -static t_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, int what, void *arg) -{ - int err = 0; - - switch (what) { - case MOD_LOAD: /* kldload */ - sdev = make_dev(echo_cdevsw, - 0, - UID_ROOT, - GID_WHEEL, - 0600, - "echo"); - /* kmalloc memory for use by this driver */ - MALLOC(echomsg, t_echo *, sizeof(t_echo), M_ECHOBUF, M_WAITOK); - printf("Echo device loaded.\n"); - break; - case MOD_UNLOAD: - destroy_dev(sdev); - FREE(echomsg,M_ECHOBUF); - printf("Echo device unloaded.\n"); - break; - default: - err = EINVAL; - break; - } - return(err); -} - -int -echo_open(dev_t dev, int oflags, int devtype, struct proc *p) -{ - int err = 0; - - uprintf("Opened device \"echo\" successfully.\n"); - return(err); -} - -int -echo_close(dev_t dev, int fflag, int devtype, struct proc *p) -{ - 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) - */ - -int -echo_read(dev_t dev, struct uio *uio, int ioflag) -{ - int err = 0; - int amt; - - /* How big is this read operation? Either as big as the user wants, - or as big as the remaining data */ - amt = MIN(uio->uio_resid, (echomsg->len - uio->uio_offset > 0) ? echomsg->len - uio->uio_offset : 0); - if ((err = uiomove(echomsg->msg + uio->uio_offset,amt,uio)) != 0) { - uprintf("uiomove failed!\n"); - } - - return err; -} - -/* - * echo_write takes in a character string and saves it - * to buf for later accessing. - */ - -int -echo_write(dev_t dev, struct uio *uio, int ioflag) -{ - int err = 0; - - /* Copy the string in from user memory to kernel memory */ - err = copyin(uio->uio_iov->iov_base, echomsg->msg, MIN(uio->uio_iov->iov_len,BUFFERSIZE)); - - /* Now we need to null terminate */ - *(echomsg->msg + MIN(uio->uio_iov->iov_len,BUFFERSIZE)) = 0; - /* Record the length */ - echomsg->len = MIN(uio->uio_iov->iov_len,BUFFERSIZE); - - if (err != 0) { - uprintf("Write failed: bad address!\n"); - } - - count++; - return(err); -} - -DEV_MODULE(echo,echo_loader,NULL); -.... - -==== - -.Пример драйвера псевдо-устройства Echo для FreeBSD 5.X -[example] -==== -[.programlisting] -.... -/* - * Simple `echo' pseudo-device KLD - * - * Murray Stokely - * - * Converted to 5.X by Sren (Xride) Straarup - */ - -#include sys/types.h -#include sys/module.h -#include sys/systm.h /* uprintf */ -#include sys/errno.h -#include sys/param.h /* defines used in kernel.h */ -#include sys/kernel.h /* types used in module initialization */ -#include sys/conf.h /* cdevsw struct */ -#include sys/uio.h /* uio struct */ -#include sys/malloc.h - -#define BUFFERSIZE 256 -#define CDEV_MAJOR 33 - -/* 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_open = echo_open, - .d_close = echo_close, - .d_maj = CDEV_MAJOR, - .d_name = "echo", - .d_read = echo_read, - .d_write = echo_write -}; - -typedef struct s_echo { - char msg[BUFFERSIZE]; - int len; -} t_echo; - -/* vars */ -static dev_t echo_dev; -static int count; -static t_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, int what, void *arg) -{ - int err = 0; - - switch (what) { - case MOD_LOAD: /* kldload */ - echo_dev = make_dev(echo_cdevsw, - 0, - UID_ROOT, - GID_WHEEL, - 0600, - "echo"); - /* kmalloc memory for use by this driver */ - MALLOC(echomsg, t_echo *, sizeof(t_echo), M_ECHOBUF, M_WAITOK); - printf("Echo device loaded.\n"); - break; - case MOD_UNLOAD: - destroy_dev(echo_dev); - FREE(echomsg,M_ECHOBUF); - printf("Echo device unloaded.\n"); - break; - default: - err = EINVAL; - break; - } - return(err); -} - -static int -echo_open(dev_t dev, int oflags, int devtype, struct thread *p) -{ - int err = 0; - - uprintf("Opened device \"echo\" successfully.\n"); - return(err); -} - -static int -echo_close(dev_t dev, int fflag, int devtype, struct thread *p) -{ - 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(dev_t dev, struct uio *uio, int ioflag) -{ - int err = 0; - int amt; - - /* - * How big is this read operation? Either as big as the user wants, - * or as big as the remaining data - */ - amt = MIN(uio->uio_resid, (echomsg->len - uio->uio_offset > 0) ? - echomsg->len - uio->uio_offset : 0); - if ((err = uiomove(echomsg->msg + uio->uio_offset,amt,uio)) != 0) { - uprintf("uiomove failed!\n"); - } - return(err); -} - -/* - * echo_write takes in a character string and saves it - * to buf for later accessing. - */ - -static int -echo_write(dev_t dev, struct uio *uio, int ioflag) -{ - int err = 0; - - /* Copy the string in from user memory to kernel memory */ - err = copyin(uio->uio_iov->iov_base, echomsg->msg, - MIN(uio->uio_iov->iov_len,BUFFERSIZE - 1)); - - /* Now we need to null terminate, then record the length */ - *(echomsg->msg + MIN(uio->uio_iov->iov_len,BUFFERSIZE - 1)) = 0; - echomsg->len = MIN(uio->uio_iov->iov_len,BUFFERSIZE); - - if (err != 0) { - uprintf("Write failed: bad address!\n"); - } - count++; - return(err); -} - -DEV_MODULE(echo,echo_loader,NULL); -.... - -==== - -Для установки этого драйвера во FreeBSD 4.X сначала вам нужно создать файл устройства в вашей файловой системе по команде типа следующей: - -[source,shell] -.... -# mknod /dev/echo c 33 0 -.... - -Когда этот драйвер загружен, вы можете выполнять следующие действия: - -[source,shell] -.... -# echo -n "Test Data" > /dev/echo -# cat /dev/echo -Test Data -.... - -Устройства, обслуживающие реальное оборудование, описываются в следующей главе. - -Дополнительные источники информации - -* http://www.daemonnews.org/200010/blueprints.html[Учебни по программированию механизма динамического компоновщика ядра (KLD)] - http://www.daemonnews.org/[Daemonnews] Октябрь 2000 -* http://www.daemonnews.org/200007/newbus-intro.html[Ка писать драйверы ядра в парадигме NEWBUS] - http://www.daemonnews.org/[Daemonnews] Июль 2000 - -[[driverbasics-block]] -== Блочные устройства (которых больше нет) - -Другие UNIX(R)-системы могут поддерживать со вторым типом дисковых устройств, так называемых устройств с блочной организацией. Блочные устройства являются дисковыми устройствами, для которых ядро организует кэширование. Такое кэширование делает блочные устройства практически бесполезными, или по крайней мере ненадёжными. Кэширование изменяет последовательность операций записи, лишая приложение возможности узнать реальное содержимое диска в любой момент времени. Это делает предсказуемое и надежное восстановление данных на диске (файл овые системы, базы данных и прочее) после сбоя невозможным. Так как запись может быть отложенной, то нет способа сообщить приложению, при выполнении какой именно операции записи ядро встретилось с ошибкой, что таким образом осложняет проблему целостности данных. По этой причине серьёзные приложения не полагаются на блочные устройства, и, на самом деле практически во всех приложениях, которые работают с диском напрямую, имеется большая проблема выбора устройств с последовательным доступом (или "raw"), которые должны использоваться. Из-за реа лизации отображения каж! дого диска (раздела) в два устройства с разными смыслами, которая усложняет соответствующий код ядра, во FreeBSD поддержка дисковых устройств с кэшированием была отброшена в процессе модернизации инфраструктуры I/O-операций с дисками. - -[[driverbasics-net]] -== Сетевые драйверы - -В случае драйверов сетевых устройств файлы устройств для доступа к ним не используются. Их выбор основан на другом механизме, работающем в ядре, и не использующем вызов open(); об использование сетевых устройств в общем случае рассказано в описании системного вызова socket(2). - -Почитайте справочную информацию о вызове ifnet(), устройстве loopback, почитайте драйверы Билла Пола (Bill Paul), и так далее.. diff --git a/documentation/content/ru/books/arch-handbook/locking/chapter.adoc b/documentation/content/ru/books/arch-handbook/locking/chapter.adoc deleted file mode 100644 index bdb37f8e29..0000000000 --- a/documentation/content/ru/books/arch-handbook/locking/chapter.adoc +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Глава 2. Замечания по блокировке -authors: ---- - -[[locking]] -= Замечания по блокировке -:doctype: book -:toc: macro -:toclevels: 1 -:icons: font -:sectnums: -:sectnumlevels: 6 -:sectnumoffset: 2 -:partnums: -:source-highlighter: rouge -:experimental: - -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 Project. Комментарии и пожелания направляйте в link:{freebsd-smp}._ - -Этот документ описывает механизм блокировки, используемый в ядре FreeBSD для обеспечения эффективной поддержки нескольких процессоров в ядре. Блокировку можно рассматривать с нескольких точек зрения. Структуры данных могут быть защищены с помощью блокировок mutex или man:lockmgr[9]. Несколько переменных защищены просто в силу атомарности используемых для доступа к ним операций. - -[[locking-mutexes]] -== Мьютексы - -Мьютекс (mutex) - это просто блокировка, используемая для реализации гарантированной исключительности. В частности, в каждый момент времени мьютексом может владеть только один объект. Если какой-то объект хочет получить мьютекс, который уже кто-то занял, он должен дождаться момента его освобождения. В ядре FreeBSD владельцами мьютексов являются процессы. - -Мьютексы могут быть затребованы рекурсивно, но предполагается, что они занимаются на короткое время. В частности, владельцу мьютекса нельзя выдерживать паузу. Если вам нужно выполнить блокировку на время паузы, используйте блокировку через man:lockmgr[9]. - -Каждый мьютекс имеет несколько представляющих интерес характеристик: - -Имя переменной:: -Имя переменной [type]#struct mtx# в исходных текстах ядра. - -Логическое имя:: -Имя мьютекса, назначенное ему через `mtx_init`. Это имя выводится в сообщениях трассировки KTR и диагностических предупреждающих и ошибочных сообщениях и используется для идентификации мьютексов в отладочном коде. - -Тип:: -Тип мьютекса в терминах флагов [constant]#MTX_*#. Значение каждого флага связано с его смыслом так, как это описано в man:mutex[9]. - -[constant]#MTX_DEF#::: -Sleep-мьютекс - -[constant]#MTX_SPIN#::: -Spin-мьютекс - -[constant]#MTX_RECURSE#::: -Этому мьютексу разрешается блокировать рекурсивно. - -Защиты:: -Список структур данных или членов структур данных, которые защищает этот мьютекс. Для членов структур данных имя будет в форме . члена структуры/. - -Зависимые функции:: -Функции, которые можно вызвать, если этот мьютекс занят. - -.Список мьютексов -[cols="15%,10%,10%,55%,20%", frame="all", options="header"] -|=== -| Variable Name -| Logical Name -| Type -| Protectees -| Dependent Functions - -|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` -|nearly everything -|lots - -|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="1,1", 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/sound/chapter.adoc b/documentation/content/ru/books/arch-handbook/sound/chapter.adoc deleted file mode 100644 index 4bb8b82ea9..0000000000 --- a/documentation/content/ru/books/arch-handbook/sound/chapter.adoc +++ /dev/null @@ -1,432 +0,0 @@ ---- -title: Глава 15. Подсистема звука -authors: ---- - -[[oss]] -= Подсистема звука -:doctype: book -:toc: macro -:toclevels: 1 -:icons: font -:sectnums: -:sectnumlevels: 6 -:sectnumoffset: 15 -:partnums: -:source-highlighter: rouge -:experimental: - -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]] -== Введение - -Перевод на русский язык: Виталий Богданов (mailto:gad@gad.glazov.net[gad@gad.glazov.net]) - -В подсистеме звука FreeBSD существует чёткое разделение между частью, поддерживающей общие звуковые возможности и аппаратно зависимой частью. Данная особенность делает более простым добавление поддержки новых устройств. - -man:pcm[4] занимает центральное место в подсистеме звука. Его основными элементами являются: - -* Интерфейс системных вызовов (read, write, ioctls) к функциям оцифрованного звука и микшера. Командный набор ioctl совместим с интерфейсом _OSS_ или _Voxware_, позволяя тем самым портирование мультимедиа приложений без дополнительной модификации. -* Общий код обработки звуковых данных (преобразования форматов, виртуальные каналы). -* Единый программный интерфейс к аппаратно-зависимым модулям звукового интерфейса. -* Дополнительная поддержка нескольких общих аппаратных интерфейсов (ac97) или разделяемого аппаратно-специфичного кода (например: функции ISA DMA). - -Поддержка отдельных звуковых карт осуществляется с помощью аппаратно-специфичных драйверов, обеспечивающих канальные и микшерные интерфейсы, включаемые в общий код. - -В этой главе термином мы будем называть центральную, общую часть звукового драйвера, как противопоставление аппаратно-специфичным модулям. - -Человек, решающий написать драйвер наверняка захочет использовать в качестве шаблона уже существующий код. Но, если звуковой код хорош и чист, он также в основном лишён комментариев. Этот документ - попытка рассмотрения базового интерфейса и попытка ответить на вопросы, возникшие при адаптировании существующего кода. - -Для старта с рабочего примера, вы можете найти шаблон драйвера, оснащенного комментариями на http://people.FreeBSD.org/\~cg/template.c[ http://people.FreeBSD.org/~cg/template.c] - -[[oss-files]] -== Файлы - -Весь исходный код, на сегодняшний момент (FreeBSD 4.4), содержится в каталоге [.filename]#/usr/src/sys/dev/sound/#, за исключением публичных определений интерфейса ioctl, находящихся в [.filename]#/usr/src/sys/sys/soundcard.h# - -В подкаталоге [.filename]#pcm/# родительского каталога [.filename]#/usr/src/sys/dev/sound/# находится главный код, а в каталогах [.filename]#isa/# и [.filename]#pci/# содержатся драйвера для ISA и PCI карт. - -[[pcm-probe-and-attach]] -== Обнаружение, подключение, и т.д. - -Обнаружение и подключение звуковых драйверов во многом схоже с драйвером любого другого устройства. За дополнительной информацией вы можете обратиться к главам <<isa-driver, ISA>> или <<pci,PCI>> данного руководства. - -Но всё же, звуковые драйвера немного отличаются: - -* Они объявляют сами себя, как устройства класса , с частной структурой устройства : -+ -[.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. Её адрес передаётся посредством вызовов `pcm_register()` и `mixer_init()`. Позже передаёт назад этот адрес, в качестве параметра в вызовах к интерфейсам звукового драйвера. -* Функция подключения звукового драйвера должна объявлять её микшерный или AC97 интерфейс посредством вызова `mixer_init()`. Для микшерного интерфейса это взамен вернёт вызов <<xxxmixer-init,`xxxmixer_init()`>>. -* Функция подключения звукового драйвера передаёт общие настройки каналов посредством вызова `pcm_register(dev, sc, nplay, nrec)`, где `sc` - адрес структуры данных устройства, используемой в дальнейших вызовах от , а `nplay` и `nrec` - количество каналов проигрывания и записи. -* Функция подключения звукового драйвера объявляет каждый из её каналов с помощью вызовов `pcm_addchan()`. Это установит занятость канала в и вызовет взамен вызов <<xxxchannel-init,`xxxchannel_init()`>>. -* Функция отключения должна вызывать `pcm_unregister()` перед объявлением её ресурсов свободными. - -Существует два метода работы с не PnP устройствами: - -* Использование метода `device_identify()` (пример смотрите в: [.filename]#sound/isa/es1888.c#). `device_identify()` пытается обнаружить оборудование, использующее известные адреса, и если найдёт поддерживаемое устройство, то создаст новое pcm устройство, которое затем будет передано процессу обнаружения/подключения. -* Использование выборочной конфигурации ядра с соответствующими хинтами для pcm устройств (пример: [.filename]#sound/isa/mss.c#). - -драйверы должны поддерживать `device_suspend`, `device_resume` и `device_shutdown` функции, для корректного функционирования управления питанием и процесса выгрузки модуля. - -[[oss-interfaces]] -== Интерфейсы - -Интерфейс между и звуковыми драйверами определён в терминах <<kernel-objects,объектов ядра>>. - -Есть 2 основных интерфейса, которые обычно обеспечивает звуковой драйвер: _канальный_ и, либо _микшерный_ либо _AC97_. - -Интерфейс _AC97_ довольно мало использует доступ к ресурсам оборудования (чтение/запись регистров). Данный интерфейс реализован в драйверах для карт с кодеком AC97. В этом случае фактический микшерный интерфейс обеспечивается разделяемым кодом AC97 в . - -=== Канальный интерфейс - -==== Общие заметки о параметрах функций - -Звуковые драйверы обычно имеют структуру с личными данными для описания их устройства и по одной структуре на каждый поддерживаемый канал проигрывания или записи данных. - -Для всех функций канального интерфейса первый параметр - непрозрачный указатель. - -Второй параметр это указатель на структуру с данными канала. Исключение: У ``channel_init()`` это указатель на частную структуру устройства (данная функция возвращает указатель на канал для дальнейшего использования в ). - -==== Обзор операций передачи данных - -Для передачи данных, и звуковые драйвера используют разделяемую область памяти, описанную в . - -принадлежит , и звуковые драйверы получают нужные значения с помощью вызовов функций (`sndbuf_getxxx()`). - -Область разделяемой памяти имеет размер, определяемый с помощью `sndbuf_getsize()` и разделён на блоки фиксированного размера, определённого в `sndbuf_getblksz()` количества байт. - -При проигрывании, общий механизм передачи данных примерно следующий (обратный механизму, используемому при записи): - -* В начале, заполняет буфер, затем вызывает функцию звукового драйвера <<channel-trigger,``xxxchannel_trigger()``>> с параметром PCMTRIG_START. -* Затем звуковой драйвер многократно передаёт всю область памяти (`sndbuf_getbuf()`, `sndbuf_getsize()`) устройству, с количеством байт, определённым в `sndbuf_getblksz()` . Взамен это вызовет `chn_intr()` функцию для каждого переданного блока (это обычно происходит во время прерывания). -* `chn_intr()` копирует новые данные в область, которая была передана устройству (сейчас свободная) и вносит соответствующие изменения в структуру . - -[[xxxchannel-init]] -=== channel_init - -`xxxchannel_init()` вызывается для инициализации каждого из каналов проигрывания или записи. Вызовы инициируются функцией подключения звукового драйвера. (Подробнее в главе <<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 - это - указатель на структуру - контроля pcm канала. Это не прозрачный - объект. Функция должна хранить его в локальной структуре - канала, для дальнейшего использования в вызовах к - pcm (например в: - chn_intr(c)). - - dir определяет для каких целей - используется канал - (PCMDIR_PLAY или - PCMDIR_REC). - - Функция должна возвращать указатель на личную, - область, используемую для контроля этого - канала. Он будет передаваться в качестве параметра в - других вызовах канального интерфейса. - - channel_setformat - - xxxchannel_setformat() настраивает - устройство на конкретный канал определённого формата звука. - - static int - xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format) - { - struct xxx_chinfo *ch = data; - ... - return 0; - } - - format используется, как - AFMT_XXX значение - (soundcard.h). - - channel_setspeed - - xxxchannel_setspeed() устанавливает - оборудование канала на определённую шаблонную скорость и возвращает - возможную корректирующую скорость. - - static int - xxxchannel_setspeed(kobj_t obj, void *data, u_int32_t speed) - { - struct xxx_chinfo *ch = data; - ... - return speed; - } - - channel_setblocksize - - xxxchannel_setblocksize() устанавливает - размер передаваемого блока между - pcm и звуковым драйвером, и между - звуковым драйвером и устройством. Обычно это будет количество - переданных байт перед прерыванием. Во время трансфера звуковой - драйвер должен должен вызывать - pcm функцию chn_intr() каждый - раз при передаче блока данных такого размера. - - Большинство звуковых драйверов только берут на заметку - размер блока для использования во время передачи данных. - - static int - xxxchannel_setblocksize(kobj_t obj, void *data, u_int32_t blocksize) - { - struct xxx_chinfo *ch = data; - ... - return blocksize; - } - - Функция возвращает возможно согласованный размер - блока. В случае, если размер блока действительно - изменился должен быть произведён вызов - sndbuf_resize() для корректирования - буфера. - - channel_trigger - - xxxchannel_trigger() вызывается - pcm для контроля над трансферными - операциями в драйвере. - - static int - xxxchannel_trigger(kobj_t obj, void *data, int go) - { - struct xxx_chinfo *ch = data; - ... - return 0; - } - - go определяет действие для - текущего вызова. Возможные значения: - - PCMTRIG_START: драйвер - должен начать передачу данных из или в канальный - буфер. Буфер и его размер могут быть получены через - вызов sndbuf_getbuf() и - sndbuf_getsize(). - - PCMTRIG_EMLDMAWR / - PCMTRIG_EMLDMARD: говорит - драйверу, что входной или выходной буфер возможно - был обновлён. Большинство драйверов игнорируют - эти вызовы. - - PCMTRIG_STOP / - PCMTRIG_ABORT: драйвер должен - остановить текущую передачу данных. - - Если драйвер использует ISA DMA, - sndbuf_isadma() должна вызываться - перед выполнением действий над устройством, она также - позаботится о вещах со стороны DMA чипа. - - channel_getptr - - xxxchannel_getptr() возвращает - текущее смещение в передаваемом буфере. Обычно вызывается - в chn_intr(), и так - pcm узнаёт, где брать данные для - новой передачи. - - channel_free - - xxxchannel_free() вызывается для - освобождения ресурсов канала. Например: должна вызываться, - при выгрузке драйвера, если структуры данных канала - распределялись динамично или, если - sndbuf_alloc() не использовалась - для выделения памяти под буфер. *** 1367 LINES SKIPPED ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202510291624.59TGOdgX025765>