[alsa-utils][PATCH 0/5] Add man page for alsaucm + other fixes

[alsa-utils][PATCH 0/5] Add man page for alsaucm + other fixes

[Antonio Ospite]

Hi,

while adding the alsaucm man page (patch 4/5) I noticed some other
things worth fixing, so here is the whole patch set.

In patch 4/5 the reStructuredText content is exactly the same reviewed
by Liam, so I put his ACK in the commit message.

Thanks,
   Antonio

Antonio Ospite (5):
  alsaucm: mention the "list1" command in the usage output
  configure.ac: fix the check for xmlto availability
  configure.ac: add a check for rst2man, a reStructuredText man page
    generator
  alsaucm: add a man page, generated from reStructuredText
  INSTALL: document how to configure a build for installation in a local
    dir

 .gitignore          |   1 +
 INSTALL             |   7 ++
 alsaucm/Makefile.am |   7 ++
 alsaucm/alsaucm.rst | 235 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 alsaucm/usecase.c   |   3 +-
 configure.ac        |  15 +++-
 6 files changed, 264 insertions(+), 4 deletions(-)
 create mode 100644 alsaucm/alsaucm.rst

-- 
Antonio Ospite
https://ao2.it
https://twitter.com/ao2it

A: Because it messes up the order in which people normally read text.
   See http://en.wikipedia.org/wiki/Posting_style
Q: Why is top-posting such a bad thing?

[alsa-utils][PATCH 1/5] alsaucm: mention the "list1" command in the usage output

[Antonio Ospite]

Signed-off-by: Antonio Ospite <ao2@ao2.it>
---
 alsaucm/usecase.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/alsaucm/usecase.c b/alsaucm/usecase.c
index 1c94680..fbbe73a 100644
--- a/alsaucm/usecase.c
+++ b/alsaucm/usecase.c
@@ -117,7 +117,8 @@ static void dump_help(struct context *context)
 "  reset                      reset sound card to default state\n"
 "  reload                     reload configuration\n"
 "  listcards                  list available cards\n"
-"  list IDENTIFIER            list command\n"
+"  list IDENTIFIER            list command, for items with value + comment\n"
+"  list1 IDENTIFIER           list command, for items without comments\n"
 "  get IDENTIFIER             get string value\n"
 "  geti IDENTIFIER            get integer value\n"
 "  set IDENTIFIER VALUE       set string value\n"
-- 
2.11.0

[alsa-utils][PATCH 2/5] configure.ac: fix the check for xmlto availability

[Antonio Ospite]

The same $xmlto variable is used both in AC_ARG_ENABLE and
AC_CHECK_PROG, but the latter is not setting a value to it when the
program is not found.

These two facts result in the "yes" value from the AC_ARG_ENABLE macro
to be still kept in the variable when the program is not found by
AC_CHECK_PROG, causing USE_XMLTO to be always set, finally resulting in
a build failure in case the xmlto program is not actually in the PATH.

As possible fix could have been to set "no" as a value in AC_CHECK_PROG
when program is not found.

However using two separate variables is more explicit, so fix the issue
this way.

Signed-off-by: Antonio Ospite <ao2@ao2.it>
---
 configure.ac | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/configure.ac b/configure.ac
index 2221617..c9629bb 100644
--- a/configure.ac
+++ b/configure.ac
@@ -166,14 +166,14 @@ AC_ARG_ENABLE(alsaloop,
      esac],[alsaloop=true])
 AM_CONDITIONAL(ALSALOOP, test x$alsaloop = xtrue)
 
-xmlto=""
+xmlto_available=""
 AC_ARG_ENABLE(xmlto,
  AS_HELP_STRING([--disable-xmlto], [Disable man page creation via xmlto]),
  xmlto="$enableval", xmlto="yes")
 if test "$xmlto" = "yes"; then
-  AC_CHECK_PROG([xmlto], [xmlto], [yes])
+  AC_CHECK_PROG([xmlto_available], [xmlto], [yes])
 fi
-AM_CONDITIONAL(USE_XMLTO, test x"$xmlto" = xyes)
+AM_CONDITIONAL(USE_XMLTO, test x"$xmlto_available" = xyes)
 
 AC_ARG_WITH(
         [udev-rules-dir],
-- 
2.11.0

[alsa-utils][PATCH 3/5] configure.ac: add a check for rst2man, a reStructuredText man page generator

[Antonio Ospite]

Define a USE_RST2MAN conditional so that, when available, rst2man can be
used to generate man pages from reStructuredText source files.

The code follows what is done to check for xmlto.

On Debian system, the rst2man executable is provided by python-docutils
or python3-docutils.

Signed-off-by: Antonio Ospite <ao2@ao2.it>
---
 configure.ac | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/configure.ac b/configure.ac
index c9629bb..d8fcf0f 100644
--- a/configure.ac
+++ b/configure.ac
@@ -175,6 +175,15 @@ if test "$xmlto" = "yes"; then
 fi
 AM_CONDITIONAL(USE_XMLTO, test x"$xmlto_available" = xyes)
 
+rst2man_available=""
+AC_ARG_ENABLE(rst2man,
+ AS_HELP_STRING([--disable-rst2man], [Disable man page creation via rst2man]),
+ rst2man="$enableval", rst2man="yes")
+if test "$rst2man" = "yes"; then
+  AC_CHECK_PROG([rst2man_available], [rst2man], [yes])
+fi
+AM_CONDITIONAL(USE_RST2MAN, test x"$rst2man_available" = xyes)
+
 AC_ARG_WITH(
         [udev-rules-dir],
         AS_HELP_STRING([--with-udev-rules-dir=DIR],[Directory where to install udev rules to (default=auto)]),
-- 
2.11.0

[alsa-utils][PATCH 4/5] alsaucm: add a man page, generated from reStructuredText

[Antonio Ospite]

Signed-off-by: Antonio Ospite <ao2@ao2.it>
Acked-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
---
 .gitignore          |   1 +
 alsaucm/Makefile.am |   7 ++
 alsaucm/alsaucm.rst | 235 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 243 insertions(+)
 create mode 100644 alsaucm/alsaucm.rst

diff --git a/.gitignore b/.gitignore
index f7e3e23..bc08f4f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -46,6 +46,7 @@ seq/aseqnet/aseqnet
 speaker-test/speaker-test
 alsaloop/alsaloop
 alsaucm/alsaucm
+alsaucm/alsaucm.1
 topology/alsatplg
 
 include/aconfig.h*
diff --git a/alsaucm/Makefile.am b/alsaucm/Makefile.am
index 39a27b1..7047215 100644
--- a/alsaucm/Makefile.am
+++ b/alsaucm/Makefile.am
@@ -1,9 +1,16 @@
 bin_PROGRAMS = \
         alsaucm
 
+if USE_RST2MAN
+man_MANS = alsaucm.1
+endif
+
 alsaucm_SOURCES = usecase.c
 
 AM_CPPFLAGS = \
          -Wall -I$(top_srcdir)/include
 
 alsaucm_LDADD = -lasound
+
+%.1: %.rst
+	rst2man $< > $@
diff --git a/alsaucm/alsaucm.rst b/alsaucm/alsaucm.rst
new file mode 100644
index 0000000..7890ba5
--- /dev/null
+++ b/alsaucm/alsaucm.rst
@@ -0,0 +1,235 @@
+=========
+ alsaucm
+=========
+
+---------------------
+ALSA Use Case Manager
+---------------------
+
+:Author: Antonio Ospite <ao2@ao2.it>
+:Date:   2016-09-22
+:Copyright: GPLv2+
+:Manual section: 1
+:Manual group: General Commands Manual
+
+SYNOPSIS
+========
+
+*alsaucm* <options> [command]
+
+DESCRIPTION
+===========
+
+alsaucm (ALSA Use Case Manager) is a program to use the ALSA `Use Case
+Interface`_ from the command line.
+
+On complex sound cards, setting up audio routes is not trivial and mixer
+settings can conflict one another preventing the audio card to work at all.
+
+The ALSA Use Case Manager is a mechanism for controlling complex audio
+hardware establishing a relationship between hardware configurations and
+meaningful use cases that the end-user can relate with.
+
+The use case manager can also be used to switch between use cases when
+necessary, in a consistent way.
+
+At a lower level, the use case manager works by configuring the sound card
+ALSA kcontrols to change the hardware digital and analog audio routing to
+match the requested device use case.
+
+The use case manager kcontrol configurations are stored in easy to modify text
+files. An audio use case can be defined by a **verb** and **device** parameter.
+
+The verb describes the use case action i.e. a phone call, listening to music,
+recording a conversation etc. The device describes the physical audio capture
+and playback hardware i.e. headphones, phone handset, bluetooth headset, etc.
+
+
+OPTIONS
+=======
+
+Available options:
+
+  **-h**, **--help**
+    this help
+
+  **-c**, **--card** `NAME`
+    open card NAME
+
+  **-i**, **--interactive**
+    interactive mode
+
+  **-b**, **--batch** `FILE`
+    batch mode (use ``'-'`` for the stdin input)
+
+  **-n**, **--no-open**
+    do not open first card found
+
+
+Available commands:
+
+  ``open`` `NAME`
+    open card NAME.
+
+    valid names are sound card names as listed in ``/usr/share/alsa/ucm``.
+
+  ``reset``
+    reset sound card to default state.
+
+  ``reload``
+    reload configuration.
+
+  ``listcards``
+    list available cards.
+
+  ``list`` `IDENTIFIER`
+    list command, for items returning two entries (value+comment).
+
+    the value of the `IDENTIFIER` argument can can be:
+
+    - ``_verbs`` - get verb list (in pair verb+comment)
+    - ``_devices[/{verb}]`` - get list of supported devices (in pair device+comment)
+    - ``_modifiers[/{verb}]`` - get list of supported modifiers (in pair modifier+comment)
+
+    The forms without the trailing ``/{verb}`` are valid only after a specific
+    verb has been set.
+
+  ``list1`` `IDENTIFIER`
+    list command, for lists returning one item per entry.
+
+    the value of the `IDENTIFIER` argument can vary depending on the context,
+    it can be:
+
+    - ``TQ[/{verb}]`` - get list of Tone Quality identifiers
+    - ``_enadevs`` - get list of enabled devices
+    - ``_enamods`` - get list of enabled modifiers
+    - ``_supporteddevs/{modifier}|{device}[/{verb}]`` - list of supported devices
+    - ``_conflictingdevs/{modifier}|{device}[/{verb}]`` - list of conflicting devices
+
+  ``get`` `IDENTIFIER`
+    get string value.
+
+    the value of the `IDENTIFIER` argument can can be:
+
+    - ``_verb`` - return current verb
+    - ``[=]{NAME}[/[{modifier}|{/device}][/{verb}]]`` (For valid NAMEs look at the
+      ALSA `Use Case Interface`_)
+
+
+  ``geti`` `IDENTIFIER`
+    get integer value.
+
+    the value of the `IDENTIFIER` argument can can be:
+
+    - ``_devstatus/{device}``
+    - ``_modtstaus/{device}``
+
+  ``set`` `IDENTIFIER` `VALUE`
+    set string value
+
+    The value of the `IDENTIFIER` argument can can be:
+
+    - ``_verb`` - set the verb to `VALUE`
+    - ``_enadev`` - enable the device specified by `VALUE`
+    - ``_disdev`` - disable the device specified by `VALUE`
+    - ``_swdev/{old_device}`` - switche device:
+
+      - disable `old_device` and then enable the device specified by
+        `VALUE`
+      - if no device was enabled just return
+
+    - ``_enamod`` - enable the modifier specified by `VALUE`
+    - ``_dismod`` - disable the modifier specified by `VALUE`
+    - ``_swmod/{old_modifier}`` - switch modifier:
+
+      - disable `old_modifier` and then enable the modifier specified by
+        `VALUE`
+      - if no modifier was enabled just return
+
+    Note that the identifiers referring to devices and modifiers are valid
+    only after setting a verb.
+
+  ``h``, ``help``
+    help
+
+  ``q``, ``quit``
+    quit
+
+
+FILES
+=====
+
+The master use case files for each supported sound card are in ``/usr/share/alsa/ucm``.
+
+For example, the master use case file for the `Pandaboard` card is in
+``/usr/share/alsa/ucm/PandaBoard/PandaBoard.conf``, this file lists all the
+supported use cases, e.g.
+
+::
+
+  SectionUseCase."HiFi" {
+                  File "hifi"
+                  Comment "Play HiFi quality Music."
+  }
+  ...
+
+
+Each use case defines a _verb, which is described in the file specified in
+the ``File`` directive, like above.
+
+The ``HiFi`` verb above is described in
+``/usr/share/alsa/ucm/PandaBoard/hifi``.
+
+For more details on the syntax of UCM files, see the alsa-lib source code:
+http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=src/ucm/parser.c
+
+
+EXAMPLES OF USE
+===============
+
+Some commands, like for instance ``list _devices``,
+can only work after setting a ``_verb`` in the **same execution**, for
+instance this sequence doesn't work:
+
+::
+
+  # alsaucm -c bytcr-rt5640 set _verb HiFi
+  # alsaucm -c bytcr-rt5640 list _devices
+
+
+However this command does:
+
+::
+
+  # alsaucm -n -b - <<EOM
+  open bytcr-rt5640
+  set _verb HiFi
+  list _devices
+  EOM
+
+
+An example of setting the `Speaker` device for the `HiFi` verb of the
+`bytcr-rt5640` card:
+
+::
+
+  # alsaucm -n -b - <<EOM
+  open bytcr-rt5640
+  reset
+  set _verb HiFi
+  set _enadev Speaker
+  EOM
+
+
+
+SEE ALSO
+========
+
+* Use Case Interface: http://www.alsa-project.org/alsa-doc/alsa-lib/group__ucm.html
+
+.. _Use Case Interface: http://www.alsa-project.org/alsa-doc/alsa-lib/group__ucm.html
+
+BUGS
+====
+
+None known.
-- 
2.11.0

[alsa-utils][PATCH 5/5] INSTALL: document how to configure a build for installation in a local dir

[Antonio Ospite]

Signed-off-by: Antonio Ospite <ao2@ao2.it>
---
 INSTALL | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/INSTALL b/INSTALL
index 544d5d2..d95bb97 100644
--- a/INSTALL
+++ b/INSTALL
@@ -42,5 +42,12 @@ For compilation you can use these commands:
 
 The included gitcompile script does this job for you.
 
+To configure the build to install in a local directory, a command like the
+following can be used:
+
+	./gitcompile --prefix="$PWD/build" \
+	  --with-systemdsystemunitdir="$PWD/build/$(pkg-config systemd --variable=systemdsystemunitdir)" \
+	  --with-udev-rules-dir="$PWD/build/$(pkg-config udev --variable=udevdir)"
+
 Note: Some automake packages have missing aclocal program. Use newer version
       in the case.
-- 
2.11.0

Re: [alsa-utils][PATCH 0/5] Add man page for alsaucm + other fixes

[Takashi Iwai]

On Fri, 09 Dec 2016 14:02:27 +0100,
Antonio Ospite wrote:
> 
> Hi,
> 
> while adding the alsaucm man page (patch 4/5) I noticed some other
> things worth fixing, so here is the whole patch set.
> 
> In patch 4/5 the reStructuredText content is exactly the same reviewed
> by Liam, so I put his ACK in the commit message.

Thanks, applied now all patches.

The change of .gitignore was split from the patch 4, since it makes
often backporting difficult.  Other than that, all patches were
applied as is.


Takashi

> 
> Thanks,
>    Antonio
> 
> Antonio Ospite (5):
>   alsaucm: mention the "list1" command in the usage output
>   configure.ac: fix the check for xmlto availability
>   configure.ac: add a check for rst2man, a reStructuredText man page
>     generator
>   alsaucm: add a man page, generated from reStructuredText
>   INSTALL: document how to configure a build for installation in a local
>     dir
> 
>  .gitignore          |   1 +
>  INSTALL             |   7 ++
>  alsaucm/Makefile.am |   7 ++
>  alsaucm/alsaucm.rst | 235 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>  alsaucm/usecase.c   |   3 +-
>  configure.ac        |  15 +++-
>  6 files changed, 264 insertions(+), 4 deletions(-)
>  create mode 100644 alsaucm/alsaucm.rst
> 
> -- 
> Antonio Ospite
> https://ao2.it
> https://twitter.com/ao2it
> 
> A: Because it messes up the order in which people normally read text.
>    See http://en.wikipedia.org/wiki/Posting_style
> Q: Why is top-posting such a bad thing?
> 

Re: [alsa-utils][PATCH 0/5] Add man page for alsaucm + other fixes

[Antonio Ospite]

On Fri, 09 Dec 2016 17:33:08 +0100
Takashi Iwai <tiwai@suse.de> wrote:

> On Fri, 09 Dec 2016 14:02:27 +0100,
> Antonio Ospite wrote:
> > 
> > Hi,
> > 
> > while adding the alsaucm man page (patch 4/5) I noticed some other
> > things worth fixing, so here is the whole patch set.
> > 
> > In patch 4/5 the reStructuredText content is exactly the same reviewed
> > by Liam, so I put his ACK in the commit message.
> 
> Thanks, applied now all patches.
> 
> The change of .gitignore was split from the patch 4, since it makes
> often backporting difficult.  Other than that, all patches were
> applied as is.
> 

Awesome, thanks.

Ciao ciao,
   Antonio

-- 
Antonio Ospite
https://ao2.it
https://twitter.com/ao2it

A: Because it messes up the order in which people normally read text.
   See http://en.wikipedia.org/wiki/Posting_style
Q: Why is top-posting such a bad thing?