More documentation changes (rawmidi, timer)

doc/doxygen.cfg

@@ -78,7 +78,8 @@ EXCLUDE		 = ../src/control/control_local.h \
 		   ../src/seq/seq_local.h
 RECURSIVE	 = YES
 FILE_PATTERNS    = *.c *.h
-EXAMPLE_PATH     = ../test/pcm.c ../test/latency.c
+EXAMPLE_PATH     = ../test/pcm.c ../test/latency.c ../test/rawmidi.c \
+		   ../test/timer.c
 QUIET            = YES
 
 EXTRACT_ALL	 = NO
@@ -87,7 +88,7 @@ SHOW_INCLUDE_FILES = NO
 JAVADOC_AUTOBRIEF = NO
 INHERIT_DOCS	 = YES
 ENABLED_SECTIONS = ""
-PREDEFINED	 = DOXYGEN PIC "DOC_HIDDEN"
+PREDEFINED	 = DOXYGEN PIC "DOC_HIDDEN" "ATTRIBUTE_UNUSED="
 
 OPTIMIZE_OUTPUT_FOR_C = YES	# doxygen 1.2.6 option
 

doc/index.doxygen

@@ -30,8 +30,13 @@ may be placed in the library code instead of the kernel driver.</P>
 <H2>API links</H2>
 
 <UL>
+  <LI>Page \ref control explains the primitive controls API
+  <LI>Page \ref hcontrol explains the high-level primitive controls API
   <LI>Page \ref pcm explains the design of PCM (digital audio) API
   <LI>Page \ref pcm_plugins explains the design of PCM (digital audio) plugins
+  <LI>Page \ref rawmidi explains the design of RawMidi API
+  <LI>Page \ref timer explains the design of Timer API
+  <LI>Page \ref seq explains the design of Sequencer API
 </UL>
 
 <H2>Configuration</H2>

include/control.h

@@ -35,6 +35,7 @@ extern "C" {
 /**
  *  \defgroup Control Control Interface
  *  The control interface.
+ *  See \ref control page for more details.
  *  \{
  */
 
@@ -398,6 +399,7 @@ void snd_ctl_elem_value_set_iec958(snd_ctl_elem_value_t *obj, const snd_aes_iec9
  *  \defgroup HControl Highlevel Control Interface
  *  \ingroup Control
  *  The highlevel control interface.
+ *  See \ref hcontrol page for more details.
  *  \{
  */
 

include/rawmidi.h

@@ -34,7 +34,7 @@ extern "C" {
 
 /**
  *  \defgroup RawMidi RawMidi Interface
- *  The RawMidi Interface.
+ *  The RawMidi Interface. See \ref rawmidi page for more details.
  *  \{
  */
 

include/seq.h

@@ -5,7 +5,8 @@
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \author Takashi Iwai <tiwai@suse.de>
  * \date 1998-2001
- *
+ */
+/*
  * Application interface library for the ALSA driver
  *
  *
@@ -34,7 +35,8 @@ extern "C" {
 
 /**
  *  \defgroup Sequencer MIDI Sequencer
- *  MIDI Sequencer Interface
+ *  MIDI Sequencer Interface.
+ *  See \ref seq page for more details.
  *  \{
  */
 
@@ -44,7 +46,7 @@ extern "C" {
 /** Sequencer handle */
 typedef struct _snd_seq snd_seq_t;
 
-/** \internal */
+/** Allocate and initialize array on stack \internal */
 #define SND_ALLOCA(type,ptr) \
 do {\
 	assert(ptr);\

include/timer.h

@@ -34,7 +34,7 @@ extern "C" {
 
 /**
  *  \defgroup Timer Timer Interface
- *  Timer Interface
+ *  Timer Interface. See \ref timer page for more details.
  *  \{
  */
 

src/control/control.c

@@ -5,6 +5,7 @@
  * \date 2000
  *
  * CTL interface is designed to access primitive controls.
+ * See \ref control page for more details.
  */
 /*
  *  Control Interface - main file
@@ -27,6 +28,18 @@
  *
  */
 
+/*! \page control Control interface
+
+<P>Control interface is designed to access primitive controls. There is
+also interface notifying about control and structure changes.
+
+\section control_general_overview General overview
+
+The primitive controls can be integer, boolean, enumerators, bytes
+and IEC958 structure.
+
+*/
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <stdarg.h>

src/control/hcontrol.c

@@ -7,6 +7,7 @@
  *
  * HCTL interface is designed to access preloaded and sorted primitive controls.
  * Callbacks may be used for event handling.
+ * See \ref hcontrol page for more details.
  */
 /*
  *  Control Interface - highlevel API
@@ -30,6 +31,17 @@
  *
  */
 
+/*! \page hcontrol High level control interface
+
+<P> High level control interface is designed to access preloaded and sorted primitive controls.
+
+\section hcontrol_general_overview General overview
+
+<P> High level control interface caches the accesses to primitive controls
+to reduce overhead accessing the real controls in kernel drivers.
+
+*/
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <unistd.h>

src/rawmidi/rawmidi.c

@@ -5,19 +5,7 @@
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \date 2000-2001
  *
- * RawMidi Interface is designed to write or read raw (unchanged) MIDI
- * data over the MIDI line. MIDI stands Musical Instrument Digital Interface
- * and more information about this standard can be found at
- * http://www.midi.org.
- *
- * RawMidi devices are opened exclusively for a selected direction.
- * While more than one process may not open a given MIDI device in the same
- * direction simultaneously, separate processes may open a single MIDI device
- * in different directions (i.e. process one opens a MIDI device in write
- * direction and process two opens the same device in read direction). MIDI
- * devices return EBUSY error to applications when other applications have
- * already opened the requested direction (nonblock behaviour) or wait
- * until the device is not available (block behaviour).
+ * See the \ref rawmidi page for more details.
  */
 /*
  *
@@ -37,6 +25,112 @@
  *
  */
 
+/*! \page rawmidi RawMidi interface
+
+<P>RawMidi Interface is designed to write or read raw (unchanged) MIDI
+data over the MIDI line without any timestamps defined in interface. MIDI
+stands Musical Instrument Digital Interface and more information about
+this standard can be found at http://www.midi.org.
+
+\section rawmidi_general_overview General overview
+
+The rawmidi implementation uses ring buffers to store outgoing and incoming
+MIDI stream. The buffer size is tunable and drivers report underruns for incoming
+stream as well.
+
+\section rawmidi_open Open handling
+
+RawMidi devices are opened exclusively for a selected direction.
+While more than one process may not open a given MIDI device in the same
+direction simultaneously, separate processes may open a single MIDI device
+in different directions (i.e. process one opens a MIDI device in write
+direction and process two opens the same device in read direction).
+
+\subsection rawmidi_open_nonblock Nonblocking open (flag)
+
+Using #SND_RAWMIDI_NONBLOCK flag for snd_rawmidi_open() or snd_rawmidi_open_lconf()
+instruct device driver to return the -EBUSY error when device is already occupied
+with another application. This flag also changes behaviour of snd_rawmidi_write()
+and snd_rawmidi_read() returning -EAGAIN when no more bytes can be processed.
+
+Note: In opposite (default) behaviour, application is blocked until device resources
+are free.
+
+\subsection rawmidi_open_append Append open (flag)
+
+Using #SND_RAWMIDI_APPEND flag (output only) instruct device driver to append
+contents of written buffer - passed by snd_rawmidi_write() - atomically
+to output ring buffer in the kernel space. This flag also means that device
+is not opened exclusively, so more applications can share given rawmidi device.
+
+\subsection rawmidi_open_sync Sync open (flag)
+
+Using #SND_RAWMIDI_SYNC flag (output only) assures that the contents of output
+buffer specified using snd_rawmidi_write() is always drained before the function
+exits. This behaviour is same like 'snd_rawmidi_write() followed by
+snd_rawmidi_drain() immediately'.
+
+\subsection rawmidi_io I/O handling
+
+There is only standard read/write access to device internal ring buffer. Use
+snd_rawmidi_read() and snd_rawmidi_write() functions to obtain / write MIDI bytes.
+
+\subsection rawmidi_dev_names RawMidi naming conventions
+
+The ALSA library uses a generic string representation for names of devices.
+The devices might be virtual, physical or a mix of both. The generic string
+is passed to \link ::snd_rawmidi_open() \endlink or \link ::snd_rawmidi_open_lconf() \endlink.
+It contains two parts: device name and arguments. Devices and arguments are described
+in configuration files. The usual place for default definitions is at /usr/share/alsa/alsa.conf.
+
+\subsection rawmidi_dev_names_default 
+
+The default device is equal to hw device. The defaults are used:
+
+defaults.rawmidi.card 0
+defaults.rawmidi.device 0
+defaults.rawmidi.subdevice -1
+
+These defaults can be freely overwritten in local cofiguration files.
+
+Example:
+
+\code
+default
+\endcode
+
+\subsection rawmidi_dev_names_hw HW device
+
+The hw device description uses the hw plugin. The three arguments (in order: CARD,DEV,SUBDEV)
+specify card number or identifier, device number and subdevice number (-1 means any).
+
+Example:
+
+\code
+hw
+hw:0
+hw:0,0
+hw:supersonic,1
+hw:soundwave,1,2
+hw:DEV=1,CARD=soundwave,SUBDEV=2
+\endcode
+
+\section rawmidi_examples Examples
+
+The full featured examples with cross-links:
+
+\par Simple input/output test program
+\ref example_test_rawmidi "example code"
+\par
+This example shows open and read/write rawmidi operations.
+
+*/
+
+/**
+ * \example ../test/rawmidi.c
+ * \anchor example_test_rawmidi
+ */
+ 
 #include <stdio.h>
 #include <stdlib.h>
 #include <stdarg.h>

src/seq/seq.c

@@ -5,6 +5,8 @@
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \author Takashi Iwai <tiwai@suse.de>
  * \date 2000-2001
+ *
+ * See \ref seq page for more details.
  */
 
 /* 
@@ -26,6 +28,12 @@
  *
  */
 
+/*! \page seq Sequencer interface
+
+<P>Description...
+
+*/
+
 #include <dlfcn.h>
 #include <sys/poll.h>
 #include "seq_local.h"

src/timer/timer.c

@@ -5,6 +5,7 @@
  * \date 1998-2001
  *
  * Timer Interface is designed to access timers.
+ * See \ref timer page for more details.
  */
 /*
  *  Timer Interface - main file
@@ -27,6 +28,45 @@
  *
  */
 
+/*! \page timer Timer interface
+
+<P> Timer interface is designed to use internal timers in sound hardware, but
+it can be driven with any timer.
+
+\section timer_general_overview General overview
+
+The timer implementation uses ring buffer to store information about timing
+events. In this buffer is recorded count of ticks and current tick resolution
+in nanoseconds.
+
+\section timer_open Opening
+
+Timer devices can be opened in two ways. When #SND_TIMER_OPEN_NONBLOCK flag
+is used, then the open functions return immediately with -EBUSY error code when
+resources are occupied with another application. When #SND_TIMER_OPEN_NONBLOCK
+is not used (by default) the open functions block the application requesting
+device until resources are not free.
+
+\section timer_events Events
+
+Events are read via snd_timer_read() function.
+
+\section timer_examples Examples
+
+The full featured examples with cross-links:
+
+\par Simple timer test program
+\ref example_test_timer "example code"
+\par
+This example shows opening a timer device and reading of timer events.
+
+*/
+
+/**
+ * \example ../test/timer.c
+ * \anchor example_test_timer
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <unistd.h>