[alsa-devel] [PATCH 1/3] axfer: add an explanation about IRQ-based scheduling model

[Takashi Sakamoto]

This commit adds a section titled as 'SCHEDULING MODEL' and fulfill a
subsection titled as 'IRQ-based scheduling model'.

This scheduling model is for a typical applications to operate a kind of
data sampled against actual time. In this model, ALSA PCM core maintains
timing of the applications with notification of hardware by
blocking/waking up their processes. This is a default behaviour of
runtime of PCM substream.

Signed-off-by: Takashi Sakamoto <o-takashi at sakamocchi.jp>
---
 axfer/axfer-transfer.1 | 45 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 44 insertions(+), 1 deletion(-)

diff --git a/axfer/axfer-transfer.1 b/axfer/axfer-transfer.1
index 272e601..a84ab3a 100644
--- a/axfer/axfer-transfer.1
+++ b/axfer/axfer-transfer.1
@@ -665,7 +665,50 @@ named \(aqchannels\-1.au\(aq and \(aqchannels\-2.au\(aq.
 
 .SH SCHEDULING MODEL
 
-(placeholder)
+In a design of ALSA PCM core, runtime of PCM substream supports two modes;
+.I period\-wakeup
+and
+.I no\-period\-wakeup.
+These two modes are for different scheduling models.
+
+.SS IRQ\-based scheduling model
+
+As a default,
+.I period\-wakeup
+mode is used. In this mode, in\-kernel drivers should operate hardware to
+generate periodical notification for transmission of audio data frame. The
+interval of notification is equivalent to the same amount of audio data frame
+as one period of buffer, against actual time.
+
+In a handler assigned to the notification, a helper function of ALSA PCM core
+is called to update a position to head of hardware transmission, then compare
+it with a position to head of application operation to judge overrun/underrun
+(XRUN) and to wake up blocked processes.
+
+For this purpose, hardware IRQ of controller for serial audio bus such as
+Inter\-IC sound is typically used. In this case, the controller generates the
+IRQ according to transmission on the serial audio bus. In the handler assigned
+to the IRQ, direct media access (DMA) transmission is requested between
+dedicated host memory and device memory.
+
+If target hardware doesn't support this kind of mechanism, the periodical
+notification should be emulated by any timer; e.g. hrtimer, kernel timer.
+External PCM plugins generated by PCM plugin SDK in alsa\-lib should also
+emulate the above behaviour.
+
+In this mode, PCM applications are programmed according to typical way of I/O
+operations. They execute blocking system calls to read/write audio data frame
+in buffer of PCM substream, or blocking system calls to wait until any audio
+data frame is available. In
+.I axfer
+, this is called
+.I IRQ\-based
+scheduling model and a default behaviour. Users can explicitly configure this
+mode by usage of
+.I \-\-sched\-model
+option with
+.I irq
+value.
 
 .SH COMPATIBILITY TO APLAY
 
-- 
2.19.1