Hi,

On 2018/10/17 23:57, Takashi Iwai wrote:

Slightly brushing up and throw the old dust away from my ancient writing-an-alsa-driver document. The contents aren't changed so much but the obsoleted parts are dropped.

Also, remove the date and the version number. It's useless.

Signed-off-by: Takashi Iwai tiwai@suse.de

This is a patch included in my devres patchset. Since this is an independent fix for documentation, let's apply this at first.

.../kernel-api/writing-an-alsa-driver.rst | 307 +++++++++--------- 1 file changed, 149 insertions(+), 158 deletions(-)

diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index a0b268466cb1..b60a26807420 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst ... @@ -4117,21 +4124,17 @@ a question now: how to put my own driver into the ALSA driver tree? Here

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, ``alsa-driver/pci`` directory in the case of PCI -cards. Then the driver is evaluated, audited and tested by developers -and users. After a certain time, the driver will go to the alsa-kernel -tree (to the corresponding directory, such as ``alsa-kernel/pci``) and -eventually will be integrated into the Linux 2.6 tree (the directory -would be ``linux/sound/pci``). +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 -alsa-driver tree. The two cases are covered: a driver consisting of a +Linux kernel tree. The two cases are covered: a driver consisting of a single source file and one consisting of several source files.

Driver with A Single Source File

-1. Modify alsa-driver/pci/Makefile +1. Modify sound/pci/Makefile

 Suppose you have a file xyz.c. Add the following two lines

@@ -4160,52 +4163,43 @@ Driver with A Single Source File

 For the details of Kconfig script, refer to the kbuild documentation.

-3. Run cvscompile script to re-generate the configure script and build

• the whole stuff again.

• Drivers with Several Source Files

  Suppose that the driver snd-xyz have several source files. They are

-located in the new subdirectory, pci/xyz. +located in the new subdirectory, sound/pci/xyz.

-1. Add a new directory (``xyz``) in ``alsa-driver/pci/Makefile`` as

• below

+1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``

• as below

  ::

• obj-$(CONFIG_SND) += xyz/

• obj-$(CONFIG_SND) += sound/pci/xyz/

-2. Under the directory ``xyz``, create a Makefile +2. Under the directory ``sound/pci/xyz``, create a Makefile

::

•     ifndef SND_TOPDIR
  

•     SND_TOPDIR=../..
  

•     endif
  

•     include $(SND_TOPDIR)/toplevel.config
  

•     include $(SND_TOPDIR)/Makefile.conf
  

•      snd-xyz-objs := xyz.o abc.o def.o
  

•      obj-$(CONFIG_SND_XYZ) += snd-xyz.o
  
  

•     include $(SND_TOPDIR)/Rules.make
  

• 3. Create the Kconfig entry

     This procedure is as same as in the last section.

-4. Run cvscompile script to re-generate the configure script and build

• the whole stuff again.

  Useful Functions

  :c:func:`snd_printk()` and friends

---

+----------------------------------

+.. note:: This subsection describes a few helper functions for +decorating a bit more on the standard :c:func:`printk()` & co. +However, in general, the use of such helpers is no longer recommended. +If possible, try to stick with the standard functions like +:c:func:`dev_err()` or :c:func:`pr_err()`.

The 'note::' admonition directive requires indentation for its section[1].

$ make SPHINXDIRS=sound htmldocs

... writing-an-alsa-driver.rst:4199: WARNING: Explicit markup ends without a blank line; unexpected unindent.

Please add 3 spaces to each line.

[1] http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions

Regards

Takashi Sakamoto