요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
======================
2
Writing an ALSA Driver
3
======================
5
:Author: Takashi Iwai <[email protected]>
7
Preface
8
=======
10
This document describes how to write an `ALSA (Advanced Linux Sound
11
Architecture) <http://www.alsa-project.org/>`__ driver. The document
12
focuses mainly on PCI soundcards. In the case of other device types, the
13
API might be different, too. However, at least the ALSA kernel API is
14
consistent, and therefore it would be still a bit help for writing them.
16
This document targets people who already have enough C language skills
17
and have basic linux kernel programming knowledge. This document doesn't
18
explain the general topic of linux kernel coding and doesn't cover
19
low-level driver implementation details. It only describes the standard
20
way to write a PCI sound driver on ALSA.
22
File Tree Structure
23
===================
25
General
26
-------
28
The file tree structure of ALSA driver is depicted below::
30
sound
31
/core
32
/oss
33
/seq
34
/oss
35
/include
36
/drivers
37
/mpu401
38
/opl3
39
/i2c
40
/synth
41
/emux
42
/pci
43
/(cards)
44
/isa
45
/(cards)
46
/arm
47
/ppc
48
/sparc
49
/usb
50
/pcmcia /(cards)
51
/soc
52
/oss
55
core directory
56
--------------
58
This directory contains the middle layer which is the heart of ALSA
59
drivers. In this directory, the native ALSA modules are stored. The
60
sub-directories contain different modules and are dependent upon the
61
kernel config.
63
core/oss
64
~~~~~~~~
66
The code for OSS PCM and mixer emulation modules is stored in this
67
directory. The OSS rawmidi emulation is included in the ALSA rawmidi
68
code since it's quite small. The sequencer code is stored in
69
``core/seq/oss`` directory (see `below <core/seq/oss_>`__).
71
core/seq
72
~~~~~~~~
74
This directory and its sub-directories are for the ALSA sequencer. This
75
directory contains the sequencer core and primary sequencer modules such
76
as snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
77
``CONFIG_SND_SEQUENCER`` is set in the kernel config.
79
core/seq/oss
80
~~~~~~~~~~~~
82
This contains the OSS sequencer emulation code.
84
include directory
85
-----------------
87
This is the place for the public header files of ALSA drivers, which are
88
to be exported to user-space, or included by several files in different
89
directories. Basically, the private header files should not be placed in
90
this directory, but you may still find files there, due to historical
91
reasons :)
93
drivers directory
94
-----------------
96
This directory contains code shared among different drivers on different
97
architectures. They are hence supposed not to be architecture-specific.
98
For example, the dummy PCM driver and the serial MIDI driver are found
99
in this directory. In the sub-directories, there is code for components
100
which are independent from bus and cpu architectures.
102
drivers/mpu401
103
~~~~~~~~~~~~~~
105
The MPU401 and MPU401-UART modules are stored here.
107
drivers/opl3 and opl4
108
~~~~~~~~~~~~~~~~~~~~~
110
The OPL3 and OPL4 FM-synth stuff is found here.
112
i2c directory
113
-------------
115
This contains the ALSA i2c components.
117
Although there is a standard i2c layer on Linux, ALSA has its own i2c
118
code for some cards, because the soundcard needs only a simple operation
119
and the standard i2c API is too complicated for such a purpose.
121
synth directory
122
---------------
124
This contains the synth middle-level modules.
126
So far, there is only Emu8000/Emu10k1 synth driver under the
127
``synth/emux`` sub-directory.
129
pci directory
130
-------------
132
This directory and its sub-directories hold the top-level card modules
133
for PCI soundcards and the code specific to the PCI BUS.
135
The drivers compiled from a single file are stored directly in the pci
136
directory, while the drivers with several source files are stored on
137
their own sub-directory (e.g. emu10k1, ice1712).
139
isa directory
140
-------------
142
This directory and its sub-directories hold the top-level card modules
143
for ISA soundcards.
145
arm, ppc, and sparc directories
146
-------------------------------
148
They are used for top-level card modules which are specific to one of
149
these architectures.
151
usb directory
152
-------------
154
This directory contains the USB-audio driver.
155
The USB MIDI driver is integrated in the usb-audio driver.
157
pcmcia directory
158
----------------
160
The PCMCIA, especially PCCard drivers will go here. CardBus drivers will
161
be in the pci directory, because their API is identical to that of
162
standard PCI cards.
164
soc directory
165
-------------
167
This directory contains the codes for ASoC (ALSA System on Chip)
168
layer including ASoC core, codec and machine drivers.
170
oss directory
171
-------------
173
This contains OSS/Lite code.
174
At the time of writing, all code has been removed except for dmasound
175
on m68k.
178
Basic Flow for PCI Drivers
179
==========================
181
Outline
182
-------
184
The minimum flow for PCI soundcards is as follows:
186
- define the PCI ID table (see the section `PCI Entries`_).
188
- create ``probe`` callback.
190
- create ``remove`` callback.
192
- create a struct pci_driver structure
193
containing the three pointers above.
195
- create an ``init`` function just calling the
196
:c:func:`pci_register_driver()` to register the pci_driver
197
table defined above.
199
- create an ``exit`` function to call the
200
:c:func:`pci_unregister_driver()` function.
202
Full Code Example
203
-----------------
205
The code example is shown below. Some parts are kept unimplemented at
206
this moment but will be filled in the next sections. The numbers in the
207
comment lines of the :c:func:`snd_mychip_probe()` function refer
208
to details explained in the following section.
210
::
212
#include <linux/init.h>
213
#include <linux/pci.h>
214
#include <linux/slab.h>
215
#include <sound/core.h>
216
#include <sound/initval.h>
218
/* module parameters (see "Module Parameters") */
219
/* SNDRV_CARDS: maximum number of cards supported by this module */
220
static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
221
static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
222
static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
224
/* definition of the chip-specific record */
225
struct mychip {
226
struct snd_card *card;
227
/* the rest of the implementation will be in section
228
* "PCI Resource Management"
229
*/
230
};
232
/* chip-specific destructor
233
* (see "PCI Resource Management")
234
*/
235
static int snd_mychip_free(struct mychip *chip)
236
{
237
.... /* will be implemented later... */
238
}
240
/* component-destructor
241
* (see "Management of Cards and Components")
242
*/
243
static int snd_mychip_dev_free(struct snd_device *device)
244
{
245
return snd_mychip_free(device->device_data);
246
}
248
/* chip-specific constructor
249
* (see "Management of Cards and Components")
250
*/
251
static int snd_mychip_create(struct snd_card *card,
252
struct pci_dev *pci,
253
struct mychip **rchip)
254
{
255
struct mychip *chip;
256
int err;
257
static const struct snd_device_ops ops = {
258
.dev_free = snd_mychip_dev_free,
259
};
261
*rchip = NULL;
263
/* check PCI availability here
264
* (see "PCI Resource Management")
265
*/
266
....
268
/* allocate a chip-specific data with zero filled */
269
chip = kzalloc(sizeof(*chip), GFP_KERNEL);
270
if (chip == NULL)
271
return -ENOMEM;
273
chip->card = card;
275
/* rest of initialization here; will be implemented
276
* later, see "PCI Resource Management"
277
*/
278
....
280
err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
281
if (err < 0) {
282
snd_mychip_free(chip);
283
return err;
284
}
286
*rchip = chip;
287
return 0;
288
}
290
/* constructor -- see "Driver Constructor" sub-section */
291
static int snd_mychip_probe(struct pci_dev *pci,
292
const struct pci_device_id *pci_id)
293
{
294
static int dev;
295
struct snd_card *card;
296
struct mychip *chip;
297
int err;
299
/* (1) */
300
if (dev >= SNDRV_CARDS)
301
return -ENODEV;
302
if (!enable[dev]) {
303
dev++;
304
return -ENOENT;
305
}
307
/* (2) */
308
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
309
0, &card);
310
if (err < 0)
311
return err;
313
/* (3) */
314
err = snd_mychip_create(card, pci, &chip);
315
if (err < 0)
316
goto error;
318
/* (4) */
319
strcpy(card->driver, "My Chip");
320
strcpy(card->shortname, "My Own Chip 123");
321
sprintf(card->longname, "%s at 0x%lx irq %i",
322
card->shortname, chip->port, chip->irq);
324
/* (5) */
325
.... /* implemented later */
327
/* (6) */
328
err = snd_card_register(card);
329
if (err < 0)
330
goto error;
332
/* (7) */
333
pci_set_drvdata(pci, card);
334
dev++;
335
return 0;
337
error:
338
snd_card_free(card);
339
return err;
340
}
342
/* destructor -- see the "Destructor" sub-section */
343
static void snd_mychip_remove(struct pci_dev *pci)
344
{
345
snd_card_free(pci_get_drvdata(pci));
346
}
350
Driver Constructor
351
------------------
353
The real constructor of PCI drivers is the ``probe`` callback. The
354
``probe`` callback and other component-constructors which are called
355
from the ``probe`` callback cannot be used with the ``__init`` prefix
356
because any PCI device could be a hotplug device.
358
In the ``probe`` callback, the following scheme is often used.
360
1) Check and increment the device index.
361
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
363
::
365
static int dev;
366
....
367
if (dev >= SNDRV_CARDS)
368
return -ENODEV;
369
if (!enable[dev]) {
370
dev++;
371
return -ENOENT;
372
}
375
where ``enable[dev]`` is the module option.
377
Each time the ``probe`` callback is called, check the availability of
378
the device. If not available, simply increment the device index and
379
return. dev will be incremented also later (`step 7
380
<7) Set the PCI driver data and return zero._>`__).
382
2) Create a card instance
383
~~~~~~~~~~~~~~~~~~~~~~~~~
385
::
387
struct snd_card *card;
388
int err;
389
....
390
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
391
0, &card);
394
The details will be explained in the section `Management of Cards and
395
Components`_.
397
3) Create a main component
398
~~~~~~~~~~~~~~~~~~~~~~~~~~
400
In this part, the PCI resources are allocated::
402
struct mychip *chip;
403
....
404
err = snd_mychip_create(card, pci, &chip);
405
if (err < 0)
406
goto error;
408
The details will be explained in the section `PCI Resource
409
Management`_.
411
When something goes wrong, the probe function needs to deal with the
412
error. In this example, we have a single error handling path placed
413
at the end of the function::
415
error:
416
snd_card_free(card);
417
return err;
419
Since each component can be properly freed, the single
420
:c:func:`snd_card_free()` call should suffice in most cases.
423
4) Set the driver ID and name strings.
424
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
426
::
428
strcpy(card->driver, "My Chip");
429
strcpy(card->shortname, "My Own Chip 123");
430
sprintf(card->longname, "%s at 0x%lx irq %i",
431
card->shortname, chip->port, chip->irq);
433
The driver field holds the minimal ID string of the chip. This is used
434
by alsa-lib's configurator, so keep it simple but unique. Even the
435
same driver can have different driver IDs to distinguish the
436
functionality of each chip type.
438
The shortname field is a string shown as more verbose name. The longname
439
field contains the information shown in ``/proc/asound/cards``.
441
5) Create other components, such as mixer, MIDI, etc.
442
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
444
Here you define the basic components such as `PCM <PCM Interface_>`__,
445
mixer (e.g. `AC97 <API for AC97 Codec_>`__), MIDI (e.g.
446
`MPU-401 <MIDI (MPU401-UART) Interface_>`__), and other interfaces.
447
Also, if you want a `proc file <Proc Interface_>`__, define it here,
448
too.
450
6) Register the card instance.
451
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
453
::
455
err = snd_card_register(card);
456
if (err < 0)
457
goto error;
459
Will be explained in the section `Management of Cards and
460
Components`_, too.
462
7) Set the PCI driver data and return zero.
463
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
465
::
467
pci_set_drvdata(pci, card);
468
dev++;
469
return 0;
471
In the above, the card record is stored. This pointer is used in the
472
remove callback and power-management callbacks, too.
474
Destructor
475
----------
477
The destructor, the remove callback, simply releases the card instance.
478
Then the ALSA middle layer will release all the attached components
479
automatically.
481
It would be typically just calling :c:func:`snd_card_free()`::
483
static void snd_mychip_remove(struct pci_dev *pci)
484
{
485
snd_card_free(pci_get_drvdata(pci));
486
}
489
The above code assumes that the card pointer is set to the PCI driver
490
data.
492
Header Files
493
------------
495
For the above example, at least the following include files are
496
necessary::
498
#include <linux/init.h>
499
#include <linux/pci.h>
500
#include <linux/slab.h>
501
#include <sound/core.h>
502
#include <sound/initval.h>
504
where the last one is necessary only when module options are defined
505
in the source file. If the code is split into several files, the files
506
without module options don't need them.
508
In addition to these headers, you'll need ``<linux/interrupt.h>`` for
509
interrupt handling, and ``<linux/io.h>`` for I/O access. If you use the
510
:c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need
511
to include ``<linux/delay.h>`` too.
513
The ALSA interfaces like the PCM and control APIs are defined in other
514
``<sound/xxx.h>`` header files. They have to be included after
515
``<sound/core.h>``.
517
Management of Cards and Components
518
==================================
520
Card Instance
521
-------------
523
For each soundcard, a “card” record must be allocated.
525
A card record is the headquarters of the soundcard. It manages the whole
526
list of devices (components) on the soundcard, such as PCM, mixers,
527
MIDI, synthesizer, and so on. Also, the card record holds the ID and the
528
name strings of the card, manages the root of proc files, and controls
529
the power-management states and hotplug disconnections. The component
530
list on the card record is used to manage the correct release of
531
resources at destruction.
533
As mentioned above, to create a card instance, call
534
:c:func:`snd_card_new()`::
536
struct snd_card *card;
537
int err;
538
err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
541
The function takes six arguments: the parent device pointer, the
542
card-index number, the id string, the module pointer (usually
543
``THIS_MODULE``), the size of extra-data space, and the pointer to
544
return the card instance. The extra_size argument is used to allocate
545
card->private_data for the chip-specific data. Note that these data are
546
allocated by :c:func:`snd_card_new()`.
548
The first argument, the pointer of struct device, specifies the parent
549
device. For PCI devices, typically ``&pci->`` is passed there.
551
Components
552
----------
554
After the card is created, you can attach the components (devices) to
555
the card instance. In an ALSA driver, a component is represented as a
556
struct snd_device object. A component
557
can be a PCM instance, a control interface, a raw MIDI interface, etc.
558
Each such instance has one component entry.
560
A component can be created via the :c:func:`snd_device_new()`
561
function::
563
snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
565
This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
566
data pointer, and the callback pointers (``&ops``). The device-level
567
defines the type of components and the order of registration and
568
de-registration. For most components, the device-level is already
569
defined. For a user-defined component, you can use
570
``SNDRV_DEV_LOWLEVEL``.
572
This function itself doesn't allocate the data space. The data must be
573
allocated manually beforehand, and its pointer is passed as the
574
argument. This pointer (``chip`` in the above example) is used as the
575
identifier for the instance.
577
Each pre-defined ALSA component such as AC97 and PCM calls
578
:c:func:`snd_device_new()` inside its constructor. The destructor
579
for each component is defined in the callback pointers. Hence, you don't
580
need to take care of calling a destructor for such a component.
582
If you wish to create your own component, you need to set the destructor
583
function to the dev_free callback in the ``ops``, so that it can be
584
released automatically via :c:func:`snd_card_free()`. The next
585
example will show an implementation of chip-specific data.
587
Chip-Specific Data
588
------------------
590
Chip-specific information, e.g. the I/O port address, its resource
591
pointer, or the irq number, is stored in the chip-specific record::
593
struct mychip {
594
....
595
};
598
In general, there are two ways of allocating the chip record.
600
1. Allocating via :c:func:`snd_card_new()`.
601
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
603
As mentioned above, you can pass the extra-data-length to the 5th
604
argument of :c:func:`snd_card_new()`, e.g.::
606
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
607
sizeof(struct mychip), &card);
609
struct mychip is the type of the chip record.
611
In return, the allocated record can be accessed as
613
::
615
struct mychip *chip = card->private_data;
617
With this method, you don't have to allocate twice. The record is
618
released together with the card instance.
620
2. Allocating an extra device.
621
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
623
After allocating a card instance via :c:func:`snd_card_new()`
624
(with ``0`` on the 4th arg), call :c:func:`kzalloc()`::
626
struct snd_card *card;
627
struct mychip *chip;
628
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
629
0, &card);
630
.....
631
chip = kzalloc(sizeof(*chip), GFP_KERNEL);
633
The chip record should have the field to hold the card pointer at least,
635
::
637
struct mychip {
638
struct snd_card *card;
639
....
640
};
643
Then, set the card pointer in the returned chip instance::
645
chip->card = card;
647
Next, initialize the fields, and register this chip record as a
648
low-level device with a specified ``ops``::
650
static const struct snd_device_ops ops = {
651
.dev_free = snd_mychip_dev_free,
652
};
653
....
654
snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
656
:c:func:`snd_mychip_dev_free()` is the device-destructor
657
function, which will call the real destructor::
659
static int snd_mychip_dev_free(struct snd_device *device)
660
{
661
return snd_mychip_free(device->device_data);
662
}
664
where :c:func:`snd_mychip_free()` is the real destructor.
666
The demerit of this method is the obviously larger amount of code.
667
The merit is, however, that you can trigger your own callback at
668
registering and disconnecting the card via a setting in snd_device_ops.
669
About registering and disconnecting the card, see the subsections
670
below.
673
Registration and Release
674
------------------------
676
After all components are assigned, register the card instance by calling
677
:c:func:`snd_card_register()`. Access to the device files is
678
enabled at this point. That is, before
679
:c:func:`snd_card_register()` is called, the components are safely
680
inaccessible from external side. If this call fails, exit the probe
681
function after releasing the card via :c:func:`snd_card_free()`.
683
For releasing the card instance, you can call simply
684
:c:func:`snd_card_free()`. As mentioned earlier, all components
685
are released automatically by this call.
687
For a device which allows hotplugging, you can use
688
:c:func:`snd_card_free_when_closed()`. This one will postpone
689
the destruction until all devices are closed.
691
PCI Resource Management
692
=======================
694
Full Code Example
695
-----------------
697
In this section, we'll complete the chip-specific constructor,
698
destructor and PCI entries. Example code is shown first, below::
700
struct mychip {
701
struct snd_card *card;
702
struct pci_dev *pci;
704
unsigned long port;
705
int irq;
706
};
708
static int snd_mychip_free(struct mychip *chip)
709
{
710
/* disable hardware here if any */
711
.... /* (not implemented in this document) */
713
/* release the irq */
714
if (chip->irq >= 0)
715
free_irq(chip->irq, chip);
716
/* release the I/O ports & memory */
717
pci_release_regions(chip->pci);
718
/* disable the PCI entry */
719
pci_disable_device(chip->pci);
720
/* release the data */
721
kfree(chip);
722
return 0;
723
}
725
/* chip-specific constructor */
726
static int snd_mychip_create(struct snd_card *card,
727
struct pci_dev *pci,
728
struct mychip **rchip)
729
{
730
struct mychip *chip;
731
int err;
732
static const struct snd_device_ops ops = {
733
.dev_free = snd_mychip_dev_free,
734
};
736
*rchip = NULL;
738
/* initialize the PCI entry */
739
err = pci_enable_device(pci);
740
if (err < 0)
741
return err;
742
/* check PCI availability (28bit DMA) */
743
if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
744
pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
745
printk(KERN_ERR "error to set 28bit mask DMA\n");
746
pci_disable_device(pci);
747
return -ENXIO;
748
}
750
chip = kzalloc(sizeof(*chip), GFP_KERNEL);
751
if (chip == NULL) {
752
pci_disable_device(pci);
753
return -ENOMEM;
754
}
756
/* initialize the stuff */
757
chip->card = card;
758
chip->pci = pci;
759
chip->irq = -1;
761
/* (1) PCI resource allocation */
762
err = pci_request_regions(pci, "My Chip");
763
if (err < 0) {
764
kfree(chip);
765
pci_disable_device(pci);
766
return err;
767
}
768
chip->port = pci_resource_start(pci, 0);
769
if (request_irq(pci->irq, snd_mychip_interrupt,
770
IRQF_SHARED, KBUILD_MODNAME, chip)) {
771
printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
772
snd_mychip_free(chip);
773
return -EBUSY;
774
}
775
chip->irq = pci->irq;
776
card->sync_irq = chip->irq;
778
/* (2) initialization of the chip hardware */
779
.... /* (not implemented in this document) */
781
err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
782
if (err < 0) {
783
snd_mychip_free(chip);
784
return err;
785
}
787
*rchip = chip;
788
return 0;
789
}
791
/* PCI IDs */
792
static struct pci_device_id snd_mychip_ids[] = {
793
{ PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
794
PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
795
....
796
{ 0, }
797
};
798
MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
800
/* pci_driver definition */
801
static struct pci_driver driver = {
802
.name = KBUILD_MODNAME,
803
.id_table = snd_mychip_ids,
804
.probe = snd_mychip_probe,
805
.remove = snd_mychip_remove,
806
};
808
/* module initialization */
809
static int __init alsa_card_mychip_init(void)
810
{
811
return pci_register_driver(&driver);
812
}
814
/* module clean up */
815
static void __exit alsa_card_mychip_exit(void)
816
{
817
pci_unregister_driver(&driver);
818
}
820
module_init(alsa_card_mychip_init)
821
module_exit(alsa_card_mychip_exit)
823
EXPORT_NO_SYMBOLS; /* for old kernels only */
825
Some Hafta's
826
------------
828
The allocation of PCI resources is done in the ``probe`` function, and
829
usually an extra :c:func:`xxx_create()` function is written for this
830
purpose.
832
In the case of PCI devices, you first have to call the
833
:c:func:`pci_enable_device()` function before allocating
834
resources. Also, you need to set the proper PCI DMA mask to limit the
835
accessed I/O range. In some cases, you might need to call
836
:c:func:`pci_set_master()` function, too.
838
Suppose a 28bit mask, the code to be added would look like::
840
err = pci_enable_device(pci);
841
if (err < 0)
842
return err;
843
if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
844
pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
845
printk(KERN_ERR "error to set 28bit mask DMA\n");
846
pci_disable_device(pci);
847
return -ENXIO;
848
}
851
Resource Allocation
852
-------------------
854
The allocation of I/O ports and irqs is done via standard kernel
855
functions. These resources must be released in the destructor
856
function (see below).
858
Now assume that the PCI device has an I/O port with 8 bytes and an
859
interrupt. Then struct mychip will have the
860
following fields::
862
struct mychip {
863
struct snd_card *card;
865
unsigned long port;
866
int irq;
867
};
870
For an I/O port (and also a memory region), you need to have the
871
resource pointer for the standard resource management. For an irq, you
872
have to keep only the irq number (integer). But you need to initialize
873
this number to -1 before actual allocation, since irq 0 is valid. The
874
port address and its resource pointer can be initialized as null by
875
:c:func:`kzalloc()` automatically, so you don't have to take care of
876
resetting them.
878
The allocation of an I/O port is done like this::
880
err = pci_request_regions(pci, "My Chip");
881
if (err < 0) {
882
kfree(chip);
883
pci_disable_device(pci);
884
return err;
885
}
886
chip->port = pci_resource_start(pci, 0);
888
It will reserve the I/O port region of 8 bytes of the given PCI device.
889
The returned value, ``chip->res_port``, is allocated via
890
:c:func:`kmalloc()` by :c:func:`request_region()`. The pointer
891
must be released via :c:func:`kfree()`, but there is a problem with
892
this. This issue will be explained later.
894
The allocation of an interrupt source is done like this::
896
if (request_irq(pci->irq, snd_mychip_interrupt,
897
IRQF_SHARED, KBUILD_MODNAME, chip)) {
898
printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
899
snd_mychip_free(chip);
900
return -EBUSY;
901
}
902
chip->irq = pci->irq;
904
where :c:func:`snd_mychip_interrupt()` is the interrupt handler
905
defined `later <PCM Interrupt Handler_>`__. Note that
906
``chip->irq`` should be defined only when :c:func:`request_irq()`
907
succeeded.
909
On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
910
as the interrupt flag of :c:func:`request_irq()`.
912
The last argument of :c:func:`request_irq()` is the data pointer
913
passed to the interrupt handler. Usually, the chip-specific record is
914
used for that, but you can use what you like, too.
916
I won't give details about the interrupt handler at this point, but at
917
least its appearance can be explained now. The interrupt handler looks
918
usually as follows::
920
static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
921
{
922
struct mychip *chip = dev_id;
923
....
924
return IRQ_HANDLED;
925
}
927
After requesting the IRQ, you can passed it to ``card->sync_irq``
928
field::
930
card->irq = chip->irq;
932
This allows the PCM core to automatically call
933
:c:func:`synchronize_irq()` at the right time, like before ``hw_free``.
934
See the later section `sync_stop callback`_ for details.
936
Now let's write the corresponding destructor for the resources above.
937
The role of destructor is simple: disable the hardware (if already
938
activated) and release the resources. So far, we have no hardware part,
939
so the disabling code is not written here.
941
To release the resources, the “check-and-release” method is a safer way.
942
For the interrupt, do like this::
944
if (chip->irq >= 0)
945
free_irq(chip->irq, chip);
947
Since the irq number can start from 0, you should initialize
948
``chip->irq`` with a negative value (e.g. -1), so that you can check
949
the validity of the irq number as above.
951
When you requested I/O ports or memory regions via
952
:c:func:`pci_request_region()` or
953
:c:func:`pci_request_regions()` like in this example, release the
954
resource(s) using the corresponding function,
955
:c:func:`pci_release_region()` or
956
:c:func:`pci_release_regions()`::
958
pci_release_regions(chip->pci);
960
When you requested manually via :c:func:`request_region()` or
961
:c:func:`request_mem_region()`, you can release it via
962
:c:func:`release_resource()`. Suppose that you keep the resource
963
pointer returned from :c:func:`request_region()` in
964
chip->res_port, the release procedure looks like::
966
release_and_free_resource(chip->res_port);
968
Don't forget to call :c:func:`pci_disable_device()` before the
969
end.
971
And finally, release the chip-specific record::
973
kfree(chip);
975
We didn't implement the hardware disabling part above. If you
976
need to do this, please note that the destructor may be called even
977
before the initialization of the chip is completed. It would be better
978
to have a flag to skip hardware disabling if the hardware was not
979
initialized yet.
981
When the chip-data is assigned to the card using
982
:c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL``, its
983
destructor is called last. That is, it is assured that all other
984
components like PCMs and controls have already been released. You don't
985
have to stop PCMs, etc. explicitly, but just call low-level hardware
986
stopping.
988
The management of a memory-mapped region is almost as same as the
989
management of an I/O port. You'll need two fields as follows::
991
struct mychip {
992
....
993
unsigned long iobase_phys;
994
void __iomem *iobase_virt;
995
};
997
and the allocation would look like below::
999
err = pci_request_regions(pci, "My Chip");
1000
if (err < 0) {
1001
kfree(chip);
1002
return err;
1003
}
1004
chip->iobase_phys = pci_resource_start(pci, 0);
1005
chip->iobase_virt = ioremap(chip->iobase_phys,
1006
pci_resource_len(pci, 0));
1008
and the corresponding destructor would be::
1010
static int snd_mychip_free(struct mychip *chip)
1011
{
1012
....
1013
if (chip->iobase_virt)
1014
iounmap(chip->iobase_virt);
1015
....
1016
pci_release_regions(chip->pci);
1017
....
1018
}
1020
Of course, a modern way with :c:func:`pci_iomap()` will make things a
1021
bit easier, too::
1023
err = pci_request_regions(pci, "My Chip");
1024
if (err < 0) {
1025
kfree(chip);
1026
return err;
1027
}
1028
chip->iobase_virt = pci_iomap(pci, 0, 0);
1030
which is paired with :c:func:`pci_iounmap()` at destructor.
1033
PCI Entries
1034
-----------
1036
So far, so good. Let's finish the missing PCI stuff. At first, we need a
1037
struct pci_device_id table for
1038
this chipset. It's a table of PCI vendor/device ID number, and some
1039
masks.
1041
For example::
1043
static struct pci_device_id snd_mychip_ids[] = {
1044
{ PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1045
PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1046
....
1047
{ 0, }
1048
};
1049
MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1051
The first and second fields of the struct pci_device_id are the vendor
1052
and device IDs. If you have no reason to filter the matching devices, you can
1053
leave the remaining fields as above. The last field of the
1054
struct pci_device_id contains private data for this entry. You can specify
1055
any value here, for example, to define specific operations for supported
1056
device IDs. Such an example is found in the intel8x0 driver.
1058
The last entry of this list is the terminator. You must specify this
1059
all-zero entry.
1061
Then, prepare the struct pci_driver
1062
record::
1064
static struct pci_driver driver = {
1065
.name = KBUILD_MODNAME,
1066
.id_table = snd_mychip_ids,
1067
.probe = snd_mychip_probe,
1068
.remove = snd_mychip_remove,
1069
};
1071
The ``probe`` and ``remove`` functions have already been defined in
1072
the previous sections. The ``name`` field is the name string of this
1073
device. Note that you must not use slashes (“/”) in this string.
1075
And at last, the module entries::
1077
static int __init alsa_card_mychip_init(void)
1078
{
1079
return pci_register_driver(&driver);
1080
}
1082
static void __exit alsa_card_mychip_exit(void)
1083
{
1084
pci_unregister_driver(&driver);
1085
}
1087
module_init(alsa_card_mychip_init)
1088
module_exit(alsa_card_mychip_exit)
1090
Note that these module entries are tagged with ``__init`` and ``__exit``
1091
prefixes.
1093
That's all!
1095
PCM Interface
1096
=============
1098
General
1099
-------
1101
The PCM middle layer of ALSA is quite powerful and it is only necessary
1102
for each driver to implement the low-level functions to access its
1103
hardware.
1105
To access the PCM layer, you need to include ``<sound/pcm.h>``
1106
first. In addition, ``<sound/pcm_params.h>`` might be needed if you
1107
access some functions related with hw_param.
1109
Each card device can have up to four PCM instances. A PCM instance
1110
corresponds to a PCM device file. The limitation of number of instances
1111
comes only from the available bit size of Linux' device numbers.
1112
Once 64bit device numbers are used, we'll have more PCM instances
1113
available.
1115
A PCM instance consists of PCM playback and capture streams, and each
1116
PCM stream consists of one or more PCM substreams. Some soundcards
1117
support multiple playback functions. For example, emu10k1 has a PCM
1118
playback of 32 stereo substreams. In this case, at each open, a free
1119
substream is (usually) automatically chosen and opened. Meanwhile, when
1120
only one substream exists and it was already opened, a subsequent open
1121
will either block or error with ``EAGAIN`` according to the file open
1122
mode. But you don't have to care about such details in your driver. The
1123
PCM middle layer will take care of such work.
1125
Full Code Example
1126
-----------------
1128
The example code below does not include any hardware access routines but
1129
shows only the skeleton, how to build up the PCM interfaces::
1131
#include <sound/pcm.h>
1132
....
1134
/* hardware definition */
1135
static struct snd_pcm_hardware snd_mychip_playback_hw = {
1136
.info = (SNDRV_PCM_INFO_MMAP |
1137
SNDRV_PCM_INFO_INTERLEAVED |
1138
SNDRV_PCM_INFO_BLOCK_TRANSFER |
1139
SNDRV_PCM_INFO_MMAP_VALID),
1140
.formats = SNDRV_PCM_FMTBIT_S16_LE,
1141
.rates = SNDRV_PCM_RATE_8000_48000,
1142
.rate_min = 8000,
1143
.rate_max = 48000,
1144
.channels_min = 2,
1145
.channels_max = 2,
1146
.buffer_bytes_max = 32768,
1147
.period_bytes_min = 4096,
1148
.period_bytes_max = 32768,
1149
.periods_min = 1,
1150
.periods_max = 1024,
1151
};
1153
/* hardware definition */
1154
static struct snd_pcm_hardware snd_mychip_capture_hw = {
1155
.info = (SNDRV_PCM_INFO_MMAP |
1156
SNDRV_PCM_INFO_INTERLEAVED |
1157
SNDRV_PCM_INFO_BLOCK_TRANSFER |
1158
SNDRV_PCM_INFO_MMAP_VALID),
1159
.formats = SNDRV_PCM_FMTBIT_S16_LE,
1160
.rates = SNDRV_PCM_RATE_8000_48000,
1161
.rate_min = 8000,
1162
.rate_max = 48000,
1163
.channels_min = 2,
1164
.channels_max = 2,
1165
.buffer_bytes_max = 32768,
1166
.period_bytes_min = 4096,
1167
.period_bytes_max = 32768,
1168
.periods_min = 1,
1169
.periods_max = 1024,
1170
};
1172
/* open callback */
1173
static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1174
{
1175
struct mychip *chip = snd_pcm_substream_chip(substream);
1176
struct snd_pcm_runtime *runtime = substream->runtime;
1178
runtime->hw = snd_mychip_playback_hw;
1179
/* more hardware-initialization will be done here */
1180
....
1181
return 0;
1182
}
1184
/* close callback */
1185
static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1186
{
1187
struct mychip *chip = snd_pcm_substream_chip(substream);
1188
/* the hardware-specific codes will be here */
1189
....
1190
return 0;
1192
}
1194
/* open callback */
1195
static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1196
{
1197
struct mychip *chip = snd_pcm_substream_chip(substream);
1198
struct snd_pcm_runtime *runtime = substream->runtime;
1200
runtime->hw = snd_mychip_capture_hw;
1201
/* more hardware-initialization will be done here */
1202
....
1203
return 0;
1204
}
1206
/* close callback */
1207
static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1208
{
1209
struct mychip *chip = snd_pcm_substream_chip(substream);
1210
/* the hardware-specific codes will be here */
1211
....
1212
return 0;
1213
}
1215
/* hw_params callback */
1216
static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1217
struct snd_pcm_hw_params *hw_params)
1218
{
1219
/* the hardware-specific codes will be here */
1220
....
1221
return 0;
1222
}
1224
/* hw_free callback */
1225
static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1226
{
1227
/* the hardware-specific codes will be here */
1228
....
1229
return 0;
1230
}
1232
/* prepare callback */
1233
static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1234
{
1235
struct mychip *chip = snd_pcm_substream_chip(substream);
1236
struct snd_pcm_runtime *runtime = substream->runtime;
1238
/* set up the hardware with the current configuration
1239
* for example...
1240
*/
1241
mychip_set_sample_format(chip, runtime->format);
1242
mychip_set_sample_rate(chip, runtime->rate);
1243
mychip_set_channels(chip, runtime->channels);
1244
mychip_set_dma_setup(chip, runtime->dma_addr,
1245
chip->buffer_size,
1246
chip->period_size);
1247
return 0;
1248
}
1250
/* trigger callback */
1251
static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1252
int cmd)
1253
{
1254
switch (cmd) {
1255
case SNDRV_PCM_TRIGGER_START:
1256
/* do something to start the PCM engine */
1257
....
1258
break;
1259
case SNDRV_PCM_TRIGGER_STOP:
1260
/* do something to stop the PCM engine */
1261
....
1262
break;
1263
default:
1264
return -EINVAL;
1265
}
1266
}
1268
/* pointer callback */
1269
static snd_pcm_uframes_t
1270
snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1271
{
1272
struct mychip *chip = snd_pcm_substream_chip(substream);
1273
unsigned int current_ptr;
1275
/* get the current hardware pointer */
1276
current_ptr = mychip_get_hw_pointer(chip);
1277
return current_ptr;
1278
}
1280
/* operators */
1281
static struct snd_pcm_ops snd_mychip_playback_ops = {
1282
.open = snd_mychip_playback_open,
1283
.close = snd_mychip_playback_close,
1284
.hw_params = snd_mychip_pcm_hw_params,
1285
.hw_free = snd_mychip_pcm_hw_free,
1286
.prepare = snd_mychip_pcm_prepare,
1287
.trigger = snd_mychip_pcm_trigger,
1288
.pointer = snd_mychip_pcm_pointer,
1289
};
1291
/* operators */
1292
static struct snd_pcm_ops snd_mychip_capture_ops = {
1293
.open = snd_mychip_capture_open,
1294
.close = snd_mychip_capture_close,
1295
.hw_params = snd_mychip_pcm_hw_params,
1296
.hw_free = snd_mychip_pcm_hw_free,
1297
.prepare = snd_mychip_pcm_prepare,
1298
.trigger = snd_mychip_pcm_trigger,
1299
.pointer = snd_mychip_pcm_pointer,
1300
};
1302
/*
1303
* definitions of capture are omitted here...
1304
*/
1306
/* create a pcm device */
1307
static int snd_mychip_new_pcm(struct mychip *chip)
1308
{
1309
struct snd_pcm *pcm;
1310
int err;
1312
err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1313
if (err < 0)
1314
return err;
1315
pcm->private_data = chip;
1316
strcpy(pcm->name, "My Chip");
1317
chip->pcm = pcm;
1318
/* set operators */
1319
snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1320
&snd_mychip_playback_ops);
1321
snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1322
&snd_mychip_capture_ops);
1323
/* pre-allocation of buffers */
1324
/* NOTE: this may fail */
1325
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
1326
&chip->pci->dev,
1327
64*1024, 64*1024);
1328
return 0;
1329
}
1332
PCM Constructor
1333
---------------
1335
A PCM instance is allocated by the :c:func:`snd_pcm_new()`
1336
function. It would be better to create a constructor for the PCM, namely::
1338
static int snd_mychip_new_pcm(struct mychip *chip)
1339
{
1340
struct snd_pcm *pcm;
1341
int err;
1343
err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1344
if (err < 0)
1345
return err;
1346
pcm->private_data = chip;
1347
strcpy(pcm->name, "My Chip");
1348
chip->pcm = pcm;
1349
...
1350
return 0;
1351
}
1353
The :c:func:`snd_pcm_new()` function takes six arguments. The
1354
first argument is the card pointer to which this PCM is assigned, and
1355
the second is the ID string.
1357
The third argument (``index``, 0 in the above) is the index of this new
1358
PCM. It begins from zero. If you create more than one PCM instances,
1359
specify the different numbers in this argument. For example, ``index =
1360
1`` for the second PCM device.
1362
The fourth and fifth arguments are the number of substreams for playback
1363
and capture, respectively. Here 1 is used for both arguments. When no
1364
playback or capture substreams are available, pass 0 to the
1365
corresponding argument.
1367
If a chip supports multiple playbacks or captures, you can specify more
1368
numbers, but they must be handled properly in open/close, etc.
1369
callbacks. When you need to know which substream you are referring to,
1370
then it can be obtained from struct snd_pcm_substream data passed to each
1371
callback as follows::
1373
struct snd_pcm_substream *substream;
1374
int index = substream->number;
1377
After the PCM is created, you need to set operators for each PCM stream::
1379
snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1380
&snd_mychip_playback_ops);
1381
snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1382
&snd_mychip_capture_ops);
1384
The operators are defined typically like this::
1386
static struct snd_pcm_ops snd_mychip_playback_ops = {
1387
.open = snd_mychip_pcm_open,
1388
.close = snd_mychip_pcm_close,
1389
.hw_params = snd_mychip_pcm_hw_params,
1390
.hw_free = snd_mychip_pcm_hw_free,
1391
.prepare = snd_mychip_pcm_prepare,
1392
.trigger = snd_mychip_pcm_trigger,
1393
.pointer = snd_mychip_pcm_pointer,
1394
};
1396
All the callbacks are described in the Operators_ subsection.
1398
After setting the operators, you probably will want to pre-allocate the
1399
buffer and set up the managed allocation mode.
1400
For that, simply call the following::
1402
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
1403
&chip->pci->dev,
1404
64*1024, 64*1024);
1406
It will allocate a buffer up to 64kB by default. Buffer management
1407
details will be described in the later section `Buffer and Memory
1408
Management`_.
1410
Additionally, you can set some extra information for this PCM in
1411
``pcm->info_flags``. The available values are defined as
1412
``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
1413
hardware definition (described later). When your soundchip supports only
1414
half-duplex, specify it like this::
1416
pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1419
... And the Destructor?
1420
-----------------------
1422
The destructor for a PCM instance is not always necessary. Since the PCM
1423
device will be released by the middle layer code automatically, you
1424
don't have to call the destructor explicitly.
1426
The destructor would be necessary if you created special records
1427
internally and needed to release them. In such a case, set the
1428
destructor function to ``pcm->private_free``::
1430
static void mychip_pcm_free(struct snd_pcm *pcm)
1431
{
1432
struct mychip *chip = snd_pcm_chip(pcm);
1433
/* free your own data */
1434
kfree(chip->my_private_pcm_data);
1435
/* do what you like else */
1436
....
1437
}
1439
static int snd_mychip_new_pcm(struct mychip *chip)
1440
{
1441
struct snd_pcm *pcm;
1442
....
1443
/* allocate your own data */
1444
chip->my_private_pcm_data = kmalloc(...);
1445
/* set the destructor */
1446
pcm->private_data = chip;
1447
pcm->private_free = mychip_pcm_free;
1448
....
1449
}
1453
Runtime Pointer - The Chest of PCM Information
1454
----------------------------------------------
1456
When the PCM substream is opened, a PCM runtime instance is allocated
1457
and assigned to the substream. This pointer is accessible via
1458
``substream->runtime``. This runtime pointer holds most information you
1459
need to control the PCM: a copy of hw_params and sw_params
1460
configurations, the buffer pointers, mmap records, spinlocks, etc.
1462
The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1463
is the relevant part of this file::
1465
struct _snd_pcm_runtime {
1466
/* -- Status -- */
1467
struct snd_pcm_substream *trigger_master;
1468
snd_timestamp_t trigger_tstamp; /* trigger timestamp */
1469
int overrange;
1470
snd_pcm_uframes_t avail_max;
1471
snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
1472
snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
1474
/* -- HW params -- */
1475
snd_pcm_access_t access; /* access mode */
1476
snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
1477
snd_pcm_subformat_t subformat; /* subformat */
1478
unsigned int rate; /* rate in Hz */
1479
unsigned int channels; /* channels */
1480
snd_pcm_uframes_t period_size; /* period size */
1481
unsigned int periods; /* periods */
1482
snd_pcm_uframes_t buffer_size; /* buffer size */
1483
unsigned int tick_time; /* tick time */
1484
snd_pcm_uframes_t min_align; /* Min alignment for the format */
1485
size_t byte_align;
1486
unsigned int frame_bits;
1487
unsigned int sample_bits;
1488
unsigned int info;
1489
unsigned int rate_num;
1490
unsigned int rate_den;
1492
/* -- SW params -- */
1493
struct timespec tstamp_mode; /* mmap timestamp is updated */
1494
unsigned int period_step;
1495
unsigned int sleep_min; /* min ticks to sleep */
1496
snd_pcm_uframes_t start_threshold;
1497
/*
1498
* The following two thresholds alleviate playback buffer underruns; when
1499
* hw_avail drops below the threshold, the respective action is triggered:
1500
*/
1501
snd_pcm_uframes_t stop_threshold; /* - stop playback */
1502
snd_pcm_uframes_t silence_threshold; /* - pre-fill buffer with silence */
1503
snd_pcm_uframes_t silence_size; /* max size of silence pre-fill; when >= boundary,
1504
* fill played area with silence immediately */
1505
snd_pcm_uframes_t boundary; /* pointers wrap point */
1507
/* internal data of auto-silencer */
1508
snd_pcm_uframes_t silence_start; /* starting pointer to silence area */
1509
snd_pcm_uframes_t silence_filled; /* size filled with silence */
1511
snd_pcm_sync_id_t sync; /* hardware synchronization ID */
1513
/* -- mmap -- */
1514
volatile struct snd_pcm_mmap_status *status;
1515
volatile struct snd_pcm_mmap_control *control;
1516
atomic_t mmap_count;
1518
/* -- locking / scheduling -- */
1519
spinlock_t lock;
1520
wait_queue_head_t sleep;
1521
struct timer_list tick_timer;
1522
struct fasync_struct *fasync;
1524
/* -- private section -- */
1525
void *private_data;
1526
void (*private_free)(struct snd_pcm_runtime *runtime);
1528
/* -- hardware description -- */
1529
struct snd_pcm_hardware hw;
1530
struct snd_pcm_hw_constraints hw_constraints;
1532
/* -- timer -- */
1533
unsigned int timer_resolution; /* timer resolution */
1535
/* -- DMA -- */
1536
unsigned char *dma_area; /* DMA area */
1537
dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
1538
size_t dma_bytes; /* size of DMA area */
1540
struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
1542
#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
1543
/* -- OSS things -- */
1544
struct snd_pcm_oss_runtime oss;
1545
#endif
1546
};
1549
For the operators (callbacks) of each sound driver, most of these
1550
records are supposed to be read-only. Only the PCM middle-layer changes
1551
/ updates them. The exceptions are the hardware description (hw) DMA
1552
buffer information and the private data. Besides, if you use the
1553
standard managed buffer allocation mode, you don't need to set the
1554
DMA buffer information by yourself.
1556
In the sections below, important records are explained.
1558
Hardware Description
1559
~~~~~~~~~~~~~~~~~~~~
1561
The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
1562
the fundamental hardware configuration. Above all, you'll need to define this
1563
in the `PCM open callback`_. Note that the runtime instance holds a copy of
1564
the descriptor, not a pointer to the existing descriptor. That is,
1565
in the open callback, you can modify the copied descriptor
1566
(``runtime->hw``) as you need. For example, if the maximum number of
1567
channels is 1 only on some chip models, you can still use the same
1568
hardware descriptor and change the channels_max later::
1570
struct snd_pcm_runtime *runtime = substream->runtime;
1571
...
1572
runtime->hw = snd_mychip_playback_hw; /* common definition */
1573
if (chip->model == VERY_OLD_ONE)
1574
runtime->hw.channels_max = 1;
1576
Typically, you'll have a hardware descriptor as below::
1578
static struct snd_pcm_hardware snd_mychip_playback_hw = {
1579
.info = (SNDRV_PCM_INFO_MMAP |
1580
SNDRV_PCM_INFO_INTERLEAVED |
1581
SNDRV_PCM_INFO_BLOCK_TRANSFER |
1582
SNDRV_PCM_INFO_MMAP_VALID),
1583
.formats = SNDRV_PCM_FMTBIT_S16_LE,
1584
.rates = SNDRV_PCM_RATE_8000_48000,
1585
.rate_min = 8000,
1586
.rate_max = 48000,
1587
.channels_min = 2,
1588
.channels_max = 2,
1589
.buffer_bytes_max = 32768,
1590
.period_bytes_min = 4096,
1591
.period_bytes_max = 32768,
1592
.periods_min = 1,
1593
.periods_max = 1024,
1594
};
1596
- The ``info`` field contains the type and capabilities of this
1597
PCM. The bit flags are defined in ``<sound/asound.h>`` as
1598
``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
1599
mmap is supported and which interleaving formats are
1600
supported. When the hardware supports mmap, add the
1601
``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
1602
interleaved or the non-interleaved formats, the
1603
``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
1604
flag must be set, respectively. If both are supported, you can set
1605
both, too.
1607
In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
1608
specified for the OSS mmap mode. Usually both are set. Of course,
1609
``MMAP_VALID`` is set only if mmap is really supported.
1611
The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
1612
``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the PCM
1613
supports the “pause” operation, while the ``RESUME`` bit means that
1614
the PCM supports the full “suspend/resume” operation. If the
1615
``PAUSE`` flag is set, the ``trigger`` callback below must handle
1616
the corresponding (pause push/release) commands. The suspend/resume
1617
trigger commands can be defined even without the ``RESUME``
1618
flag. See the `Power Management`_ section for details.
1620
When the PCM substreams can be synchronized (typically,
1621
synchronized start/stop of a playback and a capture stream), you
1622
can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
1623
need to check the linked-list of PCM substreams in the trigger
1624
callback. This will be described in a later section.
1626
- The ``formats`` field contains the bit-flags of supported formats
1627
(``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
1628
format, give all or'ed bits. In the example above, the signed 16bit
1629
little-endian format is specified.
1631
- The ``rates`` field contains the bit-flags of supported rates
1632
(``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
1633
pass the ``CONTINUOUS`` bit additionally. The pre-defined rate bits
1634
are provided only for typical rates. If your chip supports
1635
unconventional rates, you need to add the ``KNOT`` bit and set up
1636
the hardware constraint manually (explained later).
1638
- ``rate_min`` and ``rate_max`` define the minimum and maximum sample
1639
rate. This should correspond somehow to ``rates`` bits.
1641
- ``channels_min`` and ``channels_max`` define, as you might have already
1642
expected, the minimum and maximum number of channels.
1644
- ``buffer_bytes_max`` defines the maximum buffer size in
1645
bytes. There is no ``buffer_bytes_min`` field, since it can be
1646
calculated from the minimum period size and the minimum number of
1647
periods. Meanwhile, ``period_bytes_min`` and ``period_bytes_max``
1648
define the minimum and maximum size of the period in bytes.
1649
``periods_max`` and ``periods_min`` define the maximum and minimum
1650
number of periods in the buffer.
1652
The “period” is a term that corresponds to a fragment in the OSS
1653
world. The period defines the point at which a PCM interrupt is
1654
generated. This point strongly depends on the hardware. Generally,
1655
a smaller period size will give you more interrupts, which results
1656
in being able to fill/drain the buffer more timely. In the case of
1657
capture, this size defines the input latency. On the other hand,
1658
the whole buffer size defines the output latency for the playback
1659
direction.
1661
- There is also a field ``fifo_size``. This specifies the size of the
1662
hardware FIFO, but currently it is neither used by the drivers nor
1663
in the alsa-lib. So, you can ignore this field.
1665
PCM Configurations
1666
~~~~~~~~~~~~~~~~~~
1668
Ok, let's go back again to the PCM runtime records. The most
1669
frequently referred records in the runtime instance are the PCM
1670
configurations. The PCM configurations are stored in the runtime
1671
instance after the application sends ``hw_params`` data via
1672
alsa-lib. There are many fields copied from hw_params and sw_params
1673
structs. For example, ``format`` holds the format type chosen by the
1674
application. This field contains the enum value
1675
``SNDRV_PCM_FORMAT_XXX``.
1677
One thing to be noted is that the configured buffer and period sizes
1678
are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
1679
channels \* samples-size``. For conversion between frames and bytes,
1680
you can use the :c:func:`frames_to_bytes()` and
1681
:c:func:`bytes_to_frames()` helper functions::
1683
period_bytes = frames_to_bytes(runtime, runtime->period_size);
1685
Also, many software parameters (sw_params) are stored in frames, too.
1686
Please check the type of the field. ``snd_pcm_uframes_t`` is for
1687
frames as unsigned integer while ``snd_pcm_sframes_t`` is for
1688
frames as signed integer.
1690
DMA Buffer Information
1691
~~~~~~~~~~~~~~~~~~~~~~
1693
The DMA buffer is defined by the following four fields: ``dma_area``,
1694
``dma_addr``, ``dma_bytes`` and ``dma_private``. ``dma_area``
1695
holds the buffer pointer (the logical address). You can call
1696
:c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
1697
the physical address of the buffer. This field is specified only when
1698
the buffer is a linear buffer. ``dma_bytes`` holds the size of the
1699
buffer in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1701
If you use either the managed buffer allocation mode or the standard
1702
API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
1703
these fields are set by the ALSA middle layer, and you should *not*
1704
change them by yourself. You can read them but not write them. On the
1705
other hand, if you want to allocate the buffer by yourself, you'll
1706
need to manage it in the hw_params callback. At least, ``dma_bytes`` is
1707
mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
1708
your driver doesn't support mmap, this field is not
1709
necessary. ``dma_addr`` is also optional. You can use dma_private as
1710
you like, too.
1712
Running Status
1713
~~~~~~~~~~~~~~
1715
The running status can be referred via ``runtime->status``. This is
1716
a pointer to a struct snd_pcm_mmap_status record.
1717
For example, you can get the current
1718
DMA hardware pointer via ``runtime->status->hw_ptr``.
1720
The DMA application pointer can be referred via ``runtime->control``,
1721
which points to a struct snd_pcm_mmap_control record.
1722
However, accessing this value directly is not recommended.
1724
Private Data
1725
~~~~~~~~~~~~
1727
You can allocate a record for the substream and store it in
1728
``runtime->private_data``. Usually, this is done in the `PCM open
1729
callback`_. Don't mix this with ``pcm->private_data``. The
1730
``pcm->private_data`` usually points to the chip instance assigned
1731
statically at creation time of the PCM device, while
1732
``runtime->private_data``
1733
points to a dynamic data structure created in the PCM open
1734
callback::
1736
static int snd_xxx_open(struct snd_pcm_substream *substream)
1737
{
1738
struct my_pcm_data *data;
1739
....
1740
data = kmalloc(sizeof(*data), GFP_KERNEL);
1741
substream->runtime->private_data = data;
1742
....
1743
}
1746
The allocated object must be released in the `close callback`_.
1748
Operators
1749
---------
1751
OK, now let me give details about each PCM callback (``ops``). In
1752
general, every callback must return 0 if successful, or a negative
1753
error number such as ``-EINVAL``. To choose an appropriate error
1754
number, it is advised to check what value other parts of the kernel
1755
return when the same kind of request fails.
1757
Each callback function takes at least one argument containing a
1758
struct snd_pcm_substream pointer. To retrieve the chip
1759
record from the given substream instance, you can use the following
1760
macro::
1762
int xxx(...) {
1763
struct mychip *chip = snd_pcm_substream_chip(substream);
1764
....
1765
}
1767
The macro reads ``substream->private_data``, which is a copy of
1768
``pcm->private_data``. You can override the former if you need to
1769
assign different data records per PCM substream. For example, the
1770
cmi8330 driver assigns different ``private_data`` for playback and
1771
capture directions, because it uses two different codecs (SB- and
1772
AD-compatible) for different directions.
1774
PCM open callback
1775
~~~~~~~~~~~~~~~~~
1777
::
1779
static int snd_xxx_open(struct snd_pcm_substream *substream);
1781
This is called when a PCM substream is opened.
1783
At least, here you have to initialize the ``runtime->hw``
1784
record. Typically, this is done like this::
1786
static int snd_xxx_open(struct snd_pcm_substream *substream)
1787
{
1788
struct mychip *chip = snd_pcm_substream_chip(substream);
1789
struct snd_pcm_runtime *runtime = substream->runtime;
1791
runtime->hw = snd_mychip_playback_hw;
1792
return 0;
1793
}
1795
where ``snd_mychip_playback_hw`` is the pre-defined hardware
1796
description.
1798
You can allocate private data in this callback, as described in the
1799
`Private Data`_ section.
1801
If the hardware configuration needs more constraints, set the hardware
1802
constraints here, too. See Constraints_ for more details.
1804
close callback
1805
~~~~~~~~~~~~~~
1807
::
1809
static int snd_xxx_close(struct snd_pcm_substream *substream);
1812
Obviously, this is called when a PCM substream is closed.
1814
Any private instance for a PCM substream allocated in the ``open``
1815
callback will be released here::
1817
static int snd_xxx_close(struct snd_pcm_substream *substream)
1818
{
1819
....
1820
kfree(substream->runtime->private_data);
1821
....
1822
}
1824
ioctl callback
1825
~~~~~~~~~~~~~~
1827
This is used for any special call to PCM ioctls. But usually you can
1828
leave it NULL, then the PCM core calls the generic ioctl callback
1829
function :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with a
1830
unique setup of channel info or reset procedure, you can pass your own
1831
callback function here.
1833
hw_params callback
1834
~~~~~~~~~~~~~~~~~~~
1836
::
1838
static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
1839
struct snd_pcm_hw_params *hw_params);
1841
This is called when the hardware parameters (``hw_params``) are set up
1842
by the application, that is, once when the buffer size, the period
1843
size, the format, etc. are defined for the PCM substream.
1845
Many hardware setups should be done in this callback, including the
1846
allocation of buffers.
1848
Parameters to be initialized are retrieved by the
1849
:c:func:`params_xxx()` macros.
1851
When you choose managed buffer allocation mode for the substream,
1852
a buffer is already allocated before this callback gets
1853
called. Alternatively, you can call a helper function below for
1854
allocating the buffer::
1856
snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
1858
:c:func:`snd_pcm_lib_malloc_pages()` is available only when the
1859
DMA buffers have been pre-allocated. See the section `Buffer Types`_
1860
for more details.
1862
Note that this one and the ``prepare`` callback may be called multiple
1863
times per initialization. For example, the OSS emulation may call these
1864
callbacks at each change via its ioctl.
1866
Thus, you need to be careful not to allocate the same buffers many
1867
times, which will lead to memory leaks! Calling the helper function
1868
above many times is OK. It will release the previous buffer
1869
automatically when it was already allocated.
1871
Another note is that this callback is non-atomic (schedulable) by
1872
default, i.e. when no ``nonatomic`` flag set. This is important,
1873
because the ``trigger`` callback is atomic (non-schedulable). That is,
1874
mutexes or any schedule-related functions are not available in the
1875
``trigger`` callback. Please see the subsection Atomicity_ for
1876
details.
1878
hw_free callback
1879
~~~~~~~~~~~~~~~~~
1881
::
1883
static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
1885
This is called to release the resources allocated via
1886
``hw_params``.
1888
This function is always called before the close callback is called.
1889
Also, the callback may be called multiple times, too. Keep track
1890
whether each resource was already released.
1892
When you have chosen managed buffer allocation mode for the PCM
1893
substream, the allocated PCM buffer will be automatically released
1894
after this callback gets called. Otherwise you'll have to release the
1895
buffer manually. Typically, when the buffer was allocated from the
1896
pre-allocated pool, you can use the standard API function
1897
:c:func:`snd_pcm_lib_malloc_pages()` like::
1899
snd_pcm_lib_free_pages(substream);
1901
prepare callback
1902
~~~~~~~~~~~~~~~~
1904
::
1906
static int snd_xxx_prepare(struct snd_pcm_substream *substream);
1908
This callback is called when the PCM is “prepared”. You can set the
1909
format type, sample rate, etc. here. The difference from ``hw_params``
1910
is that the ``prepare`` callback will be called each time
1911
:c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
1912
underruns, etc.
1914
Note that this callback is non-atomic. You can use
1915
schedule-related functions safely in this callback.
1917
In this and the following callbacks, you can refer to the values via
1918
the runtime record, ``substream->runtime``. For example, to get the
1919
current rate, format or channels, access to ``runtime->rate``,
1920
``runtime->format`` or ``runtime->channels``, respectively. The
1921
physical address of the allocated buffer is set to
1922
``runtime->dma_area``. The buffer and period sizes are in
1923
``runtime->buffer_size`` and ``runtime->period_size``, respectively.
1925
Be careful that this callback will be called many times at each setup,
1926
too.
1928
trigger callback
1929
~~~~~~~~~~~~~~~~
1931
::
1933
static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
1935
This is called when the PCM is started, stopped or paused.
1937
The action is specified in the second argument, ``SNDRV_PCM_TRIGGER_XXX``
1938
defined in ``<sound/pcm.h>``. At least, the ``START``
1939
and ``STOP`` commands must be defined in this callback::
1941
switch (cmd) {
1942
case SNDRV_PCM_TRIGGER_START:
1943
/* do something to start the PCM engine */
1944
break;
1945
case SNDRV_PCM_TRIGGER_STOP:
1946
/* do something to stop the PCM engine */
1947
break;
1948
default:
1949
return -EINVAL;
1950
}
1952
When the PCM supports the pause operation (given in the info field of
1953
the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
1954
must be handled here, too. The former is the command to pause the PCM,
1955
and the latter to restart the PCM again.
1957
When the PCM supports the suspend/resume operation, regardless of full
1958
or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
1959
commands must be handled, too. These commands are issued when the
1960
power-management status is changed. Obviously, the ``SUSPEND`` and
1961
``RESUME`` commands suspend and resume the PCM substream, and usually,
1962
they are identical to the ``STOP`` and ``START`` commands, respectively.
1963
See the `Power Management`_ section for details.
1965
As mentioned, this callback is atomic by default unless the ``nonatomic``
1966
flag set, and you cannot call functions which may sleep. The
1967
``trigger`` callback should be as minimal as possible, just really
1968
triggering the DMA. The other stuff should be initialized in
1969
``hw_params`` and ``prepare`` callbacks properly beforehand.
1971
sync_stop callback
1972
~~~~~~~~~~~~~~~~~~
1974
::
1976
static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);
1978
This callback is optional, and NULL can be passed. It's called after
1979
the PCM core stops the stream, before it changes the stream state via
1980
``prepare``, ``hw_params`` or ``hw_free``.
1981
Since the IRQ handler might be still pending, we need to wait until
1982
the pending task finishes before moving to the next step; otherwise it
1983
might lead to a crash due to resource conflicts or access to freed
1984
resources. A typical behavior is to call a synchronization function
1985
like :c:func:`synchronize_irq()` here.
1987
For the majority of drivers that need only a call of
1988
:c:func:`synchronize_irq()`, there is a simpler setup, too.
1989
While keeping the ``sync_stop`` PCM callback NULL, the driver can set
1990
the ``card->sync_irq`` field to the returned interrupt number after
1991
requesting an IRQ, instead. Then PCM core will call
1992
:c:func:`synchronize_irq()` with the given IRQ appropriately.
1994
If the IRQ handler is released by the card destructor, you don't need
1995
to clear ``card->sync_irq``, as the card itself is being released.
1996
So, usually you'll need to add just a single line for assigning
1997
``card->sync_irq`` in the driver code unless the driver re-acquires
1998
the IRQ. When the driver frees and re-acquires the IRQ dynamically
1999
(e.g. for suspend/resume), it needs to clear and re-set
2000
``card->sync_irq`` again appropriately.
2002
pointer callback
2003
~~~~~~~~~~~~~~~~
2005
::
2007
static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2009
This callback is called when the PCM middle layer inquires the current
2010
hardware position in the buffer. The position must be returned in
2011
frames, ranging from 0 to ``buffer_size - 1``.
2013
This is usually called from the buffer-update routine in the PCM
2014
middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
2015
is called by the interrupt routine. Then the PCM middle layer updates
2016
the position and calculates the available space, and wakes up the
2017
sleeping poll threads, etc.
2019
This callback is also atomic by default.
2021
copy and fill_silence ops
2022
~~~~~~~~~~~~~~~~~~~~~~~~~
2024
These callbacks are not mandatory, and can be omitted in most cases.
2025
These callbacks are used when the hardware buffer cannot be in the
2026
normal memory space. Some chips have their own buffer in the hardware
2027
which is not mappable. In such a case, you have to transfer the data
2028
manually from the memory buffer to the hardware buffer. Or, if the
2029
buffer is non-contiguous on both physical and virtual memory spaces,
2030
these callbacks must be defined, too.
2032
If these two callbacks are defined, copy and set-silence operations
2033
are done by them. The details will be described in the later section
2034
`Buffer and Memory Management`_.
2036
ack callback
2037
~~~~~~~~~~~~
2039
This callback is also not mandatory. This callback is called when the
2040
``appl_ptr`` is updated in read or write operations. Some drivers like
2041
emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
2042
internal buffer, and this callback is useful only for such a purpose.
2044
The callback function may return 0 or a negative error. When the
2045
return value is ``-EPIPE``, PCM core treats that as a buffer XRUN,
2046
and changes the state to ``SNDRV_PCM_STATE_XRUN`` automatically.
2048
This callback is atomic by default.
2050
page callback
2051
~~~~~~~~~~~~~
2053
This callback is optional too. The mmap calls this callback to get the
2054
page fault address.
2056
You need no special callback for the standard SG-buffer or vmalloc-
2057
buffer. Hence this callback should be rarely used.
2059
mmap callback
2060
~~~~~~~~~~~~~
2062
This is another optional callback for controlling mmap behavior.
2063
When defined, the PCM core calls this callback when a page is
2064
memory-mapped, instead of using the standard helper.
2065
If you need special handling (due to some architecture or
2066
device-specific issues), implement everything here as you like.
2069
PCM Interrupt Handler
2070
---------------------
2072
The remainder of the PCM stuff is the PCM interrupt handler. The role
2073
of the PCM
2074
interrupt handler in the sound driver is to update the buffer position
2075
and to tell the PCM middle layer when the buffer position goes across
2076
the specified period boundary. To inform about this, call the
2077
:c:func:`snd_pcm_period_elapsed()` function.
2079
There are several ways sound chips can generate interrupts.
2081
Interrupts at the period (fragment) boundary
2082
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2084
This is the most frequently found type: the hardware generates an
2085
interrupt at each period boundary. In this case, you can call
2086
:c:func:`snd_pcm_period_elapsed()` at each interrupt.
2088
:c:func:`snd_pcm_period_elapsed()` takes the substream pointer as
2089
its argument. Thus, you need to keep the substream pointer accessible
2090
from the chip instance. For example, define ``substream`` field in the
2091
chip record to hold the current running substream pointer, and set the
2092
pointer value at ``open`` callback (and reset at ``close`` callback).
2094
If you acquire a spinlock in the interrupt handler, and the lock is used
2095
in other PCM callbacks, too, then you have to release the lock before
2096
calling :c:func:`snd_pcm_period_elapsed()`, because
2097
:c:func:`snd_pcm_period_elapsed()` calls other PCM callbacks
2098
inside.
2100
Typical code would look like::
2103
static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2104
{
2105
struct mychip *chip = dev_id;
2106
spin_lock(&chip->lock);
2107
....
2108
if (pcm_irq_invoked(chip)) {
2109
/* call updater, unlock before it */
2110
spin_unlock(&chip->lock);
2111
snd_pcm_period_elapsed(chip->substream);
2112
spin_lock(&chip->lock);
2113
/* acknowledge the interrupt if necessary */
2114
}
2115
....
2116
spin_unlock(&chip->lock);
2117
return IRQ_HANDLED;
2118
}
2120
Also, when the device can detect a buffer underrun/overrun, the driver
2121
can notify the XRUN status to the PCM core by calling
2122
:c:func:`snd_pcm_stop_xrun()`. This function stops the stream and sets
2123
the PCM state to ``SNDRV_PCM_STATE_XRUN``. Note that it must be called
2124
outside the PCM stream lock, hence it can't be called from the atomic
2125
callback.
2128
High frequency timer interrupts
2129
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2131
This happens when the hardware doesn't generate interrupts at the period
2132
boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
2133
or ymfpci drivers). In this case, you need to check the current hardware
2134
position and accumulate the processed sample length at each interrupt.
2135
When the accumulated size exceeds the period size, call
2136
:c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
2138
Typical code would look as follows::
2141
static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2142
{
2143
struct mychip *chip = dev_id;
2144
spin_lock(&chip->lock);
2145
....
2146
if (pcm_irq_invoked(chip)) {
2147
unsigned int last_ptr, size;
2148
/* get the current hardware pointer (in frames) */
2149
last_ptr = get_hw_ptr(chip);
2150
/* calculate the processed frames since the
2151
* last update
2152
*/
2153
if (last_ptr < chip->last_ptr)
2154
size = runtime->buffer_size + last_ptr
2155
- chip->last_ptr;
2156
else
2157
size = last_ptr - chip->last_ptr;
2158
/* remember the last updated point */
2159
chip->last_ptr = last_ptr;
2160
/* accumulate the size */
2161
chip->size += size;
2162
/* over the period boundary? */
2163
if (chip->size >= runtime->period_size) {
2164
/* reset the accumulator */
2165
chip->size %= runtime->period_size;
2166
/* call updater */
2167
spin_unlock(&chip->lock);
2168
snd_pcm_period_elapsed(substream);
2169
spin_lock(&chip->lock);
2170
}
2171
/* acknowledge the interrupt if necessary */
2172
}
2173
....
2174
spin_unlock(&chip->lock);
2175
return IRQ_HANDLED;
2176
}
2180
On calling :c:func:`snd_pcm_period_elapsed()`
2181
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2183
In both cases, even if more than one period has elapsed, you don't have
2184
to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
2185
once. And the PCM layer will check the current hardware pointer and
2186
update to the latest status.
2188
Atomicity
2189
---------
2191
One of the most important (and thus difficult to debug) problems in
2192
kernel programming are race conditions. In the Linux kernel, they are
2193
usually avoided via spin-locks, mutexes or semaphores. In general, if a
2194
race condition can happen in an interrupt handler, it has to be managed
2195
atomically, and you have to use a spinlock to protect the critical
2196
section. If the critical section is not in interrupt handler code and if
2197
taking a relatively long time to execute is acceptable, you should use
2198
mutexes or semaphores instead.
2200
As already seen, some PCM callbacks are atomic and some are not. For
2201
example, the ``hw_params`` callback is non-atomic, while the ``trigger``
2202
callback is atomic. This means, the latter is called already in a
2203
spinlock held by the PCM middle layer, the PCM stream lock. Please
2204
take this atomicity into account when you choose a locking scheme in
2205
the callbacks.
2207
In the atomic callbacks, you cannot use functions which may call
2208
:c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
2209
mutexes can sleep, and hence they cannot be used inside the atomic
2210
callbacks (e.g. ``trigger`` callback). To implement some delay in such a
2211
callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
2213
All three atomic callbacks (trigger, pointer, and ack) are called with
2214
local interrupts disabled.
2216
However, it is possible to request all PCM operations to be non-atomic.
2217
This assumes that all call sites are in
2218
non-atomic contexts. For example, the function
2219
:c:func:`snd_pcm_period_elapsed()` is called typically from the
2220
interrupt handler. But, if you set up the driver to use a threaded
2221
interrupt handler, this call can be in non-atomic context, too. In such
2222
a case, you can set the ``nonatomic`` field of the struct snd_pcm object
2223
after creating it. When this flag is set, mutex and rwsem are used internally
2224
in the PCM core instead of spin and rwlocks, so that you can call all PCM
2225
functions safely in a non-atomic
2226
context.
2228
Also, in some cases, you might need to call
2229
:c:func:`snd_pcm_period_elapsed()` in the atomic context (e.g. the
2230
period gets elapsed during ``ack`` or other callback). There is a
2231
variant that can be called inside the PCM stream lock
2232
:c:func:`snd_pcm_period_elapsed_under_stream_lock()` for that purpose,
2233
too.
2235
Constraints
2236
-----------
2238
Due to physical limitations, hardware is not infinitely configurable.
2239
These limitations are expressed by setting constraints.
2241
For example, in order to restrict the sample rates to some supported
2242
values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
2243
call this function in the open callback::
2245
static unsigned int rates[] =
2246
{4000, 10000, 22050, 44100};
2247
static struct snd_pcm_hw_constraint_list constraints_rates = {
2248
.count = ARRAY_SIZE(rates),
2249
.list = rates,
2250
.mask = 0,
2251
};
2253
static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
2254
{
2255
int err;
2256
....
2257
err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2258
SNDRV_PCM_HW_PARAM_RATE,
2259
&constraints_rates);
2260
if (err < 0)
2261
return err;
2262
....
2263
}
2265
There are many different constraints. Look at ``sound/pcm.h`` for a
2266
complete list. You can even define your own constraint rules. For
2267
example, let's suppose my_chip can manage a substream of 1 channel if
2268
and only if the format is ``S16_LE``, otherwise it supports any format
2269
specified in struct snd_pcm_hardware (or in any other
2270
constraint_list). You can build a rule like this::
2272
static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
2273
struct snd_pcm_hw_rule *rule)
2274
{
2275
struct snd_interval *c = hw_param_interval(params,
2276
SNDRV_PCM_HW_PARAM_CHANNELS);
2277
struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2278
struct snd_interval ch;
2280
snd_interval_any(&ch);
2281
if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
2282
ch.min = ch.max = 1;
2283
ch.integer = 1;
2284
return snd_interval_refine(c, &ch);
2285
}
2286
return 0;
2287
}
2290
Then you need to call this function to add your rule::
2292
snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
2293
hw_rule_channels_by_format, NULL,
2294
SNDRV_PCM_HW_PARAM_FORMAT, -1);
2296
The rule function is called when an application sets the PCM format, and
2297
it refines the number of channels accordingly. But an application may
2298
set the number of channels before setting the format. Thus you also need
2299
to define the inverse rule::
2301
static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
2302
struct snd_pcm_hw_rule *rule)
2303
{
2304
struct snd_interval *c = hw_param_interval(params,
2305
SNDRV_PCM_HW_PARAM_CHANNELS);
2306
struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2307
struct snd_mask fmt;
2309
snd_mask_any(&fmt); /* Init the struct */
2310
if (c->min < 2) {
2311
fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
2312
return snd_mask_refine(f, &fmt);
2313
}
2314
return 0;
2315
}
2318
... and in the open callback::
2320
snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2321
hw_rule_format_by_channels, NULL,
2322
SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2324
One typical usage of the hw constraints is to align the buffer size
2325
with the period size. By default, ALSA PCM core doesn't enforce the
2326
buffer size to be aligned with the period size. For example, it'd be
2327
possible to have a combination like 256 period bytes with 999 buffer
2328
bytes.
2330
Many device chips, however, require the buffer to be a multiple of
2331
periods. In such a case, call
2332
:c:func:`snd_pcm_hw_constraint_integer()` for
2333
``SNDRV_PCM_HW_PARAM_PERIODS``::
2335
snd_pcm_hw_constraint_integer(substream->runtime,
2336
SNDRV_PCM_HW_PARAM_PERIODS);
2338
This assures that the number of periods is integer, hence the buffer
2339
size is aligned with the period size.
2341
The hw constraint is a very powerful mechanism to define the
2342
preferred PCM configuration, and there are relevant helpers.
2343
I won't give more details here, rather I would like to say, “Luke, use
2344
the source.”
2346
Control Interface
2347
=================
2349
General
2350
-------
2352
The control interface is used widely for many switches, sliders, etc.
2353
which are accessed from user-space. Its most important use is the mixer
2354
interface. In other words, since ALSA 0.9.x, all the mixer stuff is
2355
implemented on the control kernel API.
2357
ALSA has a well-defined AC97 control module. If your chip supports only
2358
the AC97 and nothing else, you can skip this section.
2360
The control API is defined in ``<sound/control.h>``. Include this file
2361
if you want to add your own controls.
2363
Definition of Controls
2364
----------------------
2366
To create a new control, you need to define the following three
2367
callbacks: ``info``, ``get`` and ``put``. Then, define a
2368
struct snd_kcontrol_new record, such as::
2371
static struct snd_kcontrol_new my_control = {
2372
.iface = SNDRV_CTL_ELEM_IFACE_MIXER,
2373
.name = "PCM Playback Switch",
2374
.index = 0,
2375
.access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
2376
.private_value = 0xffff,
2377
.info = my_control_info,
2378
.get = my_control_get,
2379
.put = my_control_put
2380
};
2383
The ``iface`` field specifies the control type,
2384
``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
2385
for global controls that are not logically part of the mixer. If the
2386
control is closely associated with some specific device on the sound
2387
card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
2388
and specify the device number with the ``device`` and ``subdevice``
2389
fields.
2391
The ``name`` is the name identifier string. Since ALSA 0.9.x, the
2392
control name is very important, because its role is classified from
2393
its name. There are pre-defined standard control names. The details
2394
are described in the `Control Names`_ subsection.
2396
The ``index`` field holds the index number of this control. If there
2397
are several different controls with the same name, they can be
2398
distinguished by the index number. This is the case when several
2399
codecs exist on the card. If the index is zero, you can omit the
2400
definition above.
2402
The ``access`` field contains the access type of this control. Give
2403
the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
2404
there. The details will be explained in the `Access Flags`_
2405
subsection.
2407
The ``private_value`` field contains an arbitrary long integer value
2408
for this record. When using the generic ``info``, ``get`` and ``put``
2409
callbacks, you can pass a value through this field. If several small
2410
numbers are necessary, you can combine them in bitwise. Or, it's
2411
possible to store a pointer (casted to unsigned long) of some record in
2412
this field, too.
2414
The ``tlv`` field can be used to provide metadata about the control;
2415
see the `Metadata`_ subsection.
2417
The other three are `Control Callbacks`_.
2419
Control Names
2420
-------------
2422
There are some standards to define the control names. A control is
2423
usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
2425
The first, ``SOURCE``, specifies the source of the control, and is a
2426
string such as “Master”, “PCM”, “CD” and “Line”. There are many
2427
pre-defined sources.
2429
The second, ``DIRECTION``, is one of the following strings according to
2430
the direction of the control: “Playback”, “Capture”, “Bypass Playback”
2431
and “Bypass Capture”. Or, it can be omitted, meaning both playback and
2432
capture directions.
2434
The third, ``FUNCTION``, is one of the following strings according to
2435
the function of the control: “Switch”, “Volume” and “Route”.
2437
The example of control names are, thus, “Master Capture Switch” or “PCM
2438
Playback Volume”.
2440
There are some exceptions:
2442
Global capture and playback
2443
~~~~~~~~~~~~~~~~~~~~~~~~~~~
2445
“Capture Source”, “Capture Switch” and “Capture Volume” are used for the
2446
global capture (input) source, switch and volume. Similarly, “Playback
2447
Switch” and “Playback Volume” are used for the global output gain switch
2448
and volume.
2450
Tone-controls
2451
~~~~~~~~~~~~~
2453
tone-control switch and volumes are specified like “Tone Control - XXX”,
2454
e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2455
Center”.
2457
3D controls
2458
~~~~~~~~~~~
2460
3D-control switches and volumes are specified like “3D Control - XXX”,
2461
e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2463
Mic boost
2464
~~~~~~~~~
2466
Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2468
More precise information can be found in
2469
``Documentation/sound/designs/control-names.rst``.
2471
Access Flags
2472
------------
2474
The access flag is the bitmask which specifies the access type of the
2475
given control. The default access type is
2476
``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
2477
allowed to this control. When the access flag is omitted (i.e. = 0), it
2478
is considered as ``READWRITE`` access by default.
2480
When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2481
instead. In this case, you don't have to define the ``put`` callback.
2482
Similarly, when the control is write-only (although it's a rare case),
2483
you can use the ``WRITE`` flag instead, and you don't need the ``get``
2484
callback.
2486
If the control value changes frequently (e.g. the VU meter),
2487
``VOLATILE`` flag should be given. This means that the control may be
2488
changed without `Change notification`_. Applications should poll such
2489
a control constantly.
2491
When the control may be updated, but currently has no effect on anything,
2492
setting the ``INACTIVE`` flag may be appropriate. For example, PCM
2493
controls should be inactive while no PCM device is open.
2495
There are ``LOCK`` and ``OWNER`` flags to change the write permissions.
2497
Control Callbacks
2498
-----------------
2500
info callback
2501
~~~~~~~~~~~~~
2503
The ``info`` callback is used to get detailed information on this
2504
control. This must store the values of the given
2505
struct snd_ctl_elem_info object. For example,
2506
for a boolean control with a single element::
2509
static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
2510
struct snd_ctl_elem_info *uinfo)
2511
{
2512
uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2513
uinfo->count = 1;
2514
uinfo->value.integer.min = 0;
2515
uinfo->value.integer.max = 1;
2516
return 0;
2517
}
2521
The ``type`` field specifies the type of the control. There are
2522
``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
2523
``INTEGER64``. The ``count`` field specifies the number of elements in
2524
this control. For example, a stereo volume would have count = 2. The
2525
``value`` field is a union, and the values stored depend on the
2526
type. The boolean and integer types are identical.
2528
The enumerated type is a bit different from the others. You'll need to
2529
set the string for the selectec item index::
2531
static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2532
struct snd_ctl_elem_info *uinfo)
2533
{
2534
static char *texts[4] = {
2535
"First", "Second", "Third", "Fourth"
2536
};
2537
uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
2538
uinfo->count = 1;
2539
uinfo->value.enumerated.items = 4;
2540
if (uinfo->value.enumerated.item > 3)
2541
uinfo->value.enumerated.item = 3;
2542
strcpy(uinfo->value.enumerated.name,
2543
texts[uinfo->value.enumerated.item]);
2544
return 0;
2545
}
2547
The above callback can be simplified with a helper function,
2548
:c:func:`snd_ctl_enum_info()`. The final code looks like below.
2549
(You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
2550
it's a matter of taste.)
2552
::
2554
static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2555
struct snd_ctl_elem_info *uinfo)
2556
{
2557
static char *texts[4] = {
2558
"First", "Second", "Third", "Fourth"
2559
};
2560
return snd_ctl_enum_info(uinfo, 1, 4, texts);
2561
}
2564
Some common info callbacks are available for your convenience:
2565
:c:func:`snd_ctl_boolean_mono_info()` and
2566
:c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former
2567
is an info callback for a mono channel boolean item, just like
2568
:c:func:`snd_myctl_mono_info()` above, and the latter is for a
2569
stereo channel boolean item.
2571
get callback
2572
~~~~~~~~~~~~
2574
This callback is used to read the current value of the control, so it
2575
can be returned to user-space.
2577
For example::
2579
static int snd_myctl_get(struct snd_kcontrol *kcontrol,
2580
struct snd_ctl_elem_value *ucontrol)
2581
{
2582
struct mychip *chip = snd_kcontrol_chip(kcontrol);
2583
ucontrol->value.integer.value[0] = get_some_value(chip);
2584
return 0;
2585
}
2589
The ``value`` field depends on the type of control as well as on the
2590
info callback. For example, the sb driver uses this field to store the
2591
register offset, the bit-shift and the bit-mask. The ``private_value``
2592
field is set as follows::
2594
.private_value = reg | (shift << 16) | (mask << 24)
2596
and is retrieved in callbacks like::
2598
static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
2599
struct snd_ctl_elem_value *ucontrol)
2600
{
2601
int reg = kcontrol->private_value & 0xff;
2602
int shift = (kcontrol->private_value >> 16) & 0xff;
2603
int mask = (kcontrol->private_value >> 24) & 0xff;
2604
....
2605
}
2607
In the ``get`` callback, you have to fill all the elements if the
2608
control has more than one element, i.e. ``count > 1``. In the example
2609
above, we filled only one element (``value.integer.value[0]``) since
2610
``count = 1`` is assumed.
2612
put callback
2613
~~~~~~~~~~~~
2615
This callback is used to write a value coming from user-space.
2617
For example::
2619
static int snd_myctl_put(struct snd_kcontrol *kcontrol,
2620
struct snd_ctl_elem_value *ucontrol)
2621
{
2622
struct mychip *chip = snd_kcontrol_chip(kcontrol);
2623
int changed = 0;
2624
if (chip->current_value !=
2625
ucontrol->value.integer.value[0]) {
2626
change_current_value(chip,
2627
ucontrol->value.integer.value[0]);
2628
changed = 1;
2629
}
2630
return changed;
2631
}
2635
As seen above, you have to return 1 if the value is changed. If the
2636
value is not changed, return 0 instead. If any fatal error happens,
2637
return a negative error code as usual.
2639
As in the ``get`` callback, when the control has more than one
2640
element, all elements must be evaluated in this callback, too.
2642
Callbacks are not atomic
2643
~~~~~~~~~~~~~~~~~~~~~~~~
2645
All these three callbacks are not-atomic.
2647
Control Constructor
2648
-------------------
2650
When everything is ready, finally we can create a new control. To create
2651
a control, there are two functions to be called,
2652
:c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
2654
In the simplest way, you can do it like this::
2656
err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
2657
if (err < 0)
2658
return err;
2660
where ``my_control`` is the struct snd_kcontrol_new object defined above,
2661
and chip is the object pointer to be passed to kcontrol->private_data which
2662
can be referred to in callbacks.
2664
:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and
2665
:c:func:`snd_ctl_add()` assigns the given control component to the
2666
card.
2668
Change Notification
2669
-------------------
2671
If you need to change and update a control in the interrupt routine, you
2672
can call :c:func:`snd_ctl_notify()`. For example::
2674
snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
2676
This function takes the card pointer, the event-mask, and the control id
2677
pointer for the notification. The event-mask specifies the types of
2678
notification, for example, in the above example, the change of control
2679
values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
2680
to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
2681
for hardware volume interrupts.
2683
Metadata
2684
--------
2686
To provide information about the dB values of a mixer control, use one of
2687
the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
2688
variable containing this information, set the ``tlv.p`` field to point to
2689
this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
2690
in the ``access`` field; like this::
2692
static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2694
static struct snd_kcontrol_new my_control = {
2695
...
2696
.access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
2697
SNDRV_CTL_ELEM_ACCESS_TLV_READ,
2698
...
2699
.tlv.p = db_scale_my_control,
2700
};
2703
The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
2704
about a mixer control where each step in the control's value changes the
2705
dB value by a constant dB amount. The first parameter is the name of the
2706
variable to be defined. The second parameter is the minimum value, in
2707
units of 0.01 dB. The third parameter is the step size, in units of 0.01
2708
dB. Set the fourth parameter to 1 if the minimum value actually mutes
2709
the control.
2711
The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
2712
about a mixer control where the control's value affects the output
2713
linearly. The first parameter is the name of the variable to be defined.
2714
The second parameter is the minimum value, in units of 0.01 dB. The
2715
third parameter is the maximum value, in units of 0.01 dB. If the
2716
minimum value mutes the control, set the second parameter to
2717
``TLV_DB_GAIN_MUTE``.
2719
API for AC97 Codec
2720
==================
2722
General
2723
-------
2725
The ALSA AC97 codec layer is a well-defined one, and you don't have to
2726
write much code to control it. Only low-level control routines are
2727
necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2729
Full Code Example
2730
-----------------
2732
::
2734
struct mychip {
2735
....
2736
struct snd_ac97 *ac97;
2737
....
2738
};
2740
static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2741
unsigned short reg)
2742
{
2743
struct mychip *chip = ac97->private_data;
2744
....
2745
/* read a register value here from the codec */
2746
return the_register_value;
2747
}
2749
static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2750
unsigned short reg, unsigned short val)
2751
{
2752
struct mychip *chip = ac97->private_data;
2753
....
2754
/* write the given register value to the codec */
2755
}
2757
static int snd_mychip_ac97(struct mychip *chip)
2758
{
2759
struct snd_ac97_bus *bus;
2760
struct snd_ac97_template ac97;
2761
int err;
2762
static struct snd_ac97_bus_ops ops = {
2763
.write = snd_mychip_ac97_write,
2764
.read = snd_mychip_ac97_read,
2765
};
2767
err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
2768
if (err < 0)
2769
return err;
2770
memset(&ac97, 0, sizeof(ac97));
2771
ac97.private_data = chip;
2772
return snd_ac97_mixer(bus, &ac97, &chip->ac97);
2773
}
2776
AC97 Constructor
2777
----------------
2779
To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
2780
with an ``ac97_bus_ops_t`` record with callback functions::
2782
struct snd_ac97_bus *bus;
2783
static struct snd_ac97_bus_ops ops = {
2784
.write = snd_mychip_ac97_write,
2785
.read = snd_mychip_ac97_read,
2786
};
2788
snd_ac97_bus(card, 0, &ops, NULL, &pbus);
2790
The bus record is shared among all belonging ac97 instances.
2792
And then call :c:func:`snd_ac97_mixer()` with a struct snd_ac97_template
2793
record together with the bus pointer created above::
2795
struct snd_ac97_template ac97;
2796
int err;
2798
memset(&ac97, 0, sizeof(ac97));
2799
ac97.private_data = chip;
2800
snd_ac97_mixer(bus, &ac97, &chip->ac97);
2802
where chip->ac97 is a pointer to a newly created ``ac97_t``
2803
instance. In this case, the chip pointer is set as the private data,
2804
so that the read/write callback functions can refer to this chip
2805
instance. This instance is not necessarily stored in the chip
2806
record. If you need to change the register values from the driver, or
2807
need the suspend/resume of ac97 codecs, keep this pointer to pass to
2808
the corresponding functions.
2810
AC97 Callbacks
2811
--------------
2813
The standard callbacks are ``read`` and ``write``. Obviously they
2814
correspond to the functions for read and write accesses to the
2815
hardware low-level codes.
2817
The ``read`` callback returns the register value specified in the
2818
argument::
2820
static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2821
unsigned short reg)
2822
{
2823
struct mychip *chip = ac97->private_data;
2824
....
2825
return the_register_value;
2826
}
2828
Here, the chip can be cast from ``ac97->private_data``.
2830
Meanwhile, the ``write`` callback is used to set the register
2831
value::
2833
static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2834
unsigned short reg, unsigned short val)
2837
These callbacks are non-atomic like the control API callbacks.
2839
There are also other callbacks: ``reset``, ``wait`` and ``init``.
2841
The ``reset`` callback is used to reset the codec. If the chip
2842
requires a special kind of reset, you can define this callback.
2844
The ``wait`` callback is used to add some waiting time in the standard
2845
initialization of the codec. If the chip requires the extra waiting
2846
time, define this callback.
2848
The ``init`` callback is used for additional initialization of the
2849
codec.
2851
Updating Registers in The Driver
2852
--------------------------------
2854
If you need to access to the codec from the driver, you can call the
2855
following functions: :c:func:`snd_ac97_write()`,
2856
:c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and
2857
:c:func:`snd_ac97_update_bits()`.
2859
Both :c:func:`snd_ac97_write()` and
2860
:c:func:`snd_ac97_update()` functions are used to set a value to
2861
the given register (``AC97_XXX``). The difference between them is that
2862
:c:func:`snd_ac97_update()` doesn't write a value if the given
2863
value has been already set, while :c:func:`snd_ac97_write()`
2864
always rewrites the value::
2866
snd_ac97_write(ac97, AC97_MASTER, 0x8080);
2867
snd_ac97_update(ac97, AC97_MASTER, 0x8080);
2869
:c:func:`snd_ac97_read()` is used to read the value of the given
2870
register. For example::
2872
value = snd_ac97_read(ac97, AC97_MASTER);
2874
:c:func:`snd_ac97_update_bits()` is used to update some bits in
2875
the given register::
2877
snd_ac97_update_bits(ac97, reg, mask, value);
2879
Also, there is a function to change the sample rate (of a given register
2880
such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
2881
codec: :c:func:`snd_ac97_set_rate()`::
2883
snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
2886
The following registers are available to set the rate:
2887
``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,
2888
``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
2889
specified, the register is not really changed but the corresponding
2890
IEC958 status bits will be updated.
2892
Clock Adjustment
2893
----------------
2895
In some chips, the clock of the codec isn't 48000 but using a PCI clock
2896
(to save a quartz!). In this case, change the field ``bus->clock`` to
2897
the corresponding value. For example, intel8x0 and es1968 drivers have
2898
their own function to read from the clock.
2900
Proc Files
2901
----------
2903
The ALSA AC97 interface will create a proc file such as
2904
``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
2905
can refer to these files to see the current status and registers of
2906
the codec.
2908
Multiple Codecs
2909
---------------
2911
When there are several codecs on the same card, you need to call
2912
:c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or
2913
greater. The ``num`` field specifies the codec number.
2915
If you set up multiple codecs, you either need to write different
2916
callbacks for each codec or check ``ac97->num`` in the callback
2917
routines.
2919
MIDI (MPU401-UART) Interface
2920
============================
2922
General
2923
-------
2925
Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
2926
soundcard supports the standard MPU401-UART interface, most likely you
2927
can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
2928
``<sound/mpu401.h>``.
2930
Some soundchips have a similar but slightly different implementation of
2931
mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
2933
MIDI Constructor
2934
----------------
2936
To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`::
2938
struct snd_rawmidi *rmidi;
2939
snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
2940
irq, &rmidi);
2943
The first argument is the card pointer, and the second is the index of
2944
this component. You can create up to 8 rawmidi devices.
2946
The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
2947
it's not a special one, you can use ``MPU401_HW_MPU401``.
2949
The 4th argument is the I/O port address. Many backward-compatible
2950
MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
2951
PCI I/O region. It depends on the chip design.
2953
The 5th argument is a bitflag for additional information. When the I/O
2954
port address above is part of the PCI I/O region, the MPU401 I/O port
2955
might have been already allocated (reserved) by the driver itself. In
2956
such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
2957
mpu401-uart layer will allocate the I/O ports by itself.
2959
When the controller supports only the input or output MIDI stream, pass
2960
the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
2961
respectively. Then the rawmidi instance is created as a single stream.
2963
``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
2964
(via readb and writeb) instead of iob and outb. In this case, you have
2965
to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
2967
When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
2968
the default interrupt handler. The driver needs to call
2969
:c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
2970
processing the output stream in the irq handler.
2972
If the MPU-401 interface shares its interrupt with the other logical
2973
devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
2974
`below <MIDI Interrupt Handler_>`__).
2976
Usually, the port address corresponds to the command port and port + 1
2977
corresponds to the data port. If not, you may change the ``cport``
2978
field of struct snd_mpu401 manually afterward.
2979
However, struct snd_mpu401 pointer is
2980
not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
2981
need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly::
2983
struct snd_mpu401 *mpu;
2984
mpu = rmidi->private_data;
2986
and reset the ``cport`` as you like::
2988
mpu->cport = my_own_control_port;
2990
The 6th argument specifies the ISA irq number that will be allocated. If
2991
no interrupt is to be allocated (because your code is already allocating
2992
a shared interrupt, or because the device does not use interrupts), pass
2993
-1 instead. For a MPU-401 device without an interrupt, a polling timer
2994
will be used instead.
2996
MIDI Interrupt Handler
2997
----------------------
2999
When the interrupt is allocated in
3000
:c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
3001
handler is automatically used, hence you don't have anything else to do
3002
than creating the mpu401 stuff. Otherwise, you have to set
3003
``MPU401_INFO_IRQ_HOOK``, and call
3004
:c:func:`snd_mpu401_uart_interrupt()` explicitly from your own
3005
interrupt handler when it has determined that a UART interrupt has
3006
occurred.
3008
In this case, you need to pass the private_data of the returned rawmidi
3009
object from :c:func:`snd_mpu401_uart_new()` as the second
3010
argument of :c:func:`snd_mpu401_uart_interrupt()`::
3012
snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3015
RawMIDI Interface
3016
=================
3018
Overview
3019
--------
3021
The raw MIDI interface is used for hardware MIDI ports that can be
3022
accessed as a byte stream. It is not used for synthesizer chips that do
3023
not directly understand MIDI.
3025
ALSA handles file and buffer management. All you have to do is to write
3026
some code to move data between the buffer and the hardware.
3028
The rawmidi API is defined in ``<sound/rawmidi.h>``.
3030
RawMIDI Constructor
3031
-------------------
3033
To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
3034
function::
3036
struct snd_rawmidi *rmidi;
3037
err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
3038
if (err < 0)
3039
return err;
3040
rmidi->private_data = chip;
3041
strcpy(rmidi->name, "My MIDI");
3042
rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
3043
SNDRV_RAWMIDI_INFO_INPUT |
3044
SNDRV_RAWMIDI_INFO_DUPLEX;
3046
The first argument is the card pointer, the second argument is the ID
3047
string.
3049
The third argument is the index of this component. You can create up to
3050
8 rawmidi devices.
3052
The fourth and fifth arguments are the number of output and input
3053
substreams, respectively, of this device (a substream is the equivalent
3054
of a MIDI port).
3056
Set the ``info_flags`` field to specify the capabilities of the
3057
device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one
3058
output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one
3059
input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle
3060
output and input at the same time.
3062
After the rawmidi device is created, you need to set the operators
3063
(callbacks) for each substream. There are helper functions to set the
3064
operators for all the substreams of a device::
3066
snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
3067
snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
3069
The operators are usually defined like this::
3071
static struct snd_rawmidi_ops snd_mymidi_output_ops = {
3072
.open = snd_mymidi_output_open,
3073
.close = snd_mymidi_output_close,
3074
.trigger = snd_mymidi_output_trigger,
3075
};
3077
These callbacks are explained in the `RawMIDI Callbacks`_ section.
3079
If there are more than one substream, you should give a unique name to
3080
each of them::
3082
struct snd_rawmidi_substream *substream;
3083
list_for_each_entry(substream,
3084
&rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
3085
list {
3086
sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
3087
}
3088
/* same for SNDRV_RAWMIDI_STREAM_INPUT */
3090
RawMIDI Callbacks
3091
-----------------
3093
In all the callbacks, the private data that you've set for the rawmidi
3094
device can be accessed as ``substream->rmidi->private_data``.
3096
If there is more than one port, your callbacks can determine the port
3097
index from the struct snd_rawmidi_substream data passed to each
3098
callback::
3100
struct snd_rawmidi_substream *substream;
3101
int index = substream->number;
3103
RawMIDI open callback
3104
~~~~~~~~~~~~~~~~~~~~~
3106
::
3108
static int snd_xxx_open(struct snd_rawmidi_substream *substream);
3111
This is called when a substream is opened. You can initialize the
3112
hardware here, but you shouldn't start transmitting/receiving data yet.
3114
RawMIDI close callback
3115
~~~~~~~~~~~~~~~~~~~~~~
3117
::
3119
static int snd_xxx_close(struct snd_rawmidi_substream *substream);
3121
Guess what.
3123
The ``open`` and ``close`` callbacks of a rawmidi device are
3124
serialized with a mutex, and can sleep.
3126
Rawmidi trigger callback for output substreams
3127
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3129
::
3131
static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
3134
This is called with a nonzero ``up`` parameter when there is some data
3135
in the substream buffer that must be transmitted.
3137
To read data from the buffer, call
3138
:c:func:`snd_rawmidi_transmit_peek()`. It will return the number
3139
of bytes that have been read; this will be less than the number of bytes
3140
requested when there are no more data in the buffer. After the data have
3141
been transmitted successfully, call
3142
:c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
3143
substream buffer::
3145
unsigned char data;
3146
while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
3147
if (snd_mychip_try_to_transmit(data))
3148
snd_rawmidi_transmit_ack(substream, 1);
3149
else
3150
break; /* hardware FIFO full */
3151
}
3153
If you know beforehand that the hardware will accept data, you can use
3154
the :c:func:`snd_rawmidi_transmit()` function which reads some
3155
data and removes them from the buffer at once::
3157
while (snd_mychip_transmit_possible()) {
3158
unsigned char data;
3159
if (snd_rawmidi_transmit(substream, &data, 1) != 1)
3160
break; /* no more data */
3161
snd_mychip_transmit(data);
3162
}
3164
If you know beforehand how many bytes you can accept, you can use a
3165
buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.
3167
The ``trigger`` callback must not sleep. If the hardware FIFO is full
3168
before the substream buffer has been emptied, you have to continue
3169
transmitting data later, either in an interrupt handler, or with a
3170
timer if the hardware doesn't have a MIDI transmit interrupt.
3172
The ``trigger`` callback is called with a zero ``up`` parameter when
3173
the transmission of data should be aborted.
3175
RawMIDI trigger callback for input substreams
3176
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3178
::
3180
static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
3183
This is called with a nonzero ``up`` parameter to enable receiving data,
3184
or with a zero ``up`` parameter do disable receiving data.
3186
The ``trigger`` callback must not sleep; the actual reading of data
3187
from the device is usually done in an interrupt handler.
3189
When data reception is enabled, your interrupt handler should call
3190
:c:func:`snd_rawmidi_receive()` for all received data::
3192
void snd_mychip_midi_interrupt(...)
3193
{
3194
while (mychip_midi_available()) {
3195
unsigned char data;
3196
data = mychip_midi_read();
3197
snd_rawmidi_receive(substream, &data, 1);
3198
}
3199
}
3202
drain callback
3203
~~~~~~~~~~~~~~
3205
::
3207
static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
3210
This is only used with output substreams. This function should wait
3211
until all data read from the substream buffer have been transmitted.
3212
This ensures that the device can be closed and the driver unloaded
3213
without losing data.
3215
This callback is optional. If you do not set ``drain`` in the struct
3216
snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
3217
instead.
3219
Miscellaneous Devices
3220
=====================
3222
FM OPL3
3223
-------
3225
The FM OPL3 is still used in many chips (mainly for backward
3226
compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API
3227
is defined in ``<sound/opl3.h>``.
3229
FM registers can be directly accessed through the direct-FM API, defined
3230
in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
3231
accessed through the Hardware-Dependent Device direct-FM extension API,
3232
whereas in OSS compatible mode, FM registers can be accessed with the
3233
OSS direct-FM compatible API in ``/dev/dmfmX`` device.
3235
To create the OPL3 component, you have two functions to call. The first
3236
one is a constructor for the ``opl3_t`` instance::
3238
struct snd_opl3 *opl3;
3239
snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
3240
integrated, &opl3);
3242
The first argument is the card pointer, the second one is the left port
3243
address, and the third is the right port address. In most cases, the
3244
right port is placed at the left port + 2.
3246
The fourth argument is the hardware type.
3248
When the left and right ports have been already allocated by the card
3249
driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
3250
the opl3 module will allocate the specified ports by itself.
3252
When the accessing the hardware requires special method instead of the
3253
standard I/O access, you can create opl3 instance separately with
3254
:c:func:`snd_opl3_new()`::
3256
struct snd_opl3 *opl3;
3257
snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
3259
Then set ``command``, ``private_data`` and ``private_free`` for the
3260
private access function, the private data and the destructor. The
3261
``l_port`` and ``r_port`` are not necessarily set. Only the command
3262
must be set properly. You can retrieve the data from the
3263
``opl3->private_data`` field.
3265
After creating the opl3 instance via :c:func:`snd_opl3_new()`,
3266
call :c:func:`snd_opl3_init()` to initialize the chip to the
3267
proper state. Note that :c:func:`snd_opl3_create()` always calls
3268
it internally.
3270
If the opl3 instance is created successfully, then create a hwdep device
3271
for this opl3::
3273
struct snd_hwdep *opl3hwdep;
3274
snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
3276
The first argument is the ``opl3_t`` instance you created, and the
3277
second is the index number, usually 0.
3279
The third argument is the index-offset for the sequencer client assigned
3280
to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
3281
always takes 0).
3283
Hardware-Dependent Devices
3284
--------------------------
3286
Some chips need user-space access for special controls or for loading
3287
the micro code. In such a case, you can create a hwdep
3288
(hardware-dependent) device. The hwdep API is defined in
3289
``<sound/hwdep.h>``. You can find examples in opl3 driver or
3290
``isa/sb/sb16_csp.c``.
3292
The creation of the ``hwdep`` instance is done via
3293
:c:func:`snd_hwdep_new()`::
3295
struct snd_hwdep *hw;
3296
snd_hwdep_new(card, "My HWDEP", 0, &hw);
3298
where the third argument is the index number.
3300
You can then pass any pointer value to the ``private_data``. If you
3301
assign private data, you should define a destructor, too. The
3302
destructor function is set in the ``private_free`` field::
3304
struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
3305
hw->private_data = p;
3306
hw->private_free = mydata_free;
3308
and the implementation of the destructor would be::
3310
static void mydata_free(struct snd_hwdep *hw)
3311
{
3312
struct mydata *p = hw->private_data;
3313
kfree(p);
3314
}
3316
The arbitrary file operations can be defined for this instance. The file
3317
operators are defined in the ``ops`` table. For example, assume that
3318
this chip needs an ioctl::
3320
hw->ops.open = mydata_open;
3321
hw->ops.ioctl = mydata_ioctl;
3322
hw->ops.release = mydata_release;
3324
And implement the callback functions as you like.
3326
IEC958 (S/PDIF)
3327
---------------
3329
Usually the controls for IEC958 devices are implemented via the control
3330
interface. There is a macro to compose a name string for IEC958
3331
controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
3332
``<include/asound.h>``.
3334
There are some standard controls for IEC958 status bits. These controls
3335
use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is
3336
fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
3337
callback, you don't specify the value field for this type (the count
3338
field must be set, though).
3340
“IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
3341
status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
3342
returns the bitmask for professional mode. They are read-only controls.
3344
Meanwhile, “IEC958 Playback Default” control is defined for getting and
3345
setting the current default IEC958 bits.
3347
Due to historical reasons, both variants of the Playback Mask and the
3348
Playback Default controls can be implemented on either a
3349
``SNDRV_CTL_ELEM_IFACE_PCM`` or a ``SNDRV_CTL_ELEM_IFACE_MIXER`` iface.
3350
Drivers should expose the mask and default on the same iface though.
3352
In addition, you can define the control switches to enable/disable or to
3353
set the raw bit mode. The implementation will depend on the chip, but
3354
the control should be named as “IEC958 xxx”, preferably using the
3355
:c:func:`SNDRV_CTL_NAME_IEC958()` macro.
3357
You can find several cases, for example, ``pci/emu10k1``,
3358
``pci/ice1712``, or ``pci/cmipci.c``.
3360
Buffer and Memory Management
3361
============================
3363
Buffer Types
3364
------------
3366
ALSA provides several different buffer allocation functions depending on
3367
the bus and the architecture. All these have a consistent API. The
3368
allocation of physically-contiguous pages is done via the
3369
:c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
3370
type.
3372
The allocation of pages with fallback is done via
3373
:c:func:`snd_dma_alloc_pages_fallback()`. This function tries
3374
to allocate the specified number of pages, but if not enough pages are
3375
available, it tries to reduce the request size until enough space
3376
is found, down to one page.
3378
To release the pages, call the :c:func:`snd_dma_free_pages()`
3379
function.
3381
Usually, ALSA drivers try to allocate and reserve a large contiguous
3382
physical space at the time the module is loaded for later use. This
3383
is called “pre-allocation”. As already written, you can call the
3384
following function at PCM instance construction time (in the case of PCI
3385
bus)::
3387
snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
3388
&pci->dev, size, max);
3390
where ``size`` is the byte size to be pre-allocated and ``max`` is
3391
the maximum size settable via the ``prealloc`` proc file. The
3392
allocator will try to get an area as large as possible within the
3393
given size.
3395
The second argument (type) and the third argument (device pointer) are
3396
dependent on the bus. For normal devices, pass the device pointer
3397
(typically identical as ``card->dev``) to the third argument with
3398
``SNDRV_DMA_TYPE_DEV`` type.
3400
A continuous buffer unrelated to the
3401
bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
3402
You can pass NULL to the device pointer in that case, which is the
3403
default mode implying to allocate with the ``GFP_KERNEL`` flag.
3404
If you need a restricted (lower) address, set up the coherent DMA mask
3405
bits for the device, and pass the device pointer, like the normal
3406
device memory allocations. For this type, it's still allowed to pass
3407
NULL to the device pointer, too, if no address restriction is needed.
3409
For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the
3410
device pointer (see the `Non-Contiguous Buffers`_ section).
3412
Once the buffer is pre-allocated, you can use the allocator in the
3413
``hw_params`` callback::
3415
snd_pcm_lib_malloc_pages(substream, size);
3417
Note that you have to pre-allocate to use this function.
3419
But most drivers use the "managed buffer allocation mode" instead
3420
of manual allocation and release.
3421
This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`
3422
instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`::
3424
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
3425
&pci->dev, size, max);
3427
where the passed arguments are identical for both functions.
3428
The difference in the managed mode is that PCM core will call
3429
:c:func:`snd_pcm_lib_malloc_pages()` internally already before calling
3430
the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()`
3431
after the PCM ``hw_free`` callback automatically. So the driver
3432
doesn't have to call these functions explicitly in its callback any
3433
longer. This allows many drivers to have NULL ``hw_params`` and
3434
``hw_free`` entries.
3436
External Hardware Buffers
3437
-------------------------
3439
Some chips have their own hardware buffers and DMA transfer from the
3440
host memory is not available. In such a case, you need to either 1)
3441
copy/set the audio data directly to the external hardware buffer, or 2)
3442
make an intermediate buffer and copy/set the data from it to the
3443
external hardware buffer in interrupts (or in tasklets, preferably).
3445
The first case works fine if the external hardware buffer is large
3446
enough. This method doesn't need any extra buffers and thus is more
3447
efficient. You need to define the ``copy`` callback
3448
for the data transfer, in addition to the ``fill_silence``
3449
callback for playback. However, there is a drawback: it cannot be
3450
mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.
3452
The second case allows for mmap on the buffer, although you have to
3453
handle an interrupt or a tasklet to transfer the data from the
3454
intermediate buffer to the hardware buffer. You can find an example in
3455
the vxpocket driver.
3457
Another case is when the chip uses a PCI memory-map region for the
3458
buffer instead of the host memory. In this case, mmap is available only
3459
on certain architectures like the Intel one. In non-mmap mode, the data
3460
cannot be transferred as in the normal way. Thus you need to define the
3461
``copy`` and ``fill_silence`` callbacks as well,
3462
as in the cases above. Examples are found in ``rme32.c`` and
3463
``rme96.c``.
3465
The implementation of the ``copy`` and
3466
``silence`` callbacks depends upon whether the hardware supports
3467
interleaved or non-interleaved samples. The ``copy`` callback is
3468
defined like below, a bit differently depending on whether the direction
3469
is playback or capture::
3471
static int playback_copy(struct snd_pcm_substream *substream,
3472
int channel, unsigned long pos,
3473
struct iov_iter *src, unsigned long count);
3474
static int capture_copy(struct snd_pcm_substream *substream,
3475
int channel, unsigned long pos,
3476
struct iov_iter *dst, unsigned long count);
3478
In the case of interleaved samples, the second argument (``channel``) is
3479
not used. The third argument (``pos``) specifies the position in bytes.
3481
The meaning of the fourth argument is different between playback and
3482
capture. For playback, it holds the source data pointer, and for
3483
capture, it's the destination data pointer.
3485
The last argument is the number of bytes to be copied.
3487
What you have to do in this callback is again different between playback
3488
and capture directions. In the playback case, you copy the given amount
3489
of data (``count``) at the specified pointer (``src``) to the specified
3490
offset (``pos``) in the hardware buffer. When coded like memcpy-like
3491
way, the copy would look like::
3493
my_memcpy_from_iter(my_buffer + pos, src, count);
3495
For the capture direction, you copy the given amount of data (``count``)
3496
at the specified offset (``pos``) in the hardware buffer to the
3497
specified pointer (``dst``)::
3499
my_memcpy_to_iter(dst, my_buffer + pos, count);
3501
The given ``src`` or ``dst`` a struct iov_iter pointer containing the
3502
pointer and the size. Use the existing helpers to copy or access the
3503
data as defined in ``linux/uio.h``.
3505
Careful readers might notice that these callbacks receive the
3506
arguments in bytes, not in frames like other callbacks. It's because
3507
this makes coding easier like in the examples above, and also it makes
3508
it easier to unify both the interleaved and non-interleaved cases, as
3509
explained below.
3511
In the case of non-interleaved samples, the implementation will be a bit
3512
more complicated. The callback is called for each channel, passed in
3513
the second argument, so in total it's called N times per transfer.
3515
The meaning of the other arguments are almost the same as in the
3516
interleaved case. The callback is supposed to copy the data from/to
3517
the given user-space buffer, but only for the given channel. For
3518
details, please check ``isa/gus/gus_pcm.c`` or ``pci/rme9652/rme9652.c``
3519
as examples.
3521
Usually for the playback, another callback ``fill_silence`` is
3522
defined. It's implemented in a similar way as the copy callbacks
3523
above::
3525
static int silence(struct snd_pcm_substream *substream, int channel,
3526
unsigned long pos, unsigned long count);
3528
The meanings of arguments are the same as in the ``copy`` callback,
3529
although there is no buffer pointer
3530
argument. In the case of interleaved samples, the channel argument has
3531
no meaning, as for the ``copy`` callback.
3533
The role of the ``fill_silence`` callback is to set the given amount
3534
(``count``) of silence data at the specified offset (``pos``) in the
3535
hardware buffer. Suppose that the data format is signed (that is, the
3536
silent-data is 0), and the implementation using a memset-like function
3537
would look like::
3539
my_memset(my_buffer + pos, 0, count);
3541
In the case of non-interleaved samples, again, the implementation
3542
becomes a bit more complicated, as it's called N times per transfer
3543
for each channel. See, for example, ``isa/gus/gus_pcm.c``.
3545
Non-Contiguous Buffers
3546
----------------------
3548
If your hardware supports a page table as in emu10k1 or buffer
3549
descriptors as in via82xx, you can use scatter-gather (SG) DMA. ALSA
3550
provides an interface for handling SG-buffers. The API is provided in
3551
``<sound/pcm.h>``.
3553
For creating the SG-buffer handler, call
3554
:c:func:`snd_pcm_set_managed_buffer()` or
3555
:c:func:`snd_pcm_set_managed_buffer_all()` with
3556
``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like for other PCI
3557
pre-allocations. You need to pass ``&pci->dev``, where pci is
3558
the struct pci_dev pointer of the chip as well::
3560
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG,
3561
&pci->dev, size, max);
3563
The ``struct snd_sg_buf`` instance is created as
3564
``substream->dma_private`` in turn. You can cast the pointer like::
3566
struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
3568
Then in the :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
3569
handler will allocate the non-contiguous kernel pages of the given size
3570
and map them as virtually contiguous memory. The virtual pointer
3571
is addressed via runtime->dma_area. The physical address
3572
(``runtime->dma_addr``) is set to zero, because the buffer is
3573
physically non-contiguous. The physical address table is set up in
3574
``sgbuf->table``. You can get the physical address at a certain offset
3575
via :c:func:`snd_pcm_sgbuf_get_addr()`.
3577
If you need to release the SG-buffer data explicitly, call the
3578
standard API function :c:func:`snd_pcm_lib_free_pages()` as usual.
3580
Vmalloc'ed Buffers
3581
------------------
3583
It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
3584
example, for an intermediate buffer.
3585
You can simply allocate it via the standard
3586
:c:func:`snd_pcm_lib_malloc_pages()` and co. after setting up the
3587
buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type::
3589
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
3590
NULL, 0, 0);
3592
NULL is passed as the device pointer argument, which indicates
3593
that default pages (GFP_KERNEL and GFP_HIGHMEM) will be
3594
allocated.
3596
Also, note that zero is passed as both the size and the max size
3597
argument here. Since each vmalloc call should succeed at any time,
3598
we don't need to pre-allocate the buffers like other continuous
3599
pages.
3601
Proc Interface
3602
==============
3604
ALSA provides an easy interface for procfs. The proc files are very
3605
useful for debugging. I recommend you set up proc files if you write a
3606
driver and want to get a running status or register dumps. The API is
3607
found in ``<sound/info.h>``.
3609
To create a proc file, call :c:func:`snd_card_proc_new()`::
3611
struct snd_info_entry *entry;
3612
int err = snd_card_proc_new(card, "my-file", &entry);
3614
where the second argument specifies the name of the proc file to be
3615
created. The above example will create a file ``my-file`` under the
3616
card directory, e.g. ``/proc/asound/card0/my-file``.
3618
Like other components, the proc entry created via
3619
:c:func:`snd_card_proc_new()` will be registered and released
3620
automatically in the card registration and release functions.
3622
When the creation is successful, the function stores a new instance in
3623
the pointer given in the third argument. It is initialized as a text
3624
proc file for read only. To use this proc file as a read-only text file
3625
as-is, set the read callback with private data via
3626
:c:func:`snd_info_set_text_ops()`::
3628
snd_info_set_text_ops(entry, chip, my_proc_read);
3630
where the second argument (``chip``) is the private data to be used in
3631
the callback. The third parameter specifies the read buffer size and
3632
the fourth (``my_proc_read``) is the callback function, which is
3633
defined like::
3635
static void my_proc_read(struct snd_info_entry *entry,
3636
struct snd_info_buffer *buffer);
3638
In the read callback, use :c:func:`snd_iprintf()` for output
3639
strings, which works just like normal :c:func:`printf()`. For
3640
example::
3642
static void my_proc_read(struct snd_info_entry *entry,
3643
struct snd_info_buffer *buffer)
3644
{
3645
struct my_chip *chip = entry->private_data;
3647
snd_iprintf(buffer, "This is my chip!\n");
3648
snd_iprintf(buffer, "Port = %ld\n", chip->port);
3649
}
3651
The file permissions can be changed afterwards. By default, they are
3652
read only for all users. If you want to add write permission for the
3653
user (root by default), do as follows::
3655
entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
3657
and set the write buffer size and the callback::
3659
entry->c.text.write = my_proc_write;
3661
In the write callback, you can use :c:func:`snd_info_get_line()`
3662
to get a text line, and :c:func:`snd_info_get_str()` to retrieve
3663
a string from the line. Some examples are found in
3664
``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.
3666
For a raw-data proc-file, set the attributes as follows::
3668
static const struct snd_info_entry_ops my_file_io_ops = {
3669
.read = my_file_io_read,
3670
};
3672
entry->content = SNDRV_INFO_CONTENT_DATA;
3673
entry->private_data = chip;
3674
entry->c.ops = &my_file_io_ops;
3675
entry->size = 4096;
3676
entry->mode = S_IFREG | S_IRUGO;
3678
For raw data, ``size`` field must be set properly. This specifies
3679
the maximum size of the proc file access.
3681
The read/write callbacks of raw mode are more direct than the text mode.
3682
You need to use a low-level I/O functions such as
3683
:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the
3684
data::
3686
static ssize_t my_file_io_read(struct snd_info_entry *entry,
3687
void *file_private_data,
3688
struct file *file,
3689
char *buf,
3690
size_t count,
3691
loff_t pos)
3692
{
3693
if (copy_to_user(buf, local_data + pos, count))
3694
return -EFAULT;
3695
return count;
3696
}
3698
If the size of the info entry has been set up properly, ``count`` and
3699
``pos`` are guaranteed to fit within 0 and the given size. You don't
3700
have to check the range in the callbacks unless any other condition is
3701
required.
3703
Power Management
3704
================
3706
If the chip is supposed to work with suspend/resume functions, you need
3707
to add power-management code to the driver. The additional code for
3708
power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
3709
with __maybe_unused attribute; otherwise the compiler will complain.
3711
If the driver *fully* supports suspend/resume that is, the device can be
3712
properly resumed to its state when suspend was called, you can set the
3713
``SNDRV_PCM_INFO_RESUME`` flag in the PCM info field. Usually, this is
3714
possible when the registers of the chip can be safely saved and restored
3715
to RAM. If this is set, the trigger callback is called with
3716
``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.
3718
Even if the driver doesn't support PM fully but partial suspend/resume
3719
is still possible, it's still worthy to implement suspend/resume
3720
callbacks. In such a case, applications would reset the status by
3721
calling :c:func:`snd_pcm_prepare()` and restart the stream
3722
appropriately. Hence, you can define suspend/resume callbacks below but
3723
don't set the ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
3725
Note that the trigger with SUSPEND can always be called when
3726
:c:func:`snd_pcm_suspend_all()` is called, regardless of the
3727
``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the
3728
behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
3729
``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
3730
callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
3731
to keep it for compatibility reasons.)
3733
The driver needs to define the
3734
suspend/resume hooks according to the bus the device is connected to. In
3735
the case of PCI drivers, the callbacks look like below::
3737
static int __maybe_unused snd_my_suspend(struct device *dev)
3738
{
3739
.... /* do things for suspend */
3740
return 0;
3741
}
3742
static int __maybe_unused snd_my_resume(struct device *dev)
3743
{
3744
.... /* do things for suspend */
3745
return 0;
3746
}
3748
The scheme of the real suspend job is as follows:
3750
1. Retrieve the card and the chip data.
3752
2. Call :c:func:`snd_power_change_state()` with
3753
``SNDRV_CTL_POWER_D3hot`` to change the power status.
3755
3. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
3756
each codec.
3758
4. Save the register values if necessary.
3760
5. Stop the hardware if necessary.
3762
Typical code would look like::
3764
static int __maybe_unused mychip_suspend(struct device *dev)
3765
{
3766
/* (1) */
3767
struct snd_card *card = dev_get_drvdata(dev);
3768
struct mychip *chip = card->private_data;
3769
/* (2) */
3770
snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
3771
/* (3) */
3772
snd_ac97_suspend(chip->ac97);
3773
/* (4) */
3774
snd_mychip_save_registers(chip);
3775
/* (5) */
3776
snd_mychip_stop_hardware(chip);
3777
return 0;
3778
}
3781
The scheme of the real resume job is as follows:
3783
1. Retrieve the card and the chip data.
3785
2. Re-initialize the chip.
3787
3. Restore the saved registers if necessary.
3789
4. Resume the mixer, e.g. by calling :c:func:`snd_ac97_resume()`.
3791
5. Restart the hardware (if any).
3793
6. Call :c:func:`snd_power_change_state()` with
3794
``SNDRV_CTL_POWER_D0`` to notify the processes.
3796
Typical code would look like::
3798
static int __maybe_unused mychip_resume(struct pci_dev *pci)
3799
{
3800
/* (1) */
3801
struct snd_card *card = dev_get_drvdata(dev);
3802
struct mychip *chip = card->private_data;
3803
/* (2) */
3804
snd_mychip_reinit_chip(chip);
3805
/* (3) */
3806
snd_mychip_restore_registers(chip);
3807
/* (4) */
3808
snd_ac97_resume(chip->ac97);
3809
/* (5) */
3810
snd_mychip_restart_chip(chip);
3811
/* (6) */
3812
snd_power_change_state(card, SNDRV_CTL_POWER_D0);
3813
return 0;
3814
}
3816
Note that, at the time this callback gets called, the PCM stream has
3817
been already suspended via its own PM ops calling
3818
:c:func:`snd_pcm_suspend_all()` internally.
3820
OK, we have all callbacks now. Let's set them up. In the initialization
3821
of the card, make sure that you can get the chip data from the card
3822
instance, typically via ``private_data`` field, in case you created the
3823
chip data individually::
3825
static int snd_mychip_probe(struct pci_dev *pci,
3826
const struct pci_device_id *pci_id)
3827
{
3828
....
3829
struct snd_card *card;
3830
struct mychip *chip;
3831
int err;
3832
....
3833
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
3834
0, &card);
3835
....
3836
chip = kzalloc(sizeof(*chip), GFP_KERNEL);
3837
....
3838
card->private_data = chip;
3839
....
3840
}
3842
When you created the chip data with :c:func:`snd_card_new()`, it's
3843
anyway accessible via ``private_data`` field::
3845
static int snd_mychip_probe(struct pci_dev *pci,
3846
const struct pci_device_id *pci_id)
3847
{
3848
....
3849
struct snd_card *card;
3850
struct mychip *chip;
3851
int err;
3852
....
3853
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
3854
sizeof(struct mychip), &card);
3855
....
3856
chip = card->private_data;
3857
....
3858
}
3860
If you need space to save the registers, allocate the buffer for it
3861
here, too, since it would be fatal if you cannot allocate a memory in
3862
the suspend phase. The allocated buffer should be released in the
3863
corresponding destructor.
3865
And next, set suspend/resume callbacks to the pci_driver::
3867
static DEFINE_SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume);
3869
static struct pci_driver driver = {
3870
.name = KBUILD_MODNAME,
3871
.id_table = snd_my_ids,
3872
.probe = snd_my_probe,
3873
.remove = snd_my_remove,
3874
.driver = {
3875
.pm = &snd_my_pm_ops,
3876
},
3877
};
3879
Module Parameters
3880
=================
3882
There are standard module options for ALSA. At least, each module should
3883
have the ``index``, ``id`` and ``enable`` options.
3885
If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
3886
cards), they should be arrays. The default initial values are defined
3887
already as constants for easier programming::
3889
static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
3890
static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
3891
static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
3893
If the module supports only a single card, they could be single
3894
variables, instead. ``enable`` option is not always necessary in this
3895
case, but it would be better to have a dummy option for compatibility.
3897
The module parameters must be declared with the standard
3898
``module_param()``, ``module_param_array()`` and
3899
:c:func:`MODULE_PARM_DESC()` macros.
3901
Typical code would look as below::
3903
#define CARD_NAME "My Chip"
3905
module_param_array(index, int, NULL, 0444);
3906
MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
3907
module_param_array(id, charp, NULL, 0444);
3908
MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
3909
module_param_array(enable, bool, NULL, 0444);
3910
MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
3912
Also, don't forget to define the module description and the license.
3913
Especially, the recent modprobe requires to define the
3914
module license as GPL, etc., otherwise the system is shown as “tainted”::
3916
MODULE_DESCRIPTION("Sound driver for My Chip");
3917
MODULE_LICENSE("GPL");
3920
Device-Managed Resources
3921
========================
3923
In the examples above, all resources are allocated and released
3924
manually. But human beings are lazy in nature, especially developers
3925
are lazier. So there are some ways to automate the release part; it's
3926
the (device-)managed resources aka devres or devm family. For
3927
example, an object allocated via :c:func:`devm_kmalloc()` will be
3928
freed automatically at unbinding the device.
3930
ALSA core provides also the device-managed helper, namely,
3931
:c:func:`snd_devm_card_new()` for creating a card object.
3932
Call this functions instead of the normal :c:func:`snd_card_new()`,
3933
and you can forget the explicit :c:func:`snd_card_free()` call, as
3934
it's called automagically at error and removal paths.
3936
One caveat is that the call of :c:func:`snd_card_free()` would be put
3937
at the beginning of the call chain only after you call
3938
:c:func:`snd_card_register()`.
3940
Also, the ``private_free`` callback is always called at the card free,
3941
so be careful to put the hardware clean-up procedure in
3942
``private_free`` callback. It might be called even before you
3943
actually set up at an earlier error path. For avoiding such an
3944
invalid initialization, you can set ``private_free`` callback after
3945
:c:func:`snd_card_register()` call succeeds.
3947
Another thing to be remarked is that you should use device-managed
3948
helpers for each component as much as possible once when you manage
3949
the card in that way. Mixing up with the normal and the managed
3950
resources may screw up the release order.
3953
How To Put Your Driver Into ALSA Tree
3954
=====================================
3956
General
3957
-------
3959
So far, you've learned how to write the driver codes. And you might have
3960
a question now: how to put my own driver into the ALSA driver tree? Here
3961
(finally :) the standard procedure is described briefly.
3963
Suppose that you create a new PCI driver for the card “xyz”. The card
3964
module name would be snd-xyz. The new driver is usually put into the
3965
alsa-driver tree, ``sound/pci`` directory in the case of PCI
3966
cards.
3968
In the following sections, the driver code is supposed to be put into
3969
Linux kernel tree. The two cases are covered: a driver consisting of a
3970
single source file and one consisting of several source files.
3972
Driver with A Single Source File
3973
--------------------------------
3975
1. Modify sound/pci/Makefile
3977
Suppose you have a file xyz.c. Add the following two lines::
3979
snd-xyz-y := xyz.o
3980
obj-$(CONFIG_SND_XYZ) += snd-xyz.o
3982
2. Create the Kconfig entry
3984
Add the new entry of Kconfig for your xyz driver::
3986
config SND_XYZ
3987
tristate "Foobar XYZ"
3988
depends on SND
3989
select SND_PCM
3990
help
3991
Say Y here to include support for Foobar XYZ soundcard.
3992
To compile this driver as a module, choose M here:
3993
the module will be called snd-xyz.
3995
The line ``select SND_PCM`` specifies that the driver xyz supports PCM.
3996
In addition to SND_PCM, the following components are supported for
3997
select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
3998
SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
3999
Add the select command for each supported component.
4001
Note that some selections imply the lowlevel selections. For example,
4002
PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
4003
includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
4004
the lowlevel selections again.
4006
For the details of Kconfig script, refer to the kbuild documentation.
4008
Drivers with Several Source Files
4009
---------------------------------
4011
Suppose that the driver snd-xyz have several source files. They are
4012
located in the new subdirectory, sound/pci/xyz.
4014
1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
4015
as below::
4017
obj-$(CONFIG_SND) += sound/pci/xyz/
4020
2. Under the directory ``sound/pci/xyz``, create a Makefile::
4022
snd-xyz-y := xyz.o abc.o def.o
4023
obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4025
3. Create the Kconfig entry
4027
This procedure is as same as in the last section.
4030
Useful Functions
4031
================
4033
:c:func:`snd_BUG()`
4034
-------------------
4036
It shows the ``BUG?`` message and stack trace as well as
4037
:c:func:`snd_BUG_ON()` at the point. It's useful to show that a
4038
fatal error happens there.
4040
When no debug flag is set, this macro is ignored.
4042
:c:func:`snd_BUG_ON()`
4043
----------------------
4045
:c:func:`snd_BUG_ON()` macro is similar with
4046
:c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or
4047
it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug))
4048
return -EINVAL;
4050
The macro takes an conditional expression to evaluate. When
4051
``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
4052
the warning message such as ``BUG? (xxx)`` normally followed by stack
4053
trace. In both cases it returns the evaluated value.
4055
Acknowledgments
4056
===============
4058
I would like to thank Phil Kerr for his help for improvement and
4059
corrections of this document.
4061
Kevin Conder reformatted the original plain-text to the DocBook format.
4063
Giuliano Pochini corrected typos and contributed the example codes in
4064
the hardware constraints section.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
문서 목적과 독자
1-20Takashi Iwai <[email protected]>가 작성한 이 문서는 ALSA(Advanced Linux Sound Architecture) driver 작성법을 설명합니다. 주된 대상은 PCI sound card이므로 다른 device type은 API가 다를 수 있지만 ALSA kernel API 자체는 일관되어 있어 다른 driver를 작성할 때도 참고할 수 있습니다.
독자는 C 언어와 기본 Linux kernel programming 지식을 이미 갖추었다고 가정합니다. 일반적인 kernel coding이나 low-level hardware 구현 세부는 다루지 않고, ALSA에서 표준적인 PCI sound driver를 구성하는 방법에 집중합니다.
항목내용
주 대상PCI sound card driver
응용 범위일관된 ALSA kernel API를 쓰는 다른 device type
전제C 언어와 Linux kernel programming 기초
제외일반 kernel coding과 hardware별 low-level 구현
전제 지식과 포함·제외 범위를 구분합니다.
======================
Writing an ALSA Driver
======================
:Author: Takashi Iwai <[email protected]>
Preface
=======
This document describes how to write an `ALSA (Advanced Linux Sound
Architecture) <http://www.alsa-project.org/>`__ driver. The document
focuses mainly on PCI soundcards. In the case of other device types, the
API might be different, too. However, at least the ALSA kernel API is
consistent, and therefore it would be still a bit help for writing them.
This document targets people who already have enough C language skills
and have basic linux kernel programming knowledge. This document doesn't
explain the general topic of linux kernel coding and doesn't cover
low-level driver implementation details. It only describes the standard
way to write a PCI sound driver on ALSA.ALSA source tree 전체 구조
21-54ALSA driver source tree의 root는 `sound`입니다. `core`에는 ALSA middle layer와 OSS·sequencer 하위 계층이 있고, `include`에는 공유 header, `drivers`에는 architecture에 독립적인 공통 component가 있습니다.
Bus와 platform에 따라 `pci`, `isa`, `arm`, `ppc`, `sparc`, `usb`, `pcmcia`, `soc`로 top-level driver가 나뉩니다. `i2c`와 `synth`는 component 계층을, 마지막 `oss`는 OSS/Lite code를 담습니다.
경로주요 하위 경로역할
sound/coreoss, seq, seq/ossALSA middle layer와 emulation/sequencer
sound/include-공개·공유 ALSA header
sound/driversmpu401, opl3Bus/CPU 독립 공통 component
sound/i2c-ALSA I2C component
sound/synthemuxSynth middle layer
sound/pcicard별 directoryPCI card와 PCI bus별 code
sound/isacard별 directoryISA card module
sound/arm, ppc, sparc-Architecture-specific card module
sound/usb-USB audio와 통합 USB MIDI
sound/pcmciacard별 directoryPCMCIA/PCCard driver
sound/soc-ASoC core, codec, machine driver
sound/oss-OSS/Lite code
원문의 ASCII directory tree를 계층 관계가 보존되는 구조화 표로 다시 그렸습니다.
ALSA middle layer: sound/core→공통 component: include/drivers/i2c/synth→Bus·architecture driver: pci/isa/arm/ppc/sparc/usb/pcmcia/soc→Legacy OSS/Lite: sound/oss
Driver code를 기능과 hardware 연결 방식에 따라 찾습니다.
File Tree Structure
===================
General
-------
The file tree structure of ALSA driver is depicted below::
sound
/core
/oss
/seq
/oss
/include
/drivers
/mpu401
/opl3
/i2c
/synth
/emux
/pci
/(cards)
/isa
/(cards)
/arm
/ppc
/sparc
/usb
/pcmcia /(cards)
/soc
/oss
Core, OSS, sequencer directory
55-83`sound/core`는 ALSA driver의 심장인 middle layer이며 native ALSA module을 보관합니다. 하위 directory의 module 구성은 kernel configuration에 따라 달라집니다.
`core/oss`에는 OSS PCM과 mixer emulation이 있습니다. OSS rawmidi emulation은 작아서 ALSA rawmidi code에 직접 포함되고, OSS sequencer code는 `core/seq/oss`에 따로 있습니다.
`core/seq`와 그 하위 directory는 ALSA sequencer용입니다. Sequencer core와 `snd-seq-midi`, `snd-seq-virmidi` 같은 주 module은 `CONFIG_SND_SEQUENCER`가 설정됐을 때만 build됩니다. `core/seq/oss`는 OSS sequencer emulation을 담습니다.
Directory내용Build 조건
sound/coreNative ALSA middle layer기본 ALSA 구성
sound/core/ossOSS PCM·mixer emulationOSS emulation 선택
sound/core/seqSequencer core, snd-seq-midi, snd-seq-virmidiCONFIG_SND_SEQUENCER
sound/core/seq/ossOSS sequencer emulationSequencer/OSS 구성
Kernel config와 emulation 역할을 구분했습니다.
core directory
--------------
This directory contains the middle layer which is the heart of ALSA
drivers. In this directory, the native ALSA modules are stored. The
sub-directories contain different modules and are dependent upon the
kernel config.
core/oss
~~~~~~~~
The code for OSS PCM and mixer emulation modules is stored in this
directory. The OSS rawmidi emulation is included in the ALSA rawmidi
code since it's quite small. The sequencer code is stored in
``core/seq/oss`` directory (see `below <core/seq/oss_>`__).
core/seq
~~~~~~~~
This directory and its sub-directories are for the ALSA sequencer. This
directory contains the sequencer core and primary sequencer modules such
as snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
``CONFIG_SND_SEQUENCER`` is set in the kernel config.
core/seq/oss
~~~~~~~~~~~~
This contains the OSS sequencer emulation code.
I2C, synth, PCI directory
112-138`sound/i2c`에는 ALSA I2C component가 있습니다. Linux에 표준 I2C layer가 있지만 일부 sound card는 단순 operation만 필요하고 표준 API가 지나치게 복잡해서 ALSA 자체 I2C code를 사용합니다.
`sound/synth`에는 synth middle-level module이 있습니다. 문서 작성 시점에는 `synth/emux` 아래 Emu8000/Emu10k1 synth driver만 있습니다.
`sound/pci`와 하위 directory에는 PCI sound card top-level module과 PCI bus-specific code를 둡니다. Source 하나로 build되는 driver는 `pci` 바로 아래, source file이 여러 개인 driver는 `emu10k1`, `ice1712`처럼 자체 하위 directory에 둡니다.
경로내용배치 규칙
sound/i2cALSA 전용 I2C component단순 card operation에서 자체 API 사용
sound/synth/emuxEmu8000/Emu10k1 synthSynth middle layer 하위
sound/pci/*.c단일 source PCI driverpci root에 직접 배치
sound/pci/<card>/다중 source PCI driverDriver별 directory 사용
기능과 source 규모에 따른 위치입니다.
i2c directory
-------------
This contains the ALSA i2c components.
Although there is a standard i2c layer on Linux, ALSA has its own i2c
code for some cards, because the soundcard needs only a simple operation
and the standard i2c API is too complicated for such a purpose.
synth directory
---------------
This contains the synth middle-level modules.
So far, there is only Emu8000/Emu10k1 synth driver under the
``synth/emux`` sub-directory.
pci directory
-------------
This directory and its sub-directories hold the top-level card modules
for PCI soundcards and the code specific to the PCI BUS.
The drivers compiled from a single file are stored directly in the pci
directory, while the drivers with several source files are stored on
their own sub-directory (e.g. emu10k1, ice1712).
ISA, architecture, USB, PCMCIA, ASoC, OSS
139-177`sound/isa`와 하위 directory는 ISA sound card의 top-level module을 담습니다. `sound/arm`, `sound/ppc`, `sound/sparc`는 각 architecture에만 해당하는 top-level card module용입니다.
`sound/usb`에는 USB-audio driver가 있으며 USB MIDI driver도 그 안에 통합돼 있습니다. `sound/pcmcia`에는 PCMCIA, 특히 PCCard driver를 둡니다. CardBus는 표준 PCI card와 API가 같으므로 `sound/pci`에 둡니다.
`sound/soc`에는 ASoC(ALSA System on Chip) core, codec, machine driver가 있습니다. `sound/oss`는 OSS/Lite code 위치이며 문서 작성 시점에는 m68k의 `dmasound`를 제외한 code가 제거된 상태입니다.
경로대상
sound/isaISA sound card
sound/arm, ppc, sparc해당 architecture 전용 card
sound/usbUSB audio와 USB MIDI
sound/pcmciaPCMCIA/PCCard; CardBus는 sound/pci
sound/socASoC core·codec·machine driver
sound/ossLegacy OSS/Lite; 당시 m68k dmasound만 잔존
Hardware 연결과 architecture에 따른 위치입니다.
isa directory
-------------
This directory and its sub-directories hold the top-level card modules
for ISA soundcards.
arm, ppc, and sparc directories
-------------------------------
They are used for top-level card modules which are specific to one of
these architectures.
usb directory
-------------
This directory contains the USB-audio driver.
The USB MIDI driver is integrated in the usb-audio driver.
pcmcia directory
----------------
The PCMCIA, especially PCCard drivers will go here. CardBus drivers will
be in the pci directory, because their API is identical to that of
standard PCI cards.
soc directory
-------------
This directory contains the codes for ASoC (ALSA System on Chip)
layer including ASoC core, codec and machine drivers.
oss directory
-------------
This contains OSS/Lite code.
At the time of writing, all code has been removed except for dmasound
on m68k.
PCI driver 최소 흐름
178-201PCI sound card driver의 최소 흐름은 PCI ID table을 정의하고 `probe`와 `remove` callback을 만든 뒤, 세 pointer를 담는 `struct pci_driver`를 구성하는 것입니다.
Module 초기화에서는 :c:func:`pci_register_driver()`로 그 table을 등록하고, 종료에서는 :c:func:`pci_unregister_driver()`를 호출합니다.
PCI ID table 정의→probe callback 작성→remove callback 작성→struct pci_driver에 ID/probe/remove 연결→init: pci_register_driver()→exit: pci_unregister_driver()
원문의 여섯 항목을 등록과 해제 순서로 구조화했습니다.
Basic Flow for PCI Drivers
==========================
Outline
-------
The minimum flow for PCI soundcards is as follows:
- define the PCI ID table (see the section `PCI Entries`_).
- create ``probe`` callback.
- create ``remove`` callback.
- create a struct pci_driver structure
containing the three pointers above.
- create an ``init`` function just calling the
:c:func:`pci_register_driver()` to register the pci_driver
table defined above.
- create an ``exit`` function to call the
:c:func:`pci_unregister_driver()` function.
전체 driver skeleton
202-349이 code는 뒤 절에서 채울 부분을 `....`로 남긴 ALSA PCI driver 전체 skeleton입니다. :c:func:`snd_mychip_probe()`의 `(1)`부터 `(7)`까지 comment 번호는 다음 Driver Constructor 절의 단계와 대응합니다.
Module parameter `index`, `id`, `enable`은 최대 `SNDRV_CARDS` instance를 제어합니다. `struct mychip`은 `struct snd_card *card`와 뒤에서 추가할 PCI resource를 보관합니다.
:c:func:`snd_mychip_create()`는 PCI 가용성을 확인하고 zero-filled chip data를 :c:func:`kzalloc()`로 할당한 뒤, `SNDRV_DEV_LOWLEVEL` component와 `.dev_free = snd_mychip_dev_free` callback을 :c:func:`snd_device_new()`로 등록합니다. 실패하면 실제 destructor인 :c:func:`snd_mychip_free()`를 호출합니다.
:c:func:`snd_mychip_probe()`는 device slot 확인, :c:func:`snd_card_new()`, chip component 생성, card 이름 설정, PCM/mixer/MIDI component 생성, :c:func:`snd_card_register()`, `pci_set_drvdata()` 순서로 진행합니다. 어느 단계든 실패하면 하나의 `error` label에서 :c:func:`snd_card_free()`를 호출합니다.
Remove callback은 `pci_get_drvdata()`로 card를 가져와 :c:func:`snd_card_free()`에 전달합니다. Card에 연결된 component는 ALSA middle layer가 자동으로 해제합니다.
Symbol책임
index/id/enableModule instance별 card slot, identifier, 활성 상태
struct mychipCard pointer와 chip-specific resource
snd_mychip_free()Chip-specific 실제 destructor
snd_mychip_dev_free()snd_device callback에서 실제 destructor 호출
snd_mychip_create()Chip data 할당·초기화와 low-level component 등록
snd_mychip_probe()PCI device를 ALSA card로 구성·등록
snd_mychip_remove()등록된 card와 모든 component 해제
원본 code를 변경하지 않고 각 symbol의 책임을 해설합니다.
snd_card_new() 성공→chip과 하위 component를 card에 attach→중간 실패 시 error label→snd_card_free(card)→등록된 component destructor 자동 실행
Card를 root owner로 삼아 단일 cleanup path를 사용합니다.
Full Code Example
-----------------
The code example is shown below. Some parts are kept unimplemented at
this moment but will be filled in the next sections. The numbers in the
comment lines of the :c:func:`snd_mychip_probe()` function refer
to details explained in the following section.
::
#include <linux/init.h>
#include <linux/pci.h>
#include <linux/slab.h>
#include <sound/core.h>
#include <sound/initval.h>
/* module parameters (see "Module Parameters") */
/* SNDRV_CARDS: maximum number of cards supported by this module */
static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
/* definition of the chip-specific record */
struct mychip {
struct snd_card *card;
/* the rest of the implementation will be in section
* "PCI Resource Management"
*/
};
/* chip-specific destructor
* (see "PCI Resource Management")
*/
static int snd_mychip_free(struct mychip *chip)
{
.... /* will be implemented later... */
}
/* component-destructor
* (see "Management of Cards and Components")
*/
static int snd_mychip_dev_free(struct snd_device *device)
{
return snd_mychip_free(device->device_data);
}
/* chip-specific constructor
* (see "Management of Cards and Components")
*/
static int snd_mychip_create(struct snd_card *card,
struct pci_dev *pci,
struct mychip **rchip)
{
struct mychip *chip;
int err;
static const struct snd_device_ops ops = {
.dev_free = snd_mychip_dev_free,
};
*rchip = NULL;
/* check PCI availability here
* (see "PCI Resource Management")
*/
....
/* allocate a chip-specific data with zero filled */
chip = kzalloc(sizeof(*chip), GFP_KERNEL);
if (chip == NULL)
return -ENOMEM;
chip->card = card;
/* rest of initialization here; will be implemented
* later, see "PCI Resource Management"
*/
....
err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
if (err < 0) {
snd_mychip_free(chip);
return err;
}
*rchip = chip;
return 0;
}
/* constructor -- see "Driver Constructor" sub-section */
static int snd_mychip_probe(struct pci_dev *pci,
const struct pci_device_id *pci_id)
{
static int dev;
struct snd_card *card;
struct mychip *chip;
int err;
/* (1) */
if (dev >= SNDRV_CARDS)
return -ENODEV;
if (!enable[dev]) {
dev++;
return -ENOENT;
}
/* (2) */
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
if (err < 0)
return err;
/* (3) */
err = snd_mychip_create(card, pci, &chip);
if (err < 0)
goto error;
/* (4) */
strcpy(card->driver, "My Chip");
strcpy(card->shortname, "My Own Chip 123");
sprintf(card->longname, "%s at 0x%lx irq %i",
card->shortname, chip->port, chip->irq);
/* (5) */
.... /* implemented later */
/* (6) */
err = snd_card_register(card);
if (err < 0)
goto error;
/* (7) */
pci_set_drvdata(pci, card);
dev++;
return 0;
error:
snd_card_free(card);
return err;
}
/* destructor -- see the "Destructor" sub-section */
static void snd_mychip_remove(struct pci_dev *pci)
{
snd_card_free(pci_get_drvdata(pci));
}
Probe callback과 device index
350-381PCI driver의 실제 constructor는 `probe` callback입니다. PCI device는 hotplug 가능하므로 `probe`에서 호출되는 component constructor를 포함해 이 함수들에는 `__init` prefix를 붙일 수 없습니다.
Static `dev` index가 `SNDRV_CARDS` 이상이면 `-ENODEV`를 반환합니다. Module option인 `enable[dev]`가 false면 index를 증가시키고 `-ENOENT`로 해당 device를 건너뜁니다.
Probe가 호출될 때마다 현재 slot의 사용 가능성을 확인하며, 사용할 수 없는 slot도 반드시 증가시킵니다. 성공 경로에서도 7단계에서 `dev`를 증가시킵니다.
조건동작반환
dev >= SNDRV_CARDS지원 가능한 card 수 초과-ENODEV
!enable[dev]dev 증가 후 slot 건너뜀-ENOENT
Probe 성공PCI driver data 저장 후 dev 증가0
Probe instance와 module option의 관계입니다.
Driver Constructor
------------------
The real constructor of PCI drivers is the ``probe`` callback. The
``probe`` callback and other component-constructors which are called
from the ``probe`` callback cannot be used with the ``__init`` prefix
because any PCI device could be a hotplug device.
In the ``probe`` callback, the following scheme is often used.
1) Check and increment the device index.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
static int dev;
....
if (dev >= SNDRV_CARDS)
return -ENODEV;
if (!enable[dev]) {
dev++;
return -ENOENT;
}
where ``enable[dev]`` is the module option.
Each time the ``probe`` callback is called, check the availability of
the device. If not available, simply increment the device index and
return. dev will be incremented also later (`step 7
<7) Set the PCI driver data and return zero._>`__).
Card와 main component 생성
382-4222단계는 :c:func:`snd_card_new()`에 parent device `&pci->dev`, `index[dev]`, `id[dev]`, `THIS_MODULE`, extra data size `0`, 결과 `&card`를 전달해 card instance를 만듭니다. 자세한 인자는 Card Instance 절에서 설명합니다.
3단계는 :c:func:`snd_mychip_create()`로 PCI resource와 chip-specific component를 만듭니다. 세부 hardware 할당은 뒤의 `PCI Resource Management` 절에서 설명합니다. 실패하면 함수 끝의 단일 `error` path로 이동해 :c:func:`snd_card_free()`를 호출합니다.
각 component가 card에 올바르게 등록되어 자체 destructor를 가지므로 대부분은 :c:func:`snd_card_free()` 한 번으로 모든 중간 resource를 정리할 수 있습니다.
snd_card_new(&pci->dev, ... , &card)→snd_mychip_create(card, pci, &chip)→실패하면 error label→snd_card_free(card)
Owner가 만들어진 뒤 모든 component를 그 owner에 연결합니다.
2) Create a card instance
~~~~~~~~~~~~~~~~~~~~~~~~~
::
struct snd_card *card;
int err;
....
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
The details will be explained in the section `Management of Cards and
Components`_.
3) Create a main component
~~~~~~~~~~~~~~~~~~~~~~~~~~
In this part, the PCI resources are allocated::
struct mychip *chip;
....
err = snd_mychip_create(card, pci, &chip);
if (err < 0)
goto error;
The details will be explained in the section `PCI Resource
Management`_.
When something goes wrong, the probe function needs to deal with the
error. In this example, we have a single error handling path placed
at the end of the function::
error:
snd_card_free(card);
return err;
Since each component can be properly freed, the single
:c:func:`snd_card_free()` call should suffice in most cases.
이름, component, 등록, PCI data
423-4734단계는 `card->driver`, `card->shortname`, `card->longname`을 설정합니다. `driver`는 alsa-lib configurator가 사용하는 최소한의 고유 chip ID여야 하며, 같은 driver 안에서도 chip 기능을 구분하도록 다른 ID를 쓸 수 있습니다.
`shortname`은 사용자가 보는 비교적 자세한 이름이고 `longname`은 `/proc/asound/cards`에 표시할 port와 IRQ 같은 정보를 포함합니다.
5단계에서는 PCM, AC97 같은 mixer, MPU-401 같은 MIDI, 필요하면 proc file 등 기본 component를 만듭니다. 6단계에서 :c:func:`snd_card_register()`를 호출하고 실패하면 공통 error path로 이동합니다.
7단계는 `pci_set_drvdata(pci, card)`로 card pointer를 PCI driver data에 저장하고 `dev`를 증가시킨 뒤 0을 반환합니다. 저장한 pointer는 remove와 power-management callback에서도 사용합니다.
Field용도
card->driveralsa-lib configurator용 단순하고 고유한 chip ID
card->shortname사용자에게 보이는 자세한 card 이름
card->longname/proc/asound/cards에 표시할 port·IRQ 등 상세 정보
각 문자열의 외부 사용 위치와 작성 원칙입니다.
Card ID와 이름 설정→PCM/mixer/MIDI/proc component 생성→snd_card_register(card)→pci_set_drvdata(pci, card)→dev 증가 후 성공 반환
Card identity부터 외부 접근 가능 상태까지의 순서입니다.
4) Set the driver ID and name strings.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
strcpy(card->driver, "My Chip");
strcpy(card->shortname, "My Own Chip 123");
sprintf(card->longname, "%s at 0x%lx irq %i",
card->shortname, chip->port, chip->irq);
The driver field holds the minimal ID string of the chip. This is used
by alsa-lib's configurator, so keep it simple but unique. Even the
same driver can have different driver IDs to distinguish the
functionality of each chip type.
The shortname field is a string shown as more verbose name. The longname
field contains the information shown in ``/proc/asound/cards``.
5) Create other components, such as mixer, MIDI, etc.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here you define the basic components such as `PCM <PCM Interface_>`__,
mixer (e.g. `AC97 <API for AC97 Codec_>`__), MIDI (e.g.
`MPU-401 <MIDI (MPU401-UART) Interface_>`__), and other interfaces.
Also, if you want a `proc file <Proc Interface_>`__, define it here,
too.
6) Register the card instance.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
err = snd_card_register(card);
if (err < 0)
goto error;
Will be explained in the section `Management of Cards and
Components`_, too.
7) Set the PCI driver data and return zero.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
pci_set_drvdata(pci, card);
dev++;
return 0;
In the above, the card record is stored. This pointer is used in the
remove callback and power-management callbacks, too.
Destructor와 필수 header
474-516Remove callback인 destructor는 card instance만 해제하면 됩니다. ALSA middle layer가 attach된 모든 component를 자동 해제하므로 보통 `snd_card_free(pci_get_drvdata(pci))` 호출 하나면 충분합니다. 이 code는 probe에서 card pointer를 PCI driver data에 저장했다는 전제입니다.
기본 예제에는 `<linux/init.h>`, `<linux/pci.h>`, `<linux/slab.h>`, `<sound/core.h>`, `<sound/initval.h>`가 필요합니다. 마지막 `<sound/initval.h>`는 같은 source file에서 module option을 정의할 때만 필요하며, 여러 file로 나눈 경우 option이 없는 file에서는 생략할 수 있습니다.
Interrupt 처리에는 `<linux/interrupt.h>`, I/O access에는 `<linux/io.h>`, :c:func:`mdelay()` 또는 :c:func:`udelay()`에는 `<linux/delay.h>`가 필요합니다. PCM과 control API 같은 ALSA interface header `<sound/xxx.h>`는 `<sound/core.h>` 뒤에 include해야 합니다.
Header필요 조건
linux/init.hModule/init 선언
linux/pci.hPCI driver API
linux/slab.hkzalloc 등 memory allocation
sound/core.hALSA core; 다른 sound header보다 먼저 include
sound/initval.h해당 source에서 module option 정의
linux/interrupt.hInterrupt handling
linux/io.hI/O access
linux/delay.hmdelay()/udelay()
기능별 include와 ordering 제약입니다.
Destructor
----------
The destructor, the remove callback, simply releases the card instance.
Then the ALSA middle layer will release all the attached components
automatically.
It would be typically just calling :c:func:`snd_card_free()`::
static void snd_mychip_remove(struct pci_dev *pci)
{
snd_card_free(pci_get_drvdata(pci));
}
The above code assumes that the card pointer is set to the PCI driver
data.
Header Files
------------
For the above example, at least the following include files are
necessary::
#include <linux/init.h>
#include <linux/pci.h>
#include <linux/slab.h>
#include <sound/core.h>
#include <sound/initval.h>
where the last one is necessary only when module options are defined
in the source file. If the code is split into several files, the files
without module options don't need them.
In addition to these headers, you'll need ``<linux/interrupt.h>`` for
interrupt handling, and ``<linux/io.h>`` for I/O access. If you use the
:c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need
to include ``<linux/delay.h>`` too.
The ALSA interfaces like the PCM and control APIs are defined in other
``<sound/xxx.h>`` header files. They have to be included after
``<sound/core.h>``.
Card instance의 역할과 생성
517-550Sound card마다 `card` record 하나를 할당해야 합니다. 이 record는 sound card의 본부로서 PCM, mixer, MIDI, synthesizer 등 component 전체 목록을 관리합니다.
또한 card ID와 이름, proc file root, power-management state, hotplug disconnect를 관리합니다. Component list는 destruction 때 올바른 순서로 resource를 해제하는 데 사용됩니다.
:c:func:`snd_card_new()`의 여섯 인자는 parent `struct device *`, card index, ID string, 보통 `THIS_MODULE`인 module pointer, extra-data size, 결과 card pointer입니다. `extra_size`가 0보다 크면 chip-specific data를 `card->private_data`로 함께 할당합니다.
첫 인자는 parent device입니다. PCI 예제 code는 `&pci->dev`를 사용합니다. 원문 549줄은 이를 ``&pci->``로 끝내지만, 앞 code와 function signature를 보면 `&pci->dev`를 뜻합니다. 원문 자체는 보존합니다.
순서인자의미
1&pci->devParent device
2indexCard index number
3idCard identifier string
4module / THIS_MODULEOwning module
5extra_sizecard->private_data 추가 할당 크기
6&card생성한 card instance 반환
호출 순서와 card ownership 의미입니다.
Management of Cards and Components
==================================
Card Instance
-------------
For each soundcard, a “card” record must be allocated.
A card record is the headquarters of the soundcard. It manages the whole
list of devices (components) on the soundcard, such as PCM, mixers,
MIDI, synthesizer, and so on. Also, the card record holds the ID and the
name strings of the card, manages the root of proc files, and controls
the power-management states and hotplug disconnections. The component
list on the card record is used to manage the correct release of
resources at destruction.
As mentioned above, to create a card instance, call
:c:func:`snd_card_new()`::
struct snd_card *card;
int err;
err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
The function takes six arguments: the parent device pointer, the
card-index number, the id string, the module pointer (usually
``THIS_MODULE``), the size of extra-data space, and the pointer to
return the card instance. The extra_size argument is used to allocate
card->private_data for the chip-specific data. Note that these data are
allocated by :c:func:`snd_card_new()`.
The first argument, the pointer of struct device, specifies the parent
device. For PCI devices, typically ``&pci->`` is passed there.
snd_device component 관리
551-586Card를 만든 뒤 component를 attach합니다. ALSA driver에서 component는 `struct snd_device` object이며 PCM instance, control interface, raw MIDI interface 등 instance마다 entry 하나가 있습니다.
:c:func:`snd_device_new(card, SNDRV_DEV_XXX, chip, &ops)`는 card pointer, device level, data pointer, callback table을 받습니다. Device level은 component type과 등록·해제 순서를 정하며, 사용자 정의 component는 `SNDRV_DEV_LOWLEVEL`을 사용할 수 있습니다.
이 함수는 data space를 할당하지 않으므로 caller가 먼저 할당한 pointer를 전달해야 합니다. 그 pointer는 component instance identifier 역할도 합니다.
AC97, PCM 같은 미리 정의된 ALSA component constructor는 내부에서 :c:func:`snd_device_new()`를 호출하고 callback table에 destructor도 설정하므로 caller가 별도 destructor를 호출할 필요가 없습니다.
사용자 정의 component라면 `ops.dev_free`에 destructor를 지정해야 :c:func:`snd_card_free()`가 자동 해제할 수 있습니다.
항목책임
cardComponent owner와 lifecycle root
SNDRV_DEV_XXXComponent type 및 register/unregister ordering
chip dataCaller가 미리 할당; instance identifier로 사용
ops.dev_freeUser-defined component destructor
snd_card_free()등록된 component destructor 자동 호출
Component 등록 시 caller와 ALSA core의 책임입니다.
Components
----------
After the card is created, you can attach the components (devices) to
the card instance. In an ALSA driver, a component is represented as a
struct snd_device object. A component
can be a PCM instance, a control interface, a raw MIDI interface, etc.
Each such instance has one component entry.
A component can be created via the :c:func:`snd_device_new()`
function::
snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
data pointer, and the callback pointers (``&ops``). The device-level
defines the type of components and the order of registration and
de-registration. For most components, the device-level is already
defined. For a user-defined component, you can use
``SNDRV_DEV_LOWLEVEL``.
This function itself doesn't allocate the data space. The data must be
allocated manually beforehand, and its pointer is passed as the
argument. This pointer (``chip`` in the above example) is used as the
identifier for the instance.
Each pre-defined ALSA component such as AC97 and PCM calls
:c:func:`snd_device_new()` inside its constructor. The destructor
for each component is defined in the callback pointers. Hence, you don't
need to take care of calling a destructor for such a component.
If you wish to create your own component, you need to set the destructor
function to the dev_free callback in the ``ops``, so that it can be
released automatically via :c:func:`snd_card_free()`. The next
example will show an implementation of chip-specific data.
Card private_data로 chip data 할당
587-619I/O port 주소, resource pointer, IRQ number 같은 chip-specific 정보는 `struct mychip` record에 저장합니다. 할당 방법은 두 가지입니다.
첫 번째 방법은 :c:func:`snd_card_new()`의 다섯 번째 `extra_size` 인자에 `sizeof(struct mychip)`을 전달하는 것입니다. 생성 뒤 `card->private_data`를 `struct mychip *`로 사용합니다.
이 방법은 card와 chip record를 한 번에 할당하므로 별도 allocation이 필요 없고, card instance를 해제할 때 record도 함께 해제됩니다.
snd_card_new(..., sizeof(struct mychip), &card)→chip = card->private_data→Card와 chip data 함께 사용→snd_card_free()에서 함께 해제
Card와 chip data의 lifecycle을 하나로 묶습니다.
Chip-Specific Data
------------------
Chip-specific information, e.g. the I/O port address, its resource
pointer, or the irq number, is stored in the chip-specific record::
struct mychip {
....
};
In general, there are two ways of allocating the chip record.
1. Allocating via :c:func:`snd_card_new()`.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As mentioned above, you can pass the extra-data-length to the 5th
argument of :c:func:`snd_card_new()`, e.g.::
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
sizeof(struct mychip), &card);
struct mychip is the type of the chip record.
In return, the allocated record can be accessed as
::
struct mychip *chip = card->private_data;
With this method, you don't have to allocate twice. The record is
released together with the card instance.
별도 low-level device로 chip data 할당
620-672두 번째 방법은 :c:func:`snd_card_new()`에서 extra data 크기를 0으로 두고 :c:func:`kzalloc()`로 `struct mychip`을 별도 할당하는 것입니다. 원문은 이를 `4th arg`라고 부르지만 예제 signature에서 `0`은 다섯 번째 `extra_size` 인자입니다. 이 불일치는 해설에만 표시하고 원문은 그대로 보존합니다.
별도 chip record에는 최소한 `struct snd_card *card` field가 있어야 하며 생성 직후 `chip->card = card`를 설정합니다.
Field를 초기화한 뒤 `.dev_free = snd_mychip_dev_free`인 `struct snd_device_ops`와 함께 `SNDRV_DEV_LOWLEVEL` device로 등록합니다. Callback은 `device->device_data`를 실제 :c:func:`snd_mychip_free()`에 전달합니다.
이 방식은 code가 길다는 단점이 있지만 `snd_device_ops` 설정을 통해 card 등록과 disconnect 시점에 자체 callback을 실행할 수 있다는 장점이 있습니다.
snd_card_new(..., 0, &card)→kzalloc(sizeof(*chip), GFP_KERNEL)→chip->card = card와 hardware field 초기화→snd_device_new(..., SNDRV_DEV_LOWLEVEL, chip, &ops)→snd_card_free() → ops.dev_free → snd_mychip_free()
명시적 allocation을 card component ordering에 연결합니다.
방식장점단점
card->private_data한 번에 할당하고 card와 함께 자동 해제별도 registration/disconnect callback 없음
별도 SNDRV_DEV_LOWLEVELsnd_device_ops callback을 lifecycle에 연결Allocation·callback code가 더 많음
Allocation과 callback flexibility의 tradeoff입니다.
2. Allocating an extra device.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After allocating a card instance via :c:func:`snd_card_new()`
(with ``0`` on the 4th arg), call :c:func:`kzalloc()`::
struct snd_card *card;
struct mychip *chip;
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
.....
chip = kzalloc(sizeof(*chip), GFP_KERNEL);
The chip record should have the field to hold the card pointer at least,
::
struct mychip {
struct snd_card *card;
....
};
Then, set the card pointer in the returned chip instance::
chip->card = card;
Next, initialize the fields, and register this chip record as a
low-level device with a specified ``ops``::
static const struct snd_device_ops ops = {
.dev_free = snd_mychip_dev_free,
};
....
snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
:c:func:`snd_mychip_dev_free()` is the device-destructor
function, which will call the real destructor::
static int snd_mychip_dev_free(struct snd_device *device)
{
return snd_mychip_free(device->device_data);
}
where :c:func:`snd_mychip_free()` is the real destructor.
The demerit of this method is the obviously larger amount of code.
The merit is, however, that you can trigger your own callback at
registering and disconnecting the card via a setting in snd_device_ops.
About registering and disconnecting the card, see the subsections
below.
Card 등록과 해제
673-690모든 component를 attach한 뒤 :c:func:`snd_card_register()`로 card instance를 등록합니다. 이 호출 시점부터 device file 접근이 활성화되므로 그전에는 외부에서 component에 접근할 수 없어 안전합니다.
등록에 실패하면 :c:func:`snd_card_free()`로 card를 해제하고 probe를 종료합니다. 정상 해제도 같은 함수 하나로 모든 component를 자동 정리할 수 있습니다.
Hotplug 가능한 device는 :c:func:`snd_card_free_when_closed()`를 사용할 수 있습니다. 이 함수는 모든 device가 닫힐 때까지 실제 destruction을 연기합니다.
모든 component attach 완료→snd_card_register()→Device file 외부 접근 활성화→일반 해제: snd_card_free()→Hotplug 해제: snd_card_free_when_closed()로 close까지 연기
외부 접근 가능 시점과 hotplug-safe destruction을 구분합니다.
Registration and Release
------------------------
After all components are assigned, register the card instance by calling
:c:func:`snd_card_register()`. Access to the device files is
enabled at this point. That is, before
:c:func:`snd_card_register()` is called, the components are safely
inaccessible from external side. If this call fails, exit the probe
function after releasing the card via :c:func:`snd_card_free()`.
For releasing the card instance, you can call simply
:c:func:`snd_card_free()`. As mentioned earlier, all components
are released automatically by this call.
For a device which allows hotplugging, you can use
:c:func:`snd_card_free_when_closed()`. This one will postpone
the destruction until all devices are closed.
PCI resource 전체 code
691-824이 절은 chip-specific constructor와 destructor, PCI entry를 완성한 전체 예제를 먼저 제시합니다. `struct mychip`에는 `card`, `pci`, I/O `port`, `irq`가 들어갑니다.
:c:func:`snd_mychip_free()`는 hardware를 비활성화한 뒤 유효한 IRQ를 :c:func:`free_irq()`로 해제하고, :c:func:`pci_release_regions()`, :c:func:`pci_disable_device()`, :c:func:`kfree()` 순서로 resource를 정리합니다.
:c:func:`snd_mychip_create()`는 :c:func:`pci_enable_device()`로 device를 활성화하고 28-bit streaming·consistent DMA mask를 설정합니다. Chip record를 할당한 뒤 `irq = -1`로 초기화하고 PCI region, BAR 0 port, shared IRQ를 확보합니다.
IRQ 요청에 성공한 뒤에만 `chip->irq = pci->irq`를 설정하며 full code는 `card->sync_irq = chip->irq`도 기록합니다. Hardware 초기화 뒤 chip을 `SNDRV_DEV_LOWLEVEL` component로 등록합니다.
PCI ID table은 vendor/device ID와 all-zero terminator를 가지며 `MODULE_DEVICE_TABLE`로 export합니다. `struct pci_driver`는 `KBUILD_MODNAME`, ID table, probe, remove를 연결하고 module init/exit에서 :c:func:`pci_register_driver()`와 :c:func:`pci_unregister_driver()`를 호출합니다. `EXPORT_NO_SYMBOLS`는 old kernel 전용입니다.
Acquire/설정Release/해제
pci_enable_device()pci_disable_device()
pci_set_dma_mask() / pci_set_consistent_dma_mask()Device disable과 함께 종료
kzalloc(chip)kfree(chip)
pci_request_regions()pci_release_regions()
request_irq(..., chip)free_irq(chip->irq, chip)
snd_device_new(..., SNDRV_DEV_LOWLEVEL, ...)snd_card_free()가 dev_free callback 호출
pci_register_driver()pci_unregister_driver()
Constructor와 destructor가 같은 resource를 반대 순서로 처리합니다.
pci_enable_device()→28-bit DMA mask 설정→kzalloc()과 irq=-1 초기화→pci_request_regions()와 BAR 0 기록→request_irq(IRQF_SHARED)와 sync_irq 기록→Hardware 초기화→snd_device_new(SNDRV_DEV_LOWLEVEL)
실패 시점마다 이미 확보한 resource만 해제할 수 있게 상태를 구축합니다.
PCI Resource Management
=======================
Full Code Example
-----------------
In this section, we'll complete the chip-specific constructor,
destructor and PCI entries. Example code is shown first, below::
struct mychip {
struct snd_card *card;
struct pci_dev *pci;
unsigned long port;
int irq;
};
static int snd_mychip_free(struct mychip *chip)
{
/* disable hardware here if any */
.... /* (not implemented in this document) */
/* release the irq */
if (chip->irq >= 0)
free_irq(chip->irq, chip);
/* release the I/O ports & memory */
pci_release_regions(chip->pci);
/* disable the PCI entry */
pci_disable_device(chip->pci);
/* release the data */
kfree(chip);
return 0;
}
/* chip-specific constructor */
static int snd_mychip_create(struct snd_card *card,
struct pci_dev *pci,
struct mychip **rchip)
{
struct mychip *chip;
int err;
static const struct snd_device_ops ops = {
.dev_free = snd_mychip_dev_free,
};
*rchip = NULL;
/* initialize the PCI entry */
err = pci_enable_device(pci);
if (err < 0)
return err;
/* check PCI availability (28bit DMA) */
if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
printk(KERN_ERR "error to set 28bit mask DMA\n");
pci_disable_device(pci);
return -ENXIO;
}
chip = kzalloc(sizeof(*chip), GFP_KERNEL);
if (chip == NULL) {
pci_disable_device(pci);
return -ENOMEM;
}
/* initialize the stuff */
chip->card = card;
chip->pci = pci;
chip->irq = -1;
/* (1) PCI resource allocation */
err = pci_request_regions(pci, "My Chip");
if (err < 0) {
kfree(chip);
pci_disable_device(pci);
return err;
}
chip->port = pci_resource_start(pci, 0);
if (request_irq(pci->irq, snd_mychip_interrupt,
IRQF_SHARED, KBUILD_MODNAME, chip)) {
printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
snd_mychip_free(chip);
return -EBUSY;
}
chip->irq = pci->irq;
card->sync_irq = chip->irq;
/* (2) initialization of the chip hardware */
.... /* (not implemented in this document) */
err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
if (err < 0) {
snd_mychip_free(chip);
return err;
}
*rchip = chip;
return 0;
}
/* PCI IDs */
static struct pci_device_id snd_mychip_ids[] = {
{ PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
....
{ 0, }
};
MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
/* pci_driver definition */
static struct pci_driver driver = {
.name = KBUILD_MODNAME,
.id_table = snd_mychip_ids,
.probe = snd_mychip_probe,
.remove = snd_mychip_remove,
};
/* module initialization */
static int __init alsa_card_mychip_init(void)
{
return pci_register_driver(&driver);
}
/* module clean up */
static void __exit alsa_card_mychip_exit(void)
{
pci_unregister_driver(&driver);
}
module_init(alsa_card_mychip_init)
module_exit(alsa_card_mychip_exit)
EXPORT_NO_SYMBOLS; /* for old kernels only */
PCI enable과 DMA mask
825-850PCI resource 할당은 `probe`에서 수행하며 보통 별도 :c:func:`xxx_create()` 함수로 분리합니다. Resource를 할당하기 전에 반드시 :c:func:`pci_enable_device()`를 먼저 호출해야 합니다.
Device가 접근할 수 있는 DMA address 범위를 제한하도록 적절한 PCI DMA mask도 설정합니다. 예제는 :c:func:`pci_set_dma_mask()`와 :c:func:`pci_set_consistent_dma_mask()` 모두에 `DMA_BIT_MASK(28)`을 요구하며, 실패하면 device를 disable하고 `-ENXIO`를 반환합니다.
일부 device는 bus mastering을 위해 :c:func:`pci_set_master()` 호출도 필요합니다.
단계API실패 처리
Device 활성화pci_enable_device(pci)그 error를 반환
Streaming DMA 범위pci_set_dma_mask(..., DMA_BIT_MASK(28))Device disable 후 -ENXIO
Consistent DMA 범위pci_set_consistent_dma_mask(..., DMA_BIT_MASK(28))Device disable 후 -ENXIO
필요한 bus masterpci_set_master(pci)Device 요구에 따라 적용
실제 region과 IRQ를 잡기 전에 확인할 항목입니다.
Some Hafta's
------------
The allocation of PCI resources is done in the ``probe`` function, and
usually an extra :c:func:`xxx_create()` function is written for this
purpose.
In the case of PCI devices, you first have to call the
:c:func:`pci_enable_device()` function before allocating
resources. Also, you need to set the proper PCI DMA mask to limit the
accessed I/O range. In some cases, you might need to call
:c:func:`pci_set_master()` function, too.
Suppose a 28bit mask, the code to be added would look like::
err = pci_enable_device(pci);
if (err < 0)
return err;
if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
printk(KERN_ERR "error to set 28bit mask DMA\n");
pci_disable_device(pci);
return -ENXIO;
}
I/O port와 region 할당
851-893I/O port와 IRQ는 표준 kernel 함수로 할당하고 destructor에서 반드시 해제해야 합니다. 예제는 8-byte I/O port와 interrupt 하나를 가진 PCI device를 가정해 `struct mychip`에 `unsigned long port`와 `int irq`를 둡니다.
IRQ 0도 유효하므로 실제 할당 전에 `irq`를 `-1`로 초기화해야 합니다. Port 주소와 resource pointer는 :c:func:`kzalloc()`가 0으로 채우므로 별도 reset이 필요하지 않습니다.
:c:func:`pci_request_regions(pci, "My Chip")`으로 PCI device의 region을 예약하고 BAR 0 주소를 :c:func:`pci_resource_start(pci, 0)`에서 얻습니다. 실패하면 chip을 해제하고 PCI device를 disable합니다.
원문은 이어서 `chip->res_port`가 :c:func:`request_region()` 내부의 :c:func:`kmalloc()`로 할당돼 :c:func:`kfree()`가 필요하다고 설명하지만, 앞의 code는 `pci_request_regions()`와 `chip->port`를 사용합니다. 뒤의 해제 절에서 두 API 계열을 각각 구분하므로 이 표기 차이를 해설에만 기록하고 원문은 보존합니다.
Field초기값이유
chip->port0kzalloc()가 초기화; pci_resource_start()로 BAR 주소 기록
chip->res_portNULLrequest_region() 계열 pointer를 쓸 경우의 예
chip->irq-1IRQ 0이 유효하므로 음수로 미할당 상태 표시
Zero initialization과 별도 invalid sentinel이 필요한 field를 구분합니다.
chip allocation과 PCI enable 완료→pci_request_regions(pci, "My Chip")→실패: kfree(chip) + pci_disable_device(pci)→성공: chip->port = pci_resource_start(pci, 0)
실패 시 device와 memory ownership을 되돌립니다.
Resource Allocation
-------------------
The allocation of I/O ports and irqs is done via standard kernel
functions. These resources must be released in the destructor
function (see below).
Now assume that the PCI device has an I/O port with 8 bytes and an
interrupt. Then struct mychip will have the
following fields::
struct mychip {
struct snd_card *card;
unsigned long port;
int irq;
};
For an I/O port (and also a memory region), you need to have the
resource pointer for the standard resource management. For an irq, you
have to keep only the irq number (integer). But you need to initialize
this number to -1 before actual allocation, since irq 0 is valid. The
port address and its resource pointer can be initialized as null by
:c:func:`kzalloc()` automatically, so you don't have to take care of
resetting them.
The allocation of an I/O port is done like this::
err = pci_request_regions(pci, "My Chip");
if (err < 0) {
kfree(chip);
pci_disable_device(pci);
return err;
}
chip->port = pci_resource_start(pci, 0);
It will reserve the I/O port region of 8 bytes of the given PCI device.
The returned value, ``chip->res_port``, is allocated via
:c:func:`kmalloc()` by :c:func:`request_region()`. The pointer
must be released via :c:func:`kfree()`, but there is a problem with
this. This issue will be explained later.
Shared IRQ와 PCM 동기화
894-935:c:func:`request_irq()`에는 PCI IRQ, :c:func:`snd_mychip_interrupt()`, `IRQF_SHARED`, `KBUILD_MODNAME`, handler에 전달할 `chip` pointer를 줍니다. 실패하면 constructor가 :c:func:`snd_mychip_free()`를 호출하고 `-EBUSY`를 반환합니다.
`chip->irq`는 :c:func:`request_irq()`가 성공한 뒤에만 설정합니다. PCI bus에서는 interrupt 공유가 가능하므로 `IRQF_SHARED`를 사용하며 마지막 `dev_id` 인자는 handler가 chip-specific record를 되찾는 데 씁니다.
Handler의 기본 signature는 `static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)`이며 `dev_id`를 `struct mychip *`로 변환하고 처리 뒤 `IRQ_HANDLED`를 반환합니다. 실제 PCM interrupt 처리는 뒤 절에서 설명합니다.
IRQ를 card의 sync field에 전달하면 PCM core가 `hw_free` 전처럼 필요한 시점에 :c:func:`synchronize_irq()`를 자동 호출합니다. Full code 776줄은 `card->sync_irq = chip->irq`를 쓰지만 설명 예제 930줄은 `card->irq = chip->irq`라고 적습니다. 문맥과 뒤의 `sync_stop callback` 설명은 synchronization field를 뜻하므로 차이를 해설에 표시하되 두 원문 표기를 모두 보존합니다.
인자예제 값역할
IRQ numberpci->irqPCI device interrupt line
Handlersnd_mychip_interruptInterrupt service routine
FlagsIRQF_SHAREDPCI shared interrupt 허용
NameKBUILD_MODNAMEInterrupt owner 이름
dev_idchipHandler context이자 free_irq() 식별자
Shared PCI interrupt 등록에 사용한 값입니다.
request_irq(..., IRQF_SHARED, ..., chip)→성공하면 chip->irq = pci->irq→Card sync IRQ field에 전달→PCM core가 필요한 시점에 synchronize_irq()→Destructor에서 free_irq(chip->irq, chip)
성공 뒤에만 state를 publish합니다.
The allocation of an interrupt source is done like this::
if (request_irq(pci->irq, snd_mychip_interrupt,
IRQF_SHARED, KBUILD_MODNAME, chip)) {
printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
snd_mychip_free(chip);
return -EBUSY;
}
chip->irq = pci->irq;
where :c:func:`snd_mychip_interrupt()` is the interrupt handler
defined `later <PCM Interrupt Handler_>`__. Note that
``chip->irq`` should be defined only when :c:func:`request_irq()`
succeeded.
On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
as the interrupt flag of :c:func:`request_irq()`.
The last argument of :c:func:`request_irq()` is the data pointer
passed to the interrupt handler. Usually, the chip-specific record is
used for that, but you can use what you like, too.
I won't give details about the interrupt handler at this point, but at
least its appearance can be explained now. The interrupt handler looks
usually as follows::
static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
{
struct mychip *chip = dev_id;
....
return IRQ_HANDLED;
}
After requesting the IRQ, you can passed it to ``card->sync_irq``
field::
card->irq = chip->irq;
This allows the PCM core to automatically call
:c:func:`synchronize_irq()` at the right time, like before ``hw_free``.
See the later section `sync_stop callback`_ for details.
Check-and-release destructor
936-987Destructor는 활성화된 hardware를 끄고 확보한 resource를 해제합니다. 초기화가 끝나기 전에도 호출될 수 있으므로 각 resource의 유효성을 먼저 검사하는 `check-and-release` 방식이 안전합니다.
IRQ는 `chip->irq >= 0`일 때만 :c:func:`free_irq(chip->irq, chip)`로 해제합니다. 0이 유효한 IRQ이기 때문에 constructor가 미할당 상태를 `-1`로 초기화해야 합니다.
:c:func:`pci_request_region()` 또는 :c:func:`pci_request_regions()`로 얻은 resource는 각각 :c:func:`pci_release_region()` 또는 :c:func:`pci_release_regions()`로 해제합니다. :c:func:`request_region()`이나 :c:func:`request_mem_region()`을 직접 썼고 pointer를 `chip->res_port`에 보관했다면 :c:func:`release_and_free_resource()`를 사용합니다.
마지막에는 :c:func:`pci_disable_device()`와 :c:func:`kfree(chip)`를 호출합니다. Hardware disable이 필요하면 초기화 완료 flag를 두어 완료 전에 호출된 destructor가 미초기화 hardware를 건드리지 않게 해야 합니다.
Chip data를 `SNDRV_DEV_LOWLEVEL`로 등록하면 destructor는 PCM과 control 같은 다른 component가 모두 해제된 뒤 마지막에 호출됩니다. 원문 982줄의 `SNDRV_DEV_LOWLELVEL`은 앞 code의 `SNDRV_DEV_LOWLEVEL`과 철자가 다르며 원문은 그대로 보존합니다. 이 ordering 덕분에 PCM을 직접 stop할 필요 없이 low-level hardware만 중지하면 됩니다.
ResourceGuard/상태Release
IRQchip->irq >= 0free_irq(chip->irq, chip)
단일 PCI regionpci_request_region() 성공pci_release_region()
모든 PCI regionpci_request_regions() 성공pci_release_regions()
수동 resource pointerchip->res_port != NULLrelease_and_free_resource()
PCI device활성화됨pci_disable_device()
Chip record할당됨kfree(chip)
할당 API에 맞는 해제 API와 guard입니다.
Hardware initialized flag 확인 후 필요하면 disable→irq >= 0이면 IRQ 해제→확보한 region 해제→PCI device disable→Chip record 해제
Constructor의 어느 지점에서도 같은 destructor를 안전하게 호출합니다.
Now let's write the corresponding destructor for the resources above.
The role of destructor is simple: disable the hardware (if already
activated) and release the resources. So far, we have no hardware part,
so the disabling code is not written here.
To release the resources, the “check-and-release” method is a safer way.
For the interrupt, do like this::
if (chip->irq >= 0)
free_irq(chip->irq, chip);
Since the irq number can start from 0, you should initialize
``chip->irq`` with a negative value (e.g. -1), so that you can check
the validity of the irq number as above.
When you requested I/O ports or memory regions via
:c:func:`pci_request_region()` or
:c:func:`pci_request_regions()` like in this example, release the
resource(s) using the corresponding function,
:c:func:`pci_release_region()` or
:c:func:`pci_release_regions()`::
pci_release_regions(chip->pci);
When you requested manually via :c:func:`request_region()` or
:c:func:`request_mem_region()`, you can release it via
:c:func:`release_resource()`. Suppose that you keep the resource
pointer returned from :c:func:`request_region()` in
chip->res_port, the release procedure looks like::
release_and_free_resource(chip->res_port);
Don't forget to call :c:func:`pci_disable_device()` before the
end.
And finally, release the chip-specific record::
kfree(chip);
We didn't implement the hardware disabling part above. If you
need to do this, please note that the destructor may be called even
before the initialization of the chip is completed. It would be better
to have a flag to skip hardware disabling if the hardware was not
initialized yet.
When the chip-data is assigned to the card using
:c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL``, its
destructor is called last. That is, it is assured that all other
components like PCMs and controls have already been released. You don't
have to stop PCMs, etc. explicitly, but just call low-level hardware
stopping.
Memory-mapped I/O 관리
988-1032Memory-mapped region의 관리는 I/O port와 거의 같습니다. Chip record에는 physical base인 `unsigned long iobase_phys`와 mapped virtual address인 `void __iomem *iobase_virt`를 둡니다.
:c:func:`pci_request_regions()` 뒤 BAR 0 physical address와 길이를 :c:func:`pci_resource_start()`와 :c:func:`pci_resource_len()`으로 얻어 :c:func:`ioremap()`합니다. Destructor는 `iobase_virt`가 있으면 :c:func:`iounmap()`한 뒤 PCI region을 해제합니다.
더 현대적인 방법은 :c:func:`pci_iomap(pci, 0, 0)`으로 BAR를 mapping하고 destructor에서 짝이 되는 :c:func:`pci_iounmap()`을 호출하는 것입니다.
방식MappingUnmapping
직접 mappingpci_resource_start/len + ioremapiounmap
PCI helperpci_iomap(pci, 0, 0)pci_iounmap
공통 region ownershippci_request_regionspci_release_regions
전통적인 ioremap과 PCI helper의 acquire/release 쌍입니다.
The management of a memory-mapped region is almost as same as the
management of an I/O port. You'll need two fields as follows::
struct mychip {
....
unsigned long iobase_phys;
void __iomem *iobase_virt;
};
and the allocation would look like below::
err = pci_request_regions(pci, "My Chip");
if (err < 0) {
kfree(chip);
return err;
}
chip->iobase_phys = pci_resource_start(pci, 0);
chip->iobase_virt = ioremap(chip->iobase_phys,
pci_resource_len(pci, 0));
and the corresponding destructor would be::
static int snd_mychip_free(struct mychip *chip)
{
....
if (chip->iobase_virt)
iounmap(chip->iobase_virt);
....
pci_release_regions(chip->pci);
....
}
Of course, a modern way with :c:func:`pci_iomap()` will make things a
bit easier, too::
err = pci_request_regions(pci, "My Chip");
if (err < 0) {
kfree(chip);
return err;
}
chip->iobase_virt = pci_iomap(pci, 0, 0);
which is paired with :c:func:`pci_iounmap()` at destructor.
PCI ID, pci_driver, module entry
1033-1094Chipset을 match하려면 `struct pci_device_id` table을 정의합니다. 첫째와 둘째 field는 vendor ID와 device ID이며 추가 filter가 필요 없으면 나머지 match field를 `PCI_ANY_ID` 등 예제처럼 둘 수 있습니다.
마지막 private-data field에는 지원 device ID별 operation을 고르는 임의 값을 넣을 수 있으며 `intel8x0` driver가 그런 예입니다. Table 마지막에는 반드시 모든 field가 0인 terminator entry가 있어야 하고 `MODULE_DEVICE_TABLE(pci, snd_mychip_ids)`로 module device table을 선언합니다.
`struct pci_driver`의 `name`은 `KBUILD_MODNAME`, `id_table`은 ID table, `probe`와 `remove`는 앞에서 만든 callback을 가리킵니다. `name` string에는 slash(`/`)를 사용할 수 없습니다.
Module init은 `__init` prefix와 함께 :c:func:`pci_register_driver()`를 호출하고 module exit는 `__exit` prefix와 함께 :c:func:`pci_unregister_driver()`를 호출합니다. `module_init()`과 `module_exit()`로 두 entry를 등록하면 PCI skeleton이 완성되고, 다음 1095줄의 `PCM Interface` 대단원으로 이어집니다.
Object/field값·역할
pci_device_id vendor/device지원 PCI ID match
pci_device_id private dataDevice ID별 operation 선택용 driver data
All-zero entryID table terminator
MODULE_DEVICE_TABLEPCI ID를 module metadata로 export
pci_driver.nameKBUILD_MODNAME; slash 금지
pci_driver.id_tablesnd_mychip_ids
pci_driver.probe/removeDevice bind/unbind callback
module_init/module_exitPCI driver register/unregister entry
ID match부터 module lifecycle까지 연결되는 object입니다.
module_init(alsa_card_mychip_init)→pci_register_driver(&driver)→PCI core가 snd_mychip_ids와 device match→snd_mychip_probe() 호출→Unload 시 pci_unregister_driver()와 remove 호출
Module load에서 device probe까지의 연결입니다.
PCI Entries
-----------
So far, so good. Let's finish the missing PCI stuff. At first, we need a
struct pci_device_id table for
this chipset. It's a table of PCI vendor/device ID number, and some
masks.
For example::
static struct pci_device_id snd_mychip_ids[] = {
{ PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
....
{ 0, }
};
MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
The first and second fields of the struct pci_device_id are the vendor
and device IDs. If you have no reason to filter the matching devices, you can
leave the remaining fields as above. The last field of the
struct pci_device_id contains private data for this entry. You can specify
any value here, for example, to define specific operations for supported
device IDs. Such an example is found in the intel8x0 driver.
The last entry of this list is the terminator. You must specify this
all-zero entry.
Then, prepare the struct pci_driver
record::
static struct pci_driver driver = {
.name = KBUILD_MODNAME,
.id_table = snd_mychip_ids,
.probe = snd_mychip_probe,
.remove = snd_mychip_remove,
};
The ``probe`` and ``remove`` functions have already been defined in
the previous sections. The ``name`` field is the name string of this
device. Note that you must not use slashes (“/”) in this string.
And at last, the module entries::
static int __init alsa_card_mychip_init(void)
{
return pci_register_driver(&driver);
}
static void __exit alsa_card_mychip_exit(void)
{
pci_unregister_driver(&driver);
}
module_init(alsa_card_mychip_init)
module_exit(alsa_card_mychip_exit)
Note that these module entries are tagged with ``__init`` and ``__exit``
prefixes.
That's all!
PCM instance, stream, substream
1095-1124ALSA PCM middle layer는 device file, open 경합, substream 선택 같은 공통 동작을 담당하므로 driver는 hardware에 접근하는 low-level 함수만 구현하면 됩니다. PCM API의 기본 header는 `<sound/pcm.h>`이며 `hw_param` 관련 helper를 직접 사용할 때는 `<sound/pcm_params.h>`도 포함할 수 있습니다.
Card device 하나에는 최대 네 개의 PCM instance를 둘 수 있고 각 instance는 PCM device file 하나에 대응합니다. 원문은 이 제한이 Linux device number의 가용 bit 수에서만 비롯되며 64-bit device number를 사용하면 더 많은 instance를 제공할 수 있다고 설명합니다.
PCM instance는 playback stream과 capture stream으로 구성되고, 각 stream에는 하나 이상의 PCM substream이 있습니다. 예를 들어 emu10k1 playback은 stereo substream 32개를 제공하며 open할 때 비어 있는 substream이 보통 자동 선택됩니다.
Substream이 하나뿐이고 이미 열렸다면 다음 open은 file open mode에 따라 block되거나 `EAGAIN`으로 실패합니다. 이 선택과 대기 정책은 PCM middle layer가 처리하므로 개별 driver가 중복 구현할 필요가 없습니다.
계층구성·역할
Card device최대 네 PCM instance를 보유
PCM instancePCM device file 하나에 대응
PCM streamPlayback 또는 capture 방향
PCM substreamOpen 시 할당되는 실제 playback/capture endpoint
Device file에서 실제 stream endpoint까지의 계층입니다.
PCM device file open→가용 substream 탐색→가용 항목이 있으면 자동 선택→없으면 mode에 따라 block 또는 EAGAIN
Middle layer가 가용 substream과 file mode를 기준으로 open을 처리합니다.
PCM Interface
=============
General
-------
The PCM middle layer of ALSA is quite powerful and it is only necessary
for each driver to implement the low-level functions to access its
hardware.
To access the PCM layer, you need to include ``<sound/pcm.h>``
first. In addition, ``<sound/pcm_params.h>`` might be needed if you
access some functions related with hw_param.
Each card device can have up to four PCM instances. A PCM instance
corresponds to a PCM device file. The limitation of number of instances
comes only from the available bit size of Linux' device numbers.
Once 64bit device numbers are used, we'll have more PCM instances
available.
A PCM instance consists of PCM playback and capture streams, and each
PCM stream consists of one or more PCM substreams. Some soundcards
support multiple playback functions. For example, emu10k1 has a PCM
playback of 32 stereo substreams. In this case, at each open, a free
substream is (usually) automatically chosen and opened. Meanwhile, when
only one substream exists and it was already opened, a subsequent open
will either block or error with ``EAGAIN`` according to the file open
mode. But you don't have to care about such details in your driver. The
PCM middle layer will take care of such work.
PCM interface 전체 골격
1125-1331이 full code example은 실제 hardware access routine을 생략하고 PCM interface를 세우는 전체 골격만 보여 줍니다. Playback과 capture 각각의 `struct snd_pcm_hardware`는 mmap, interleaved access, block transfer, mmap validity를 알리고, signed 16-bit little-endian format, 8~48 kHz, stereo 2 channel, 최대 32768-byte buffer와 period 범위를 선언합니다.
Playback·capture `open` callback은 :c:func:`snd_pcm_substream_chip()`으로 chip을 얻고 `substream->runtime`의 `hw`에 해당 방향의 hardware capability를 복사합니다. `close`는 방향별 hardware 정리를 수행하는 자리이며 모든 callback은 성공하면 0을 반환하는 형태입니다.
공통 `hw_params`와 `hw_free` callback은 협상된 hardware parameter에 맞춘 resource 확보와 해제를 담당할 자리입니다. `prepare`는 `runtime->format`, `runtime->rate`, `runtime->channels`, DMA address, buffer size, period size를 사용해 시작 직전 hardware를 programming합니다.
`trigger`는 `SNDRV_PCM_TRIGGER_START`와 `SNDRV_PCM_TRIGGER_STOP` command에 따라 PCM engine을 시작하거나 멈추고 알 수 없는 command에는 `-EINVAL`을 반환합니다. 원문 골격 1250~1266줄에는 START/STOP 처리 뒤 성공을 반환하는 문장이 보이지 않습니다. 이는 원문을 수정하지 않고 해설에만 기록하며, 실제 구현은 callback의 `int` 반환 계약에 맞게 성공 값을 반환해야 합니다.
`pointer` callback은 현재 hardware pointer를 읽어 PCM 위치를 돌려줍니다. Playback과 capture의 `struct snd_pcm_ops`는 각 방향의 `open`·`close`와 공통 `hw_params`, `hw_free`, `prepare`, `trigger`, `pointer`를 연결합니다.
:c:func:`snd_pcm_new()`는 card에 index 0 PCM을 만들면서 playback substream 하나와 capture substream 하나를 요청합니다. 생성 뒤 `pcm->private_data`, 표시 이름, `chip->pcm`을 설정하고 :c:func:`snd_pcm_set_ops()`로 두 stream의 operation table을 연결합니다.
마지막 :c:func:`snd_pcm_set_managed_buffer_all()`은 `SNDRV_DMA_TYPE_DEV`와 PCI device를 사용해 모든 substream에 64 KiB managed buffer를 사전 설정합니다. 원문 주석처럼 buffer allocation은 실패할 수 있으므로 실제 driver는 사용 API의 반환·할당 결과를 해당 kernel version의 계약에 맞춰 다뤄야 합니다.
Field예제 값
infoSNDRV_PCM_INFO_MMAP | SNDRV_PCM_INFO_INTERLEAVED | SNDRV_PCM_INFO_BLOCK_TRANSFER | SNDRV_PCM_INFO_MMAP_VALID
formatsSNDRV_PCM_FMTBIT_S16_LE
ratesSNDRV_PCM_RATE_8000_48000
rate_min / rate_max8000 / 48000 Hz
channels_min / channels_max2 / 2
buffer_bytes_max32768 bytes
period_bytes_min / max4096 / 32768 bytes
periods_min / max1 / 1024
Playback과 capture에 공통으로 선언한 범위입니다.
Callback핵심 책임
open / closeRuntime capability 설정과 방향별 hardware open/close
hw_params / hw_free협상 parameter에 따른 resource 확보·해제
prepareFormat, rate, channel, DMA와 period를 hardware에 programming
triggerSTART/STOP command로 PCM engine 제어
pointer현재 hardware playback/capture 위치 반환
Operation table에 연결되는 callback의 책임입니다.
snd_pcm_hardware 정의→open/close와 공통 callback 구현→snd_pcm_ops에 callback 연결→snd_pcm_new(card, id, 0, 1, 1, &pcm)→Playback/capture ops 설정→Managed DMA buffer 사전 설정
Capability 선언부터 managed buffer까지의 생성 순서입니다.
Full Code Example
-----------------
The example code below does not include any hardware access routines but
shows only the skeleton, how to build up the PCM interfaces::
#include <sound/pcm.h>
....
/* hardware definition */
static struct snd_pcm_hardware snd_mychip_playback_hw = {
.info = (SNDRV_PCM_INFO_MMAP |
SNDRV_PCM_INFO_INTERLEAVED |
SNDRV_PCM_INFO_BLOCK_TRANSFER |
SNDRV_PCM_INFO_MMAP_VALID),
.formats = SNDRV_PCM_FMTBIT_S16_LE,
.rates = SNDRV_PCM_RATE_8000_48000,
.rate_min = 8000,
.rate_max = 48000,
.channels_min = 2,
.channels_max = 2,
.buffer_bytes_max = 32768,
.period_bytes_min = 4096,
.period_bytes_max = 32768,
.periods_min = 1,
.periods_max = 1024,
};
/* hardware definition */
static struct snd_pcm_hardware snd_mychip_capture_hw = {
.info = (SNDRV_PCM_INFO_MMAP |
SNDRV_PCM_INFO_INTERLEAVED |
SNDRV_PCM_INFO_BLOCK_TRANSFER |
SNDRV_PCM_INFO_MMAP_VALID),
.formats = SNDRV_PCM_FMTBIT_S16_LE,
.rates = SNDRV_PCM_RATE_8000_48000,
.rate_min = 8000,
.rate_max = 48000,
.channels_min = 2,
.channels_max = 2,
.buffer_bytes_max = 32768,
.period_bytes_min = 4096,
.period_bytes_max = 32768,
.periods_min = 1,
.periods_max = 1024,
};
/* open callback */
static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
{
struct mychip *chip = snd_pcm_substream_chip(substream);
struct snd_pcm_runtime *runtime = substream->runtime;
runtime->hw = snd_mychip_playback_hw;
/* more hardware-initialization will be done here */
....
return 0;
}
/* close callback */
static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
{
struct mychip *chip = snd_pcm_substream_chip(substream);
/* the hardware-specific codes will be here */
....
return 0;
}
/* open callback */
static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
{
struct mychip *chip = snd_pcm_substream_chip(substream);
struct snd_pcm_runtime *runtime = substream->runtime;
runtime->hw = snd_mychip_capture_hw;
/* more hardware-initialization will be done here */
....
return 0;
}
/* close callback */
static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
{
struct mychip *chip = snd_pcm_substream_chip(substream);
/* the hardware-specific codes will be here */
....
return 0;
}
/* hw_params callback */
static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
struct snd_pcm_hw_params *hw_params)
{
/* the hardware-specific codes will be here */
....
return 0;
}
/* hw_free callback */
static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
{
/* the hardware-specific codes will be here */
....
return 0;
}
/* prepare callback */
static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
{
struct mychip *chip = snd_pcm_substream_chip(substream);
struct snd_pcm_runtime *runtime = substream->runtime;
/* set up the hardware with the current configuration
* for example...
*/
mychip_set_sample_format(chip, runtime->format);
mychip_set_sample_rate(chip, runtime->rate);
mychip_set_channels(chip, runtime->channels);
mychip_set_dma_setup(chip, runtime->dma_addr,
chip->buffer_size,
chip->period_size);
return 0;
}
/* trigger callback */
static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
int cmd)
{
switch (cmd) {
case SNDRV_PCM_TRIGGER_START:
/* do something to start the PCM engine */
....
break;
case SNDRV_PCM_TRIGGER_STOP:
/* do something to stop the PCM engine */
....
break;
default:
return -EINVAL;
}
}
/* pointer callback */
static snd_pcm_uframes_t
snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
{
struct mychip *chip = snd_pcm_substream_chip(substream);
unsigned int current_ptr;
/* get the current hardware pointer */
current_ptr = mychip_get_hw_pointer(chip);
return current_ptr;
}
/* operators */
static struct snd_pcm_ops snd_mychip_playback_ops = {
.open = snd_mychip_playback_open,
.close = snd_mychip_playback_close,
.hw_params = snd_mychip_pcm_hw_params,
.hw_free = snd_mychip_pcm_hw_free,
.prepare = snd_mychip_pcm_prepare,
.trigger = snd_mychip_pcm_trigger,
.pointer = snd_mychip_pcm_pointer,
};
/* operators */
static struct snd_pcm_ops snd_mychip_capture_ops = {
.open = snd_mychip_capture_open,
.close = snd_mychip_capture_close,
.hw_params = snd_mychip_pcm_hw_params,
.hw_free = snd_mychip_pcm_hw_free,
.prepare = snd_mychip_pcm_prepare,
.trigger = snd_mychip_pcm_trigger,
.pointer = snd_mychip_pcm_pointer,
};
/*
* definitions of capture are omitted here...
*/
/* create a pcm device */
static int snd_mychip_new_pcm(struct mychip *chip)
{
struct snd_pcm *pcm;
int err;
err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
if (err < 0)
return err;
pcm->private_data = chip;
strcpy(pcm->name, "My Chip");
chip->pcm = pcm;
/* set operators */
snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
&snd_mychip_playback_ops);
snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
&snd_mychip_capture_ops);
/* pre-allocation of buffers */
/* NOTE: this may fail */
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
&chip->pci->dev,
64*1024, 64*1024);
return 0;
}
PCM constructor와 stream operation
1332-1418PCM instance는 :c:func:`snd_pcm_new()`로 할당하며 보통 `snd_mychip_new_pcm()` 같은 전용 constructor에 생성 절차를 모읍니다. 예제는 반환된 `struct snd_pcm *`에 chip을 private data로 연결하고 이름과 `chip->pcm` 역참조를 설정합니다.
:c:func:`snd_pcm_new()`의 여섯 인자는 차례로 소속 card pointer, ID string, PCM index, playback substream 수, capture substream 수, 결과 PCM pointer입니다. Index는 0부터 시작하므로 두 번째 PCM device에는 1처럼 서로 다른 값을 써야 합니다.
Playback 또는 capture 기능이 없으면 해당 substream 수에 0을 전달합니다. 여러 playback/capture를 지원하면 더 큰 수를 지정할 수 있지만 `open`, `close` 등 callback에서 각 substream을 올바르게 구별해야 하며 현재 번호는 `substream->number`에서 얻습니다.
PCM 생성 뒤 :c:func:`snd_pcm_set_ops()`를 playback과 capture 각각에 호출해 `struct snd_pcm_ops`를 연결합니다. 전형적인 table은 `open`, `close`, `hw_params`, `hw_free`, `prepare`, `trigger`, `pointer` callback으로 구성되며 각 callback의 자세한 계약은 뒤 `Operators` 절에서 설명합니다.
Operation 설정 뒤 :c:func:`snd_pcm_set_managed_buffer_all()`로 managed allocation mode를 구성할 수 있습니다. 예제의 최소·최대 크기는 모두 `64*1024`여서 기본적으로 최대 64 KiB buffer를 할당하며 세부 사항은 뒤 `Buffer and Memory Management` 절에서 다룹니다.
PCM 전체의 추가 capability는 `pcm->info_flags`에 기록합니다. 값은 `<sound/asound.h>`의 `SNDRV_PCM_INFO_XXX`이며 hardware definition에도 쓰입니다. Chip이 half-duplex만 지원한다면 `SNDRV_PCM_INFO_HALF_DUPLEX`를 설정합니다.
순서예제의미
1chip->cardPCM이 속할 card
2"My Chip"PCM ID string
300부터 시작하는 PCM index
41Playback substream 수
51Capture substream 수
6&pcm생성된 PCM pointer 반환 위치
PCM instance 생성에 전달하는 여섯 값입니다.
설정목적
pcm->private_data = chipCallback에서 chip context 회수
pcm->name / chip->pcm표시 이름과 driver 역참조
snd_pcm_set_ops()Playback·capture operation table 연결
snd_pcm_set_managed_buffer_all()모든 substream의 managed DMA buffer 구성
pcm->info_flagsHalf-duplex 등 PCM 공통 capability 표시
생성된 instance에 driver 관계와 capability를 연결합니다.
snd_pcm_new()→private_data와 이름 설정→Playback ops 연결→Capture ops 연결→Managed buffer 설정→필요하면 info_flags 설정
Instance 생성 후 stream별 동작과 memory policy를 결합합니다.
PCM Constructor
---------------
A PCM instance is allocated by the :c:func:`snd_pcm_new()`
function. It would be better to create a constructor for the PCM, namely::
static int snd_mychip_new_pcm(struct mychip *chip)
{
struct snd_pcm *pcm;
int err;
err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
if (err < 0)
return err;
pcm->private_data = chip;
strcpy(pcm->name, "My Chip");
chip->pcm = pcm;
...
return 0;
}
The :c:func:`snd_pcm_new()` function takes six arguments. The
first argument is the card pointer to which this PCM is assigned, and
the second is the ID string.
The third argument (``index``, 0 in the above) is the index of this new
PCM. It begins from zero. If you create more than one PCM instances,
specify the different numbers in this argument. For example, ``index =
1`` for the second PCM device.
The fourth and fifth arguments are the number of substreams for playback
and capture, respectively. Here 1 is used for both arguments. When no
playback or capture substreams are available, pass 0 to the
corresponding argument.
If a chip supports multiple playbacks or captures, you can specify more
numbers, but they must be handled properly in open/close, etc.
callbacks. When you need to know which substream you are referring to,
then it can be obtained from struct snd_pcm_substream data passed to each
callback as follows::
struct snd_pcm_substream *substream;
int index = substream->number;
After the PCM is created, you need to set operators for each PCM stream::
snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
&snd_mychip_playback_ops);
snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
&snd_mychip_capture_ops);
The operators are defined typically like this::
static struct snd_pcm_ops snd_mychip_playback_ops = {
.open = snd_mychip_pcm_open,
.close = snd_mychip_pcm_close,
.hw_params = snd_mychip_pcm_hw_params,
.hw_free = snd_mychip_pcm_hw_free,
.prepare = snd_mychip_pcm_prepare,
.trigger = snd_mychip_pcm_trigger,
.pointer = snd_mychip_pcm_pointer,
};
All the callbacks are described in the Operators_ subsection.
After setting the operators, you probably will want to pre-allocate the
buffer and set up the managed allocation mode.
For that, simply call the following::
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
&chip->pci->dev,
64*1024, 64*1024);
It will allocate a buffer up to 64kB by default. Buffer management
details will be described in the later section `Buffer and Memory
Management`_.
Additionally, you can set some extra information for this PCM in
``pcm->info_flags``. The available values are defined as
``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
hardware definition (described later). When your soundchip supports only
half-duplex, specify it like this::
pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
PCM private data 소멸
1419-1452PCM instance 자체는 middle layer가 자동 해제하므로 driver가 일반적인 PCM destructor를 명시적으로 호출할 필요는 없습니다. 따라서 별도 소멸 callback은 PCM에 종속된 driver-private record를 추가로 만들었을 때만 필요합니다.
그 경우 `pcm->private_free`에 `mychip_pcm_free` 같은 함수를 설정합니다. Callback은 :c:func:`snd_pcm_chip()`으로 `struct mychip *`를 되찾아 `chip->my_private_pcm_data`처럼 driver가 별도로 할당한 data를 :c:func:`kfree()`하고 필요한 추가 정리를 수행합니다.
Constructor에서는 private record를 :c:func:`kmalloc()`한 뒤 `pcm->private_data = chip`과 `pcm->private_free = mychip_pcm_free`를 함께 설정합니다. 이 연결을 통해 PCM lifetime이 끝날 때 middle layer가 driver 전용 resource까지 정리합니다.
이 절 다음 1453줄부터는 `Runtime Pointer - The Chest of PCM Information` 절이 이어지며, `substream->runtime`에 보관되는 PCM 상태와 parameter를 자세히 설명합니다.
대상소유·해제 주체
struct snd_pcm instanceALSA PCM middle layer가 자동 해제
pcm->private_data가 가리키는 chipCard/low-level driver lifetime에서 관리
PCM 전용 추가 recordpcm->private_free callback에서 해제
Core와 driver가 각각 해제할 대상을 구분합니다.
Constructor에서 private record 할당→pcm->private_data에 chip 연결→pcm->private_free 설정→PCM 해제 시 middle layer가 callback 호출→Callback에서 private record 해제
PCM 생성과 해제에 driver-private record를 묶습니다.
... And the Destructor?
-----------------------
The destructor for a PCM instance is not always necessary. Since the PCM
device will be released by the middle layer code automatically, you
don't have to call the destructor explicitly.
The destructor would be necessary if you created special records
internally and needed to release them. In such a case, set the
destructor function to ``pcm->private_free``::
static void mychip_pcm_free(struct snd_pcm *pcm)
{
struct mychip *chip = snd_pcm_chip(pcm);
/* free your own data */
kfree(chip->my_private_pcm_data);
/* do what you like else */
....
}
static int snd_mychip_new_pcm(struct mychip *chip)
{
struct snd_pcm *pcm;
....
/* allocate your own data */
chip->my_private_pcm_data = kmalloc(...);
/* set the destructor */
pcm->private_data = chip;
pcm->private_free = mychip_pcm_free;
....
}
PCM runtime 정보와 소유권
1453-1557PCM substream을 열면 PCM runtime instance가 할당되어 `substream->runtime`에 연결됩니다. 이 pointer에는 `hw_params`·`sw_params` 구성 사본, buffer pointer, mmap record, spinlock 등 PCM 제어에 필요한 대부분의 상태가 모입니다.
`<sound/pcm.h>`의 `struct _snd_pcm_runtime`은 status, hardware parameter, software parameter, auto-silencer 내부 상태, synchronization ID, mmap status/control, locking·scheduling, private data, hardware description·constraint, timer, DMA buffer, 선택적 OSS runtime을 한 object에 보관합니다.
Status에는 trigger master와 timestamp, overrange, 최대 가용 frame, buffer restart·interrupt 시점의 hardware pointer가 있습니다. HW parameter에는 access, format, subformat, rate, channel, period·buffer 크기, alignment, frame/sample bit 수, info와 rate 분수가 들어갑니다.
SW parameter는 timestamp mode, period step, 최소 sleep, start·stop·silence threshold와 silence size, pointer wrap boundary를 포함합니다. Underrun을 완화하기 위해 hardware availability가 threshold 아래로 떨어지면 playback을 멈추거나 buffer를 silence로 미리 채우며, auto-silencer는 시작 pointer와 채운 크기를 별도로 추적합니다.
Mmap 영역에는 `snd_pcm_mmap_status`, `snd_pcm_mmap_control`, mmap reference count가 있고 locking 영역에는 spinlock, wait queue, tick timer, asynchronous notification이 있습니다. Runtime 전용 `private_data`와 `private_free`, `struct snd_pcm_hardware hw`, hardware constraints, timer resolution도 함께 보관됩니다.
DMA 영역의 `dma_area`는 CPU가 접근하는 logical address, `dma_addr`는 physical bus address, `dma_bytes`는 크기이며 `dma_buffer_p`는 할당된 `struct snd_dma_buffer`를 가리킵니다. `CONFIG_SND_PCM_OSS` 또는 module 구성이 켜지면 OSS runtime도 포함됩니다.
Sound driver callback 관점에서 runtime record 대부분은 PCM middle layer만 갱신하는 읽기 전용 값입니다. Driver가 설정할 수 있는 예외는 hardware description인 `hw`, DMA buffer 정보, private data이며, 표준 managed buffer allocation을 사용하면 DMA 정보도 직접 설정할 필요가 없습니다.
영역대표 field용도
Statustrigger_tstamp, avail_max, hw_ptr_*Trigger와 hardware 진행 상태
HW paramsaccess, format, rate, channels, period_size, buffer_size협상된 hardware 구성
SW paramsstart_threshold, stop_threshold, silence_threshold, silence_size시작·정지와 underrun 완화 정책
mmapstatus, control, mmap_countUserspace 공유 상태와 reference
Locking/schedulinglock, sleep, tick_timer, fasync동시성·대기·notification
Private/hardwareprivate_data, hw, hw_constraintsDriver context와 capability
DMAdma_area, dma_addr, dma_bytes, dma_buffer_pPCM sample buffer
OSSoss선택적 OSS emulation runtime
Runtime 구조체 field를 책임별로 다시 묶었습니다.
PCM substream open→snd_pcm_runtime 할당→hw_params와 sw_params 반영→Middle layer가 상태·mmap·lock 갱신→Driver는 hw·DMA·private 영역만 필요에 따라 설정→Substream close에서 runtime 해제
Substream open부터 middle layer와 driver가 runtime을 사용하는 과정입니다.
Runtime Pointer - The Chest of PCM Information
----------------------------------------------
When the PCM substream is opened, a PCM runtime instance is allocated
and assigned to the substream. This pointer is accessible via
``substream->runtime``. This runtime pointer holds most information you
need to control the PCM: a copy of hw_params and sw_params
configurations, the buffer pointers, mmap records, spinlocks, etc.
The definition of runtime instance is found in ``<sound/pcm.h>``. Here
is the relevant part of this file::
struct _snd_pcm_runtime {
/* -- Status -- */
struct snd_pcm_substream *trigger_master;
snd_timestamp_t trigger_tstamp; /* trigger timestamp */
int overrange;
snd_pcm_uframes_t avail_max;
snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
/* -- HW params -- */
snd_pcm_access_t access; /* access mode */
snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
snd_pcm_subformat_t subformat; /* subformat */
unsigned int rate; /* rate in Hz */
unsigned int channels; /* channels */
snd_pcm_uframes_t period_size; /* period size */
unsigned int periods; /* periods */
snd_pcm_uframes_t buffer_size; /* buffer size */
unsigned int tick_time; /* tick time */
snd_pcm_uframes_t min_align; /* Min alignment for the format */
size_t byte_align;
unsigned int frame_bits;
unsigned int sample_bits;
unsigned int info;
unsigned int rate_num;
unsigned int rate_den;
/* -- SW params -- */
struct timespec tstamp_mode; /* mmap timestamp is updated */
unsigned int period_step;
unsigned int sleep_min; /* min ticks to sleep */
snd_pcm_uframes_t start_threshold;
/*
* The following two thresholds alleviate playback buffer underruns; when
* hw_avail drops below the threshold, the respective action is triggered:
*/
snd_pcm_uframes_t stop_threshold; /* - stop playback */
snd_pcm_uframes_t silence_threshold; /* - pre-fill buffer with silence */
snd_pcm_uframes_t silence_size; /* max size of silence pre-fill; when >= boundary,
* fill played area with silence immediately */
snd_pcm_uframes_t boundary; /* pointers wrap point */
/* internal data of auto-silencer */
snd_pcm_uframes_t silence_start; /* starting pointer to silence area */
snd_pcm_uframes_t silence_filled; /* size filled with silence */
snd_pcm_sync_id_t sync; /* hardware synchronization ID */
/* -- mmap -- */
volatile struct snd_pcm_mmap_status *status;
volatile struct snd_pcm_mmap_control *control;
atomic_t mmap_count;
/* -- locking / scheduling -- */
spinlock_t lock;
wait_queue_head_t sleep;
struct timer_list tick_timer;
struct fasync_struct *fasync;
/* -- private section -- */
void *private_data;
void (*private_free)(struct snd_pcm_runtime *runtime);
/* -- hardware description -- */
struct snd_pcm_hardware hw;
struct snd_pcm_hw_constraints hw_constraints;
/* -- timer -- */
unsigned int timer_resolution; /* timer resolution */
/* -- DMA -- */
unsigned char *dma_area; /* DMA area */
dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
size_t dma_bytes; /* size of DMA area */
struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
/* -- OSS things -- */
struct snd_pcm_oss_runtime oss;
#endif
};
For the operators (callbacks) of each sound driver, most of these
records are supposed to be read-only. Only the PCM middle-layer changes
/ updates them. The exceptions are the hardware description (hw) DMA
buffer information and the private data. Besides, if you use the
standard managed buffer allocation mode, you don't need to set the
DMA buffer information by yourself.
In the sections below, important records are explained.
PCM hardware descriptor
1558-1664`struct snd_pcm_hardware`는 PCM hardware의 기본 구성과 capability를 정의하며 `PCM open callback`에서 반드시 `runtime->hw`에 설정합니다. Runtime은 기존 descriptor pointer가 아니라 사본을 보관하므로 공통 정의를 복사한 뒤 model별로 `channels_max` 같은 field를 수정할 수 있습니다.
`info`에는 `<sound/asound.h>`의 `SNDRV_PCM_INFO_XXX` flag를 넣습니다. Mmap 지원 여부와 interleaved·non-interleaved access 지원을 명시해야 하며, 둘 다 지원하면 `SNDRV_PCM_INFO_INTERLEAVED`와 `SNDRV_PCM_INFO_NONINTERLEAVED`를 함께 설정할 수 있습니다.
예제의 `SNDRV_PCM_INFO_MMAP_VALID`와 `SNDRV_PCM_INFO_BLOCK_TRANSFER`는 OSS mmap mode를 위한 flag로 보통 함께 설정하지만, `MMAP_VALID`는 실제 mmap 지원이 있을 때만 유효합니다.
`SNDRV_PCM_INFO_PAUSE`는 pause operation을, `SNDRV_PCM_INFO_RESUME`은 완전한 suspend/resume operation을 뜻합니다. `PAUSE`를 선언하면 `trigger` callback이 pause push/release command를 처리해야 합니다. Suspend/resume trigger command 자체는 `RESUME` flag 없이도 정의할 수 있으며 자세한 내용은 `Power Management` 절에서 다룹니다.
Playback과 capture 등 여러 PCM substream을 동기화해 시작·정지할 수 있다면 `SNDRV_PCM_INFO_SYNC_START`를 줄 수 있습니다. 이 경우 `trigger` callback에서 연결된 PCM substream list를 확인해야 하며 구체적인 처리는 뒤 절에서 설명합니다.
`formats`는 `SNDRV_PCM_FMTBIT_XXX` 지원 format flag의 OR이며 예제는 signed 16-bit little-endian입니다. `rates`는 `SNDRV_PCM_RATE_XXX` flag의 OR이고 연속 rate라면 `CONTINUOUS`, 미리 정의되지 않은 비정형 rate라면 `KNOT`을 추가한 뒤 hardware constraint를 수동 설정합니다.
`rate_min`·`rate_max`는 `rates` bit와 일관된 최소·최대 sample rate, `channels_min`·`channels_max`는 channel 수 범위입니다. `buffer_bytes_max`는 전체 buffer 최대 크기이며 최소 크기는 최소 period 크기와 최소 period 수로 계산할 수 있어 별도 `buffer_bytes_min` field가 없습니다.
`period_bytes_min`·`period_bytes_max`와 `periods_min`·`periods_max`는 period 크기와 buffer 안의 period 수 범위를 정합니다. Period는 OSS의 fragment에 해당하며 PCM interrupt 발생 지점입니다. Period가 작을수록 interrupt가 잦아져 buffer를 더 제때 채우거나 비울 수 있습니다.
Capture에서는 period 크기가 input latency를, playback에서는 전체 buffer 크기가 output latency를 좌우합니다. `fifo_size`는 hardware FIFO 크기이지만 원문 기준 driver와 alsa-lib 모두 사용하지 않으므로 무시할 수 있습니다.
Field의미
infoMmap, interleaving, pause/resume, synchronized start capability
formatsSNDRV_PCM_FMTBIT_XXX format 집합
ratesSNDRV_PCM_RATE_XXX rate 집합과 CONTINUOUS/KNOT
rate_min / rate_maxSample rate 범위
channels_min / channels_maxChannel 수 범위
buffer_bytes_max전체 buffer 최대 byte
period_bytes_min / maxInterrupt period 크기 범위
periods_min / maxBuffer당 period 수 범위
fifo_size현재 driver와 alsa-lib가 사용하지 않는 FIFO 크기
Capability와 buffer geometry를 협상하는 기준입니다.
Flag의미·의무
SNDRV_PCM_INFO_MMAPPCM buffer mmap 지원
SNDRV_PCM_INFO_INTERLEAVEDInterleaved access 지원
SNDRV_PCM_INFO_NONINTERLEAVEDNon-interleaved access 지원
SNDRV_PCM_INFO_PAUSETrigger에서 pause push/release 처리
SNDRV_PCM_INFO_RESUME완전한 suspend/resume 지원
SNDRV_PCM_INFO_SYNC_STARTLinked substream의 동기 start/stop 처리
Flag를 선언하면 callback이 제공해야 하는 동작입니다.
Period 크기 감소→PCM interrupt 빈도 증가→더 빠른 buffer fill/drain→Capture input latency 감소 가능
Playback 전체 buffer 크기→Playback output latency 결정
Period geometry가 interrupt 빈도와 방향별 latency에 미치는 관계입니다.
Hardware Description
~~~~~~~~~~~~~~~~~~~~
The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
the fundamental hardware configuration. Above all, you'll need to define this
in the `PCM open callback`_. Note that the runtime instance holds a copy of
the descriptor, not a pointer to the existing descriptor. That is,
in the open callback, you can modify the copied descriptor
(``runtime->hw``) as you need. For example, if the maximum number of
channels is 1 only on some chip models, you can still use the same
hardware descriptor and change the channels_max later::
struct snd_pcm_runtime *runtime = substream->runtime;
...
runtime->hw = snd_mychip_playback_hw; /* common definition */
if (chip->model == VERY_OLD_ONE)
runtime->hw.channels_max = 1;
Typically, you'll have a hardware descriptor as below::
static struct snd_pcm_hardware snd_mychip_playback_hw = {
.info = (SNDRV_PCM_INFO_MMAP |
SNDRV_PCM_INFO_INTERLEAVED |
SNDRV_PCM_INFO_BLOCK_TRANSFER |
SNDRV_PCM_INFO_MMAP_VALID),
.formats = SNDRV_PCM_FMTBIT_S16_LE,
.rates = SNDRV_PCM_RATE_8000_48000,
.rate_min = 8000,
.rate_max = 48000,
.channels_min = 2,
.channels_max = 2,
.buffer_bytes_max = 32768,
.period_bytes_min = 4096,
.period_bytes_max = 32768,
.periods_min = 1,
.periods_max = 1024,
};
- The ``info`` field contains the type and capabilities of this
PCM. The bit flags are defined in ``<sound/asound.h>`` as
``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
mmap is supported and which interleaving formats are
supported. When the hardware supports mmap, add the
``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
interleaved or the non-interleaved formats, the
``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
flag must be set, respectively. If both are supported, you can set
both, too.
In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
specified for the OSS mmap mode. Usually both are set. Of course,
``MMAP_VALID`` is set only if mmap is really supported.
The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the PCM
supports the “pause” operation, while the ``RESUME`` bit means that
the PCM supports the full “suspend/resume” operation. If the
``PAUSE`` flag is set, the ``trigger`` callback below must handle
the corresponding (pause push/release) commands. The suspend/resume
trigger commands can be defined even without the ``RESUME``
flag. See the `Power Management`_ section for details.
When the PCM substreams can be synchronized (typically,
synchronized start/stop of a playback and a capture stream), you
can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
need to check the linked-list of PCM substreams in the trigger
callback. This will be described in a later section.
- The ``formats`` field contains the bit-flags of supported formats
(``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
format, give all or'ed bits. In the example above, the signed 16bit
little-endian format is specified.
- The ``rates`` field contains the bit-flags of supported rates
(``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
pass the ``CONTINUOUS`` bit additionally. The pre-defined rate bits
are provided only for typical rates. If your chip supports
unconventional rates, you need to add the ``KNOT`` bit and set up
the hardware constraint manually (explained later).
- ``rate_min`` and ``rate_max`` define the minimum and maximum sample
rate. This should correspond somehow to ``rates`` bits.
- ``channels_min`` and ``channels_max`` define, as you might have already
expected, the minimum and maximum number of channels.
- ``buffer_bytes_max`` defines the maximum buffer size in
bytes. There is no ``buffer_bytes_min`` field, since it can be
calculated from the minimum period size and the minimum number of
periods. Meanwhile, ``period_bytes_min`` and ``period_bytes_max``
define the minimum and maximum size of the period in bytes.
``periods_max`` and ``periods_min`` define the maximum and minimum
number of periods in the buffer.
The “period” is a term that corresponds to a fragment in the OSS
world. The period defines the point at which a PCM interrupt is
generated. This point strongly depends on the hardware. Generally,
a smaller period size will give you more interrupts, which results
in being able to fill/drain the buffer more timely. In the case of
capture, this size defines the input latency. On the other hand,
the whole buffer size defines the output latency for the playback
direction.
- There is also a field ``fifo_size``. This specifies the size of the
hardware FIFO, but currently it is neither used by the drivers nor
in the alsa-lib. So, you can ignore this field.
PCM configuration과 frame 단위
1665-1689Application이 alsa-lib를 통해 `hw_params`를 보내면 PCM configuration이 runtime에 저장됩니다. `hw_params`와 `sw_params` 구조체의 여러 field가 복사되며, 예를 들어 `runtime->format`에는 선택한 `SNDRV_PCM_FORMAT_XXX` enum 값이 들어갑니다.
Runtime의 buffer 크기와 period 크기는 byte가 아니라 frame 단위입니다. ALSA에서 한 frame은 `channels * sample-size`이며, byte 변환에는 :c:func:`frames_to_bytes()`와 :c:func:`bytes_to_frames()`를 사용합니다.
Software parameter도 frame 단위인 경우가 많으므로 field type을 확인해야 합니다. `snd_pcm_uframes_t`는 unsigned frame 수, `snd_pcm_sframes_t`는 signed frame 수를 나타냅니다.
항목규칙
1 framechannels * sample-size
frames_to_bytes(runtime, frames)Frame 수를 byte로 변환
bytes_to_frames(runtime, bytes)Byte 수를 frame으로 변환
snd_pcm_uframes_tUnsigned frame count
snd_pcm_sframes_tSigned frame count
Frame과 byte 사이의 변환 및 type 구분입니다.
Application과 alsa-lib가 hw_params 협상→PCM middle layer가 runtime에 parameter 복사→Driver callback이 format/rate/channels 참조→Buffer·period는 frame 단위로 사용
Application 협상 결과가 runtime field로 들어가는 흐름입니다.
PCM Configurations
~~~~~~~~~~~~~~~~~~
Ok, let's go back again to the PCM runtime records. The most
frequently referred records in the runtime instance are the PCM
configurations. The PCM configurations are stored in the runtime
instance after the application sends ``hw_params`` data via
alsa-lib. There are many fields copied from hw_params and sw_params
structs. For example, ``format`` holds the format type chosen by the
application. This field contains the enum value
``SNDRV_PCM_FORMAT_XXX``.
One thing to be noted is that the configured buffer and period sizes
are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
channels \* samples-size``. For conversion between frames and bytes,
you can use the :c:func:`frames_to_bytes()` and
:c:func:`bytes_to_frames()` helper functions::
period_bytes = frames_to_bytes(runtime, runtime->period_size);
Also, many software parameters (sw_params) are stored in frames, too.
Please check the type of the field. ``snd_pcm_uframes_t`` is for
frames as unsigned integer while ``snd_pcm_sframes_t`` is for
frames as signed integer.
PCM DMA buffer 정보
1690-1711DMA buffer 설명은 `dma_area`, `dma_addr`, `dma_bytes`, `dma_private` 네 field를 듭니다. `dma_area`는 :c:func:`memcpy()`로 접근할 수 있는 logical address이고, `dma_addr`는 linear buffer일 때의 physical address이며, `dma_bytes`는 byte 크기, `dma_private`는 ALSA DMA allocator용 private 값입니다.
앞 runtime 구조체 발췌 1535~1540줄에는 `dma_area`, `dma_addr`, `dma_bytes`와 `dma_buffer_p`가 나오지만 이 설명 문단은 네 번째 이름을 `dma_private`라고 부릅니다. 두 표기는 로컬 v6.18.37 원문 그대로 보존하고, 실제 field 사용은 대상 kernel header와 allocator API를 기준으로 확인해야 합니다.
Managed buffer allocation 또는 :c:func:`snd_pcm_lib_malloc_pages()`를 쓰면 ALSA middle layer가 DMA field를 설정하므로 driver는 읽기만 하고 직접 변경하면 안 됩니다.
Driver가 buffer를 자체 할당한다면 `hw_params` callback에서 관리해야 하며 적어도 `dma_bytes`는 필수입니다. `dma_area`는 mmap을 지원할 때 필요하고 mmap 미지원 driver에서는 생략할 수 있습니다. `dma_addr`도 선택 사항이며 `dma_private`는 driver 목적에 맞게 사용할 수 있습니다.
Field의미필수 조건
dma_areaCPU logical addressMmap 지원 시 필요
dma_addrLinear buffer physical/bus address선택
dma_bytesBuffer byte 크기자체 할당 시 필수
dma_privateALSA DMA allocator/private 용도선택
dma_buffer_p구조체 발췌의 allocated buffer pointerHeader/API 계약 확인
PCM buffer 주소와 크기의 의미를 구분합니다.
Managed buffer 또는 snd_pcm_lib_malloc_pages()→ALSA middle layer가 DMA field 설정→Driver는 field를 읽기만 함
Driver 자체 buffer 할당→hw_params에서 수명 관리→dma_bytes와 필요한 주소 field 설정
할당 방식을 먼저 정한 뒤 field 작성 주체를 결정합니다.
DMA Buffer Information
~~~~~~~~~~~~~~~~~~~~~~
The DMA buffer is defined by the following four fields: ``dma_area``,
``dma_addr``, ``dma_bytes`` and ``dma_private``. ``dma_area``
holds the buffer pointer (the logical address). You can call
:c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
the physical address of the buffer. This field is specified only when
the buffer is a linear buffer. ``dma_bytes`` holds the size of the
buffer in bytes. ``dma_private`` is used for the ALSA DMA allocator.
If you use either the managed buffer allocation mode or the standard
API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
these fields are set by the ALSA middle layer, and you should *not*
change them by yourself. You can read them but not write them. On the
other hand, if you want to allocate the buffer by yourself, you'll
need to manage it in the hw_params callback. At least, ``dma_bytes`` is
mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
your driver doesn't support mmap, this field is not
necessary. ``dma_addr`` is also optional. You can use dma_private as
you like, too.
PCM 실행 상태 pointer
1712-1723현재 실행 상태는 `runtime->status`가 가리키는 `struct snd_pcm_mmap_status`에서 확인합니다. 예를 들어 현재 DMA hardware pointer는 `runtime->status->hw_ptr`로 읽을 수 있습니다.
DMA application pointer는 `runtime->control`이 가리키는 `struct snd_pcm_mmap_control`에 있지만 원문은 이 값을 직접 접근하는 방식을 권장하지 않습니다.
경로내용주의
runtime->status->hw_ptr현재 DMA hardware pointermmap status record에서 읽음
runtime->controlDMA application pointer를 담는 mmap control직접 접근 비권장
Hardware와 application 진행 위치의 접근 경로입니다.
Running Status
~~~~~~~~~~~~~~
The running status can be referred via ``runtime->status``. This is
a pointer to a struct snd_pcm_mmap_status record.
For example, you can get the current
DMA hardware pointer via ``runtime->status->hw_ptr``.
The DMA application pointer can be referred via ``runtime->control``,
which points to a struct snd_pcm_mmap_control record.
However, accessing this value directly is not recommended.
Substream runtime private data
1724-1747Substream마다 필요한 동적 record는 보통 `PCM open callback`에서 할당해 `runtime->private_data`에 저장합니다. 이는 PCM device 생성 때 정적으로 chip instance를 가리키도록 설정한 `pcm->private_data`와 혼동하면 안 됩니다.
예제 `snd_xxx_open()`은 `struct my_pcm_data`를 :c:func:`kmalloc(..., GFP_KERNEL)`로 할당한 뒤 `substream->runtime->private_data`에 연결합니다. 이렇게 open마다 만들어진 object는 반드시 대응하는 `close callback`에서 해제해야 합니다.
Pointer생성 시점대상해제 시점
pcm->private_dataPCM device 생성Card/chip 공통 contextPCM/card lifetime
runtime->private_dataSubstream openOpen instance별 동적 contextSubstream close
Lifetime과 적용 범위가 서로 다른 두 pointer입니다.
PCM open callback→kmalloc(sizeof(*data), GFP_KERNEL)→runtime->private_data에 저장→PCM close callback→동적 record 해제
Open/close callback 쌍이 동적 object를 관리합니다.
Private Data
~~~~~~~~~~~~
You can allocate a record for the substream and store it in
``runtime->private_data``. Usually, this is done in the `PCM open
callback`_. Don't mix this with ``pcm->private_data``. The
``pcm->private_data`` usually points to the chip instance assigned
statically at creation time of the PCM device, while
``runtime->private_data``
points to a dynamic data structure created in the PCM open
callback::
static int snd_xxx_open(struct snd_pcm_substream *substream)
{
struct my_pcm_data *data;
....
data = kmalloc(sizeof(*data), GFP_KERNEL);
substream->runtime->private_data = data;
....
}
The allocated object must be released in the `close callback`_.
PCM operator 공통 계약
1748-1773PCM `ops`의 각 callback은 성공하면 0, 실패하면 `-EINVAL` 같은 음수 error를 반환합니다. 적절한 error number는 같은 종류의 요청이 실패할 때 kernel의 다른 부분이 무엇을 반환하는지 확인해 선택하는 것이 좋습니다.
모든 callback은 최소한 `struct snd_pcm_substream *` 인자를 받습니다. :c:func:`snd_pcm_substream_chip()`은 `substream->private_data`에서 chip record를 얻으며, 이 값은 기본적으로 `pcm->private_data`의 사본입니다.
Substream마다 다른 record가 필요하면 `substream->private_data`를 덮어쓸 수 있습니다. 예를 들어 cmi8330 driver는 playback과 capture에 SB-compatible codec과 AD-compatible codec을 각각 사용하므로 방향별 private data를 다르게 연결합니다.
항목규칙
기본 인자struct snd_pcm_substream *substream
Chip 회수snd_pcm_substream_chip(substream)
성공0 반환
실패요청 종류에 맞는 음수 kernel error
방향별 context필요하면 substream->private_data override
모든 operation에 적용되는 context와 반환 규칙입니다.
Operators
---------
OK, now let me give details about each PCM callback (``ops``). In
general, every callback must return 0 if successful, or a negative
error number such as ``-EINVAL``. To choose an appropriate error
number, it is advised to check what value other parts of the kernel
return when the same kind of request fails.
Each callback function takes at least one argument containing a
struct snd_pcm_substream pointer. To retrieve the chip
record from the given substream instance, you can use the following
macro::
int xxx(...) {
struct mychip *chip = snd_pcm_substream_chip(substream);
....
}
The macro reads ``substream->private_data``, which is a copy of
``pcm->private_data``. You can override the former if you need to
assign different data records per PCM substream. For example, the
cmi8330 driver assigns different ``private_data`` for playback and
capture directions, because it uses two different codecs (SB- and
AD-compatible) for different directions.
PCM open callback
1774-1803`snd_xxx_open(struct snd_pcm_substream *substream)`은 PCM substream이 열릴 때 호출됩니다. 최소한 `substream->runtime`을 얻어 미리 정의한 `snd_mychip_playback_hw` 같은 hardware description을 `runtime->hw`에 복사해야 합니다.
Open instance별 private data가 필요하면 이 callback에서 할당해 runtime에 연결할 수 있습니다. Hardware 구성이 기본 descriptor보다 더 좁은 constraint를 필요로 한다면 같은 시점에 hardware constraint도 설정합니다.
PCM substream open→snd_pcm_substream_chip()으로 chip 회수→substream->runtime 획득→runtime->hw 설정→필요하면 private data와 constraint 설정→0 반환
Substream open 시 runtime capability와 instance별 context를 준비합니다.
PCM open callback
~~~~~~~~~~~~~~~~~
::
static int snd_xxx_open(struct snd_pcm_substream *substream);
This is called when a PCM substream is opened.
At least, here you have to initialize the ``runtime->hw``
record. Typically, this is done like this::
static int snd_xxx_open(struct snd_pcm_substream *substream)
{
struct mychip *chip = snd_pcm_substream_chip(substream);
struct snd_pcm_runtime *runtime = substream->runtime;
runtime->hw = snd_mychip_playback_hw;
return 0;
}
where ``snd_mychip_playback_hw`` is the pre-defined hardware
description.
You can allocate private data in this callback, as described in the
`Private Data`_ section.
If the hardware configuration needs more constraints, set the hardware
constraints here, too. See Constraints_ for more details.
PCM close callback
1804-1823`snd_xxx_close(struct snd_pcm_substream *substream)`은 PCM substream을 닫을 때 호출됩니다. `open` callback에서 해당 substream용 private instance를 할당했다면 여기서 `substream->runtime->private_data`를 :c:func:`kfree()`해 수명을 닫아야 합니다.
open: runtime->private_data 할당→Substream 사용→close: kfree(runtime->private_data)
Open마다 생성한 object를 같은 substream close에서 해제합니다.
close callback
~~~~~~~~~~~~~~
::
static int snd_xxx_close(struct snd_pcm_substream *substream);
Obviously, this is called when a PCM substream is closed.
Any private instance for a PCM substream allocated in the ``open``
callback will be released here::
static int snd_xxx_close(struct snd_pcm_substream *substream)
{
....
kfree(substream->runtime->private_data);
....
}
PCM ioctl callback
1824-1832PCM 전용 특수 ioctl 처리가 없다면 `ioctl` callback은 `NULL`로 둘 수 있고 PCM core가 generic :c:func:`snd_pcm_lib_ioctl()`을 호출합니다. Channel information을 독특하게 구성하거나 별도 reset 절차가 필요할 때만 driver 고유 callback을 연결합니다.
조건설정
표준 PCM ioctlops.ioctl = NULL; snd_pcm_lib_ioctl() 사용
특수 channel info 또는 resetDriver 전용 ioctl callback 구현
일반 처리와 device-specific 처리를 구분합니다.
ioctl callback
~~~~~~~~~~~~~~
This is used for any special call to PCM ioctls. But usually you can
leave it NULL, then the PCM core calls the generic ioctl callback
function :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with a
unique setup of channel info or reset procedure, you can pass your own
callback function here.
hw_params callback
1833-1877`snd_xxx_hw_params(substream, hw_params)`는 application이 buffer 크기, period 크기, format 등 hardware parameter를 확정할 때 호출됩니다. Driver는 :c:func:`params_xxx()` macro로 값을 읽어 buffer 할당을 포함한 hardware setup을 수행합니다.
Managed buffer allocation을 선택했다면 callback 호출 전에 buffer가 이미 할당됩니다. 또는 미리 할당된 DMA buffer가 있을 때 :c:func:`snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params))` helper로 필요한 크기를 선택할 수 있습니다.
`hw_params`와 `prepare`는 initialization 한 번에 여러 차례 호출될 수 있습니다. OSS emulation은 ioctl로 설정이 바뀔 때마다 호출할 수 있으므로 같은 buffer를 반복 할당해 memory leak을 내면 안 됩니다. `snd_pcm_lib_malloc_pages()`는 기존 buffer가 있으면 자동 해제하므로 반복 호출해도 됩니다.
기본적으로 `nonatomic` flag가 설정되지 않은 `hw_params`는 non-atomic이며 scheduling할 수 있습니다. 반대로 기본 `trigger` callback은 atomic이므로 mutex나 sleep 가능한 함수를 사용할 수 없습니다. Sleep이 필요한 준비는 미리 `hw_params` 또는 `prepare`에서 끝내야 합니다.
항목처리
Parameter 읽기params_xxx(hw_params) macro
Managed bufferCallback 전에 middle layer가 할당
Pre-allocated poolsnd_pcm_lib_malloc_pages()로 크기 선택
반복 호출중복 resource와 memory leak 방지
기본 contextNon-atomic, schedulable
협상 결과를 hardware resource와 연결합니다.
Application이 hw_params 확정→params_xxx()로 값 조회→Buffer와 hardware resource 구성→반복 호출에도 기존 resource를 안전하게 교체→0 또는 음수 error 반환
Application 협상부터 반복 가능한 hardware 설정까지의 흐름입니다.
hw_params callback
~~~~~~~~~~~~~~~~~~~
::
static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
struct snd_pcm_hw_params *hw_params);
This is called when the hardware parameters (``hw_params``) are set up
by the application, that is, once when the buffer size, the period
size, the format, etc. are defined for the PCM substream.
Many hardware setups should be done in this callback, including the
allocation of buffers.
Parameters to be initialized are retrieved by the
:c:func:`params_xxx()` macros.
When you choose managed buffer allocation mode for the substream,
a buffer is already allocated before this callback gets
called. Alternatively, you can call a helper function below for
allocating the buffer::
snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
:c:func:`snd_pcm_lib_malloc_pages()` is available only when the
DMA buffers have been pre-allocated. See the section `Buffer Types`_
for more details.
Note that this one and the ``prepare`` callback may be called multiple
times per initialization. For example, the OSS emulation may call these
callbacks at each change via its ioctl.
Thus, you need to be careful not to allocate the same buffers many
times, which will lead to memory leaks! Calling the helper function
above many times is OK. It will release the previous buffer
automatically when it was already allocated.
Another note is that this callback is non-atomic (schedulable) by
default, i.e. when no ``nonatomic`` flag set. This is important,
because the ``trigger`` callback is atomic (non-schedulable). That is,
mutexes or any schedule-related functions are not available in the
``trigger`` callback. Please see the subsection Atomicity_ for
details.
hw_free callback
1878-1900`snd_xxx_hw_free(substream)`는 `hw_params`에서 확보한 resource를 해제하며 항상 `close` callback보다 먼저 호출됩니다. 이 callback도 여러 번 호출될 수 있으므로 각 resource가 이미 해제됐는지 추적해야 합니다.
Managed buffer mode에서는 callback이 끝난 뒤 PCM buffer가 자동 해제됩니다. 그렇지 않으면 driver가 직접 해제해야 하며 pre-allocated pool에서 선택한 buffer는 :c:func:`snd_pcm_lib_free_pages(substream)`로 반환합니다.
원문은 이 해제 예제를 소개하면서 ‘standard API function `snd_pcm_lib_malloc_pages()`’라고 적은 뒤 실제 code에서는 :c:func:`snd_pcm_lib_free_pages()`를 호출합니다. 할당 helper와 해제 helper의 이름 차이는 원문을 그대로 보존하고 이 해설에만 명시합니다.
할당 방식해제
Managed bufferhw_free callback 뒤 PCM core가 자동 해제
Pre-allocated pool에서 선택snd_pcm_lib_free_pages(substream)
Driver 자체 resource중복 호출 guard와 함께 직접 해제
할당 mode에 따른 해제 주체입니다.
hw_params에서 resource 확보→PCM 사용→hw_free에서 resource 해제→close callback
Parameter resource를 먼저 닫은 뒤 substream을 닫습니다.
hw_free callback
~~~~~~~~~~~~~~~~~
::
static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
This is called to release the resources allocated via
``hw_params``.
This function is always called before the close callback is called.
Also, the callback may be called multiple times, too. Keep track
whether each resource was already released.
When you have chosen managed buffer allocation mode for the PCM
substream, the allocated PCM buffer will be automatically released
after this callback gets called. Otherwise you'll have to release the
buffer manually. Typically, when the buffer was allocated from the
pre-allocated pool, you can use the standard API function
:c:func:`snd_pcm_lib_malloc_pages()` like::
snd_pcm_lib_free_pages(substream);
prepare callback
1901-1927`snd_xxx_prepare(substream)`은 PCM이 prepared 상태로 들어갈 때 format, sample rate 등을 hardware에 설정합니다. `hw_params`와 달리 :c:func:`snd_pcm_prepare()`가 호출될 때마다, 예를 들어 underrun 복구 때도 다시 실행됩니다.
이 callback은 non-atomic이므로 schedule 관련 함수를 안전하게 사용할 수 있습니다. 현재 rate, format, channel은 각각 `runtime->rate`, `runtime->format`, `runtime->channels`에서 읽고 buffer·period 크기는 `runtime->buffer_size`, `runtime->period_size`에서 frame 단위로 얻습니다.
원문 1921~1922줄은 할당 buffer의 ‘physical address’가 `runtime->dma_area`에 설정된다고 설명하지만 앞 1536~1538줄은 `dma_area`를 CPU logical address, `dma_addr`를 physical bus address로 정의합니다. 로컬 원문의 두 표현은 수정하지 않고 실제 programming에서는 field 정의에 따라 `dma_addr`와 `dma_area`를 구분해야 합니다.
Setup마다 여러 번 호출될 수 있으므로 `prepare` 구현도 반복 실행에 안전해야 합니다.
Field내용
runtime->rate현재 sample rate
runtime->format현재 PCM format
runtime->channels현재 channel 수
runtime->dma_areaCPU logical buffer address
runtime->dma_addrPhysical/bus DMA address
runtime->buffer_sizeFrame 단위 전체 buffer
runtime->period_sizeFrame 단위 period
Hardware programming에 사용하는 협상 결과입니다.
snd_pcm_prepare()→Runtime parameter 읽기→Hardware format/rate/channel/DMA programming→PCM prepared
Underrun 복구→snd_pcm_prepare() 재호출→동일 setup을 안전하게 반복
초기 setup과 XRUN 복구 모두 같은 callback을 통과합니다.
prepare callback
~~~~~~~~~~~~~~~~
::
static int snd_xxx_prepare(struct snd_pcm_substream *substream);
This callback is called when the PCM is “prepared”. You can set the
format type, sample rate, etc. here. The difference from ``hw_params``
is that the ``prepare`` callback will be called each time
:c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
underruns, etc.
Note that this callback is non-atomic. You can use
schedule-related functions safely in this callback.
In this and the following callbacks, you can refer to the values via
the runtime record, ``substream->runtime``. For example, to get the
current rate, format or channels, access to ``runtime->rate``,
``runtime->format`` or ``runtime->channels``, respectively. The
physical address of the allocated buffer is set to
``runtime->dma_area``. The buffer and period sizes are in
``runtime->buffer_size`` and ``runtime->period_size``, respectively.
Be careful that this callback will be called many times at each setup,
too.
trigger callback
1928-1970`snd_xxx_trigger(substream, cmd)`는 PCM을 시작·정지·일시정지할 때 호출됩니다. `<sound/pcm.h>`의 `SNDRV_PCM_TRIGGER_XXX` command 중 최소 `SNDRV_PCM_TRIGGER_START`와 `SNDRV_PCM_TRIGGER_STOP`을 처리하고 알 수 없는 command에는 `-EINVAL`을 반환해야 합니다.
Hardware table에서 pause capability를 선언했다면 `SNDRV_PCM_TRIGGER_PAUSE_PUSH`로 일시정지하고 `SNDRV_PCM_TRIGGER_PAUSE_RELEASE`로 다시 시작해야 합니다. Suspend/resume 지원 범위가 완전하든 부분적이든 power-management 상태 변경 때 발행되는 `SUSPEND`와 `RESUME`도 처리하며 보통 각각 STOP과 START 동작에 대응합니다.
`nonatomic` flag가 없으면 `trigger`는 기본적으로 atomic이어서 sleep 가능한 함수를 호출할 수 없습니다. 이 callback은 실제 DMA start/stop만 수행하도록 최소화하고 나머지 초기화는 미리 `hw_params`와 `prepare`에서 완료해야 합니다.
Command동작
SNDRV_PCM_TRIGGER_STARTPCM/DMA 시작
SNDRV_PCM_TRIGGER_STOPPCM/DMA 정지
SNDRV_PCM_TRIGGER_PAUSE_PUSHPCM 일시정지
SNDRV_PCM_TRIGGER_PAUSE_RELEASE일시정지에서 재시작
SNDRV_PCM_TRIGGER_SUSPENDPower transition에서 substream suspend
SNDRV_PCM_TRIGGER_RESUMEPower transition에서 substream resume
PCM engine과 power 상태에 대응하는 command입니다.
hw_params: resource와 장기 setup→prepare: 현재 parameter programming→trigger: atomic DMA start/stop
Sleep 가능한 준비와 즉시 실행할 DMA 제어를 분리합니다.
trigger callback
~~~~~~~~~~~~~~~~
::
static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
This is called when the PCM is started, stopped or paused.
The action is specified in the second argument, ``SNDRV_PCM_TRIGGER_XXX``
defined in ``<sound/pcm.h>``. At least, the ``START``
and ``STOP`` commands must be defined in this callback::
switch (cmd) {
case SNDRV_PCM_TRIGGER_START:
/* do something to start the PCM engine */
break;
case SNDRV_PCM_TRIGGER_STOP:
/* do something to stop the PCM engine */
break;
default:
return -EINVAL;
}
When the PCM supports the pause operation (given in the info field of
the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
must be handled here, too. The former is the command to pause the PCM,
and the latter to restart the PCM again.
When the PCM supports the suspend/resume operation, regardless of full
or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
commands must be handled, too. These commands are issued when the
power-management status is changed. Obviously, the ``SUSPEND`` and
``RESUME`` commands suspend and resume the PCM substream, and usually,
they are identical to the ``STOP`` and ``START`` commands, respectively.
See the `Power Management`_ section for details.
As mentioned, this callback is atomic by default unless the ``nonatomic``
flag set, and you cannot call functions which may sleep. The
``trigger`` callback should be as minimal as possible, just really
triggering the DMA. The other stuff should be initialized in
``hw_params`` and ``prepare`` callbacks properly beforehand.
sync_stop callback과 IRQ 동기화
1971-2001선택적인 `snd_xxx_sync_stop(substream)`은 `NULL`로 둘 수 있습니다. PCM core가 stream을 멈춘 뒤 `prepare`, `hw_params`, `hw_free`로 state를 바꾸기 전에 호출되어 아직 pending인 IRQ handler가 끝날 때까지 기다립니다.
이 동기화가 없으면 다음 단계의 resource와 pending handler가 충돌하거나 해제된 resource에 접근해 crash가 날 수 있습니다. 전형적인 구현은 :c:func:`synchronize_irq()`를 호출하는 것입니다.
대부분의 driver처럼 `synchronize_irq()` 한 번이면 충분하다면 `sync_stop` callback을 `NULL`로 두고 IRQ 요청 뒤 반환된 번호를 `card->sync_irq`에 설정할 수 있습니다. 그러면 PCM core가 적절한 시점에 해당 IRQ를 동기화합니다.
Card destructor가 IRQ를 해제하면 card 자체도 사라지므로 `card->sync_irq`를 따로 지울 필요가 없습니다. 다만 suspend/resume 등에서 IRQ를 동적으로 해제하고 다시 얻는 driver는 해제 때 clear하고 재획득 때 새 번호를 다시 설정해야 합니다.
상황구성
특수 동기화 필요Driver sync_stop callback 구현
synchronize_irq()만 필요sync_stop = NULL, card->sync_irq 설정
Card destructor에서 IRQ 해제별도 clear 불필요
IRQ 동적 재획득해제 시 clear, 재획득 시 reset
IRQ lifetime에 따라 직접 callback 또는 card field를 선택합니다.
PCM core가 stream stop→sync_stop 또는 card->sync_irq 동기화→Pending IRQ handler 종료→prepare / hw_params / hw_free 진입
Pending interrupt를 끝낸 뒤 resource/state를 변경합니다.
sync_stop callback
~~~~~~~~~~~~~~~~~~
::
static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);
This callback is optional, and NULL can be passed. It's called after
the PCM core stops the stream, before it changes the stream state via
``prepare``, ``hw_params`` or ``hw_free``.
Since the IRQ handler might be still pending, we need to wait until
the pending task finishes before moving to the next step; otherwise it
might lead to a crash due to resource conflicts or access to freed
resources. A typical behavior is to call a synchronization function
like :c:func:`synchronize_irq()` here.
For the majority of drivers that need only a call of
:c:func:`synchronize_irq()`, there is a simpler setup, too.
While keeping the ``sync_stop`` PCM callback NULL, the driver can set
the ``card->sync_irq`` field to the returned interrupt number after
requesting an IRQ, instead. Then PCM core will call
:c:func:`synchronize_irq()` with the given IRQ appropriately.
If the IRQ handler is released by the card destructor, you don't need
to clear ``card->sync_irq``, as the card itself is being released.
So, usually you'll need to add just a single line for assigning
``card->sync_irq`` in the driver code unless the driver re-acquires
the IRQ. When the driver frees and re-acquires the IRQ dynamically
(e.g. for suspend/resume), it needs to clear and re-set
``card->sync_irq`` again appropriately.
pointer callback
2002-2020`snd_xxx_pointer(substream)`는 PCM middle layer가 buffer 안의 현재 hardware 위치를 물을 때 호출됩니다. 반환 단위는 frame이며 범위는 0부터 `buffer_size - 1`까지입니다.
Interrupt routine이 :c:func:`snd_pcm_period_elapsed()`를 호출하면 PCM middle layer의 buffer-update routine이 `pointer`를 조회해 위치와 가용 공간을 갱신하고 poll에서 잠든 thread 등을 깨웁니다. 이 callback도 기본적으로 atomic입니다.
Interrupt handler→snd_pcm_period_elapsed()→PCM middle layer가 pointer callback 호출→Frame 위치와 available space 계산→대기 중 poll thread wakeup
Period interrupt가 userspace 가용 공간 갱신으로 이어집니다.
pointer callback
~~~~~~~~~~~~~~~~
::
static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
This callback is called when the PCM middle layer inquires the current
hardware position in the buffer. The position must be returned in
frames, ranging from 0 to ``buffer_size - 1``.
This is usually called from the buffer-update routine in the PCM
middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
is called by the interrupt routine. Then the PCM middle layer updates
the position and calculates the available space, and wakes up the
sleeping poll threads, etc.
This callback is also atomic by default.
copy와 fill_silence operation
2021-2035`copy`와 `fill_silence` callback은 필수가 아니며 대부분의 driver에서 생략할 수 있습니다. Hardware 자체 buffer가 normal memory에 mapping되지 않거나 physical·virtual 양쪽에서 non-contiguous라면 memory buffer와 hardware buffer 사이 data transfer 또는 silence 채우기를 driver가 직접 구현해야 합니다.
두 callback을 정의하면 PCM core의 copy와 set-silence operation이 이를 사용합니다. 자세한 memory model은 뒤 `Buffer and Memory Management` 절에서 설명합니다.
Buffer 특성필요 동작
Normal memory에서 직접 접근 가능Callback 생략
Hardware 내부 non-mappable bufferManual copy/fill_silence 구현
Physical·virtual non-contiguousCustom copy/fill_silence 구현
표준 memory 접근이 불가능할 때만 operation을 제공합니다.
copy and fill_silence ops
~~~~~~~~~~~~~~~~~~~~~~~~~
These callbacks are not mandatory, and can be omitted in most cases.
These callbacks are used when the hardware buffer cannot be in the
normal memory space. Some chips have their own buffer in the hardware
which is not mappable. In such a case, you have to transfer the data
manually from the memory buffer to the hardware buffer. Or, if the
buffer is non-contiguous on both physical and virtual memory spaces,
these callbacks must be defined, too.
If these two callbacks are defined, copy and set-silence operations
are done by them. The details will be described in the later section
`Buffer and Memory Management`_.
ack callback
2036-2049선택적인 `ack` callback은 read/write operation이 `appl_ptr`을 갱신할 때 호출됩니다. emu10k1-fx와 cs46xx처럼 내부 buffer를 위해 현재 application pointer를 추적해야 하는 driver에만 유용합니다.
Callback은 0 또는 음수 error를 반환할 수 있습니다. `-EPIPE`를 반환하면 PCM core가 이를 buffer XRUN으로 보고 state를 자동으로 `SNDRV_PCM_STATE_XRUN`으로 바꿉니다. 이 callback은 기본적으로 atomic입니다.
반환PCM core 처리
0appl_ptr update 성공
일반 음수 error해당 operation 실패
-EPIPEBuffer XRUN으로 처리하고 SNDRV_PCM_STATE_XRUN 설정
Application pointer update 결과가 PCM state에 미치는 영향입니다.
ack callback
~~~~~~~~~~~~
This callback is also not mandatory. This callback is called when the
``appl_ptr`` is updated in read or write operations. Some drivers like
emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
internal buffer, and this callback is useful only for such a purpose.
The callback function may return 0 or a negative error. When the
return value is ``-EPIPE``, PCM core treats that as a buffer XRUN,
and changes the state to ``SNDRV_PCM_STATE_XRUN`` automatically.
This callback is atomic by default.
page와 mmap callback
2050-2068선택적인 `page` callback은 mmap page fault address를 얻을 때 호출됩니다. 표준 scatter-gather buffer나 vmalloc buffer에는 특별한 callback이 필요 없으므로 드물게 사용합니다.
`mmap` callback도 선택 사항입니다. 정의하면 page를 memory-map할 때 PCM core가 표준 helper 대신 driver callback을 호출합니다. Architecture 또는 device-specific 문제가 있어 mapping 전체를 특별히 처리해야 할 때 구현합니다.
다음 2069줄부터는 `PCM Interrupt Handler` 대단원이 이어져 period 경계를 middle layer에 통지하는 방법을 설명합니다.
Callback사용 조건
page비표준 buffer의 page fault address 제공
mmapArchitecture/device-specific 전체 mapping 제어
생략표준 SG 또는 vmalloc buffer와 일반 mmap
표준 helper로 처리할 수 있는지 먼저 판단합니다.
PCM mmap 요청→표준 helper로 처리 가능 여부 확인→가능: PCM core 기본 mapping→불가: driver page/mmap callback
일반 buffer는 core helper를 사용하고 예외만 driver가 처리합니다.
page callback
~~~~~~~~~~~~~
This callback is optional too. The mmap calls this callback to get the
page fault address.
You need no special callback for the standard SG-buffer or vmalloc-
buffer. Hence this callback should be rarely used.
mmap callback
~~~~~~~~~~~~~
This is another optional callback for controlling mmap behavior.
When defined, the PCM core calls this callback when a page is
memory-mapped, instead of using the standard helper.
If you need special handling (due to some architecture or
device-specific issues), implement everything here as you like.
Period 경계 PCM interrupt
2069-2127Sound driver의 PCM interrupt handler는 buffer 위치를 갱신하고 지정한 period 경계를 넘었음을 PCM middle layer에 알려야 합니다. 이 통지는 :c:func:`snd_pcm_period_elapsed(substream)`으로 수행합니다.
가장 흔한 hardware는 period, 즉 OSS의 fragment 경계마다 interrupt를 발생시킵니다. 이 경우 interrupt마다 :c:func:`snd_pcm_period_elapsed()`를 한 번 호출하면 됩니다.
함수 인자로 현재 실행 중인 `struct snd_pcm_substream *`가 필요하므로 chip record에 `substream` field를 두고 `open`에서 설정한 뒤 `close`에서 해제할 수 있습니다.
Interrupt handler와 다른 PCM callback이 같은 spinlock을 쓴다면 :c:func:`snd_pcm_period_elapsed()`를 호출하기 전에 lock을 풀어야 합니다. 이 함수 내부에서 다른 PCM callback을 다시 호출할 수 있어 lock을 쥔 채 진입하면 deadlock 또는 lock recursion이 생길 수 있습니다. 예제는 unlock, period notification, relock 순서를 사용합니다.
Device가 buffer underrun/overrun을 감지하면 :c:func:`snd_pcm_stop_xrun()`으로 stream을 멈추고 state를 `SNDRV_PCM_STATE_XRUN`으로 설정할 수 있습니다. 이 함수는 PCM stream lock 밖에서 호출해야 하므로 atomic callback 안에서는 사용할 수 없습니다.
시점처리
openchip->substream에 실행 substream 저장
IRQ 진입chip lock으로 hardware state 보호
Period 통지 전공유 spinlock 해제
통지snd_pcm_period_elapsed(chip->substream)
통지 후필요하면 lock 재획득·interrupt acknowledge
closechip->substream reset
Open부터 interrupt와 close까지 필요한 state입니다.
Hardware period IRQ→IRQ source 확인→공유 spinlock 해제→snd_pcm_period_elapsed()→Spinlock 재획득→IRQ acknowledge 후 IRQ_HANDLED
PCM callback 재진입을 고려해 lock 밖에서 middle layer를 호출합니다.
PCM Interrupt Handler
---------------------
The remainder of the PCM stuff is the PCM interrupt handler. The role
of the PCM
interrupt handler in the sound driver is to update the buffer position
and to tell the PCM middle layer when the buffer position goes across
the specified period boundary. To inform about this, call the
:c:func:`snd_pcm_period_elapsed()` function.
There are several ways sound chips can generate interrupts.
Interrupts at the period (fragment) boundary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the most frequently found type: the hardware generates an
interrupt at each period boundary. In this case, you can call
:c:func:`snd_pcm_period_elapsed()` at each interrupt.
:c:func:`snd_pcm_period_elapsed()` takes the substream pointer as
its argument. Thus, you need to keep the substream pointer accessible
from the chip instance. For example, define ``substream`` field in the
chip record to hold the current running substream pointer, and set the
pointer value at ``open`` callback (and reset at ``close`` callback).
If you acquire a spinlock in the interrupt handler, and the lock is used
in other PCM callbacks, too, then you have to release the lock before
calling :c:func:`snd_pcm_period_elapsed()`, because
:c:func:`snd_pcm_period_elapsed()` calls other PCM callbacks
inside.
Typical code would look like::
static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
{
struct mychip *chip = dev_id;
spin_lock(&chip->lock);
....
if (pcm_irq_invoked(chip)) {
/* call updater, unlock before it */
spin_unlock(&chip->lock);
snd_pcm_period_elapsed(chip->substream);
spin_lock(&chip->lock);
/* acknowledge the interrupt if necessary */
}
....
spin_unlock(&chip->lock);
return IRQ_HANDLED;
}
Also, when the device can detect a buffer underrun/overrun, the driver
can notify the XRUN status to the PCM core by calling
:c:func:`snd_pcm_stop_xrun()`. This function stops the stream and sets
the PCM state to ``SNDRV_PCM_STATE_XRUN``. Note that it must be called
outside the PCM stream lock, hence it can't be called from the atomic
callback.
고주파 timer interrupt 누적
2128-2179es1968이나 ymfpci처럼 hardware가 period 경계 interrupt 대신 고정 rate timer interrupt를 내는 경우, 매 interrupt에서 `get_hw_ptr(chip)` 같은 방법으로 현재 hardware pointer를 읽고 지난 update 이후 처리된 frame 수를 누적해야 합니다.
현재 `last_ptr`가 이전 `chip->last_ptr`보다 작으면 ring buffer가 wrap된 것이므로 `runtime->buffer_size + last_ptr - chip->last_ptr`로 이동량을 계산하고, 그렇지 않으면 단순 차이를 씁니다. 새 pointer를 저장하고 `chip->size`에 처리 frame을 더합니다.
누적량이 `runtime->period_size` 이상이면 modulo로 period 나머지만 남기고, lock을 푼 뒤 :c:func:`snd_pcm_period_elapsed(substream)`를 호출한 다음 lock을 다시 얻습니다.
원문 예제 handler는 `runtime`과 `substream`을 사용하는 부분만 보여 주며 이 local 변수를 얻는 선언은 생략한 skeleton입니다. 실제 driver는 현재 runtime과 running substream을 chip state 등에서 유효하게 가져와야 합니다.
조건처리 frame 수
last_ptr >= previouslast_ptr - previous
last_ptr < previousbuffer_size + last_ptr - previous
누적 size >= period_sizesize %= period_size 후 period_elapsed 통지
Ring-buffer wrap을 포함한 처리량 계산입니다.
고정 rate timer IRQ→현재 hardware frame pointer 조회→Wrap을 고려한 이동량 계산→처리 frame 누적→Period 이상이면 나머지 보존→Lock 밖에서 snd_pcm_period_elapsed()
Timer tick을 frame 이동량으로 변환해 가상 period 경계를 만듭니다.
High frequency timer interrupts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This happens when the hardware doesn't generate interrupts at the period
boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
or ymfpci drivers). In this case, you need to check the current hardware
position and accumulate the processed sample length at each interrupt.
When the accumulated size exceeds the period size, call
:c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
Typical code would look as follows::
static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
{
struct mychip *chip = dev_id;
spin_lock(&chip->lock);
....
if (pcm_irq_invoked(chip)) {
unsigned int last_ptr, size;
/* get the current hardware pointer (in frames) */
last_ptr = get_hw_ptr(chip);
/* calculate the processed frames since the
* last update
*/
if (last_ptr < chip->last_ptr)
size = runtime->buffer_size + last_ptr
- chip->last_ptr;
else
size = last_ptr - chip->last_ptr;
/* remember the last updated point */
chip->last_ptr = last_ptr;
/* accumulate the size */
chip->size += size;
/* over the period boundary? */
if (chip->size >= runtime->period_size) {
/* reset the accumulator */
chip->size %= runtime->period_size;
/* call updater */
spin_unlock(&chip->lock);
snd_pcm_period_elapsed(substream);
spin_lock(&chip->lock);
}
/* acknowledge the interrupt if necessary */
}
....
spin_unlock(&chip->lock);
return IRQ_HANDLED;
}
period_elapsed 호출 횟수
2180-2187Period 경계 IRQ와 고주파 timer IRQ 어느 경우든 한 번의 처리 사이에 period가 여러 개 지났더라도 :c:func:`snd_pcm_period_elapsed()`를 여러 번 호출할 필요가 없습니다. 한 번만 호출하면 PCM layer가 현재 hardware pointer를 확인해 최신 상태까지 갱신합니다.
하나 이상의 period 경과 감지→snd_pcm_period_elapsed() 한 번 호출→PCM layer가 current hardware pointer 조회→최신 buffer 상태로 갱신
Notification 수가 아니라 현재 pointer가 최종 상태를 결정합니다.
On calling :c:func:`snd_pcm_period_elapsed()`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In both cases, even if more than one period has elapsed, you don't have
to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
once. And the PCM layer will check the current hardware pointer and
update to the latest status.
PCM callback atomicity
2188-2234Kernel race condition은 interrupt handler가 관여하는 짧은 critical section이면 spinlock으로 원자적으로 보호하고, interrupt context가 아니며 비교적 오래 걸려도 되는 영역이면 mutex 또는 semaphore를 사용하는 것이 일반적입니다.
PCM callback의 context는 서로 다릅니다. `hw_params`는 non-atomic이지만 `trigger`는 PCM middle layer가 PCM stream spinlock을 이미 잡은 상태에서 호출하는 atomic callback입니다. Locking scheme을 정할 때 이 호출 context를 반영해야 합니다.
Atomic callback에서는 :c:func:`schedule()`이나 :c:func:`sleep()`으로 이어질 수 있는 함수, semaphore, mutex를 사용할 수 없습니다. 짧은 delay가 필요하면 :c:func:`udelay()` 또는 :c:func:`mdelay()`을 사용합니다. `trigger`, `pointer`, `ack` 세 atomic callback은 local interrupt가 disable된 상태로 호출됩니다.
모든 PCM operation을 non-atomic으로 요청할 수도 있습니다. Threaded interrupt handler처럼 :c:func:`snd_pcm_period_elapsed()`를 포함한 모든 call site가 non-atomic context라면 PCM 생성 뒤 `struct snd_pcm`의 `nonatomic` field를 설정합니다.
`nonatomic`을 설정하면 PCM core 내부가 spinlock·rwlock 대신 mutex·rwsem을 사용하므로 non-atomic context에서 PCM 함수를 안전하게 호출할 수 있습니다. 반대로 `ack` 등 PCM stream lock 안의 atomic context에서 period가 경과했다면 :c:func:`snd_pcm_period_elapsed_under_stream_lock()` 변형을 사용합니다.
Callback/구성기본 context허용·주의
hw_params, prepareNon-atomicSleep 가능한 setup 허용
trigger, pointer, ackAtomic, local IRQ disabledMutex·sleep 금지
PCM nonatomic = 1전체 non-atomicCore가 mutex·rwsem 사용
stream lock 내부 period 통지Atomic lock-heldsnd_pcm_period_elapsed_under_stream_lock()
기본 atomicity와 허용되는 synchronization을 구분합니다.
Interrupt/atomic critical section→Spinlock과 non-sleeping operation
Non-atomic이며 긴 critical section 허용→Mutex 또는 semaphore
Threaded IRQ를 포함해 모든 PCM call site non-atomic→pcm->nonatomic 설정→PCM core 내부 mutex·rwsem
실행 context와 critical-section 길이에 따라 primitive를 고릅니다.
Atomicity
---------
One of the most important (and thus difficult to debug) problems in
kernel programming are race conditions. In the Linux kernel, they are
usually avoided via spin-locks, mutexes or semaphores. In general, if a
race condition can happen in an interrupt handler, it has to be managed
atomically, and you have to use a spinlock to protect the critical
section. If the critical section is not in interrupt handler code and if
taking a relatively long time to execute is acceptable, you should use
mutexes or semaphores instead.
As already seen, some PCM callbacks are atomic and some are not. For
example, the ``hw_params`` callback is non-atomic, while the ``trigger``
callback is atomic. This means, the latter is called already in a
spinlock held by the PCM middle layer, the PCM stream lock. Please
take this atomicity into account when you choose a locking scheme in
the callbacks.
In the atomic callbacks, you cannot use functions which may call
:c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
mutexes can sleep, and hence they cannot be used inside the atomic
callbacks (e.g. ``trigger`` callback). To implement some delay in such a
callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
All three atomic callbacks (trigger, pointer, and ack) are called with
local interrupts disabled.
However, it is possible to request all PCM operations to be non-atomic.
This assumes that all call sites are in
non-atomic contexts. For example, the function
:c:func:`snd_pcm_period_elapsed()` is called typically from the
interrupt handler. But, if you set up the driver to use a threaded
interrupt handler, this call can be in non-atomic context, too. In such
a case, you can set the ``nonatomic`` field of the struct snd_pcm object
after creating it. When this flag is set, mutex and rwsem are used internally
in the PCM core instead of spin and rwlocks, so that you can call all PCM
functions safely in a non-atomic
context.
Also, in some cases, you might need to call
:c:func:`snd_pcm_period_elapsed()` in the atomic context (e.g. the
period gets elapsed during ``ack`` or other callback). There is a
variant that can be called inside the PCM stream lock
:c:func:`snd_pcm_period_elapsed_under_stream_lock()` for that purpose,
too.
PCM hardware constraints
2235-2345Hardware는 물리적 한계 때문에 모든 PCM parameter 조합을 지원할 수 없으며 이를 constraint로 표현합니다. 지원 sample rate를 4000, 10000, 22050, 44100 Hz로 제한하는 예제는 `struct snd_pcm_hw_constraint_list`를 만들고 `open` callback에서 :c:func:`snd_pcm_hw_constraint_list()`를 `SNDRV_PCM_HW_PARAM_RATE`에 적용합니다.
전체 constraint 종류는 `sound/pcm.h`에서 확인할 수 있고 driver는 custom rule도 정의할 수 있습니다. 예제 hardware는 format이 `S16_LE`일 때만 1 channel을 허용하고 그 밖에는 hardware descriptor나 다른 constraint list가 허용하는 format/channel 조합을 사용합니다.
`hw_rule_channels_by_format()`은 :c:func:`hw_param_interval()`로 channel interval을, :c:func:`hw_param_mask()`로 format mask를 얻습니다. Format mask가 `SNDRV_PCM_FMTBIT_S16_LE`이면 channel interval을 정확히 1로 만들고 :c:func:`snd_interval_refine()`으로 기존 constraint를 좁힙니다.
:c:func:`snd_pcm_hw_rule_add()`로 이 rule을 `SNDRV_PCM_HW_PARAM_CHANNELS`에 등록하고 의존 parameter로 `SNDRV_PCM_HW_PARAM_FORMAT`을 지정합니다. Application이 format을 설정하면 rule이 channel 수를 refine합니다.
Application은 format보다 channel 수를 먼저 설정할 수도 있으므로 역방향 `hw_rule_format_by_channels()`도 필요합니다. Channel minimum이 2보다 작으면 format mask를 `SNDRV_PCM_FMTBIT_S16_LE`로 좁히고 :c:func:`snd_mask_refine()`을 호출한 뒤, 이 rule을 FORMAT parameter에 CHANNELS 의존성으로 등록합니다.
ALSA PCM core는 기본적으로 buffer 크기가 period 크기의 정수배가 되도록 강제하지 않으므로 256-byte period와 999-byte buffer 같은 조합도 가능합니다. Hardware가 period 정렬을 요구하면 :c:func:`snd_pcm_hw_constraint_integer(runtime, SNDRV_PCM_HW_PARAM_PERIODS)`로 period 수를 정수로 제한해 buffer를 period 크기에 맞춥니다.
Hardware constraint는 선호·지원 PCM 구성을 표현하는 강력한 mechanism이며 관련 helper가 더 많이 있습니다. 원문은 추가 세부 대신 source를 직접 참고하라고 권합니다. 다음 2346줄부터는 `Control Interface` 대단원입니다.
Helper용도
snd_pcm_hw_constraint_list()허용 가능한 rate 등 값 목록 제한
hw_param_interval()Numeric parameter interval 조회
hw_param_mask()Format 같은 bitmask parameter 조회
snd_interval_refine()Interval을 더 좁은 범위로 refine
snd_mask_refine()Mask를 허용 format 집합으로 refine
snd_pcm_hw_rule_add()Parameter 간 custom dependency rule 등록
snd_pcm_hw_constraint_integer()Period 수 같은 parameter를 정수로 제한
단순 목록, custom dependency, 정수 정렬을 구분합니다.
TargetDependencyRefinement
CHANNELSFORMATS16_LE이면 channel = 1
FORMATCHANNELSChannel이 1일 수 있으면 S16_LE로 제한
Application의 parameter 설정 순서와 무관하게 동일한 조합을 강제합니다.
상태가능한 조합
기본 PCM corePeriod 256 bytes, buffer 999 bytes 가능
Integer PERIODS constraintBuffer가 period 크기의 정수배
Core 기본값과 hardware 요구를 비교합니다.
지원 rate array 정의→snd_pcm_hw_constraint_list 구성→PCM open callback→SNDRV_PCM_HW_PARAM_RATE에 constraint 적용
Open 시 runtime에 허용 rate 목록을 연결합니다.
Application이 FORMAT 설정→channels_by_format rule→CHANNELS refine
Application이 CHANNELS 설정→format_by_channels rule→FORMAT refine
Format과 channel 어느 쪽을 먼저 설정해도 양방향 rule이 조합을 좁힙니다.
Constraints
-----------
Due to physical limitations, hardware is not infinitely configurable.
These limitations are expressed by setting constraints.
For example, in order to restrict the sample rates to some supported
values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
call this function in the open callback::
static unsigned int rates[] =
{4000, 10000, 22050, 44100};
static struct snd_pcm_hw_constraint_list constraints_rates = {
.count = ARRAY_SIZE(rates),
.list = rates,
.mask = 0,
};
static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
{
int err;
....
err = snd_pcm_hw_constraint_list(substream->runtime, 0,
SNDRV_PCM_HW_PARAM_RATE,
&constraints_rates);
if (err < 0)
return err;
....
}
There are many different constraints. Look at ``sound/pcm.h`` for a
complete list. You can even define your own constraint rules. For
example, let's suppose my_chip can manage a substream of 1 channel if
and only if the format is ``S16_LE``, otherwise it supports any format
specified in struct snd_pcm_hardware (or in any other
constraint_list). You can build a rule like this::
static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
struct snd_pcm_hw_rule *rule)
{
struct snd_interval *c = hw_param_interval(params,
SNDRV_PCM_HW_PARAM_CHANNELS);
struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
struct snd_interval ch;
snd_interval_any(&ch);
if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
ch.min = ch.max = 1;
ch.integer = 1;
return snd_interval_refine(c, &ch);
}
return 0;
}
Then you need to call this function to add your rule::
snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
hw_rule_channels_by_format, NULL,
SNDRV_PCM_HW_PARAM_FORMAT, -1);
The rule function is called when an application sets the PCM format, and
it refines the number of channels accordingly. But an application may
set the number of channels before setting the format. Thus you also need
to define the inverse rule::
static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
struct snd_pcm_hw_rule *rule)
{
struct snd_interval *c = hw_param_interval(params,
SNDRV_PCM_HW_PARAM_CHANNELS);
struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
struct snd_mask fmt;
snd_mask_any(&fmt); /* Init the struct */
if (c->min < 2) {
fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
return snd_mask_refine(f, &fmt);
}
return 0;
}
... and in the open callback::
snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
hw_rule_format_by_channels, NULL,
SNDRV_PCM_HW_PARAM_CHANNELS, -1);
One typical usage of the hw constraints is to align the buffer size
with the period size. By default, ALSA PCM core doesn't enforce the
buffer size to be aligned with the period size. For example, it'd be
possible to have a combination like 256 period bytes with 999 buffer
bytes.
Many device chips, however, require the buffer to be a multiple of
periods. In such a case, call
:c:func:`snd_pcm_hw_constraint_integer()` for
``SNDRV_PCM_HW_PARAM_PERIODS``::
snd_pcm_hw_constraint_integer(substream->runtime,
SNDRV_PCM_HW_PARAM_PERIODS);
This assures that the number of periods is integer, hence the buffer
size is aligned with the period size.
The hw constraint is a very powerful mechanism to define the
preferred PCM configuration, and there are relevant helpers.
I won't give more details here, rather I would like to say, “Luke, use
the source.”
ALSA control interface 개요
2346-2362Control interface는 userspace에서 접근하는 switch, slider 등에 널리 쓰이며 가장 중요한 용도는 mixer입니다. ALSA 0.9.x 이후 mixer 기능은 모두 control kernel API 위에 구현됩니다.
ALSA에는 정립된 AC97 control module이 있으므로 chip이 AC97만 지원하고 별도 control이 없다면 이 대단원을 건너뛸 수 있습니다. Driver 고유 control을 추가하려면 `<sound/control.h>`를 포함합니다.
Hardware처리
AC97만 지원기존 AC97 control module 사용
추가 switch·slider·mixer 기능<sound/control.h>의 control API로 구현
표준 AC97 control과 driver 고유 control을 구분합니다.
Control Interface
=================
General
-------
The control interface is used widely for many switches, sliders, etc.
which are accessed from user-space. Its most important use is the mixer
interface. In other words, since ALSA 0.9.x, all the mixer stuff is
implemented on the control kernel API.
ALSA has a well-defined AC97 control module. If your chip supports only
the AC97 and nothing else, you can skip this section.
The control API is defined in ``<sound/control.h>``. Include this file
if you want to add your own controls.
struct snd_kcontrol_new 정의
2363-2418새 control은 `info`, `get`, `put` callback을 정의한 뒤 `struct snd_kcontrol_new` record로 기술합니다. 예제 `PCM Playback Switch`는 mixer interface, index 0, read/write access, `private_value = 0xffff`와 세 callback을 연결합니다.
`iface`는 보통 `SNDRV_CTL_ELEM_IFACE_MIXER`입니다. Mixer 논리 영역 밖의 card-wide control은 `CARD`, 특정 sound device와 밀접하면 `HWDEP`, `PCM`, `RAWMIDI`, `TIMER`, `SEQUENCER`를 쓰고 `device`·`subdevice` 번호도 지정합니다.
`name`은 control 역할을 분류하는 identifier이므로 ALSA 0.9.x 이후 매우 중요하며 표준 이름을 따라야 합니다. 같은 이름의 control이 여러 개이면 `index`로 구분하고, card에 여러 codec이 있는 경우가 대표적입니다. Index 0은 field 선언을 생략할 수 있습니다.
`access`에는 `SNDRV_CTL_ELEM_ACCESS_XXX` bitmask 조합을 넣습니다. `private_value`는 generic callback에 arbitrary long 값을 전달하며 여러 작은 값을 bit packing하거나 record pointer를 `unsigned long`로 cast해 저장할 수도 있습니다.
`tlv` field는 control metadata를 제공하며 세 callback의 구체적 계약과 함께 뒤 절에서 설명합니다.
Field역할
ifaceMIXER/CARD/HWDEP/PCM/RAWMIDI/TIMER/SEQUENCER 분류
name표준 naming rule을 따르는 role identifier
index같은 이름의 여러 control 구분
device / subdevice특정 sound device 연계
accessSNDRV_CTL_ELEM_ACCESS_XXX 권한·특성
private_valueCallback용 packed integer 또는 pointer
tlvdB 등 control metadata
info / get / putDescriptor, read, write callback
Control identity, access, callback context를 구성합니다.
Control 표준 이름 선택→iface/index/access 설정→private_value와 TLV 필요성 결정→info/get/put callback 연결→snd_kcontrol_new 완성
정적 정의가 callback과 userspace identity를 결합합니다.
Definition of Controls
----------------------
To create a new control, you need to define the following three
callbacks: ``info``, ``get`` and ``put``. Then, define a
struct snd_kcontrol_new record, such as::
static struct snd_kcontrol_new my_control = {
.iface = SNDRV_CTL_ELEM_IFACE_MIXER,
.name = "PCM Playback Switch",
.index = 0,
.access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
.private_value = 0xffff,
.info = my_control_info,
.get = my_control_get,
.put = my_control_put
};
The ``iface`` field specifies the control type,
``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
for global controls that are not logically part of the mixer. If the
control is closely associated with some specific device on the sound
card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
and specify the device number with the ``device`` and ``subdevice``
fields.
The ``name`` is the name identifier string. Since ALSA 0.9.x, the
control name is very important, because its role is classified from
its name. There are pre-defined standard control names. The details
are described in the `Control Names`_ subsection.
The ``index`` field holds the index number of this control. If there
are several different controls with the same name, they can be
distinguished by the index number. This is the case when several
codecs exist on the card. If the index is zero, you can omit the
definition above.
The ``access`` field contains the access type of this control. Give
the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
there. The details will be explained in the `Access Flags`_
subsection.
The ``private_value`` field contains an arbitrary long integer value
for this record. When using the generic ``info``, ``get`` and ``put``
callbacks, you can pass a value through this field. If several small
numbers are necessary, you can combine them in bitwise. Or, it's
possible to store a pointer (casted to unsigned long) of some record in
this field, too.
The ``tlv`` field can be used to provide metadata about the control;
see the `Metadata`_ subsection.
The other three are `Control Callbacks`_.
Control 표준 이름
2419-2470일반 control 이름은 `SOURCE DIRECTION FUNCTION` 세 부분으로 구성합니다. `SOURCE`는 Master, PCM, CD, Line 같은 입력·출력 source이고, `DIRECTION`은 Playback, Capture, Bypass Playback, Bypass Capture 중 하나입니다. Direction을 생략하면 playback과 capture 양쪽을 뜻합니다.
`FUNCTION`은 Switch, Volume, Route 중 하나이며 `Master Capture Switch`, `PCM Playback Volume`이 완성된 예입니다.
Global input에는 `Capture Source`, `Capture Switch`, `Capture Volume`, global output gain에는 `Playback Switch`, `Playback Volume`이라는 예외 이름을 사용합니다.
Tone control은 `Tone Control - Switch`, `Tone Control - Bass`, `Tone Control - Center`처럼 `Tone Control - XXX`, 3D control은 `3D Control - Switch`, `3D Control - Center`, `3D Control - Space`처럼 `3D Control - XXX` 형식입니다.
Mic boost switch는 `Mic Boost` 또는 `Mic Boost (6dB)`로 이름 붙입니다. 더 정확한 규칙은 `Documentation/sound/designs/control-names.rst`에 있습니다.
부분예
SOURCEMaster, PCM, CD, Line
DIRECTIONPlayback, Capture, Bypass Playback, Bypass Capture 또는 생략
FUNCTIONSwitch, Volume, Route
일반적인 세 부분의 허용 예입니다.
종류이름 예
Global captureCapture Source / Switch / Volume
Global playbackPlayback Switch / Volume
ToneTone Control - XXX
3D3D Control - XXX
Mic boostMic Boost 또는 Mic Boost (6dB)
Global·tone·3D·mic boost의 고정 형식입니다.
Control Names
-------------
There are some standards to define the control names. A control is
usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
The first, ``SOURCE``, specifies the source of the control, and is a
string such as “Master”, “PCM”, “CD” and “Line”. There are many
pre-defined sources.
The second, ``DIRECTION``, is one of the following strings according to
the direction of the control: “Playback”, “Capture”, “Bypass Playback”
and “Bypass Capture”. Or, it can be omitted, meaning both playback and
capture directions.
The third, ``FUNCTION``, is one of the following strings according to
the function of the control: “Switch”, “Volume” and “Route”.
The example of control names are, thus, “Master Capture Switch” or “PCM
Playback Volume”.
There are some exceptions:
Global capture and playback
~~~~~~~~~~~~~~~~~~~~~~~~~~~
“Capture Source”, “Capture Switch” and “Capture Volume” are used for the
global capture (input) source, switch and volume. Similarly, “Playback
Switch” and “Playback Volume” are used for the global output gain switch
and volume.
Tone-controls
~~~~~~~~~~~~~
tone-control switch and volumes are specified like “Tone Control - XXX”,
e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
Center”.
3D controls
~~~~~~~~~~~
3D-control switches and volumes are specified like “3D Control - XXX”,
e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
Mic boost
~~~~~~~~~
Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
More precise information can be found in
``Documentation/sound/designs/control-names.rst``.
Control access flag
2471-2496`access` bitmask의 기본값은 `SNDRV_CTL_ELEM_ACCESS_READWRITE`이며 read와 write를 모두 허용합니다. Field를 생략해 0으로 두어도 기본적으로 READWRITE로 해석합니다.
Read-only control은 `SNDRV_CTL_ELEM_ACCESS_READ`를 사용하고 `put` callback을 생략합니다. 드문 write-only control은 `SNDRV_CTL_ELEM_ACCESS_WRITE`를 사용하며 `get` callback이 필요 없습니다.
VU meter처럼 값이 change notification 없이 자주 바뀌면 `SNDRV_CTL_ELEM_ACCESS_VOLATILE`을 설정하고 application이 계속 poll하도록 합니다. 값은 갱신할 수 있지만 현재 효과가 없으면 `SNDRV_CTL_ELEM_ACCESS_INACTIVE`가 적절하며, 예를 들어 PCM device가 열리지 않았을 때 PCM control을 inactive로 둘 수 있습니다.
`SNDRV_CTL_ELEM_ACCESS_LOCK`과 `SNDRV_CTL_ELEM_ACCESS_OWNER` flag는 write permission 변경에 사용합니다.
Flag의미·callback
READWRITE 또는 0Read/get과 write/put 모두
READRead-only; put 불필요
WRITEWrite-only; get 불필요
VOLATILENotification 없이 변할 수 있어 application polling 필요
INACTIVE현재 값의 실제 효과 없음
LOCK / OWNERWrite permission 제어
권한과 값의 동작 특성을 구분합니다.
Access Flags
------------
The access flag is the bitmask which specifies the access type of the
given control. The default access type is
``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
allowed to this control. When the access flag is omitted (i.e. = 0), it
is considered as ``READWRITE`` access by default.
When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
instead. In this case, you don't have to define the ``put`` callback.
Similarly, when the control is write-only (although it's a rare case),
you can use the ``WRITE`` flag instead, and you don't need the ``get``
callback.
If the control value changes frequently (e.g. the VU meter),
``VOLATILE`` flag should be given. This means that the control may be
changed without `Change notification`_. Applications should poll such
a control constantly.
When the control may be updated, but currently has no effect on anything,
setting the ``INACTIVE`` flag may be appropriate. For example, PCM
controls should be inactive while no PCM device is open.
There are ``LOCK`` and ``OWNER`` flags to change the write permissions.
Control info callback
2497-2570`info` callback은 control의 상세 descriptor를 `struct snd_ctl_elem_info`에 채웁니다. 단일 boolean 예제는 `type = SNDRV_CTL_ELEM_TYPE_BOOLEAN`, `count = 1`, integer 범위 0~1을 설정하고 0을 반환합니다.
Control type에는 `BOOLEAN`, `INTEGER`, `ENUMERATED`, `BYTES`, `IEC958`, `INTEGER64`가 있습니다. `count`는 element 수이며 stereo volume은 2입니다. `value`는 type에 따라 해석되는 union이고 boolean과 integer는 같은 형태를 사용합니다.
`SNDRV_CTL_ELEM_TYPE_ENUMERATED` control은 전체 item 수와 요청된 item index의 이름을 설정해야 합니다. 예제는 네 문자열 중 index가 3보다 크면 3으로 clamp한 뒤 선택한 이름을 복사합니다. 원문 2529줄의 `selectec` 표기는 오타로 보이지만 영어 원문은 수정하지 않고 의미를 선택된 item index로 번역합니다.
:c:func:`snd_ctl_enum_info(uinfo, 1, 4, texts)` helper를 쓰면 enum descriptor를 간단히 만들 수 있으며 item 수에는 `ARRAY_SIZE(texts)`를 전달해도 됩니다.
공통 boolean descriptor용 helper로 mono 한 element의 :c:func:`snd_ctl_boolean_mono_info()`와 stereo 두 element의 :c:func:`snd_ctl_boolean_stereo_info()`가 제공됩니다.
Type용도
BOOLEAN0/1 switch
INTEGER / INTEGER64범위를 가진 정수 값
ENUMERATEDItem index와 표시 문자열
BYTESByte sequence
IEC958IEC958 control data
Control value union의 해석을 결정합니다.
Control info 요청→type과 count 설정→Range 또는 enum items/name 설정→struct snd_ctl_elem_info 반환
Userspace가 읽을 control schema를 완성합니다.
Control Callbacks
-----------------
info callback
~~~~~~~~~~~~~
The ``info`` callback is used to get detailed information on this
control. This must store the values of the given
struct snd_ctl_elem_info object. For example,
for a boolean control with a single element::
static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
struct snd_ctl_elem_info *uinfo)
{
uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
uinfo->count = 1;
uinfo->value.integer.min = 0;
uinfo->value.integer.max = 1;
return 0;
}
The ``type`` field specifies the type of the control. There are
``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
``INTEGER64``. The ``count`` field specifies the number of elements in
this control. For example, a stereo volume would have count = 2. The
``value`` field is a union, and the values stored depend on the
type. The boolean and integer types are identical.
The enumerated type is a bit different from the others. You'll need to
set the string for the selectec item index::
static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
struct snd_ctl_elem_info *uinfo)
{
static char *texts[4] = {
"First", "Second", "Third", "Fourth"
};
uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
uinfo->count = 1;
uinfo->value.enumerated.items = 4;
if (uinfo->value.enumerated.item > 3)
uinfo->value.enumerated.item = 3;
strcpy(uinfo->value.enumerated.name,
texts[uinfo->value.enumerated.item]);
return 0;
}
The above callback can be simplified with a helper function,
:c:func:`snd_ctl_enum_info()`. The final code looks like below.
(You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
it's a matter of taste.)
::
static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
struct snd_ctl_elem_info *uinfo)
{
static char *texts[4] = {
"First", "Second", "Third", "Fourth"
};
return snd_ctl_enum_info(uinfo, 1, 4, texts);
}
Some common info callbacks are available for your convenience:
:c:func:`snd_ctl_boolean_mono_info()` and
:c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former
is an info callback for a mono channel boolean item, just like
:c:func:`snd_myctl_mono_info()` above, and the latter is for a
stereo channel boolean item.
Control get callback
2571-2611`get` callback은 현재 control 값을 읽어 userspace에 반환합니다. :c:func:`snd_kcontrol_chip(kcontrol)`으로 chip context를 얻고 control type에 맞는 `ucontrol->value` union member를 채웁니다.
`private_value`에는 sb driver 예제처럼 register offset, bit shift, bit mask를 하나의 long에 packing할 수 있습니다. `reg | (shift << 16) | (mask << 24)`로 저장하고 callback에서 mask와 shift로 각각 복원합니다.
Control의 `count > 1`이면 `get` callback은 모든 element를 채워야 합니다. 예제는 count 1을 가정해 `value.integer.value[0]` 하나만 설정합니다.
입력사용
snd_kcontrol_chip(kcontrol)Driver chip context
kcontrol->private_valuePacked register/shift/mask 또는 pointer
ucontrol->valueType·count에 맞춰 모든 element 작성
정적 descriptor와 hardware state를 userspace value로 변환합니다.
reg | shift<<16 | mask<<24 저장→get callback에서 private_value 읽기→Bit mask로 reg/shift/mask 분리→Hardware register 읽기→ucontrol의 모든 element 채우기
여러 작은 hardware field를 하나의 long으로 전달합니다.
get callback
~~~~~~~~~~~~
This callback is used to read the current value of the control, so it
can be returned to user-space.
For example::
static int snd_myctl_get(struct snd_kcontrol *kcontrol,
struct snd_ctl_elem_value *ucontrol)
{
struct mychip *chip = snd_kcontrol_chip(kcontrol);
ucontrol->value.integer.value[0] = get_some_value(chip);
return 0;
}
The ``value`` field depends on the type of control as well as on the
info callback. For example, the sb driver uses this field to store the
register offset, the bit-shift and the bit-mask. The ``private_value``
field is set as follows::
.private_value = reg | (shift << 16) | (mask << 24)
and is retrieved in callbacks like::
static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
struct snd_ctl_elem_value *ucontrol)
{
int reg = kcontrol->private_value & 0xff;
int shift = (kcontrol->private_value >> 16) & 0xff;
int mask = (kcontrol->private_value >> 24) & 0xff;
....
}
In the ``get`` callback, you have to fill all the elements if the
control has more than one element, i.e. ``count > 1``. In the example
above, we filled only one element (``value.integer.value[0]``) since
``count = 1`` is assumed.
Control put callback
2612-2646`put` callback은 userspace에서 전달된 값을 hardware·driver state에 씁니다. 기존 값과 `ucontrol->value`를 비교해 실제로 다를 때만 변경하고 `changed = 1`을 반환합니다.
반환값 1은 값이 변경됐음을, 0은 변화가 없음을 뜻합니다. 치명적 error에는 일반 callback처럼 음수 error code를 반환합니다. `count > 1`이면 `get`과 마찬가지로 모든 element를 평가해야 합니다.
`info`, `get`, `put` 세 control callback은 모두 non-atomic입니다.
반환의미
1Control 값이 실제 변경됨
0요청 값이 기존 값과 같아 변경 없음
음수 errorHardware 또는 validation 실패
변경 여부와 error를 명확히 구분합니다.
Userspace value 수신→현재 값과 모든 element 비교→다르면 hardware/state 변경→변경 1 / 미변경 0 / 실패 음수 반환
불필요한 hardware write 없이 변화 여부를 PCM control core에 알립니다.
put callback
~~~~~~~~~~~~
This callback is used to write a value coming from user-space.
For example::
static int snd_myctl_put(struct snd_kcontrol *kcontrol,
struct snd_ctl_elem_value *ucontrol)
{
struct mychip *chip = snd_kcontrol_chip(kcontrol);
int changed = 0;
if (chip->current_value !=
ucontrol->value.integer.value[0]) {
change_current_value(chip,
ucontrol->value.integer.value[0]);
changed = 1;
}
return changed;
}
As seen above, you have to return 1 if the value is changed. If the
value is not changed, return 0 instead. If any fatal error happens,
return a negative error code as usual.
As in the ``get`` callback, when the control has more than one
element, all elements must be evaluated in this callback, too.
Callbacks are not atomic
~~~~~~~~~~~~~~~~~~~~~~~~
All these three callbacks are not-atomic.
Control constructor
2647-2667Descriptor와 callback이 준비되면 :c:func:`snd_ctl_new1(&my_control, chip)`으로 `struct snd_kcontrol` instance를 할당하고 :c:func:`snd_ctl_add(card, ...)`로 card에 control component를 연결합니다. Error가 음수면 그대로 반환합니다.
두 번째 인자 `chip`은 `kcontrol->private_data`에 저장되어 callback에서 참조할 수 있습니다.
struct snd_kcontrol_new 준비→snd_ctl_new1(template, chip)→struct snd_kcontrol 할당→snd_ctl_add(card, kcontrol)→Card control component 등록
정적 template에서 card 소속 runtime control을 만듭니다.
Control Constructor
-------------------
When everything is ready, finally we can create a new control. To create
a control, there are two functions to be called,
:c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
In the simplest way, you can do it like this::
err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
if (err < 0)
return err;
where ``my_control`` is the struct snd_kcontrol_new object defined above,
and chip is the object pointer to be passed to kcontrol->private_data which
can be referred to in callbacks.
:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and
:c:func:`snd_ctl_add()` assigns the given control component to the
card.
Control 변경 notification
2668-2682Interrupt routine 등에서 control을 변경·갱신했다면 :c:func:`snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer)`로 userspace에 알릴 수 있습니다.
인자는 card pointer, notification 종류를 나타내는 event mask, 대상 `struct snd_ctl_elem_id *`입니다. `SNDRV_CTL_EVENT_MASK_VALUE`는 control value 변경을 뜻하며 hardware volume interrupt 사례는 `es1938.c`와 `es1968.c`에서 볼 수 있습니다.
인자의미
cardControl이 속한 sound card
SNDRV_CTL_EVENT_MASK_VALUEValue 변경 event
id_pointer통지할 struct snd_ctl_elem_id pointer
정확한 control identity와 event type을 전달합니다.
Change Notification
-------------------
If you need to change and update a control in the interrupt routine, you
can call :c:func:`snd_ctl_notify()`. For example::
snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
This function takes the card pointer, the event-mask, and the control id
pointer for the notification. The event-mask specifies the types of
notification, for example, in the above example, the change of control
values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
for hardware volume interrupts.
Mixer dB TLV metadata
2683-2718Mixer control의 dB 정보를 제공하려면 `<sound/tlv.h>`의 `DECLARE_TLV_xxx` macro로 metadata 변수를 만들고 `tlv.p`가 이를 가리키게 한 뒤 `access`에 `SNDRV_CTL_ELEM_ACCESS_TLV_READ`를 추가합니다.
:c:func:`DECLARE_TLV_DB_SCALE(name, min, step, mute)`은 control 값 한 step마다 일정한 dB만큼 변하는 scale을 정의합니다. `min`과 `step`은 0.01 dB 단위이며 네 번째 값이 1이면 최솟값이 mute를 뜻합니다. 예제 `-4050, 150, 0`은 -40.50 dB에서 시작해 step당 1.50 dB이며 최솟값을 mute로 취급하지 않습니다.
:c:func:`DECLARE_TLV_DB_LINEAR(name, min, max)`는 control 값이 output에 선형으로 영향을 주는 범위를 정의합니다. 최소·최대는 0.01 dB 단위이며 minimum이 mute라면 두 번째 인자에 `TLV_DB_GAIN_MUTE`를 사용합니다.
다음 2719줄부터는 `API for AC97 Codec` 대단원입니다.
Macro인자의미
DECLARE_TLV_DB_SCALEname, min, step, mute고정 dB step
DECLARE_TLV_DB_LINEARname, min, max선형 output 범위
TLV_DB_GAIN_MUTELinear minimum최솟값이 mute임을 표시
Scale형과 linear형 metadata의 인자를 구분합니다.
DECLARE_TLV_xxx 변수 정의→kcontrol_new.tlv.p에 pointer 설정→access에 TLV_READ 추가→Userspace가 dB metadata 조회
Control value를 userspace dB 표현과 연결합니다.
Metadata
--------
To provide information about the dB values of a mixer control, use one of
the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
variable containing this information, set the ``tlv.p`` field to point to
this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
in the ``access`` field; like this::
static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
static struct snd_kcontrol_new my_control = {
...
.access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
SNDRV_CTL_ELEM_ACCESS_TLV_READ,
...
.tlv.p = db_scale_my_control,
};
The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
about a mixer control where each step in the control's value changes the
dB value by a constant dB amount. The first parameter is the name of the
variable to be defined. The second parameter is the minimum value, in
units of 0.01 dB. The third parameter is the step size, in units of 0.01
dB. Set the fourth parameter to 1 if the minimum value actually mutes
the control.
The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
about a mixer control where the control's value affects the output
linearly. The first parameter is the name of the variable to be defined.
The second parameter is the minimum value, in units of 0.01 dB. The
third parameter is the maximum value, in units of 0.01 dB. If the
minimum value mutes the control, set the second parameter to
``TLV_DB_GAIN_MUTE``.
AC97 코덱 API 개요
2719-2728ALSA의 AC97 코덱 계층은 이미 명확하게 정의되어 있으므로 드라이버가 코덱 제어 코드를 많이 작성할 필요는 없습니다. 하드웨어에 직접 접근하는 저수준 제어 루틴만 제공하면 나머지 공통 동작은 AC97 계층이 맡습니다.
AC97 코덱 API의 선언은 `<sound/ac97_codec.h>`에 있습니다. 따라서 AC97을 사용하는 카드 드라이버는 이 헤더의 형식과 도우미를 기준으로 버스, 코덱 인스턴스, 레지스터 접근을 구성합니다.
구성 요소담당 범위
ALSA AC97 계층표준 코덱 제어와 공통 API
카드 드라이버코덱 레지스터를 읽고 쓰는 저수준 루틴
API 헤더<sound/ac97_codec.h>
공통 코덱 계층과 카드별 저수준 구현의 경계를 구분합니다.
API for AC97 Codec
==================
General
-------
The ALSA AC97 codec layer is a well-defined one, and you don't have to
write much code to control it. Only low-level control routines are
necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
AC97 전체 코드 예제
2729-2775전체 예제에서 카드별 `struct mychip`은 생성된 `struct snd_ac97 *ac97` 포인터를 보관합니다. `snd_mychip_ac97_read()`와 `snd_mychip_ac97_write()`는 전달받은 AC97 객체의 `ac97->private_data`에서 카드별 `chip`을 되찾은 뒤, 각각 지정 레지스터를 읽어 `unsigned short` 값을 반환하거나 지정 값으로 레지스터를 씁니다.
`snd_mychip_ac97()`는 먼저 `struct snd_ac97_bus *bus`와 `struct snd_ac97_template ac97`을 준비합니다. 정적인 `struct snd_ac97_bus_ops ops`의 `.write`와 `.read`에는 앞서 구현한 저수준 callback을 연결합니다.
이어 :c:func:`snd_ac97_bus()`를 `chip->card`, 버스 번호 0, callback ops와 함께 호출해 AC97 bus를 만듭니다. 오류가 발생하면 음수 오류를 그대로 반환합니다. 성공하면 template을 0으로 초기화하고 `ac97.private_data = chip`으로 callback context를 지정한 다음, :c:func:`snd_ac97_mixer()`가 만든 코덱 인스턴스를 `chip->ac97`에 저장합니다.
객체역할
struct snd_ac97생성된 코덱 인스턴스
struct snd_ac97_busAC97 인스턴스들이 공유하는 버스
struct snd_ac97_template새 인스턴스 생성에 전달하는 설정
struct snd_ac97_bus_opssnd_mychip_ac97_read/write 저수준 callback 집합
코드에 등장하는 AC97 객체와 연결 관계입니다.
snd_mychip_ac97_read/write 구현→struct snd_ac97_bus_ops에 연결→snd_ac97_bus()로 버스 생성→template을 0으로 초기화→ac97.private_data에 chip 저장→snd_ac97_mixer()로 chip->ac97 생성
카드별 레지스터 접근에서 코덱 mixer 생성까지 이어지는 순서입니다.
Full Code Example
-----------------
::
struct mychip {
....
struct snd_ac97 *ac97;
....
};
static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
unsigned short reg)
{
struct mychip *chip = ac97->private_data;
....
/* read a register value here from the codec */
return the_register_value;
}
static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
unsigned short reg, unsigned short val)
{
struct mychip *chip = ac97->private_data;
....
/* write the given register value to the codec */
}
static int snd_mychip_ac97(struct mychip *chip)
{
struct snd_ac97_bus *bus;
struct snd_ac97_template ac97;
int err;
static struct snd_ac97_bus_ops ops = {
.write = snd_mychip_ac97_write,
.read = snd_mychip_ac97_read,
};
err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
if (err < 0)
return err;
memset(&ac97, 0, sizeof(ac97));
ac97.private_data = chip;
return snd_ac97_mixer(bus, &ac97, &chip->ac97);
}
AC97 생성자
2776-2809AC97 인스턴스를 만들 때는 먼저 callback 함수가 들어 있는 `ac97_bus_ops_t` 레코드, 즉 `struct snd_ac97_bus_ops`를 :c:func:`snd_ac97_bus()`에 전달합니다. 예제는 `.write = snd_mychip_ac97_write`, `.read = snd_mychip_ac97_read`로 설정한 뒤 card의 0번 AC97 bus를 생성합니다.
이 bus 레코드는 그 bus에 속한 모든 AC97 인스턴스가 공유합니다. 각 코덱마다 공통 bus를 다시 만드는 것이 아니라, 하나의 bus 위에 필요한 코덱 인스턴스를 구성하는 구조입니다.
다음으로 `struct snd_ac97_template` 레코드를 0으로 초기화하고 `ac97.private_data = chip`을 설정한 뒤, 앞에서 만든 bus 포인터와 함께 :c:func:`snd_ac97_mixer()`에 넘깁니다. 결과로 새 `ac97_t` 인스턴스를 가리키는 `chip->ac97`이 만들어집니다.
여기서 chip 포인터를 private data로 설정했기 때문에 read/write callback은 `ac97->private_data`를 통해 해당 카드 인스턴스를 참조할 수 있습니다. 생성된 AC97 포인터를 반드시 chip 레코드에 보관해야 하는 것은 아닙니다. 다만 드라이버가 코덱 레지스터 값을 직접 바꾸거나 AC97 코덱의 suspend/resume 함수를 호출해야 한다면 대응 함수에 넘길 수 있도록 이 포인터를 유지해야 합니다.
단계입력과 결과
버스 생성snd_ac97_bus(card, 0, &ops, NULL, &bus)
템플릿 준비struct snd_ac97_template을 0으로 초기화
문맥 연결ac97.private_data = chip
코덱 생성snd_ac97_mixer(bus, &ac97, &chip->ac97)
공유 bus와 개별 코덱 인스턴스의 생성 순서를 정리합니다.
struct snd_ac97_bus_ops→공유 struct snd_ac97_bus→struct snd_ac97_template→개별 struct snd_ac97 인스턴스→필요하면 register 및 suspend/resume 함수에 전달
하나의 bus가 여러 AC97 인스턴스의 공통 접근 경로가 됩니다.
AC97 Constructor
----------------
To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
with an ``ac97_bus_ops_t`` record with callback functions::
struct snd_ac97_bus *bus;
static struct snd_ac97_bus_ops ops = {
.write = snd_mychip_ac97_write,
.read = snd_mychip_ac97_read,
};
snd_ac97_bus(card, 0, &ops, NULL, &pbus);
The bus record is shared among all belonging ac97 instances.
And then call :c:func:`snd_ac97_mixer()` with a struct snd_ac97_template
record together with the bus pointer created above::
struct snd_ac97_template ac97;
int err;
memset(&ac97, 0, sizeof(ac97));
ac97.private_data = chip;
snd_ac97_mixer(bus, &ac97, &chip->ac97);
where chip->ac97 is a pointer to a newly created ``ac97_t``
instance. In this case, the chip pointer is set as the private data,
so that the read/write callback functions can refer to this chip
instance. This instance is not necessarily stored in the chip
record. If you need to change the register values from the driver, or
need the suspend/resume of ac97 codecs, keep this pointer to pass to
the corresponding functions.
AC97 callback
2810-2850표준 AC97 callback은 `read`와 `write`이며, 각각 하드웨어 저수준 코드의 읽기와 쓰기 접근에 대응합니다. `read` callback은 인자로 받은 register 번호를 읽고 그 값을 `unsigned short`로 반환합니다. 예제처럼 `ac97->private_data`를 `struct mychip *`으로 받아 카드별 하드웨어에 접근할 수 있습니다.
`write` callback은 `reg`로 지정한 레지스터에 `val` 값을 설정합니다. 이들 callback은 control API callback과 마찬가지로 non-atomic context에서 실행되므로, 그 실행 문맥에 맞는 동기화와 접근 방법을 사용해야 합니다.
선택적으로 `reset`, `wait`, `init` callback도 제공할 수 있습니다. `reset`은 코덱을 재설정하며 chip이 특별한 reset 절차를 요구할 때 정의합니다. `wait`는 표준 코덱 초기화 과정에 추가 대기 시간이 필요할 때 사용합니다. `init`은 표준 절차 뒤에 코덱별 추가 초기화를 수행합니다.
Callback동작
read지정 register 값을 읽어 반환
write지정 register에 값 기록
resetchip별 특별한 코덱 reset
wait표준 초기화 중 추가 대기
init코덱별 추가 초기화
필수 저수준 접근과 선택적 초기화 callback을 구분합니다.
AC97 core가 read/write 호출→ac97->private_data에서 chip 복원→chip별 하드웨어 register 접근→read 값 반환 또는 write 완료
AC97 객체에서 카드별 하드웨어 문맥을 찾아 저수준 접근을 수행합니다.
AC97 Callbacks
--------------
The standard callbacks are ``read`` and ``write``. Obviously they
correspond to the functions for read and write accesses to the
hardware low-level codes.
The ``read`` callback returns the register value specified in the
argument::
static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
unsigned short reg)
{
struct mychip *chip = ac97->private_data;
....
return the_register_value;
}
Here, the chip can be cast from ``ac97->private_data``.
Meanwhile, the ``write`` callback is used to set the register
value::
static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
unsigned short reg, unsigned short val)
These callbacks are non-atomic like the control API callbacks.
There are also other callbacks: ``reset``, ``wait`` and ``init``.
The ``reset`` callback is used to reset the codec. If the chip
requires a special kind of reset, you can define this callback.
The ``wait`` callback is used to add some waiting time in the standard
initialization of the codec. If the chip requires the extra waiting
time, define this callback.
The ``init`` callback is used for additional initialization of the
codec.
드라이버의 AC97 레지스터 갱신
2851-2891드라이버에서 코덱에 접근해야 할 때는 :c:func:`snd_ac97_write()`, :c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()`, :c:func:`snd_ac97_update_bits()`를 사용할 수 있습니다. 이 도우미들은 앞서 보관한 AC97 인스턴스 포인터를 받습니다.
:c:func:`snd_ac97_write()`와 :c:func:`snd_ac97_update()`는 모두 지정한 `AC97_XXX` 레지스터에 값을 설정합니다. 차이는 이미 같은 값이 들어 있을 때 `snd_ac97_update()`는 쓰기를 생략하지만 `snd_ac97_write()`는 항상 값을 다시 쓴다는 점입니다. 예제의 `AC97_MASTER`에 `0x8080`을 쓰는 두 호출은 결과 값은 같아도 실제 bus write 여부가 다를 수 있습니다.
:c:func:`snd_ac97_read()`는 지정한 register의 현재 값을 읽습니다. :c:func:`snd_ac97_update_bits()`는 `mask`로 선택한 일부 bit만 `value`에 맞춰 갱신하여 나머지 bit를 보존합니다.
코덱이 VRA 또는 DRA를 지원하면 :c:func:`snd_ac97_set_rate()`로 `AC97_PCM_FRONT_DAC_RATE` 같은 지정 register의 sample rate를 바꿀 수 있습니다. 예제는 front DAC rate를 44,100 Hz로 설정합니다.
rate를 지정할 수 있는 register는 `AC97_PCM_MIC_ADC_RATE`, `AC97_PCM_FRONT_DAC_RATE`, `AC97_PCM_LR_ADC_RATE`, `AC97_SPDIF`입니다. `AC97_SPDIF`를 지정한 경우 실제 AC97 register 자체를 바꾸는 것이 아니라 대응하는 IEC958 status bit를 갱신합니다.
함수동작
snd_ac97_write()같은 값이어도 항상 register를 다시 씀
snd_ac97_update()현재 값과 다를 때만 register를 씀
snd_ac97_read()지정 register 값을 읽음
snd_ac97_update_bits()mask로 선택한 bit만 갱신
snd_ac97_set_rate()VRA/DRA 지원 코덱의 sample rate 설정
전체 값 쓰기, 조건부 쓰기, 읽기, 일부 bit 갱신을 구분합니다.
Register대상
AC97_PCM_MIC_ADC_RATE마이크 ADC rate
AC97_PCM_FRONT_DAC_RATE전면 DAC rate
AC97_PCM_LR_ADC_RATE좌우 ADC rate
AC97_SPDIFregister 대신 대응 IEC958 status bit 갱신
snd_ac97_set_rate()가 다루는 register와 의미입니다.
전체 값을 무조건 기록→snd_ac97_write()
전체 값이 다를 때만 기록→snd_ac97_update()
일부 bit만 변경→snd_ac97_update_bits()
VRA/DRA sample rate 변경→snd_ac97_set_rate()
변경 범위와 불필요한 쓰기 허용 여부에 따라 도우미를 선택합니다.
Updating Registers in The Driver
--------------------------------
If you need to access to the codec from the driver, you can call the
following functions: :c:func:`snd_ac97_write()`,
:c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and
:c:func:`snd_ac97_update_bits()`.
Both :c:func:`snd_ac97_write()` and
:c:func:`snd_ac97_update()` functions are used to set a value to
the given register (``AC97_XXX``). The difference between them is that
:c:func:`snd_ac97_update()` doesn't write a value if the given
value has been already set, while :c:func:`snd_ac97_write()`
always rewrites the value::
snd_ac97_write(ac97, AC97_MASTER, 0x8080);
snd_ac97_update(ac97, AC97_MASTER, 0x8080);
:c:func:`snd_ac97_read()` is used to read the value of the given
register. For example::
value = snd_ac97_read(ac97, AC97_MASTER);
:c:func:`snd_ac97_update_bits()` is used to update some bits in
the given register::
snd_ac97_update_bits(ac97, reg, mask, value);
Also, there is a function to change the sample rate (of a given register
such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
codec: :c:func:`snd_ac97_set_rate()`::
snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
The following registers are available to set the rate:
``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,
``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
specified, the register is not really changed but the corresponding
IEC958 status bits will be updated.
AC97 clock 조정과 proc 파일
2892-2907일부 chip은 수정 발진자를 아끼기 위해 코덱에 48,000 Hz 기준 clock이 아니라 PCI clock을 사용합니다. 이 경우 실제 기준값에 맞게 `bus->clock` field를 변경해야 합니다. `intel8x0`과 `es1968` 드라이버는 clock을 읽는 자체 함수를 둔 사례입니다.
ALSA AC97 interface는 `/proc/asound/card0/codec97#0/ac97#0-0`과 `ac97#0-0+regs` 같은 proc 파일을 만듭니다. 이 파일을 조회하면 현재 코덱 상태와 register 값을 확인할 수 있어 초기화와 레지스터 접근을 진단하는 데 사용할 수 있습니다.
항목사용법
bus->clock코덱의 실제 기준 clock 값으로 조정
ac97#0-0현재 코덱 상태 확인
ac97#0-0+regs현재 코덱 register 확인
비표준 기준 clock 보정과 런타임 상태 확인 수단입니다.
Clock Adjustment
----------------
In some chips, the clock of the codec isn't 48000 but using a PCI clock
(to save a quartz!). In this case, change the field ``bus->clock`` to
the corresponding value. For example, intel8x0 and es1968 drivers have
their own function to read from the clock.
Proc Files
----------
The ALSA AC97 interface will create a proc file such as
``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
can refer to these files to see the current status and registers of
the codec.
여러 AC97 코덱
2908-2918같은 카드에 여러 코덱이 있으면 `ac97.num=1` 이상의 서로 다른 codec 번호를 지정하여 :c:func:`snd_ac97_mixer()`를 여러 번 호출해야 합니다. `num` field가 각 코덱의 번호를 나타냅니다.
여러 코덱을 구성한 드라이버는 코덱별로 서로 다른 callback을 작성하거나, 공통 callback 안에서 `ac97->num`을 검사해 어느 코덱에 대한 요청인지 구분해야 합니다. 다음 2,919행부터는 `MIDI (MPU401-UART) Interface` 절로 이어집니다.
위치구분 방법
생성각 template의 ac97.num에 codec 번호 지정
callback코덱별 callback 사용 또는 ac97->num 검사
생성 시 번호 지정과 callback의 요청 분기 방법입니다.
Multiple Codecs
---------------
When there are several codecs on the same card, you need to call
:c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or
greater. The ``num`` field specifies the codec number.
If you set up multiple codecs, you either need to write different
callbacks for each codec or check ``ac97->num`` in the callback
routines.
MIDI MPU401-UART 개요
2919-2932많은 sound card에는 MIDI용 `MPU401-UART` interface가 내장되어 있습니다. 카드가 표준 MPU401-UART interface를 지원한다면 대개 ALSA의 MPU401-UART API를 그대로 사용할 수 있으며, 관련 선언은 `<sound/mpu401.h>`에 있습니다.
일부 sound chip은 MPU401과 비슷하지만 세부 구현이 다릅니다. 예를 들어 `emu10k1`은 자체 MPU401 routine을 사용하므로, 표준 helper를 적용하기 전에 chip의 실제 register와 interrupt 동작이 호환되는지 확인해야 합니다.
Hardware사용 경로
표준 MPU401-UART<sound/mpu401.h>의 ALSA MPU401-UART API
유사하지만 다른 구현chip 전용 routine; emu10k1이 예
표준 UART와 chip 전용 구현을 구분합니다.
MIDI (MPU401-UART) Interface
============================
General
-------
Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
soundcard supports the standard MPU401-UART interface, most likely you
can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
``<sound/mpu401.h>``.
Some soundchips have a similar but slightly different implementation of
mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
MIDI 생성자와 기본 인자
2933-2952RawMIDI 객체는 :c:func:`snd_mpu401_uart_new()`로 생성합니다. 예제는 card, component index 0, hardware type `MPU401_HW_MPU401`, I/O port, 추가 정보 flag, IRQ를 전달하고 결과 `struct snd_rawmidi *rmidi`를 받습니다.
첫 번째 인자는 card pointer이고 두 번째는 이 component의 index입니다. RawMIDI device는 최대 8개까지 만들 수 있습니다. 세 번째 인자는 `MPU401_HW_XXX` 형식의 hardware type이며 특별한 종류가 아니라면 `MPU401_HW_MPU401`을 사용합니다.
네 번째 인자는 I/O port 주소입니다. 하위 호환 MPU401은 흔히 `0x330` 같은 독립 I/O port를 사용하지만, 자체 PCI I/O 영역의 일부일 수도 있습니다. 정확한 주소 형태는 chip 설계에 달려 있습니다.
순서인자의미
1cardsound card pointer
2index0~7 component index
3MPU401_HW_XXXhardware type
4port독립 I/O port 또는 PCI I/O 영역 안의 주소
생성자 앞부분의 카드, 식별자, hardware, port를 정리합니다.
Card와 component index 선택→MPU401 hardware type 지정→I/O 또는 MMIO 주소 준비→정보 flag와 IRQ 지정→snd_mpu401_uart_new()→struct snd_rawmidi 반환
Hardware 접근 정보에서 ALSA RawMIDI 객체가 만들어집니다.
MIDI Constructor
----------------
To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`::
struct snd_rawmidi *rmidi;
snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
irq, &rmidi);
The first argument is the card pointer, and the second is the index of
this component. You can create up to 8 rawmidi devices.
The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
it's not a special one, you can use ``MPU401_HW_MPU401``.
The 4th argument is the I/O port address. Many backward-compatible
MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
PCI I/O region. It depends on the chip design.
MPU401 정보 flag
2953-2974다섯 번째 인자는 추가 정보를 나타내는 bit flag입니다. 앞의 I/O port가 PCI I/O 영역에 포함되어 카드 드라이버가 이미 그 영역을 할당하거나 예약했다면 `MPU401_INFO_INTEGRATED`를 전달합니다. 원문은 이 경우 mpu401-uart 계층이 I/O port를 스스로 할당한다고 설명하므로, 실제 소유 관계와 helper의 동작을 함께 확인해야 합니다.
Controller가 MIDI input 또는 output stream 중 하나만 지원하면 각각 `MPU401_INFO_INPUT` 또는 `MPU401_INFO_OUTPUT`을 전달합니다. 그러면 RawMIDI 인스턴스가 단일 stream으로 만들어집니다.
`MPU401_INFO_MMIO`는 `inb`/`outb` 대신 `readb`/`writeb`를 사용하는 MMIO 접근으로 바꿉니다. 이 경우 :c:func:`snd_mpu401_uart_new()`에는 I/O mapping을 마친 주소를 전달해야 합니다.
`MPU401_INFO_TX_IRQ`가 설정되면 기본 interrupt handler가 output stream을 검사하지 않습니다. 드라이버의 IRQ handler가 직접 :c:func:`snd_mpu401_uart_interrupt_tx()`를 호출해 output stream 처리를 시작해야 합니다.
MPU-401 interface가 카드의 다른 논리 device와 interrupt를 공유한다면 `MPU401_INFO_IRQ_HOOK`을 설정하고, 뒤의 MIDI interrupt handler 절에서 설명하는 방식으로 카드 드라이버의 handler에 연결합니다.
Flag의미
MPU401_INFO_INTEGRATED카드의 통합 I/O 영역과 관련된 port 처리
MPU401_INFO_INPUTinput-only RawMIDI stream
MPU401_INFO_OUTPUToutput-only RawMIDI stream
MPU401_INFO_MMIOreadb/writeb 기반 MMIO 접근
MPU401_INFO_TX_IRQdriver가 snd_mpu401_uart_interrupt_tx() 호출
MPU401_INFO_IRQ_HOOK카드의 공유 interrupt handler에 UART 처리 연결
접근 방식, stream 방향, interrupt 소유권을 지정합니다.
The 5th argument is a bitflag for additional information. When the I/O
port address above is part of the PCI I/O region, the MPU401 I/O port
might have been already allocated (reserved) by the driver itself. In
such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
mpu401-uart layer will allocate the I/O ports by itself.
When the controller supports only the input or output MIDI stream, pass
the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
respectively. Then the rawmidi instance is created as a single stream.
``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
(via readb and writeb) instead of iob and outb. In this case, you have
to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
the default interrupt handler. The driver needs to call
:c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
processing the output stream in the irq handler.
If the MPU-401 interface shares its interrupt with the other logical
devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
`below <MIDI Interrupt Handler_>`__).MPU401 command port와 IRQ
2975-2995보통 `port` 주소는 command port이고 `port + 1`은 data port입니다. 배치가 다르면 생성 후 `struct snd_mpu401`의 `cport` field를 수동으로 바꿀 수 있습니다.
:c:func:`snd_mpu401_uart_new()`는 `struct snd_mpu401` pointer를 직접 반환하지 않습니다. 대신 반환된 RawMIDI 객체의 `rmidi->private_data`를 `struct snd_mpu401 *`로 명시적으로 받아 `mpu->cport = my_own_control_port`처럼 원하는 control port를 설정합니다.
여섯 번째 인자는 할당할 ISA IRQ 번호입니다. 카드 코드가 공유 interrupt를 이미 할당했거나 device가 interrupt를 쓰지 않아 MPU401 계층이 별도 IRQ를 할당하면 안 되는 경우에는 `-1`을 전달합니다. Interrupt가 없는 MPU-401 device는 대신 polling timer를 사용합니다.
항목기본값 또는 처리
command portport
data portport + 1
비표준 command portrmidi->private_data에서 mpu를 얻어 mpu->cport 변경
전용 ISA IRQ여섯 번째 인자에 IRQ 번호
공유 또는 IRQ 없음-1; IRQ가 없으면 polling timer
기본 배치와 예외 구성을 정리합니다.
Usually, the port address corresponds to the command port and port + 1
corresponds to the data port. If not, you may change the ``cport``
field of struct snd_mpu401 manually afterward.
However, struct snd_mpu401 pointer is
not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly::
struct snd_mpu401 *mpu;
mpu = rmidi->private_data;
and reset the ``cport`` as you like::
mpu->cport = my_own_control_port;
The 6th argument specifies the ISA irq number that will be allocated. If
no interrupt is to be allocated (because your code is already allocating
a shared interrupt, or because the device does not use interrupts), pass
-1 instead. For a MPU-401 device without an interrupt, a polling timer
will be used instead.
MIDI interrupt handler
2996-3014:c:func:`snd_mpu401_uart_new()`가 interrupt를 직접 할당하면 전용 ISA interrupt handler가 자동으로 사용됩니다. 이 경우 드라이버는 MPU401 객체를 만드는 것 외에 별도 interrupt 연결 코드를 작성할 필요가 없습니다.
그렇지 않고 카드 드라이버가 interrupt를 공유하거나 직접 관리하면 `MPU401_INFO_IRQ_HOOK`을 설정해야 합니다. 카드의 handler가 UART interrupt 발생을 판별한 뒤 :c:func:`snd_mpu401_uart_interrupt()`를 명시적으로 호출합니다.
이 호출의 두 번째 인자에는 :c:func:`snd_mpu401_uart_new()`가 반환한 RawMIDI 객체의 `rmidi->private_data`를 전달합니다. 예제 호출은 `snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs)`입니다.
카드 interrupt 발생→UART interrupt 여부 판별→rmidi->private_data 준비→snd_mpu401_uart_interrupt() 호출→MPU401 input/output 처리
카드 IRQ handler가 UART 발생 여부를 판별한 뒤 ALSA helper로 넘깁니다.
MIDI Interrupt Handler
----------------------
When the interrupt is allocated in
:c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
handler is automatically used, hence you don't have anything else to do
than creating the mpu401 stuff. Otherwise, you have to set
``MPU401_INFO_IRQ_HOOK``, and call
:c:func:`snd_mpu401_uart_interrupt()` explicitly from your own
interrupt handler when it has determined that a UART interrupt has
occurred.
In this case, you need to pass the private_data of the returned rawmidi
object from :c:func:`snd_mpu401_uart_new()` as the second
argument of :c:func:`snd_mpu401_uart_interrupt()`::
snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
RawMIDI interface 개요
3015-3029Raw MIDI interface는 byte stream으로 접근할 수 있는 hardware MIDI port에 사용합니다. MIDI 명령을 직접 이해하지 못하는 synthesizer chip을 제어하는 interface는 아닙니다.
ALSA가 file과 buffer 관리를 담당하므로 드라이버가 구현할 핵심은 ALSA buffer와 hardware 사이에서 data를 이동하는 코드입니다. RawMIDI API는 `<sound/rawmidi.h>`에 정의되어 있습니다.
주체역할
ALSA RawMIDI corefile과 buffer 관리
Hardware driverbuffer와 MIDI port 사이의 byte 이동
적용 대상byte stream으로 접근 가능한 hardware MIDI port
Core가 관리하는 부분과 driver가 구현하는 부분입니다.
RawMIDI Interface
=================
Overview
--------
The raw MIDI interface is used for hardware MIDI ports that can be
accessed as a byte stream. It is not used for synthesizer chips that do
not directly understand MIDI.
ALSA handles file and buffer management. All you have to do is to write
some code to move data between the buffer and the hardware.
The rawmidi API is defined in ``<sound/rawmidi.h>``.
RawMIDI 생성자와 operator
3030-3078RawMIDI device는 :c:func:`snd_rawmidi_new()`로 만듭니다. 예제는 `chip->card`, ID 문자열 `MyMIDI`, component index 0, output과 input substream 수를 전달하고 `rmidi`를 받습니다. 오류면 음수 값을 반환하며, 성공 후 `rmidi->private_data = chip`으로 callback context를 저장하고 사람이 읽을 이름을 `My MIDI`로 설정합니다.
첫 번째 인자는 card pointer, 두 번째는 ID string, 세 번째는 component index이며 최대 8개의 RawMIDI device를 만들 수 있습니다. 네 번째와 다섯 번째 인자는 각각 output과 input substream 수이고, RawMIDI의 substream 하나는 MIDI port 하나에 해당합니다.
`info_flags`에는 device capability를 설정합니다. Output port가 하나 이상이면 `SNDRV_RAWMIDI_INFO_OUTPUT`, input port가 하나 이상이면 `SNDRV_RAWMIDI_INFO_INPUT`, input과 output을 동시에 처리할 수 있으면 `SNDRV_RAWMIDI_INFO_DUPLEX`를 지정합니다.
Device를 만든 뒤 각 방향의 substream에 operator callback을 설정해야 합니다. :c:func:`snd_rawmidi_set_ops()`를 output과 input stream에 각각 호출하면 해당 방향의 모든 substream에 `struct snd_rawmidi_ops`가 적용됩니다.
일반적인 output ops에는 `.open`, `.close`, `.trigger`가 들어갑니다. 이 callback들의 구체적인 계약은 뒤의 RawMIDI callback 절에서 설명합니다.
순서인자의미
1cardsound card pointer
2IDcomponent ID string
3index0~7 device index
4outsoutput substream 또는 MIDI port 수
5insinput substream 또는 MIDI port 수
6rmidi생성된 struct snd_rawmidi 반환
RawMIDI device와 port 수를 정의합니다.
Flag조건
SNDRV_RAWMIDI_INFO_OUTPUToutput port가 하나 이상
SNDRV_RAWMIDI_INFO_INPUTinput port가 하나 이상
SNDRV_RAWMIDI_INFO_DUPLEXinput과 output 동시 처리 가능
info_flags가 userspace에 알리는 동작 범위입니다.
snd_rawmidi_new()→private_data와 name 설정→info_flags로 capability 선언→snd_rawmidi_set_ops() output→snd_rawmidi_set_ops() input→각 substream에 callback 적용
Device 생성 후 방향별 callback을 연결합니다.
RawMIDI Constructor
-------------------
To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
function::
struct snd_rawmidi *rmidi;
err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
if (err < 0)
return err;
rmidi->private_data = chip;
strcpy(rmidi->name, "My MIDI");
rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
SNDRV_RAWMIDI_INFO_INPUT |
SNDRV_RAWMIDI_INFO_DUPLEX;
The first argument is the card pointer, the second argument is the ID
string.
The third argument is the index of this component. You can create up to
8 rawmidi devices.
The fourth and fifth arguments are the number of output and input
substreams, respectively, of this device (a substream is the equivalent
of a MIDI port).
Set the ``info_flags`` field to specify the capabilities of the
device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one
output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one
input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle
output and input at the same time.
After the rawmidi device is created, you need to set the operators
(callbacks) for each substream. There are helper functions to set the
operators for all the substreams of a device::
snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
The operators are usually defined like this::
static struct snd_rawmidi_ops snd_mymidi_output_ops = {
.open = snd_mymidi_output_open,
.close = snd_mymidi_output_close,
.trigger = snd_mymidi_output_trigger,
};
These callbacks are explained in the `RawMIDI Callbacks`_ section.
RawMIDI substream 이름과 문맥
3079-3102Substream이 둘 이상이면 각각 고유한 이름을 부여해야 합니다. 예제는 output stream의 substream list를 순회하면서 `substream->number + 1`을 사용해 `My MIDI Port 1` 같은 이름을 만들며, input stream에도 같은 작업을 수행합니다. 원문 예제의 `list {` 표기는 그대로 보존하되 실제 구현에서는 현재 kernel list macro 문법을 확인해야 합니다.
모든 callback에서는 RawMIDI device에 저장한 private data를 `substream->rmidi->private_data`로 참조할 수 있습니다. Port가 여러 개라면 callback 인자로 받은 `struct snd_rawmidi_substream`의 `substream->number`를 port index로 사용해 hardware channel을 구분합니다.
정보접근
고유 표시 이름substream->name
0부터 시작하는 port indexsubstream->number
카드별 driver contextsubstream->rmidi->private_data
Output 방향 listrmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams
Input 방향 listrmidi->streams[SNDRV_RAWMIDI_STREAM_INPUT].substreams
이름, 번호, driver context의 접근 경로입니다.
If there are more than one substream, you should give a unique name to
each of them::
struct snd_rawmidi_substream *substream;
list_for_each_entry(substream,
&rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
list {
sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
}
/* same for SNDRV_RAWMIDI_STREAM_INPUT */
RawMIDI Callbacks
-----------------
In all the callbacks, the private data that you've set for the rawmidi
device can be accessed as ``substream->rmidi->private_data``.
If there is more than one port, your callbacks can determine the port
index from the struct snd_rawmidi_substream data passed to each
callback::
struct snd_rawmidi_substream *substream;
int index = substream->number;
RawMIDI open과 close callback
3103-3125`open` callback의 형식은 `static int snd_xxx_open(struct snd_rawmidi_substream *substream)`입니다. Substream이 열릴 때 호출되며 hardware를 초기화할 수 있지만, 이 시점에는 아직 data 송신이나 수신을 시작하면 안 됩니다.
`close` callback은 같은 substream 인자를 받아 열린 port를 닫을 때 호출됩니다. 원문의 짧은 `Guess what.` 문장은 close가 예상한 정리 동작을 맡는다는 익살스러운 표현이며, 구체적인 hardware 종료 절차는 driver가 구현합니다.
RawMIDI device의 `open`과 `close` callback은 mutex로 직렬화되며 sleep할 수 있습니다. 따라서 이 두 callback은 non-atomic 초기화와 정리 작업을 수행할 수 있습니다.
Callback허용 동작
openHardware 초기화; 송수신은 아직 시작하지 않음
closeHardware와 port 정리
공통 문맥Mutex로 직렬화되며 sleep 가능
Data 전송을 시작하는 trigger와 실행 문맥이 다릅니다.
RawMIDI open callback
~~~~~~~~~~~~~~~~~~~~~
::
static int snd_xxx_open(struct snd_rawmidi_substream *substream);
This is called when a substream is opened. You can initialize the
hardware here, but you shouldn't start transmitting/receiving data yet.
RawMIDI close callback
~~~~~~~~~~~~~~~~~~~~~~
::
static int snd_xxx_close(struct snd_rawmidi_substream *substream);
Guess what.
The ``open`` and ``close`` callbacks of a rawmidi device are
serialized with a mutex, and can sleep.
RawMIDI output trigger
3126-3174Output substream의 `trigger` callback은 `static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up)` 형식입니다. `up`이 0이 아니면 substream buffer에 전송해야 할 data가 있다는 뜻입니다.
Buffer data를 확인할 때 :c:func:`snd_rawmidi_transmit_peek()`를 호출하면 읽어 본 byte 수를 반환합니다. Buffer에 남은 data가 요청량보다 적으면 반환값도 작습니다. Hardware 전송이 실제로 성공한 뒤에만 :c:func:`snd_rawmidi_transmit_ack()`를 호출해 그 byte를 substream buffer에서 제거합니다. 예제는 한 byte를 peek하고 FIFO가 받을 때 ack하며, FIFO가 가득 차면 loop를 멈춥니다.
Hardware가 data를 받아들일 수 있음을 미리 안다면 :c:func:`snd_rawmidi_transmit()`을 사용할 수 있습니다. 이 함수는 data를 읽는 동시에 buffer에서 제거하므로, 반환된 byte를 반드시 hardware로 보낼 수 있는 조건에서 사용해야 합니다. 수용 가능한 byte 수를 미리 알면 `snd_rawmidi_transmit*()` 함수에 1보다 큰 buffer 크기를 전달할 수 있습니다.
`trigger` callback은 sleep하면 안 됩니다. Substream buffer를 모두 비우기 전에 hardware FIFO가 가득 차면, MIDI transmit interrupt가 있을 때는 interrupt handler에서, 없다면 timer에서 나머지 전송을 계속해야 합니다.
`up`이 0인 상태로 `trigger`가 호출되면 진행 중인 data 전송을 중단해야 합니다.
함수Buffer 처리사용 조건
snd_rawmidi_transmit_peek()Data를 보되 제거하지 않음Hardware 전송 성공 뒤 ack 가능
snd_rawmidi_transmit_ack()성공한 data를 제거실제 전송이 끝난 뒤
snd_rawmidi_transmit()읽기와 제거를 한 번에 수행Hardware가 즉시 받을 수 있음이 확실할 때
전송 성공을 사전에 보장할 수 있는지에 따라 buffer 제거 시점이 달라집니다.
up != 0 trigger→transmit_peek()으로 data 확인→Hardware FIFO 전송 시도→성공하면 transmit_ack()→FIFO가 차면 IRQ 또는 timer에서 재개
up == 0 trigger→전송 중단
FIFO 수용 가능 여부를 확인하며 ack와 후속 처리를 결정합니다.
Rawmidi trigger callback for output substreams
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
This is called with a nonzero ``up`` parameter when there is some data
in the substream buffer that must be transmitted.
To read data from the buffer, call
:c:func:`snd_rawmidi_transmit_peek()`. It will return the number
of bytes that have been read; this will be less than the number of bytes
requested when there are no more data in the buffer. After the data have
been transmitted successfully, call
:c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
substream buffer::
unsigned char data;
while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
if (snd_mychip_try_to_transmit(data))
snd_rawmidi_transmit_ack(substream, 1);
else
break; /* hardware FIFO full */
}
If you know beforehand that the hardware will accept data, you can use
the :c:func:`snd_rawmidi_transmit()` function which reads some
data and removes them from the buffer at once::
while (snd_mychip_transmit_possible()) {
unsigned char data;
if (snd_rawmidi_transmit(substream, &data, 1) != 1)
break; /* no more data */
snd_mychip_transmit(data);
}
If you know beforehand how many bytes you can accept, you can use a
buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.
The ``trigger`` callback must not sleep. If the hardware FIFO is full
before the substream buffer has been emptied, you have to continue
transmitting data later, either in an interrupt handler, or with a
timer if the hardware doesn't have a MIDI transmit interrupt.
The ``trigger`` callback is called with a zero ``up`` parameter when
the transmission of data should be aborted.
RawMIDI input trigger
3175-3201Input substream의 `trigger` callback은 `static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up)` 형식입니다. `up`이 0이 아니면 data 수신을 활성화하고, 0이면 수신을 비활성화합니다.
Input `trigger`도 sleep하면 안 됩니다. Device에서 실제 data를 읽는 작업은 보통 interrupt handler가 수행합니다.
수신이 활성화된 동안 interrupt handler는 hardware에 도착한 모든 data에 대해 :c:func:`snd_rawmidi_receive()`를 호출해야 합니다. 예제는 data가 존재하는 동안 한 byte씩 hardware에서 읽고, 해당 byte를 RawMIDI substream buffer에 전달합니다.
상태동작
up != 0Hardware 수신 활성화
up == 0Hardware 수신 비활성화
Interrupt handler도착 byte마다 snd_rawmidi_receive() 호출
Trigger contextSleep 금지
up 값과 실제 수신 처리 위치를 구분합니다.
Input trigger로 수신 활성화→MIDI interrupt 발생→Hardware에 data가 있는 동안 읽기→snd_rawmidi_receive(substream, data, count)→Userspace가 RawMIDI buffer에서 읽음
Hardware byte를 ALSA RawMIDI buffer로 옮깁니다.
RawMIDI trigger callback for input substreams
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
This is called with a nonzero ``up`` parameter to enable receiving data,
or with a zero ``up`` parameter do disable receiving data.
The ``trigger`` callback must not sleep; the actual reading of data
from the device is usually done in an interrupt handler.
When data reception is enabled, your interrupt handler should call
:c:func:`snd_rawmidi_receive()` for all received data::
void snd_mychip_midi_interrupt(...)
{
while (mychip_midi_available()) {
unsigned char data;
data = mychip_midi_read();
snd_rawmidi_receive(substream, &data, 1);
}
}
RawMIDI drain callback
3202-3218`drain` callback은 output substream에만 사용합니다. Substream buffer에서 읽어 간 모든 data가 hardware로 실제 전송될 때까지 기다려야 합니다. 이 보장은 device를 닫거나 driver를 unload할 때 아직 전달되지 않은 MIDI data가 유실되는 것을 막습니다.
이 callback은 선택 사항입니다. `struct snd_rawmidi_ops`에 `drain`을 설정하지 않으면 ALSA는 대신 50 millisecond를 단순히 기다립니다. 정확한 완료 감지가 가능한 hardware라면 전용 drain을 구현하는 편이 전송 보장을 더 명확하게 합니다. 다음 3,219행부터는 `Miscellaneous Devices` 절입니다.
구성닫기 전 동작
drain callback 제공모든 읽힌 data의 실제 hardware 전송 완료까지 대기
drain callback 없음ALSA가 50 ms 대기
적용 방향Output substream 전용
명시적 완료 대기와 기본 fallback을 비교합니다.
drain callback
~~~~~~~~~~~~~~
::
static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
This is only used with output substreams. This function should wait
until all data read from the substream buffer have been transmitted.
This ensures that the device can be closed and the driver unloaded
without losing data.
This callback is optional. If you do not set ``drain`` in the struct
snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
instead.
FM OPL3과 direct-FM
3219-3234FM OPL3는 주로 하위 호환성 때문에 여전히 많은 chip에서 사용됩니다. ALSA는 OPL3 FM control 계층을 제공하며 OPL3 API는 `<sound/opl3.h>`에 정의되어 있습니다.
FM register는 `<sound/asound_fm.h>`의 direct-FM API로 직접 접근할 수 있습니다. ALSA native mode에서는 Hardware-Dependent Device의 direct-FM extension API를 사용하고, OSS compatibility mode에서는 `/dev/dmfmX` device가 제공하는 OSS direct-FM compatible API를 사용합니다.
Mode접근 API
ALSA nativeHwdep direct-FM extension API
OSS compatible/dev/dmfmX의 OSS direct-FM API
공통 선언<sound/opl3.h> 및 <sound/asound_fm.h>
실행 mode에 따라 FM register를 노출하는 interface가 달라집니다.
Miscellaneous Devices
=====================
FM OPL3
-------
The FM OPL3 is still used in many chips (mainly for backward
compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API
is defined in ``<sound/opl3.h>``.
FM registers can be directly accessed through the direct-FM API, defined
in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
accessed through the Hardware-Dependent Device direct-FM extension API,
whereas in OSS compatible mode, FM registers can be accessed with the
OSS direct-FM compatible API in ``/dev/dmfmX`` device.
표준 OPL3 생성
3235-3251OPL3 component를 만들려면 두 함수를 차례로 호출합니다. 먼저 :c:func:`snd_opl3_create()`로 `opl3_t`, 즉 `struct snd_opl3` 인스턴스를 생성합니다.
첫 번째 인자는 card pointer, 두 번째는 left port 주소, 세 번째는 right port 주소입니다. 대부분 right port는 `left port + 2`에 위치합니다. 네 번째 인자는 `OPL3_HW_OPL3_XXX` 형식의 hardware type입니다.
Card driver가 left와 right port를 이미 할당했다면 다섯 번째 `integrated` 인자에 0이 아닌 값을 전달합니다. 그렇지 않으면 OPL3 module이 지정된 port를 직접 할당합니다.
인자의미
cardsound card pointer
lportleft port 주소
rportright port 주소; 보통 lport + 2
OPL3_HW_OPL3_XXXhardware type
integratedport가 이미 card driver에 할당되었는지 표시
opl3생성된 struct snd_opl3 반환
표준 I/O 방식의 OPL3 인스턴스 구성입니다.
Left/right port와 hardware type 준비→Port 선할당 여부로 integrated 설정→snd_opl3_create()→Port 할당과 snd_opl3_init() 내부 수행→struct snd_opl3 반환
Port 소유권을 반영해 인스턴스를 초기화합니다.
To create the OPL3 component, you have two functions to call. The first
one is a constructor for the ``opl3_t`` instance::
struct snd_opl3 *opl3;
snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
integrated, &opl3);
The first argument is the card pointer, the second one is the left port
address, and the third is the right port address. In most cases, the
right port is placed at the left port + 2.
The fourth argument is the hardware type.
When the left and right ports have been already allocated by the card
driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
the opl3 module will allocate the specified ports by itself.
사용자 지정 OPL3 접근과 hwdep
3252-3282표준 I/O 접근이 아닌 특별한 hardware 접근법이 필요하면 :c:func:`snd_opl3_new()`로 OPL3 인스턴스만 별도로 생성합니다. 그 뒤 전용 접근 함수 `command`, callback context `private_data`, destructor `private_free`를 설정합니다.
이 방식에서는 `l_port`와 `r_port`를 반드시 설정할 필요가 없지만 `command`는 올바르게 지정해야 합니다. 전용 접근 함수에서는 `opl3->private_data`를 통해 driver data를 가져올 수 있습니다.
:c:func:`snd_opl3_new()`로 생성한 뒤에는 :c:func:`snd_opl3_init()`을 호출해 chip을 올바른 상태로 초기화해야 합니다. 반면 :c:func:`snd_opl3_create()`는 내부에서 이 초기화를 항상 수행합니다.
OPL3 인스턴스 생성에 성공하면 :c:func:`snd_opl3_hwdep_new()`로 대응하는 hwdep device를 만듭니다. 첫 인자는 OPL3 인스턴스, 두 번째는 보통 0인 hwdep index, 세 번째는 OPL3 port에 할당되는 sequencer client의 index offset입니다. MPU401-UART가 함께 있으면 UART가 0을 사용하므로 OPL3 offset에는 1을 지정합니다.
Field역할
command필수 전용 hardware 접근 함수
private_data전용 driver context
private_freecontext destructor
l_port / r_port전용 접근에서는 선택 사항
비표준 hardware 접근에 필요한 callback과 context입니다.
snd_opl3_new()→command/private_data/private_free 설정→snd_opl3_init()→snd_opl3_hwdep_new()→Direct-FM hwdep device 등록
인스턴스 생성, 명시적 초기화, hwdep 노출 순서입니다.
When the accessing the hardware requires special method instead of the
standard I/O access, you can create opl3 instance separately with
:c:func:`snd_opl3_new()`::
struct snd_opl3 *opl3;
snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
Then set ``command``, ``private_data`` and ``private_free`` for the
private access function, the private data and the destructor. The
``l_port`` and ``r_port`` are not necessarily set. Only the command
must be set properly. You can retrieve the data from the
``opl3->private_data`` field.
After creating the opl3 instance via :c:func:`snd_opl3_new()`,
call :c:func:`snd_opl3_init()` to initialize the chip to the
proper state. Note that :c:func:`snd_opl3_create()` always calls
it internally.
If the opl3 instance is created successfully, then create a hwdep device
for this opl3::
struct snd_hwdep *opl3hwdep;
snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
The first argument is the ``opl3_t`` instance you created, and the
second is the index number, usually 0.
The third argument is the index-offset for the sequencer client assigned
to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
always takes 0).
Hardware-dependent device 생성
3283-3315일부 chip은 특수 control이나 microcode loading을 위해 userspace의 직접 접근이 필요합니다. 이때 hwdep(hardware-dependent) device를 만들 수 있습니다. API는 `<sound/hwdep.h>`에 있으며 OPL3 driver와 `isa/sb/sb16_csp.c`에서 예제를 찾을 수 있습니다.
Hwdep 인스턴스는 :c:func:`snd_hwdep_new()`로 만듭니다. 예제의 세 번째 인자 0은 hwdep index이며, 결과는 `struct snd_hwdep *hw`에 저장됩니다.
`private_data`에는 임의의 pointer를 보관할 수 있습니다. Private data를 할당했다면 `private_free` field에 destructor도 함께 설정해야 합니다. 예제는 `kmalloc()`으로 만든 `struct mydata`를 저장하고, destructor에서 `hw->private_data`를 꺼내 :c:func:`kfree()`합니다.
단계동작
생성snd_hwdep_new(card, ID, index, &hw)
Context 연결hw->private_data = p
Destructor 연결hw->private_free = mydata_free
해제private_free에서 kfree(hw->private_data)
Private data를 hwdep device와 함께 관리합니다.
Driver data 할당→hw->private_data 저장→hw->private_free 등록→Hwdep release→Destructor가 private data 해제
할당과 해제를 device lifetime에 묶습니다.
Hardware-Dependent Devices
--------------------------
Some chips need user-space access for special controls or for loading
the micro code. In such a case, you can create a hwdep
(hardware-dependent) device. The hwdep API is defined in
``<sound/hwdep.h>``. You can find examples in opl3 driver or
``isa/sb/sb16_csp.c``.
The creation of the ``hwdep`` instance is done via
:c:func:`snd_hwdep_new()`::
struct snd_hwdep *hw;
snd_hwdep_new(card, "My HWDEP", 0, &hw);
where the third argument is the index number.
You can then pass any pointer value to the ``private_data``. If you
assign private data, you should define a destructor, too. The
destructor function is set in the ``private_free`` field::
struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
hw->private_data = p;
hw->private_free = mydata_free;
and the implementation of the destructor would be::
static void mydata_free(struct snd_hwdep *hw)
{
struct mydata *p = hw->private_data;
kfree(p);
}
Hwdep file operation
3316-3325Hwdep 인스턴스에는 필요한 file operation을 임의로 정의할 수 있습니다. Operation은 `hw->ops` table에 넣으며, 예제는 `.open = mydata_open`, `.ioctl = mydata_ioctl`, `.release = mydata_release`를 연결합니다.
각 callback의 구체적인 정책은 chip의 userspace control이나 firmware loading protocol에 맞게 driver가 구현합니다.
Operation역할
openHwdep file open 준비
ioctlChip별 control command 처리
releaseFile별 상태 정리
Userspace file lifetime과 command 처리를 연결합니다.
The arbitrary file operations can be defined for this instance. The file
operators are defined in the ``ops`` table. For example, assume that
this chip needs an ioctl::
hw->ops.open = mydata_open;
hw->ops.ioctl = mydata_ioctl;
hw->ops.release = mydata_release;
And implement the callback functions as you like.
IEC958 S/PDIF control
3326-3359IEC958 device의 control은 보통 ALSA control interface로 구현합니다. `<include/asound.h>`에 정의된 :c:func:`SNDRV_CTL_NAME_IEC958()` macro로 표준 IEC958 control 이름을 조합할 수 있습니다.
IEC958 status bit용 표준 control은 `SNDRV_CTL_ELEM_TYPE_IEC958` type을 사용하며 element 크기는 `value.iec958.status[x]`로 접근하는 4-byte array로 고정됩니다. `info` callback에서는 count field는 설정하지만 이 type의 value field는 별도로 지정하지 않습니다.
원문 3,340~3,345행의 깨진 따옴표 표기는 문맥상 `IEC958 Playback Con Mask`, `IEC958 Playback Pro Mask`, `IEC958 Playback Default`를 뜻합니다. Con Mask는 consumer mode status bit mask, Pro Mask는 professional mode bit mask를 반환하며 둘 다 read-only control입니다. Playback Default는 현재 기본 IEC958 bit를 읽고 설정하는 control입니다.
역사적인 이유로 Playback Mask 두 종류와 Playback Default는 `SNDRV_CTL_ELEM_IFACE_PCM` 또는 `SNDRV_CTL_ELEM_IFACE_MIXER` 어느 iface에도 구현할 수 있습니다. 다만 한 driver의 mask와 default control은 같은 iface에 노출해야 합니다.
Enable/disable 또는 raw bit mode 설정용 switch도 chip에 맞춰 추가할 수 있습니다. 이름은 가급적 :c:func:`SNDRV_CTL_NAME_IEC958()` macro를 사용한 `IEC958 xxx` 형식을 따릅니다. 구현 예는 `pci/emu10k1`, `pci/ice1712`, `pci/cmipci.c`에 있습니다.
Control의미Access
IEC958 Playback Con MaskConsumer mode status bit maskRead-only
IEC958 Playback Pro MaskProfessional mode status bit maskRead-only
IEC958 Playback Default현재 기본 IEC958 status bitRead/write
Status mask와 기본값 control의 접근 권한입니다.
항목규칙
TypeSNDRV_CTL_ELEM_TYPE_IEC958
Data4-byte value.iec958.status[]
Infocount 설정; value field 지정 불필요
IfacePCM 또는 MIXER; mask와 default는 같은 iface
Control schema와 iface 배치 규칙입니다.
IEC958 (S/PDIF)
---------------
Usually the controls for IEC958 devices are implemented via the control
interface. There is a macro to compose a name string for IEC958
controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
``<include/asound.h>``.
There are some standard controls for IEC958 status bits. These controls
use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is
fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
callback, you don't specify the value field for this type (the count
field must be set, though).
“IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
returns the bitmask for professional mode. They are read-only controls.
Meanwhile, “IEC958 Playback Default” control is defined for getting and
setting the current default IEC958 bits.
Due to historical reasons, both variants of the Playback Mask and the
Playback Default controls can be implemented on either a
``SNDRV_CTL_ELEM_IFACE_PCM`` or a ``SNDRV_CTL_ELEM_IFACE_MIXER`` iface.
Drivers should expose the mask and default on the same iface though.
In addition, you can define the control switches to enable/disable or to
set the raw bit mode. The implementation will depend on the chip, but
the control should be named as “IEC958 xxx”, preferably using the
:c:func:`SNDRV_CTL_NAME_IEC958()` macro.
You can find several cases, for example, ``pci/emu10k1``,
``pci/ice1712``, or ``pci/cmipci.c``.
ALSA buffer 종류와 기본 할당
3360-3379ALSA는 bus와 architecture에 맞춘 여러 buffer allocation 함수를 제공하지만 API 형태는 일관됩니다. 물리적으로 연속된 page는 bus type이 이름에 들어가는 :c:func:`snd_malloc_xxx_pages()` 계열로 할당합니다.
:c:func:`snd_dma_alloc_pages_fallback()`은 요청한 page 수를 먼저 시도하고 공간이 부족하면 성공할 때까지 요청 크기를 줄입니다. 최소 한 page까지 내려가며 가능한 크기의 영역을 확보합니다.
할당한 page는 :c:func:`snd_dma_free_pages()`로 해제합니다.
함수동작
snd_malloc_xxx_pages()Bus type별 physically contiguous page 할당
snd_dma_alloc_pages_fallback()요청량에서 한 page까지 줄여가며 재시도
snd_dma_free_pages()할당 page 해제
연속 page 할당, fallback, 해제를 구분합니다.
Buffer and Memory Management
============================
Buffer Types
------------
ALSA provides several different buffer allocation functions depending on
the bus and the architecture. All these have a consistent API. The
allocation of physically-contiguous pages is done via the
:c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
type.
The allocation of pages with fallback is done via
:c:func:`snd_dma_alloc_pages_fallback()`. This function tries
to allocate the specified number of pages, but if not enough pages are
available, it tries to reduce the request size until enough space
is found, down to one page.
To release the pages, call the :c:func:`snd_dma_free_pages()`
function.PCM buffer pre-allocation
3380-3418ALSA driver는 module load 시점에 나중에 사용할 큰 연속 물리 공간을 미리 할당하고 예약하는 경우가 많습니다. 원문 3,383행의 깨진 표기는 문맥상 `pre-allocation`을 뜻합니다.
PCI PCM 생성 시 :c:func:`snd_pcm_lib_preallocate_pages_for_all()`에 PCM, DMA type `SNDRV_DMA_TYPE_DEV`, `&pci->dev`, 기본 `size`, 최대 `max`를 전달합니다. `size`는 미리 할당할 byte 수이고 `max`는 `prealloc` proc file을 통해 설정할 수 있는 최대 크기입니다. Allocator는 지정된 size 범위 안에서 가능한 한 큰 영역을 얻으려 합니다.
두 번째 DMA type과 세 번째 device pointer는 bus에 따라 달라집니다. 일반 device는 보통 `card->dev`와 같은 device pointer를 `SNDRV_DMA_TYPE_DEV`와 함께 전달합니다.
Bus와 무관한 continuous buffer에는 `SNDRV_DMA_TYPE_CONTINUOUS`를 사용합니다. Device pointer를 NULL로 두면 기본적으로 `GFP_KERNEL` 할당을 뜻합니다. 낮은 주소 같은 제한이 필요하면 device의 coherent DMA mask를 설정하고 일반 device memory처럼 device pointer를 넘깁니다. 주소 제한이 없으면 이 type에서도 NULL을 사용할 수 있습니다.
Scatter-gather buffer에는 device pointer와 `SNDRV_DMA_TYPE_DEV_SG`를 사용합니다. Buffer를 pre-allocate했다면 `hw_params` callback에서 :c:func:`snd_pcm_lib_malloc_pages()`로 요청 크기를 활성화할 수 있으며, 이 함수 사용 전에는 반드시 pre-allocation이 있어야 합니다.
인자의미
pcm대상 PCM instance
DMA typeDEV, CONTINUOUS, DEV_SG
device pointerDMA constraint를 제공하는 struct device 또는 NULL
size기본 pre-allocation byte 수
maxprealloc proc에서 허용할 최대 byte 수
기본 크기와 최대 크기, DMA 주소 조건을 지정합니다.
PCM constructor→snd_pcm_lib_preallocate_pages_for_all()→가능한 큰 영역 예약→hw_params→snd_pcm_lib_malloc_pages(substream, size)
PCM 생성 시 예약하고 hw_params에서 필요한 크기를 선택합니다.
Usually, ALSA drivers try to allocate and reserve a large contiguous
physical space at the time the module is loaded for later use. This
is called “pre-allocation”. As already written, you can call the
following function at PCM instance construction time (in the case of PCI
bus)::
snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
&pci->dev, size, max);
where ``size`` is the byte size to be pre-allocated and ``max`` is
the maximum size settable via the ``prealloc`` proc file. The
allocator will try to get an area as large as possible within the
given size.
The second argument (type) and the third argument (device pointer) are
dependent on the bus. For normal devices, pass the device pointer
(typically identical as ``card->dev``) to the third argument with
``SNDRV_DMA_TYPE_DEV`` type.
A continuous buffer unrelated to the
bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
You can pass NULL to the device pointer in that case, which is the
default mode implying to allocate with the ``GFP_KERNEL`` flag.
If you need a restricted (lower) address, set up the coherent DMA mask
bits for the device, and pass the device pointer, like the normal
device memory allocations. For this type, it's still allowed to pass
NULL to the device pointer, too, if no address restriction is needed.
For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the
device pointer (see the `Non-Contiguous Buffers`_ section).
Once the buffer is pre-allocated, you can use the allocator in the
``hw_params`` callback::
snd_pcm_lib_malloc_pages(substream, size);
Note that you have to pre-allocate to use this function.
PCM managed buffer allocation
3419-3435대부분의 driver는 수동 할당과 해제 대신 managed buffer allocation mode를 사용합니다. :c:func:`snd_pcm_lib_preallocate_pages_for_all()` 대신 :c:func:`snd_pcm_set_managed_buffer_all()`을 호출하며 인자는 동일합니다.
Managed mode에서는 PCM core가 PCM `hw_params` callback을 호출하기 전에 내부적으로 :c:func:`snd_pcm_lib_malloc_pages()`를 실행하고, PCM `hw_free` callback 뒤에는 :c:func:`snd_pcm_lib_free_pages()`를 자동 호출합니다.
따라서 driver callback이 이 함수들을 명시적으로 호출할 필요가 없고, 많은 driver가 `hw_params`와 `hw_free` ops entry를 NULL로 둘 수 있습니다.
Modemalloc/free 호출 주체
수동 pre-allocationDriver의 hw_params/hw_free callback
Managed bufferPCM core가 callback 전후에 자동 호출
Allocation helper 호출 주체가 다릅니다.
snd_pcm_set_managed_buffer_all()→PCM core가 malloc_pages()→hw_params callback→PCM 사용→hw_free callback→PCM core가 free_pages()
Core가 buffer 할당과 해제를 callback 경계에 배치합니다.
But most drivers use the "managed buffer allocation mode" instead
of manual allocation and release.
This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`
instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`::
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
&pci->dev, size, max);
where the passed arguments are identical for both functions.
The difference in the managed mode is that PCM core will call
:c:func:`snd_pcm_lib_malloc_pages()` internally already before calling
the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()`
after the PCM ``hw_free`` callback automatically. So the driver
doesn't have to call these functions explicitly in its callback any
longer. This allows many drivers to have NULL ``hw_params`` and
``hw_free`` entries.
외부 hardware buffer
3436-3463일부 chip은 자체 hardware buffer를 가지며 host memory에서 DMA transfer를 할 수 없습니다. 이 경우 첫째, audio data를 외부 hardware buffer에 직접 copy 또는 set하거나, 둘째, intermediate buffer를 만들고 interrupt 또는 가급적 tasklet에서 외부 buffer로 옮깁니다.
외부 buffer가 충분히 크다면 직접 접근 방식이 잘 동작합니다. 추가 buffer가 없어 효율적이며 data transfer용 `copy` callback과 playback silence용 `fill_silence` callback을 구현해야 합니다. 단점은 mmap을 지원할 수 없다는 것입니다. GUS GF1 PCM과 emu8000 wavetable PCM이 예입니다.
Intermediate buffer 방식은 mmap을 허용하지만 interrupt나 tasklet이 intermediate buffer에서 hardware buffer로 data를 복사해야 합니다. `vxpocket` driver에서 예를 볼 수 있습니다.
또 다른 경우는 host memory 대신 PCI memory-map 영역을 buffer로 사용하는 chip입니다. 이 buffer의 mmap은 Intel 같은 일부 architecture에서만 가능합니다. Non-mmap mode에서는 일반 방식으로 data를 옮길 수 없으므로 앞의 경우처럼 `copy`와 `fill_silence` callback을 구현합니다. `rme32.c`와 `rme96.c`가 예입니다.
전략장점제약
Hardware buffer 직접 접근추가 buffer 없이 효율적mmap 불가; copy/fill_silence 필요
Intermediate buffermmap 가능IRQ 또는 tasklet 복사 필요
PCI memory-map buffer일부 architecture에서 mmapNon-mmap에서는 copy/fill_silence 필요
효율, mmap 가능성, 추가 전송 작업을 비교합니다.
Host DMA 불가→큰 외부 buffer→직접 copy/fill_silence
Host DMA 불가→mmap 필요→Intermediate buffer→IRQ/tasklet에서 외부 buffer로 복사
Hardware mapping 특성에 따라 data 이동 경로를 정합니다.
External Hardware Buffers
-------------------------
Some chips have their own hardware buffers and DMA transfer from the
host memory is not available. In such a case, you need to either 1)
copy/set the audio data directly to the external hardware buffer, or 2)
make an intermediate buffer and copy/set the data from it to the
external hardware buffer in interrupts (or in tasklets, preferably).
The first case works fine if the external hardware buffer is large
enough. This method doesn't need any extra buffers and thus is more
efficient. You need to define the ``copy`` callback
for the data transfer, in addition to the ``fill_silence``
callback for playback. However, there is a drawback: it cannot be
mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.
The second case allows for mmap on the buffer, although you have to
handle an interrupt or a tasklet to transfer the data from the
intermediate buffer to the hardware buffer. You can find an example in
the vxpocket driver.
Another case is when the chip uses a PCI memory-map region for the
buffer instead of the host memory. In this case, mmap is available only
on certain architectures like the Intel one. In non-mmap mode, the data
cannot be transferred as in the normal way. Thus you need to define the
``copy`` and ``fill_silence`` callbacks as well,
as in the cases above. Examples are found in ``rme32.c`` and
``rme96.c``.PCM copy callback
3464-3520`copy`와 silence callback의 구현은 hardware가 interleaved 또는 non-interleaved sample을 지원하는지에 따라 달라집니다. Playback copy는 source `struct iov_iter *src`, capture copy는 destination `struct iov_iter *dst`를 받으며, 공통으로 substream, channel, byte 위치 `pos`, byte 수 `count`를 받습니다.
Interleaved sample에서는 두 번째 `channel` 인자를 사용하지 않습니다. 세 번째 `pos`는 byte 단위 hardware buffer 위치입니다. 네 번째 인자는 playback에서는 source data iterator, capture에서는 destination data iterator이며 마지막 `count`는 복사할 byte 수입니다.
Playback callback은 `src`의 `count` byte를 hardware buffer의 `pos` offset으로 복사합니다. 원문의 memcpy 형태 예는 `my_memcpy_from_iter(my_buffer + pos, src, count)`입니다. Capture callback은 반대로 hardware buffer의 `pos`부터 `count` byte를 `dst`로 옮기며 예는 `my_memcpy_to_iter(dst, my_buffer + pos, count)`입니다.
`src`와 `dst`는 pointer와 size를 담은 `struct iov_iter` pointer입니다. 실제 data 복사와 접근에는 `linux/uio.h`의 기존 helper를 사용합니다.
다른 PCM callback이 frame 단위를 쓰는 것과 달리 이 callback들은 byte 단위 인자를 받습니다. 이 방식은 위의 메모리 복사 코드를 단순하게 하고 interleaved와 non-interleaved 경우를 하나의 callback 형태로 통합하기 쉽습니다.
Non-interleaved sample에서는 callback이 두 번째 인자로 각 channel을 받아 transfer마다 총 N번 호출됩니다. 나머지 인자의 뜻은 거의 같지만 지정된 channel의 data만 userspace buffer와 주고받아야 합니다. 구현 예는 `isa/gus/gus_pcm.c`와 `pci/rme9652/rme9652.c`에 있습니다.
인자PlaybackCapture
substream대상 PCM substream대상 PCM substream
channelNon-interleaved channelNon-interleaved channel
posHardware buffer byte offsetHardware buffer byte offset
iov_iterSource srcDestination dst
count복사할 byte 수복사할 byte 수
Playback과 capture에서 iterator 방향만 달라집니다.
Playback src iov_iter→linux/uio.h helper→hardware buffer + pos
Hardware buffer + pos→linux/uio.h helper→Capture dst iov_iter
Playback은 userspace에서 hardware로, capture는 반대로 이동합니다.
The implementation of the ``copy`` and
``silence`` callbacks depends upon whether the hardware supports
interleaved or non-interleaved samples. The ``copy`` callback is
defined like below, a bit differently depending on whether the direction
is playback or capture::
static int playback_copy(struct snd_pcm_substream *substream,
int channel, unsigned long pos,
struct iov_iter *src, unsigned long count);
static int capture_copy(struct snd_pcm_substream *substream,
int channel, unsigned long pos,
struct iov_iter *dst, unsigned long count);
In the case of interleaved samples, the second argument (``channel``) is
not used. The third argument (``pos``) specifies the position in bytes.
The meaning of the fourth argument is different between playback and
capture. For playback, it holds the source data pointer, and for
capture, it's the destination data pointer.
The last argument is the number of bytes to be copied.
What you have to do in this callback is again different between playback
and capture directions. In the playback case, you copy the given amount
of data (``count``) at the specified pointer (``src``) to the specified
offset (``pos``) in the hardware buffer. When coded like memcpy-like
way, the copy would look like::
my_memcpy_from_iter(my_buffer + pos, src, count);
For the capture direction, you copy the given amount of data (``count``)
at the specified offset (``pos``) in the hardware buffer to the
specified pointer (``dst``)::
my_memcpy_to_iter(dst, my_buffer + pos, count);
The given ``src`` or ``dst`` a struct iov_iter pointer containing the
pointer and the size. Use the existing helpers to copy or access the
data as defined in ``linux/uio.h``.
Careful readers might notice that these callbacks receive the
arguments in bytes, not in frames like other callbacks. It's because
this makes coding easier like in the examples above, and also it makes
it easier to unify both the interleaved and non-interleaved cases, as
explained below.
In the case of non-interleaved samples, the implementation will be a bit
more complicated. The callback is called for each channel, passed in
the second argument, so in total it's called N times per transfer.
The meaning of the other arguments are almost the same as in the
interleaved case. The callback is supposed to copy the data from/to
the given user-space buffer, but only for the given channel. For
details, please check ``isa/gus/gus_pcm.c`` or ``pci/rme9652/rme9652.c``
as examples.
PCM fill_silence callback
3521-3544Playback에는 보통 `fill_silence` callback도 정의합니다. 형식은 copy와 비슷하지만 userspace buffer pointer 없이 substream, channel, byte offset `pos`, byte 수 `count`를 받습니다. Interleaved sample에서는 copy와 마찬가지로 channel 인자를 사용하지 않습니다.
이 callback은 hardware buffer의 `pos` 위치부터 `count` byte만큼 silence data를 채웁니다. Signed sample처럼 silence 값이 0이면 원문의 예처럼 `my_memset(my_buffer + pos, 0, count)` 형태로 구현할 수 있습니다.
Non-interleaved sample에서는 channel마다 transfer당 N번 호출되므로 지정 channel의 memory layout을 반영해야 합니다. `isa/gus/gus_pcm.c`가 구현 예입니다.
항목의미
posHardware buffer의 byte offset
count채울 silence byte 수
channelNon-interleaved일 때 대상 channel
signed sample 예0으로 memset
Copy와 같은 byte 좌표를 사용하되 source data가 없습니다.
Usually for the playback, another callback ``fill_silence`` is
defined. It's implemented in a similar way as the copy callbacks
above::
static int silence(struct snd_pcm_substream *substream, int channel,
unsigned long pos, unsigned long count);
The meanings of arguments are the same as in the ``copy`` callback,
although there is no buffer pointer
argument. In the case of interleaved samples, the channel argument has
no meaning, as for the ``copy`` callback.
The role of the ``fill_silence`` callback is to set the given amount
(``count``) of silence data at the specified offset (``pos``) in the
hardware buffer. Suppose that the data format is signed (that is, the
silent-data is 0), and the implementation using a memset-like function
would look like::
my_memset(my_buffer + pos, 0, count);
In the case of non-interleaved samples, again, the implementation
becomes a bit more complicated, as it's called N times per transfer
for each channel. See, for example, ``isa/gus/gus_pcm.c``.
Non-contiguous SG buffer
3545-3579`emu10k1`처럼 page table을 지원하거나 `via82xx`처럼 buffer descriptor를 지원하는 hardware는 scatter-gather(SG) DMA를 사용할 수 있습니다. ALSA의 SG buffer API는 `<sound/pcm.h>`에 있습니다.
PCM constructor에서 다른 PCI pre-allocation과 마찬가지로 :c:func:`snd_pcm_set_managed_buffer()` 또는 :c:func:`snd_pcm_set_managed_buffer_all()`을 `SNDRV_DMA_TYPE_DEV_SG`와 함께 호출하고 chip의 `struct pci_dev`에 해당하는 `&pci->dev`를 전달합니다.
그 결과 `struct snd_sg_buf` 인스턴스가 `substream->dma_private`에 만들어집니다. :c:func:`snd_pcm_lib_malloc_pages()` 호출 시 공통 SG handler는 요청 크기의 물리적으로 불연속인 kernel page를 할당하고 가상 주소에서는 연속 memory처럼 mapping합니다.
Virtual pointer는 `runtime->dma_area`로 접근합니다. Buffer가 물리적으로 불연속이므로 `runtime->dma_addr`는 0이고 실제 physical address table은 `sgbuf->table`에 있습니다. 특정 offset의 physical address는 :c:func:`snd_pcm_sgbuf_get_addr()`로 구합니다.
SG buffer data를 명시적으로 해제해야 하면 평소처럼 :c:func:`snd_pcm_lib_free_pages()`를 호출합니다.
Field 또는 함수의미
substream->dma_privatestruct snd_sg_buf
runtime->dma_area가상 연속 mapping pointer
runtime->dma_addr물리 불연속이므로 0
sgbuf->tablePhysical address table
snd_pcm_sgbuf_get_addr()지정 offset의 physical address
가상 연속 주소와 실제 page table을 구분합니다.
SNDRV_DMA_TYPE_DEV_SG 설정→snd_pcm_lib_malloc_pages()→불연속 kernel page 할당→가상 연속 mapping→runtime->dma_area로 접근→sgbuf->table로 DMA 주소 조회
불연속 page를 PCM에서 연속 가상 buffer처럼 사용합니다.
Non-Contiguous Buffers
----------------------
If your hardware supports a page table as in emu10k1 or buffer
descriptors as in via82xx, you can use scatter-gather (SG) DMA. ALSA
provides an interface for handling SG-buffers. The API is provided in
``<sound/pcm.h>``.
For creating the SG-buffer handler, call
:c:func:`snd_pcm_set_managed_buffer()` or
:c:func:`snd_pcm_set_managed_buffer_all()` with
``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like for other PCI
pre-allocations. You need to pass ``&pci->dev``, where pci is
the struct pci_dev pointer of the chip as well::
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG,
&pci->dev, size, max);
The ``struct snd_sg_buf`` instance is created as
``substream->dma_private`` in turn. You can cast the pointer like::
struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
Then in the :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
handler will allocate the non-contiguous kernel pages of the given size
and map them as virtually contiguous memory. The virtual pointer
is addressed via runtime->dma_area. The physical address
(``runtime->dma_addr``) is set to zero, because the buffer is
physically non-contiguous. The physical address table is set up in
``sgbuf->table``. You can get the physical address at a certain offset
via :c:func:`snd_pcm_sgbuf_get_addr()`.
If you need to release the SG-buffer data explicitly, call the
standard API function :c:func:`snd_pcm_lib_free_pages()` as usual.
Vmalloc buffer
3580-3600:c:func:`vmalloc()`로 할당한 memory도 intermediate buffer 등에 사용할 수 있습니다. Buffer pre-allocation type을 `SNDRV_DMA_TYPE_VMALLOC`로 설정한 뒤 표준 :c:func:`snd_pcm_lib_malloc_pages()` 계열을 사용하면 됩니다.
예제의 :c:func:`snd_pcm_set_managed_buffer_all()`에는 device pointer로 NULL을 전달합니다. 이는 `GFP_KERNEL`과 `GFP_HIGHMEM`을 사용하는 기본 page를 할당한다는 뜻입니다.
`size`와 `max`에도 모두 0을 전달합니다. 각 vmalloc 호출은 필요할 때 성공할 수 있으므로 연속 physical page와 달리 buffer를 미리 예약할 필요가 없습니다. 다음 3,601행부터는 `Proc Interface` 절로 이어집니다.
인자값과 의미
DMA typeSNDRV_DMA_TYPE_VMALLOC
deviceNULL; 기본 GFP_KERNEL/GFP_HIGHMEM page
size0; pre-allocation 없음
max0; pre-allocation 최대값 없음
물리 연속성이나 사전 예약이 필요 없는 설정입니다.
Vmalloc'ed Buffers
------------------
It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
example, for an intermediate buffer.
You can simply allocate it via the standard
:c:func:`snd_pcm_lib_malloc_pages()` and co. after setting up the
buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type::
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
NULL, 0, 0);
NULL is passed as the device pointer argument, which indicates
that default pages (GFP_KERNEL and GFP_HIGHMEM) will be
allocated.
Also, note that zero is passed as both the size and the max size
argument here. Since each vmalloc call should succeed at any time,
we don't need to pre-allocate the buffers like other continuous
pages.
ALSA proc text interface
3601-3650ALSA는 procfs를 위한 간단한 interface를 제공합니다. Proc file은 driver의 실행 상태나 register dump를 확인하는 debugging 수단으로 유용하며 API는 `<sound/info.h>`에 있습니다.
Proc file은 :c:func:`snd_card_proc_new()`로 만듭니다. 두 번째 인자가 card directory 아래의 file 이름이며, 예제의 `my-file`은 `/proc/asound/card0/my-file`로 생성됩니다.
다른 ALSA component와 마찬가지로 이 helper로 만든 proc entry는 card 등록과 해제 과정에서 자동으로 등록되고 해제됩니다.
생성에 성공하면 세 번째 인자로 새 `struct snd_info_entry`를 돌려주며 기본값은 read-only text proc file입니다. 그대로 사용할 때는 :c:func:`snd_info_set_text_ops()`에 entry, callback private data인 `chip`, read callback `my_proc_read`를 전달합니다. 원문 3,631행은 세 번째 parameter가 read buffer size이고 네 번째가 callback이라고 적지만 제시된 호출은 세 인자이므로, 영어 원문은 보존하고 실제 v6.18.37 prototype을 기준으로 구현해야 합니다.
Read callback은 `struct snd_info_entry *entry`와 `struct snd_info_buffer *buffer`를 받습니다. `entry->private_data`에서 chip을 얻고, 일반 :c:func:`printf()`처럼 동작하는 :c:func:`snd_iprintf()`로 상태 문자열과 register 값을 출력합니다.
단계API 또는 field
Entry 생성snd_card_proc_new(card, name, &entry)
경로/proc/asound/cardN/name
Text opssnd_info_set_text_ops(entry, chip, callback)
Driver contextentry->private_data
출력snd_iprintf(buffer, format, ...)
Card별 진단 file과 read callback을 연결합니다.
Proc file read→my_proc_read(entry, buffer)→entry->private_data에서 chip 조회→snd_iprintf()로 상태 작성→Userspace에 text 반환
Userspace read 요청이 driver 상태 문자열로 변환됩니다.
Proc Interface
==============
ALSA provides an easy interface for procfs. The proc files are very
useful for debugging. I recommend you set up proc files if you write a
driver and want to get a running status or register dumps. The API is
found in ``<sound/info.h>``.
To create a proc file, call :c:func:`snd_card_proc_new()`::
struct snd_info_entry *entry;
int err = snd_card_proc_new(card, "my-file", &entry);
where the second argument specifies the name of the proc file to be
created. The above example will create a file ``my-file`` under the
card directory, e.g. ``/proc/asound/card0/my-file``.
Like other components, the proc entry created via
:c:func:`snd_card_proc_new()` will be registered and released
automatically in the card registration and release functions.
When the creation is successful, the function stores a new instance in
the pointer given in the third argument. It is initialized as a text
proc file for read only. To use this proc file as a read-only text file
as-is, set the read callback with private data via
:c:func:`snd_info_set_text_ops()`::
snd_info_set_text_ops(entry, chip, my_proc_read);
where the second argument (``chip``) is the private data to be used in
the callback. The third parameter specifies the read buffer size and
the fourth (``my_proc_read``) is the callback function, which is
defined like::
static void my_proc_read(struct snd_info_entry *entry,
struct snd_info_buffer *buffer);
In the read callback, use :c:func:`snd_iprintf()` for output
strings, which works just like normal :c:func:`printf()`. For
example::
static void my_proc_read(struct snd_info_entry *entry,
struct snd_info_buffer *buffer)
{
struct my_chip *chip = entry->private_data;
snd_iprintf(buffer, "This is my chip!\n");
snd_iprintf(buffer, "Port = %ld\n", chip->port);
}
Writable text와 raw-data proc
3651-3702Proc file의 permission은 생성 후 바꿀 수 있습니다. 기본값은 모든 user에게 read-only이며 root user의 write permission을 추가하려면 `entry->mode = S_IFREG | S_IRUGO | S_IWUSR`로 설정하고 `entry->c.text.write = my_proc_write`에 write callback을 연결합니다.
Text write callback에서는 :c:func:`snd_info_get_line()`으로 한 줄을 읽고 :c:func:`snd_info_get_str()`로 그 줄에서 문자열을 꺼낼 수 있습니다. 원문에 적힌 예제 경로는 `core/oss/mixer_oss.c`와 `pcm_oss.c`이며 중간의 `core/oss/and` 표기는 원문 그대로 보존합니다.
Raw-data proc file은 `struct snd_info_entry_ops`에 read/write op를 두고 `entry->content = SNDRV_INFO_CONTENT_DATA`, private data, ops pointer, 최대 `size`, file mode를 설정합니다. Raw data에서는 `size`가 proc file access의 최대 크기를 정하므로 반드시 올바르게 지정해야 합니다.
Raw mode callback은 text mode보다 직접적이며 :c:func:`copy_from_user()`와 :c:func:`copy_to_user()` 같은 저수준 I/O helper로 data를 전송합니다. 예제 read는 `local_data + pos`에서 `count` byte를 userspace로 복사하고 실패 시 `-EFAULT`, 성공 시 `count`를 반환합니다.
Info entry의 size를 올바르게 설정했다면 ALSA가 `count`와 `pos`를 0부터 해당 size 범위 안으로 보장합니다. 다른 hardware 조건이 없다면 callback에서 같은 범위를 다시 검사할 필요가 없습니다.
ModeCallback/API크기 처리
Read-only textsnd_info_set_text_ops(), snd_iprintf()Core text buffer
Writable textsnd_info_get_line(), snd_info_get_str()Text parsing
Raw datasnd_info_entry_ops, copy_to/from_user()entry->size 필수
Text helper와 raw file operation의 차이입니다.
Entry size 설정→Read callback에 pos/count 전달→copy_to_user(buf, local_data + pos, count)→실패 -EFAULT / 성공 count
보장된 offset 범위에서 kernel data를 userspace로 복사합니다.
The file permissions can be changed afterwards. By default, they are
read only for all users. If you want to add write permission for the
user (root by default), do as follows::
entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
and set the write buffer size and the callback::
entry->c.text.write = my_proc_write;
In the write callback, you can use :c:func:`snd_info_get_line()`
to get a text line, and :c:func:`snd_info_get_str()` to retrieve
a string from the line. Some examples are found in
``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.
For a raw-data proc-file, set the attributes as follows::
static const struct snd_info_entry_ops my_file_io_ops = {
.read = my_file_io_read,
};
entry->content = SNDRV_INFO_CONTENT_DATA;
entry->private_data = chip;
entry->c.ops = &my_file_io_ops;
entry->size = 4096;
entry->mode = S_IFREG | S_IRUGO;
For raw data, ``size`` field must be set properly. This specifies
the maximum size of the proc file access.
The read/write callbacks of raw mode are more direct than the text mode.
You need to use a low-level I/O functions such as
:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the
data::
static ssize_t my_file_io_read(struct snd_info_entry *entry,
void *file_private_data,
struct file *file,
char *buf,
size_t count,
loff_t pos)
{
if (copy_to_user(buf, local_data + pos, count))
return -EFAULT;
return count;
}
If the size of the info entry has been set up properly, ``count`` and
``pos`` are guaranteed to fit within 0 and the given size. You don't
have to check the range in the callbacks unless any other condition is
required.
Power management 지원 수준
3703-3731Chip이 suspend/resume을 지원해야 한다면 driver에 power-management 코드를 추가합니다. PM 전용 코드는 `CONFIG_PM` 조건으로 감싸거나 `__maybe_unused` attribute를 붙여 PM이 꺼진 build에서 compiler warning이 나지 않게 합니다.
Suspend 호출 시점의 상태로 device를 정확히 복원할 수 있는 완전한 지원이라면 PCM info에 `SNDRV_PCM_INFO_RESUME` flag를 설정할 수 있습니다. 보통 chip register를 RAM에 안전하게 저장했다가 복원할 수 있을 때 가능합니다. 이 flag가 있으면 resume callback 완료 뒤 trigger callback에 `SNDRV_PCM_TRIGGER_RESUME`이 전달됩니다.
완전 복원은 못 해도 부분 suspend/resume이 가능하면 callback을 구현할 가치가 있습니다. 이 경우 application이 :c:func:`snd_pcm_prepare()`로 상태를 reset하고 stream을 다시 시작하므로, callback은 제공하되 PCM의 `SNDRV_PCM_INFO_RESUME` flag는 설정하지 않습니다.
:c:func:`snd_pcm_suspend_all()`은 RESUME flag와 무관하게 항상 SUSPEND trigger를 일으킬 수 있습니다. RESUME flag는 :c:func:`snd_pcm_resume()`의 동작에만 영향을 줍니다. 이론상 flag가 없으면 trigger가 `SNDRV_PCM_TRIGGER_RESUME`을 처리하지 않아도 되지만 compatibility를 위해 처리 코드를 유지하는 편이 좋습니다.
지원SNDRV_PCM_INFO_RESUME복귀 방식
완전 suspend/resume설정Resume callback 뒤 RESUME trigger
부분 suspend/resume설정하지 않음Application이 snd_pcm_prepare() 후 재시작
Suspend triggerFlag와 무관snd_pcm_suspend_all()이 호출 가능
완전 복원 가능 여부가 RESUME flag와 application 절차를 결정합니다.
Suspend 전 상태를 완전히 저장 가능한가→예: SNDRV_PCM_INFO_RESUME 설정→Resume callback 후 RESUME trigger
부분 복원만 가능한가→Callback 구현, RESUME flag 생략→Application prepare 후 stream 재시작
Register 상태 복원 능력에 따라 capability를 선언합니다.
Power Management
================
If the chip is supposed to work with suspend/resume functions, you need
to add power-management code to the driver. The additional code for
power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
with __maybe_unused attribute; otherwise the compiler will complain.
If the driver *fully* supports suspend/resume that is, the device can be
properly resumed to its state when suspend was called, you can set the
``SNDRV_PCM_INFO_RESUME`` flag in the PCM info field. Usually, this is
possible when the registers of the chip can be safely saved and restored
to RAM. If this is set, the trigger callback is called with
``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.
Even if the driver doesn't support PM fully but partial suspend/resume
is still possible, it's still worthy to implement suspend/resume
callbacks. In such a case, applications would reset the status by
calling :c:func:`snd_pcm_prepare()` and restart the stream
appropriately. Hence, you can define suspend/resume callbacks below but
don't set the ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
Note that the trigger with SUSPEND can always be called when
:c:func:`snd_pcm_suspend_all()` is called, regardless of the
``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the
behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
to keep it for compatibility reasons.)PCI PM hook과 suspend 순서
3732-3780Driver는 device가 연결된 bus 규칙에 맞춰 suspend/resume hook을 정의해야 합니다. PCI 예제의 함수는 `struct device *dev`를 받고 `__maybe_unused`로 표시되며 성공 시 0을 반환합니다. 원문 resume skeleton의 주석이 `do things for suspend`인 점은 그대로 보존합니다.
실제 suspend는 먼저 device에서 card와 chip data를 찾고, :c:func:`snd_power_change_state()`에 `SNDRV_CTL_POWER_D3hot`을 전달해 power state를 바꿉니다. AC97 codec을 사용한다면 각 codec에 :c:func:`snd_ac97_suspend()`를 호출합니다.
그 다음 필요하면 register 값을 저장하고 hardware를 정지합니다. 예제는 `dev_get_drvdata(dev)`로 card를 얻고 `card->private_data`로 chip을 찾은 뒤 power state 변경, AC97 suspend, register 저장, hardware stop 순서로 실행합니다.
단계동작
1Card와 chip data 조회
2snd_power_change_state(..., SNDRV_CTL_POWER_D3hot)
3각 AC97 codec에 snd_ac97_suspend()
4필요한 register 저장
5필요한 hardware 정지
State 알림과 hardware 정지의 원문 순서입니다.
dev_get_drvdata()→D3hot state→AC97 suspend→Register save→Hardware stop
Userspace에 low-power 상태를 알리고 복원 정보를 보존합니다.
The driver needs to define the
suspend/resume hooks according to the bus the device is connected to. In
the case of PCI drivers, the callbacks look like below::
static int __maybe_unused snd_my_suspend(struct device *dev)
{
.... /* do things for suspend */
return 0;
}
static int __maybe_unused snd_my_resume(struct device *dev)
{
.... /* do things for suspend */
return 0;
}
The scheme of the real suspend job is as follows:
1. Retrieve the card and the chip data.
2. Call :c:func:`snd_power_change_state()` with
``SNDRV_CTL_POWER_D3hot`` to change the power status.
3. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
each codec.
4. Save the register values if necessary.
5. Stop the hardware if necessary.
Typical code would look like::
static int __maybe_unused mychip_suspend(struct device *dev)
{
/* (1) */
struct snd_card *card = dev_get_drvdata(dev);
struct mychip *chip = card->private_data;
/* (2) */
snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
/* (3) */
snd_ac97_suspend(chip->ac97);
/* (4) */
snd_mychip_save_registers(chip);
/* (5) */
snd_mychip_stop_hardware(chip);
return 0;
}
Resume 순서
3781-3819Resume은 card와 chip data를 찾은 뒤 chip을 다시 초기화하고, 필요하면 저장한 register를 복원합니다. 이어 :c:func:`snd_ac97_resume()` 같은 mixer 복귀 함수를 호출하고 hardware가 있다면 다시 시작합니다.
마지막에는 :c:func:`snd_power_change_state()`에 `SNDRV_CTL_POWER_D0`을 전달해 process들에게 정상 power state 복귀를 알립니다. 원문 예제 signature는 `struct pci_dev *pci`이지만 본문에서 `dev`를 참조하므로 이 불일치는 원문에 그대로 보존하고 실제 callback prototype에 맞춰 구현해야 합니다.
이 bus resume callback이 호출될 때 PCM stream은 자체 PM ops가 내부적으로 :c:func:`snd_pcm_suspend_all()`을 호출하여 이미 suspend된 상태입니다.
단계동작
1Card와 chip data 조회
2Chip 재초기화
3저장 register 복원
4snd_ac97_resume() 등 mixer 복귀
5Hardware 재시작
6snd_power_change_state(..., SNDRV_CTL_POWER_D0)
Suspend의 역순으로 hardware를 복구한 뒤 D0 상태를 알립니다.
Chip reinit→Register restore→Mixer resume→Hardware restart→D0 state notification
Hardware가 정상 동작한 뒤 process에 D0를 알립니다.
The scheme of the real resume job is as follows:
1. Retrieve the card and the chip data.
2. Re-initialize the chip.
3. Restore the saved registers if necessary.
4. Resume the mixer, e.g. by calling :c:func:`snd_ac97_resume()`.
5. Restart the hardware (if any).
6. Call :c:func:`snd_power_change_state()` with
``SNDRV_CTL_POWER_D0`` to notify the processes.
Typical code would look like::
static int __maybe_unused mychip_resume(struct pci_dev *pci)
{
/* (1) */
struct snd_card *card = dev_get_drvdata(dev);
struct mychip *chip = card->private_data;
/* (2) */
snd_mychip_reinit_chip(chip);
/* (3) */
snd_mychip_restore_registers(chip);
/* (4) */
snd_ac97_resume(chip->ac97);
/* (5) */
snd_mychip_restart_chip(chip);
/* (6) */
snd_power_change_state(card, SNDRV_CTL_POWER_D0);
return 0;
}
Note that, at the time this callback gets called, the PCM stream has
been already suspended via its own PM ops calling
:c:func:`snd_pcm_suspend_all()` internally.
PM용 card private data
3820-3864PM callback에서 chip data를 얻을 수 있도록 card 초기화 때 `private_data` 연결을 보장해야 합니다. Chip을 별도로 `kzalloc()`했다면 `card->private_data = chip`으로 저장합니다.
또는 :c:func:`snd_card_new()`의 private data 크기에 `sizeof(struct mychip)`을 전달해 card와 함께 chip data를 만들었다면 `chip = card->private_data`로 바로 접근합니다.
Register 저장 공간이 필요하면 probe 시점에 미리 할당해야 합니다. Suspend phase에서 memory allocation에 실패하면 복원이 불가능한 치명적 상황이 되므로 suspend 중에 할당하지 않습니다. 이 buffer는 대응 destructor에서 해제합니다.
방식생성접근
별도 할당kzalloc(sizeof(*chip), GFP_KERNEL)card->private_data = chip
Card 내장snd_card_new(..., sizeof(struct mychip), &card)chip = card->private_data
Register save bufferProbe에서 사전 할당Destructor에서 해제
별도 할당과 card 내장 할당 모두 private_data로 PM hook에 노출합니다.
Card와 chip 생성→card->private_data 연결→Register save buffer 사전 할당→Suspend/resume hook에서 조회→Destructor에서 해제
Probe에서 suspend에 필요한 모든 memory를 확보합니다.
OK, we have all callbacks now. Let's set them up. In the initialization
of the card, make sure that you can get the chip data from the card
instance, typically via ``private_data`` field, in case you created the
chip data individually::
static int snd_mychip_probe(struct pci_dev *pci,
const struct pci_device_id *pci_id)
{
....
struct snd_card *card;
struct mychip *chip;
int err;
....
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
....
chip = kzalloc(sizeof(*chip), GFP_KERNEL);
....
card->private_data = chip;
....
}
When you created the chip data with :c:func:`snd_card_new()`, it's
anyway accessible via ``private_data`` field::
static int snd_mychip_probe(struct pci_dev *pci,
const struct pci_device_id *pci_id)
{
....
struct snd_card *card;
struct mychip *chip;
int err;
....
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
sizeof(struct mychip), &card);
....
chip = card->private_data;
....
}
If you need space to save the registers, allocate the buffer for it
here, too, since it would be fatal if you cannot allocate a memory in
the suspend phase. The allocated buffer should be released in the
corresponding destructor.
PCI driver PM 등록
3865-3878Suspend와 resume callback은 `DEFINE_SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume)`로 PM ops에 묶습니다. 그런 다음 `struct pci_driver`의 내장 `.driver.pm` field에 `&snd_my_pm_ops`를 지정합니다.
PCI driver에는 기존처럼 module name, device ID table, probe, remove callback도 함께 등록됩니다.
mychip_suspend/resume 구현→DEFINE_SIMPLE_DEV_PM_OPS→snd_my_pm_ops 생성→pci_driver.driver.pm에 연결→PCI core가 PM event에서 호출
개별 hook을 device PM ops와 PCI driver에 연결합니다.
And next, set suspend/resume callbacks to the pci_driver::
static DEFINE_SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume);
static struct pci_driver driver = {
.name = KBUILD_MODNAME,
.id_table = snd_my_ids,
.probe = snd_my_probe,
.remove = snd_my_remove,
.driver = {
.pm = &snd_my_pm_ops,
},
};
ALSA 표준 module parameter
3879-3911ALSA module은 최소한 `index`, `id`, `enable` 표준 option을 제공해야 합니다. 여러 card, 보통 `SNDRV_CARDS`인 최대 8개를 지원하면 이 option들을 array로 선언합니다.
기본 초기값은 각각 `SNDRV_DEFAULT_IDX`, `SNDRV_DEFAULT_STR`, `SNDRV_DEFAULT_ENABLE_PNP` constant로 제공됩니다. 단일 card만 지원하면 scalar variable로 둘 수 있으며 `enable`이 반드시 필요하지 않더라도 compatibility를 위한 dummy option을 제공하는 편이 좋습니다.
Module parameter는 표준 `module_param()`, `module_param_array()`, :c:func:`MODULE_PARM_DESC()` macro로 선언합니다. 예제는 `CARD_NAME`을 사용해 index, ID string, enable 설명을 일관되게 작성하고 permission 0444로 노출합니다.
OptionType기본값
indexint arraySNDRV_DEFAULT_IDX
idchar pointer arraySNDRV_DEFAULT_STR
enablebool arraySNDRV_DEFAULT_ENABLE_PNP
Card 선택, 표시 ID, 활성화 여부를 instance별로 지정합니다.
SNDRV_CARDS 크기 array 정의→module_param_array()→MODULE_PARM_DESC()→modprobe option으로 instance별 값 전달
변수, parameter macro, 설명을 한 세트로 유지합니다.
Module Parameters
=================
There are standard module options for ALSA. At least, each module should
have the ``index``, ``id`` and ``enable`` options.
If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
cards), they should be arrays. The default initial values are defined
already as constants for easier programming::
static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
If the module supports only a single card, they could be single
variables, instead. ``enable`` option is not always necessary in this
case, but it would be better to have a dummy option for compatibility.
The module parameters must be declared with the standard
``module_param()``, ``module_param_array()`` and
:c:func:`MODULE_PARM_DESC()` macros.
Typical code would look as below::
#define CARD_NAME "My Chip"
module_param_array(index, int, NULL, 0444);
MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
module_param_array(id, charp, NULL, 0444);
MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
module_param_array(enable, bool, NULL, 0444);
MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
Module 설명과 license
3912-3919Module description과 license도 빠뜨리면 안 됩니다. 최근 modprobe 환경에서는 `MODULE_LICENSE()`로 GPL 같은 license를 선언하지 않으면 system이 tainted 상태로 표시됩니다. 원문 3,914행의 깨진 표기는 문맥상 `tainted`를 뜻합니다.
예제는 `MODULE_DESCRIPTION("Sound driver for My Chip")`과 `MODULE_LICENSE("GPL")`을 사용합니다.
Macro역할
MODULE_DESCRIPTIONDriver 목적 설명
MODULE_LICENSELicense 선언과 taint 판단
설명과 license가 module 식별 및 kernel taint에 영향을 줍니다.
Also, don't forget to define the module description and the license.
Especially, the recent modprobe requires to define the
module license as GPL, etc., otherwise the system is shown as “tainted”::
MODULE_DESCRIPTION("Sound driver for My Chip");
MODULE_LICENSE("GPL");
Device-managed resource
3920-3952앞의 예제는 resource를 수동으로 할당하고 해제했지만 devres 또는 devm 계열은 해제 과정을 자동화합니다. 예를 들어 :c:func:`devm_kmalloc()`으로 할당한 object는 device unbind 시 자동으로 해제됩니다.
ALSA core도 card 생성용 device-managed helper :c:func:`snd_devm_card_new()`를 제공합니다. :c:func:`snd_card_new()` 대신 사용하면 error와 remove path에서 :c:func:`snd_card_free()`가 자동 호출되어 명시적 free를 생략할 수 있습니다.
주의할 점은 :c:func:`snd_card_register()`를 호출한 뒤에야 :c:func:`snd_card_free()`가 release call chain의 앞쪽에 배치된다는 것입니다.
Card free 때 `private_free` callback은 항상 호출됩니다. Early error path에서는 hardware setup이 끝나기 전에도 호출될 수 있으므로, 초기화되지 않은 hardware 정리를 피하려면 :c:func:`snd_card_register()` 성공 뒤에 `private_free`를 설정할 수 있습니다.
Card를 managed 방식으로 다루기 시작했다면 각 component도 가능한 한 device-managed helper를 사용해야 합니다. 일반 resource와 managed resource를 섞으면 release 순서가 깨질 수 있습니다.
항목규칙
devm_kmalloc()Device unbind 때 자동 해제
snd_devm_card_new()Error/remove path에서 card 자동 해제
snd_card_register()Free action의 call-chain 위치 확정
private_free초기화 전 early error에서도 호출될 수 있음
혼용Managed와 일반 resource 혼용 시 release order 위험
자동 해제의 편의와 callback 순서 조건입니다.
snd_devm_card_new()→Hardware/component 초기화→snd_card_register() 성공→필요하면 private_free 설정→Error 또는 unbind→Devres가 역순 해제
등록 성공 시점을 기준으로 안전한 cleanup 순서를 구성합니다.
Device-Managed Resources
========================
In the examples above, all resources are allocated and released
manually. But human beings are lazy in nature, especially developers
are lazier. So there are some ways to automate the release part; it's
the (device-)managed resources aka devres or devm family. For
example, an object allocated via :c:func:`devm_kmalloc()` will be
freed automatically at unbinding the device.
ALSA core provides also the device-managed helper, namely,
:c:func:`snd_devm_card_new()` for creating a card object.
Call this functions instead of the normal :c:func:`snd_card_new()`,
and you can forget the explicit :c:func:`snd_card_free()` call, as
it's called automagically at error and removal paths.
One caveat is that the call of :c:func:`snd_card_free()` would be put
at the beginning of the call chain only after you call
:c:func:`snd_card_register()`.
Also, the ``private_free`` callback is always called at the card free,
so be careful to put the hardware clean-up procedure in
``private_free`` callback. It might be called even before you
actually set up at an earlier error path. For avoiding such an
invalid initialization, you can set ``private_free`` callback after
:c:func:`snd_card_register()` call succeeds.
Another thing to be remarked is that you should use device-managed
helpers for each component as much as possible once when you manage
the card in that way. Mixing up with the normal and the managed
resources may screw up the release order.
Driver를 ALSA tree에 넣기
3953-3971Driver code를 작성한 뒤 ALSA driver tree에 편입하는 표준 절차를 설명합니다. 원문은 예시 PCI card 이름의 깨진 표기를 문맥상 `xyz`로 사용하며 module 이름은 `snd-xyz`입니다.
새 PCI driver는 Linux kernel tree의 `sound/pci` 아래에 둡니다. 이어지는 절은 source file 하나로 구성된 driver와 여러 source file을 새 subdirectory에 배치하는 두 경우를 다룹니다.
항목값
Card/driver 예시xyz
Modulesnd-xyz
PCI source rootsound/pci
구성단일 source 또는 여러 source subdirectory
예시 xyz driver의 module과 source 위치입니다.
How To Put Your Driver Into ALSA Tree
=====================================
General
-------
So far, you've learned how to write the driver codes. And you might have
a question now: how to put my own driver into the ALSA driver tree? Here
(finally :) the standard procedure is described briefly.
Suppose that you create a new PCI driver for the card “xyz”. The card
module name would be snd-xyz. The new driver is usually put into the
alsa-driver tree, ``sound/pci`` directory in the case of PCI
cards.
In the following sections, the driver code is supposed to be put into
Linux kernel tree. The two cases are covered: a driver consisting of a
single source file and one consisting of several source files.
단일 source driver
3972-4007단일 `xyz.c` driver는 먼저 `sound/pci/Makefile`에 `snd-xyz-y := xyz.o`와 `obj-$(CONFIG_SND_XYZ) += snd-xyz.o`를 추가합니다. 첫 줄은 module object 구성을, 둘째 줄은 Kconfig symbol이 선택될 때 build에 포함하는 규칙을 정의합니다.
다음으로 Kconfig에 `config SND_XYZ`, tristate 표시 이름, `depends on SND`, 필요한 component `select`, help text를 추가합니다. Module로 build하면 이름이 `snd-xyz`임을 help에 적습니다.
`select SND_PCM`은 xyz driver가 PCM을 지원함을 뜻합니다. 추가로 선택 가능한 component에는 `SND_RAWMIDI`, `SND_TIMER`, `SND_HWDEP`, `SND_MPU401_UART`, `SND_OPL3_LIB`, `SND_OPL4_LIB`, `SND_VX_LIB`, `SND_AC97_CODEC`이 있으며 실제 지원 기능마다 select를 추가합니다.
일부 상위 component는 저수준 dependency를 이미 포함합니다. PCM은 TIMER, MPU401_UART는 RAWMIDI, AC97_CODEC은 PCM, OPL3_LIB은 HWDEP를 포함하므로 이 하위 select를 중복 작성할 필요가 없습니다. Kconfig 문법의 자세한 내용은 kbuild 문서를 참조합니다.
Rule역할
snd-xyz-y := xyz.oModule 구성 object
obj-$(CONFIG_SND_XYZ) += snd-xyz.oKconfig에 따른 build 포함
xyz.c에서 snd-xyz module을 만드는 두 규칙입니다.
Component암시하는 하위 기능
SND_PCMSND_TIMER
SND_MPU401_UARTSND_RAWMIDI
SND_AC97_CODECSND_PCM
SND_OPL3_LIBSND_HWDEP
상위 component가 암시하는 dependency를 함께 표시합니다.
sound/pci/xyz.c 추가→Makefile에 snd-xyz object 규칙→Kconfig SND_XYZ entry→지원 component select→Built-in 또는 snd-xyz module build
Source, Makefile, Kconfig를 같은 symbol로 연결합니다.
Driver with A Single Source File
--------------------------------
1. Modify sound/pci/Makefile
Suppose you have a file xyz.c. Add the following two lines::
snd-xyz-y := xyz.o
obj-$(CONFIG_SND_XYZ) += snd-xyz.o
2. Create the Kconfig entry
Add the new entry of Kconfig for your xyz driver::
config SND_XYZ
tristate "Foobar XYZ"
depends on SND
select SND_PCM
help
Say Y here to include support for Foobar XYZ soundcard.
To compile this driver as a module, choose M here:
the module will be called snd-xyz.
The line ``select SND_PCM`` specifies that the driver xyz supports PCM.
In addition to SND_PCM, the following components are supported for
select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
Add the select command for each supported component.
Note that some selections imply the lowlevel selections. For example,
PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
the lowlevel selections again.
For the details of Kconfig script, refer to the kbuild documentation.
여러 source file driver
4008-4029여러 source file로 된 `snd-xyz` driver는 새 `sound/pci/xyz` subdirectory에 둡니다. 상위 `sound/pci/Makefile`에는 `obj-$(CONFIG_SND) += sound/pci/xyz/`를 추가해 ALSA build가 해당 directory로 내려가게 합니다.
Subdirectory의 Makefile에는 `snd-xyz-y := xyz.o abc.o def.o`로 module 구성 object를 나열하고 `obj-$(CONFIG_SND_XYZ) += snd-xyz.o`로 Kconfig symbol에 연결합니다.
Kconfig entry를 만드는 절차는 단일 source driver와 같습니다.
위치Rule
sound/pci/Makefileobj-$(CONFIG_SND) += sound/pci/xyz/
sound/pci/xyz/Makefilesnd-xyz-y := xyz.o abc.o def.o
sound/pci/xyz/Makefileobj-$(CONFIG_SND_XYZ) += snd-xyz.o
Kconfig단일 source와 같은 SND_XYZ entry
상위 directory 진입과 하위 module 조립을 분리합니다.
sound/pci/xyz directory 생성→상위 Makefile에 directory 추가→하위 Makefile에 object 목록→CONFIG_SND_XYZ와 snd-xyz 연결→Kconfig entry 추가
상위 Makefile에서 subdirectory로 진입해 module object를 조립합니다.
Drivers with Several Source Files
---------------------------------
Suppose that the driver snd-xyz have several source files. They are
located in the new subdirectory, sound/pci/xyz.
1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
as below::
obj-$(CONFIG_SND) += sound/pci/xyz/
2. Under the directory ``sound/pci/xyz``, create a Makefile::
snd-xyz-y := xyz.o abc.o def.o
obj-$(CONFIG_SND_XYZ) += snd-xyz.o
3. Create the Kconfig entry
This procedure is as same as in the last section.
snd_BUG()
4030-4041:c:func:`snd_BUG()`는 호출 지점에서 :c:func:`snd_BUG_ON()`과 마찬가지로 `BUG?` message와 stack trace를 표시해 치명적인 오류가 발생한 위치를 드러냅니다.
Debug flag가 설정되지 않은 build에서는 이 macro가 무시됩니다.
조건결과
Debug 활성BUG? message와 stack trace 출력
Debug 비활성Macro 무시
Debug build 여부에 따른 진단 효과입니다.
Useful Functions
================
:c:func:`snd_BUG()`
-------------------
It shows the ``BUG?`` message and stack trace as well as
:c:func:`snd_BUG_ON()` at the point. It's useful to show that a
fatal error happens there.
When no debug flag is set, this macro is ignored.
snd_BUG_ON()
4042-4054:c:func:`snd_BUG_ON()`은 :c:func:`WARN_ON()`과 비슷하며 `snd_BUG_ON(!pointer)`처럼 단독 진단에 쓰거나 `if (snd_BUG_ON(non_zero_is_bug)) return -EINVAL;`처럼 condition으로 사용할 수 있습니다.
Macro는 평가할 conditional expression을 받습니다. `CONFIG_SND_DEBUG`가 설정되고 expression이 0이 아니면 보통 stack trace가 뒤따르는 `BUG? (xxx)` warning을 표시합니다. Debug 설정과 관계없이 평가된 expression 값을 반환합니다.
항목동작
입력Conditional expression
Debug + nonzeroBUG? warning과 stack trace
반환평가된 expression 값
용도진단 또는 if condition
조건 평가, warning, 반환값을 구분합니다.
:c:func:`snd_BUG_ON()`
----------------------
:c:func:`snd_BUG_ON()` macro is similar with
:c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or
it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug))
return -EINVAL;
The macro takes an conditional expression to evaluate. When
``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
the warning message such as ``BUG? (xxx)`` normally followed by stack
trace. In both cases it returns the evaluated value.
감사의 말
4055-4064저자는 문서 개선과 교정을 도운 Phil Kerr에게 감사를 전합니다.
Kevin Conder는 원래 plain-text 문서를 DocBook 형식으로 다시 구성했습니다.
Giuliano Pochini는 오탈자를 고치고 hardware constraint 절의 example code를 기여했습니다.
기여자기여
Phil Kerr문서 개선과 교정 지원
Kevin ConderPlain-text를 DocBook으로 변환
Giuliano Pochini오탈자 수정과 hardware constraint example code
마지막 감사 절에 기록된 기여입니다.
Acknowledgments
===============
I would like to thank Phil Kerr for his help for improvement and
corrections of this document.
Kevin Conder reformatted the original plain-text to the DocBook format.
Giuliano Pochini corrected typos and contributed the example codes in
the hardware constraints section.
요약·해설
writing-an-alsa-driver.rst:1-4064ALSA kernel driver의 card 생성과 component 수명부터 PCI resource, PCM, control, AC97, MIDI, RawMIDI, OPL3, hwdep, IEC958, DMA buffer, procfs, power management, module parameter, devres, Kbuild 편입과 debug helper까지 실제 driver 구현 순서에 맞춰 설명합니다.