[alsa-devel] [PATCH] ALSA: doc: Brush up the old writing-an-alsa-driver

[Takashi Sakamoto]

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 at 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