ALSA 보조 프로세서 가속 API

목적과 요구사항

저자는 Jaroslav Kysela(`perex@perex.cz`)다. Sample-rate converter, compressed stream decoder처럼 여러 audio 작업을 가속하는 하드웨어를 사용자 공간에 노출할 필요가 있다.

이 문서는 실시간 동작에 묶이지 않은 `task`를 처리하고 여러 operation을 직렬화할 수 있도록 ALSA compress API를 확장한 passthrough API를 설명한다.

주요 요구사항은 사용자 공간 개입 없이 여러 operation을 수행할 수 있는 다중 task 직렬화, operation마다 분리된 input/output buffer, mmap을 통한 사용자 공간 buffer 공개, 표준 poll mechanism을 이용한 task 완료 통보다.

==================================
ALSA Co-processor Acceleration API
==================================

Jaroslav Kysela <perex@perex.cz>


Overview
========

There is a requirement to expose the audio hardware that accelerates various
tasks for user space such as sample rate converters, compressed
stream decoders, etc.

This is description for the API extension for the compress ALSA API which
is able to handle "tasks" that are not bound to real-time operations
and allows for the serialization of operations.

Requirements
============

The main requirements are:

- serialization of multiple tasks for user space to allow multiple
  operations without user space intervention

- separate buffers (input + output) for each operation

- expose buffers using mmap to user space

- signal user space when the task is finished (standard poll mechanism)

Passthrough 방향, 상태와 dma-buf

새 방향 `SND_COMPRESS_ACCEL`은 passthrough API를 식별한다. 이 확장은 주 compressed API의 장치 열거와 parameter 처리를 공유한다. 그 밖의 실시간 streaming ioctl은 비활성화하고 task 전용 ioctl 집합을 추가한다. Passthrough 장치 자체에서는 표준 `read`/`write`/`mmap` I/O operation을 지원하지 않는다.

장치 또는 stream 상태는 `OPEN`과 `SETUP`만 남기며 passthrough mode에서는 다른 상태를 사용할 수 없다.

실제 data I/O는 mmap, 표준 I/O, buffer 공유 기능을 제공하는 dma-buf interface를 사용한다. Input data용 buffer와 별도의 output data용 buffer를 두며 각 task는 자체 I/O buffer 쌍을 가진다.

Buffering parameter에서 `fragments`는 해당 장치가 할당할 수 있는 task 수의 한계이고 `fragment_size`는 input buffer 크기의 한계다. Output buffer 크기는 driver가 정하며 input과 다를 수 있다.

Design
======

A new direction SND_COMPRESS_ACCEL is introduced to identify
the passthrough API.

The API extension shares device enumeration and parameters handling from
the main compressed API. All other realtime streaming ioctls are deactivated
and a new set of task related ioctls are introduced. The standard
read/write/mmap I/O operations are not supported in the passthrough device.

Device ("stream") state handling is reduced to OPEN/SETUP. All other
states are not available for the passthrough mode.

Data I/O mechanism is using standard dma-buf interface with all advantages
like mmap, standard I/O, buffer sharing etc. One buffer is used for the
input data and second (separate) buffer is used for the output data. Each task
have separate I/O buffers.

For the buffering parameters, the fragments means a limit of allocated tasks
for given device. The fragment_size limits the input buffer size for the given
device. The output buffer size is determined by the driver (may be different
from the input buffer size).

OPEN과 SETUP 상태 머신

Passthrough audio stream은 `OPEN`과 `SETUP` 두 상태만 사용한다. `compr_set_params()`를 호출하면 `OPEN`에서 `SETUP`으로 전이한다. 모든 passthrough task operation은 `SETUP` 상태에서 실행되고 완료 후에도 `SETUP`에 머물러 다음 작업을 받을 수 있다.

State Machine
=============

The passthrough audio stream state machine is described below::

                                       +----------+
                                       |          |
                                       |   OPEN   |
                                       |          |
                                       +----------+
                                             |
                                             |
                                             | compr_set_params()
                                             |
                                             v
         all passthrough task ops      +----------+
  +------------------------------------|          |
  |                                    |   SETUP  |
  |                                    |
  |                                    +----------+
  |                                          |
  +------------------------------------------+

CREATE와 FREE ioctl

모든 passthrough operation은 `stream->device->lock` mutex로 보호한다.

`CREATE`는 input/output buffer 쌍을 만들고 고유한 `seqno`를 할당한다. Input buffer 크기는 `fragment_size`다. 하드웨어 driver는 `dma_buf_export()`로 input과 output 각각의 내부 `struct dma_buf`를 할당하고, 두 buffer의 anonymous file descriptor를 사용자 공간에 전달한다.

`FREE`는 input/output buffer 쌍을 해제한다. Task가 active면 먼저 stop operation을 수행한다. `seqno`가 0이면 모든 task에 operation을 적용한다.

Passthrough operations (ioctls)
===============================

All operations are protected using stream->device->lock (mutex).

CREATE
------
Creates a set of input/output buffers. The input buffer size is
fragment_size. Allocates unique seqno.

The hardware drivers allocate internal 'struct dma_buf' for both input and
output buffers (using 'dma_buf_export()' function). The anonymous
file descriptors for those buffers are passed to user space.

FREE
----
Free a set of input/output buffers. If a task is active, the stop
operation is executed before. If seqno is zero, operation is executed for all
tasks.

START, task 재사용과 처리 순서

`START`는 task를 시작해 queue에 넣는다. 새로 만든 task를 즉시 시작하는 경우 `origin_seqno`는 0이어야 한다. 이미 끝난 task를 재사용하는 경우에는 `origin_seqno`로 재사용할 task를 식별해야 한다. 두 경우 모두 새 `seqno`를 할당해 사용자 공간에 반환한다.

시작 전에 응용 프로그램은 input dma-buf에 새 source data를 채우고, 실제 data 크기를 driver에 전달하도록 `input_size`를 설정해야 한다.

Data 처리 순서는 보존되어 먼저 시작한 job이 먼저 끝나야 한다. Resampling처럼 여러 task 사이에 상태를 이어야 하면 사용자 공간은 `SND_COMPRESS_TFLG_NEW_STREAM` flag로 새 stream data의 시작을 표시할 수 있다. 이를 통해 open/close를 반복하지 않고 할당한 buffer를 새 operation에 재사용할 수 있다.

START
-----
Starts (queues) a task. There are two cases of the task start - right after
the task is created. In this case, origin_seqno must be zero.
The second case is for reusing of already finished task. The origin_seqno
must identify the task to be reused. In both cases, a new seqno value
is allocated and returned to user space.

The prerequisite is that application filled input dma buffer with
new source data and set input_size to pass the real data size to the driver.

The order of data processing is preserved (first started job must be
finished at first).

If the multiple tasks require a state handling (e.g. resampling operation),
the user space may set SND_COMPRESS_TFLG_NEW_STREAM flag to mark the
start of the new stream data. It is useful to keep the allocated buffers
for the new operation rather using open/close mechanism.

STOP, STATUS와 기여자

`STOP`은 task를 정지하고 queue에서 제거한다. `seqno`가 0이면 모든 task에 적용한다.

`STATUS`는 task가 active인지 finished인지 상태를 얻는다. Driver는 output buffer에서 실제로 유효한 data 영역의 크기도 설정한다.

기여자는 Shengjiu Wang(`shengjiu.wang@gmail.com`), Takashi Iwai(`tiwai@suse.de`), Vinod Koul(`vkoul@kernel.org`)이다.

STOP
----
Stop (dequeues) a task. If seqno is zero, operation is executed for all
tasks.

STATUS
------
Obtain the task status (active, finished). Also, the driver will set
the real output data size (valid area in the output buffer).

Credits
=======
- Shengjiu Wang <shengjiu.wang@gmail.com>
- Takashi Iwai <tiwai@suse.de>
- Vinod Koul <vkoul@kernel.org>