Skip to content

L
linux
Commit 5469306a authored by Jaroslav Kysela's avatar Jaroslav Kysela
Browse files
Options

ALSA CVS update - Takashi Iwai <tiwai@suse.de> 

Documentation
changed the description of the buffer allocation routines
for the new designed functions.
parent cd37e0d6
Hide whitespace changes
Inline Side-by-side
Showing with 69 additions and 81 deletions
Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
View file @ 5469306a
...@@ -18,8 +18,8 @@ ...@@ -18,8 +18,8 @@
</affiliation> </affiliation>
</author> </author>
<date>Mar. 26, 2003</date> <date>Mar. 6, 2004</date>
<edition>0.3</edition> <edition>0.3.1</edition>
<abstract> <abstract>
<para> <para>
...@@ -30,7 +30,7 @@ ...@@ -30,7 +30,7 @@
<legalnotice> <legalnotice>
<para> <para>
Copyright (c) 2002, 2003 Takashi Iwai <email>tiwai@suse.de</email> Copyright (c) 2002-2004 Takashi Iwai <email>tiwai@suse.de</email>
</para> </para>
<para> <para>
...@@ -111,18 +111,18 @@ ...@@ -111,18 +111,18 @@
<para> <para>
One is the the trees provided as a tarball or via cvs from the One is the the trees provided as a tarball or via cvs from the
ALSA's ftp site, and another is the 2.5 (or later) Linux kernel ALSA's ftp site, and another is the 2.6 (or later) Linux kernel
tree. To synchronize both, the ALSA driver tree is split to tree. To synchronize both, the ALSA driver tree is split to
two different trees: alsa-kernel and alsa-driver. The former two different trees: alsa-kernel and alsa-driver. The former
contains purely the source codes for the Linux 2.5 (or later) contains purely the source codes for the Linux 2.6 (or later)
tree. This tree is designed only for compilation on 2.5 or tree. This tree is designed only for compilation on 2.6 or
later environment. The latter, alsa-driver, contains many subtle later environment. The latter, alsa-driver, contains many subtle
files for compiling the ALSA driver on the outside of Linux files for compiling the ALSA driver on the outside of Linux
kernel like configure script, the wrapper functions for older, kernel like configure script, the wrapper functions for older,
2.2 and 2.4 kernels, to adapt the latest kernel API, 2.2 and 2.4 kernels, to adapt the latest kernel API,
and additional drivers which are still in development or in and additional drivers which are still in development or in
tests. The drivers in alsa-driver tree will be moved to tests. The drivers in alsa-driver tree will be moved to
alsa-kernel (eventually 2.5 kernel tree) once when they are alsa-kernel (eventually 2.6 kernel tree) once when they are
finished and confirmed to work fine. finished and confirmed to work fine.
</para> </para>
...@@ -346,7 +346,7 @@ ...@@ -346,7 +346,7 @@
<section id="file-tree-oss-directory"> <section id="file-tree-oss-directory">
<title>oss directory</title> <title>oss directory</title>
<para> <para>
The OSS/Lite source files are stored here on Linux 2.5 (or The OSS/Lite source files are stored here on Linux 2.6 (or
later) tree. (In the ALSA driver tarball, it's empty, of course :) later) tree. (In the ALSA driver tarball, it's empty, of course :)
</para> </para>
</section> </section>
...@@ -1815,7 +1815,7 @@ ...@@ -1815,7 +1815,7 @@
<para> <para>
Oh, one thing was forgotten. If you have no exported symbols, Oh, one thing was forgotten. If you have no exported symbols,
you need to declare it on 2.2 or 2.4 kernels (on 2.5 kernels you need to declare it on 2.2 or 2.4 kernels (on 2.6 kernels
it's not necessary, though). it's not necessary, though).
<informalexample> <informalexample>
...@@ -2075,8 +2075,9 @@ ...@@ -2075,8 +2075,9 @@
snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
&snd_mychip_capture_ops); &snd_mychip_capture_ops);
/* pre-allocation of buffers */ /* pre-allocation of buffers */
snd_pcm_lib_preallocate_pci_pages_for_all(chip->pci, pcm, snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
64*1024, 64*1024); snd_dma_pci_data(chip->pci),
64*1024, 64*1024);
return 0; return 0;
} }
]]> ]]>
...@@ -2202,8 +2203,9 @@ ...@@ -2202,8 +2203,9 @@
<informalexample> <informalexample>
<programlisting> <programlisting>
<![CDATA[ <![CDATA[
snd_pcm_lib_preallocate_pci_pages_for_all(chip->pci, pcm, snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
64*1024, 64*1024); snd_dma_pci_data(chip->pci),
64*1024, 64*1024);
]]> ]]>
</programlisting> </programlisting>
</informalexample> </informalexample>
...@@ -4724,7 +4726,8 @@ struct _snd_pcm_runtime { ...@@ -4724,7 +4726,8 @@ struct _snd_pcm_runtime {
<informalexample> <informalexample>
<programlisting> <programlisting>
<![CDATA[ <![CDATA[
snd_pcm_lib_preallocate_pci_pages_for_all(pci, pcm, size, max); snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
snd_dma_pci_data(pci), size, max);
]]> ]]>
</programlisting> </programlisting>
</informalexample> </informalexample>
...@@ -4734,8 +4737,25 @@ struct _snd_pcm_runtime { ...@@ -4734,8 +4737,25 @@ struct _snd_pcm_runtime {
size to be changed via <filename>prealloc</filename> proc file. size to be changed via <filename>prealloc</filename> proc file.
The allocator will try to get as the large area as possible The allocator will try to get as the large area as possible
within the given size. within the given size.
There are different versions of pre-allocator for different </para>
buses.
<para>
The second argument (type) and the third argument (device pointer)
are dependent on the bus.
In the case of ISA bus, pass <function>snd_dma_isa_data()</function>
as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
For the continuous buffer unrelated to the bus can be pre-allocated
with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
<function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
whereh <constant>GFP_KERNEL</constant> is the kernel allocation flag to
use. For the SBUS, <constant>SNDRV_DMA_TYPE_SBUS</constant> and
<function>snd_dma_sbus_data(sbus_dev)</function> are used instead.
For the PCI scatter-gather buffers, use
<constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
<function>snd_dma_pci_data(pci)</function>
(see the section
<link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
</citetitle></link>).
</para> </para>
<para> <para>
...@@ -4942,11 +4962,13 @@ struct _snd_pcm_runtime { ...@@ -4942,11 +4962,13 @@ struct _snd_pcm_runtime {
<para> <para>
For creating the SG-buffer handler, call For creating the SG-buffer handler, call
<function>snd_pcm_lib_preallocate_sg_pages()</function> or <function>snd_pcm_lib_preallocate_pages()</function> or
<function>snd_pcm_lib_preallocate_sg_pages_for_all()</function> <function>snd_pcm_lib_preallocate_pages_for_all()</function>
with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
in the PCM constructor like other PCI pre-allocator. in the PCM constructor like other PCI pre-allocator.
You need to pass the You need to pass the <function>snd_dma_pci_data(pci)</function>,
<structname>pci_dev</structname> struct pointer of the chip. where pci is the struct <structname>pci_dev</structname> pointer
of the chip as well.
The <type>snd_sg_buf_t</type> instance is created as The <type>snd_sg_buf_t</type> instance is created as
substream-&gt;dma_private. You can cast substream-&gt;dma_private. You can cast
the pointer like: the pointer like:
...@@ -5280,7 +5302,7 @@ struct _snd_pcm_runtime { ...@@ -5280,7 +5302,7 @@ struct _snd_pcm_runtime {
</para> </para>
<para> <para>
For keeping the readability of 2.5 source code, it's recommended to For keeping the readability of 2.6 source code, it's recommended to
separate the above ifdef condition as the patch file in alsa-driver separate the above ifdef condition as the patch file in alsa-driver
directory. directory.
See <filename>alsa-driver/pci/ali5451.c</filename> for example. See <filename>alsa-driver/pci/ali5451.c</filename> for example.
...@@ -5612,7 +5634,7 @@ struct _snd_pcm_runtime { ...@@ -5612,7 +5634,7 @@ struct _snd_pcm_runtime {
tree. Then the driver is evaluated, audited and tested tree. Then the driver is evaluated, audited and tested
by developers and users. After a certain time, the driver by developers and users. After a certain time, the driver
will go to alsa-kernel tree and eventually integrated into will go to alsa-kernel tree and eventually integrated into
Linux 2.5 tree. Linux 2.6 tree.
</para> </para>
<para> <para>
...@@ -5648,61 +5670,44 @@ struct _snd_pcm_runtime { ...@@ -5648,61 +5670,44 @@ struct _snd_pcm_runtime {
<listitem> <listitem>
<para> <para>
Modify alsa-driver/acore/Makefile Create the Kconfig entry
</para> </para>
<para> <para>
Here define the dependent modules. Add the new entry of Kconfig for your xyz driver.
<informalexample> <informalexample>
<programlisting> <programlisting>
<![CDATA[ <![CDATA[
obj-$(CONFIG_SND_XYZ) += snd.o ... config SND_BT87X
tristate "Foobar XYX"
depends on SND
select SND_PCM
help
Say 'Y' or 'M' to include support for Foobar XYZ soundcard.
]]> ]]>
</programlisting> </programlisting>
</informalexample> </informalexample>
If the driver supports PCM, snd-pcm.o, the line, select SND_PCM, specifies that the driver xyz supports
snd-timer.o and snd-page-alloc.o PCM. In addition to SND_PCM, the following components are
will be needed. supported for select command:
</para> SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
<para> SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
For rawmidi, snd-rawmidi.o is needed in addition. Add the select command for each supported component.
The MIDI stuff is also related to the sequencer.
You'll need to modify alsa-driver/acore/seq/Makefile.
</para> </para>
<para> <para>
For OPL3, snd-hwdep.o is needed, too. Note that some selections imply the lowlevel selections.
It's involved with the sequencer, and as well as rawmidi, For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
you'll need to modify alsa-driver/acore/seq/Makefile AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
and acore/seq/instr/Makefile in addition. You don't need to give the lowlevel selections again.
Also, a new entry is necessary in
alsa-driver/drivers/opl3/Makefile.
</para> </para>
</listitem>
<listitem>
<para> <para>
Modify alsa-driver/utils/Modules.dep For the details of Kconfig script, refer to the kbuild
documentation.
</para> </para>
<para>
Add the module definition for configure, here.
The beginning of the line must be a vertical bar, following
the card module name (snd-xyz) and the list of its all
dependent modules.
<informalexample>
<programlisting>
<![CDATA[
%dir linux/sound/pci
|snd-azt3328 snd-pcm snd-mpu401-uart snd-opl3-lib snd-opl3-synth
|snd-xyz snd-pcm ...
]]>
</programlisting>
</informalexample>
</para>
</listitem> </listitem>
<listitem> <listitem>
...@@ -5730,7 +5735,7 @@ struct _snd_pcm_runtime { ...@@ -5730,7 +5735,7 @@ struct _snd_pcm_runtime {
<informalexample> <informalexample>
<programlisting> <programlisting>
<![CDATA[ <![CDATA[
extra-subdir-y := pdplus vx222 xyz obj-$(CONFIG_SND) += xyz/
]]> ]]>
</programlisting> </programlisting>
</informalexample> </informalexample>
...@@ -5745,13 +5750,13 @@ struct _snd_pcm_runtime { ...@@ -5745,13 +5750,13 @@ struct _snd_pcm_runtime {
<title>Sample Makefile for a driver xyz</title> <title>Sample Makefile for a driver xyz</title>
<programlisting> <programlisting>
<![CDATA[ <![CDATA[
TOPDIR = ../.. ifndef SND_TOPDIR
SND_TOPDIR=../..
endif
include $(TOPDIR)/toplevel.config include $(TOPDIR)/toplevel.config
include $(TOPDIR)/Makefile.conf include $(TOPDIR)/Makefile.conf
TOPDIR = $(MAINSRCDIR)
snd-xyz-objs := xyz.o abc.o def.o snd-xyz-objs := xyz.o abc.o def.o
obj-$(CONFIG_SND_XYZ) += snd-xyz.o obj-$(CONFIG_SND_XYZ) += snd-xyz.o
...@@ -5765,7 +5770,7 @@ struct _snd_pcm_runtime { ...@@ -5765,7 +5770,7 @@ struct _snd_pcm_runtime {
<listitem> <listitem>
<para> <para>
Modify alsa-driver/acore/Makefile Create the Kconfig entry
</para> </para>
<para> <para>
...@@ -5773,23 +5778,6 @@ struct _snd_pcm_runtime { ...@@ -5773,23 +5778,6 @@ struct _snd_pcm_runtime {
</para> </para>
</listitem> </listitem>
<listitem>
<para>
Modify alsa-driver/utils/Modules.dep
</para>
<para>
<informalexample>
<programlisting>
<![CDATA[
%dir linux/sound/pci/xyz
|snd-xyz snd-pcm ...
]]>
</programlisting>
</informalexample>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Run cvscompile script to re-generate the configure script and Run cvscompile script to re-generate the configure script and
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7