From: Jaroslav Kysela Date: Mon, 11 Feb 2002 18:11:16 +0000 (+0000) Subject: More documentation changes (rawmidi, timer) X-Git-Tag: v1.0.3~485 X-Git-Url: https://git.alsa-project.org/?a=commitdiff_plain;h=2ca5ace9cb737bc301b0a19bad4cd80549a1702e;p=alsa-lib.git More documentation changes (rawmidi, timer) --- diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg index d0b26057..4d741303 100644 --- a/doc/doxygen.cfg +++ b/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 diff --git a/doc/index.doxygen b/doc/index.doxygen index 1c445d14..c0645f04 100644 --- a/doc/index.doxygen +++ b/doc/index.doxygen @@ -30,8 +30,13 @@ may be placed in the library code instead of the kernel driver.

API links

Configuration

diff --git a/include/control.h b/include/control.h index 56214bb3..d0a7d643 100644 --- a/include/control.h +++ b/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. * \{ */ diff --git a/include/rawmidi.h b/include/rawmidi.h index 36162241..4c369db0 100644 --- a/include/rawmidi.h +++ b/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. * \{ */ diff --git a/include/seq.h b/include/seq.h index 1a56e76c..469cc622 100644 --- a/include/seq.h +++ b/include/seq.h @@ -5,7 +5,8 @@ * \author Abramo Bagnara * \author Takashi Iwai * \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);\ diff --git a/include/timer.h b/include/timer.h index 4dc0acb3..f211e3bf 100644 --- a/include/timer.h +++ b/include/timer.h @@ -34,7 +34,7 @@ extern "C" { /** * \defgroup Timer Timer Interface - * Timer Interface + * Timer Interface. See \ref timer page for more details. * \{ */ diff --git a/src/control/control.c b/src/control/control.c index 396132d3..5521a161 100644 --- a/src/control/control.c +++ b/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 + +

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 #include #include diff --git a/src/control/hcontrol.c b/src/control/hcontrol.c index 308c440d..79d39563 100644 --- a/src/control/hcontrol.c +++ b/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 + +

High level control interface is designed to access preloaded and sorted primitive controls. + +\section hcontrol_general_overview General overview + +

High level control interface caches the accesses to primitive controls +to reduce overhead accessing the real controls in kernel drivers. + +*/ + #include #include #include diff --git a/src/rawmidi/rawmidi.c b/src/rawmidi/rawmidi.c index 3b9424f7..44a7b4c0 100644 --- a/src/rawmidi/rawmidi.c +++ b/src/rawmidi/rawmidi.c @@ -5,19 +5,7 @@ * \author Abramo Bagnara * \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 + +

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 #include #include diff --git a/src/seq/seq.c b/src/seq/seq.c index 226f7391..c239395a 100644 --- a/src/seq/seq.c +++ b/src/seq/seq.c @@ -5,6 +5,8 @@ * \author Abramo Bagnara * \author Takashi Iwai * \date 2000-2001 + * + * See \ref seq page for more details. */ /* @@ -26,6 +28,12 @@ * */ +/*! \page seq Sequencer interface + +

Description... + +*/ + #include #include #include "seq_local.h" diff --git a/src/timer/timer.c b/src/timer/timer.c index c83c7a3c..1996b5b3 100644 --- a/src/timer/timer.c +++ b/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 + +

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 #include #include