More documentation changes (rawmidi, timer)

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>