ALSA lib-io plugin

Posted 2020-11-28 fellow1988

https://www.alsa-project.org/alsa-doc/alsa-lib/pcm_external_plugins.html

External Plugin: I/O Plugin

The I/O-type plugin is a PCM plugin to work as the input or output terminal point, i.e. as a user-space PCM driver.

The new plugin is created via snd_pcm_ioplug_create() function. The first argument is a pointer of the pluging information. Some of this struct must be initialized in prior to call snd_pcm_ioplug_create(). Then the function fills other fields in return. The rest arguments, name, stream and mode, are usually identical with the values passed from the ALSA plugin constructor.

The following fields are mandatory: version, name, callback. Otherfields are optional and should be initialized with zero.

The constant SND_PCM_IOPLUG_VERSION must be passed to the version field for the version check in alsa-lib. A non-NULL ASCII string has to be passed to the name field. The callback field contains the table of callback functions for this plugin (defined as snd_pcm_ioplug_callback_t).

flags field specifies the optional bit-flags. poll_fd and poll_events specify the poll file descriptor and the corresponding poll events (POLLIN, POLLOUT) for the plugin. If the plugin requires multiple poll descriptors or poll descriptor(s) dynamically varying, set poll_descriptors and poll_descriptors_count callbacks to the callback table. Then the poll_fd and poll_events field are ignored.

mmap_rw specifies whether the plugin behaves in the pseudo mmap mode. When this value is set to 1, the plugin creates always a local buffer and performs read/write calls using this buffer as if it‘s mmapped. The address of local buffer can be obtained via snd_pcm_ioplug_mmap_areas() function. When poll_fd, poll_events and mmap_rw fields are changed after snd_pcm_ioplug_create(), call snd_pcm_ioplug_reinit_status() to reflect the changes.

The driver can set an arbitrary value (pointer) to private_data field to refer its own data in the callbacks.

The rest fields are filled by snd_pcm_ioplug_create(). The pcm field is the resultant PCM handle. The others are the current status of the PCM.

The callback functions in snd_pcm_ioplug_callback_t define the real behavior of the driver. At least, start, stop and pointer callbacks must be given. Other callbacks are optional. The start and stop callbacks are called when the PCM stream is started and stopped, repsectively. The pointer callback returns the current DMA position, which may be called at any time.

The transfer callback is called when any data transfer happens. It receives the area array, offset and the size to transfer. The area array contains the array ofsnd_pcm_channel_area_t with the elements of number of channels.

When the PCM is closed, close callback is called. If the driver allocates any internal buffers, they should be released in this callback. The hw_params and hw_free callbacks are called when hw_params are set and reset, respectively. Note that they may be called multiple times according to the application. Similarly, sw_params callback is called when sw_params is set or changed.

The prepare, drain, pause and resume callbacks are called when snd_pcm_prepare(), snd_pcm_drain(), snd_pcm_pause(), and snd_pcm_resume() are called. The poll_descriptors_count and poll_descriptors callbacks are used to return the multiple or dynamic poll descriptors as mentioned above. The poll_revents callback is used to modify poll events. If the driver needs to mangle the native poll events to proper poll events for PCM, you can do it in this callback.

Finally, the dump callback is used to print the status of the plugin.

Note that some callbacks (start, stop, pointer, transfer and pause) may be called inside the internal pthread mutex, and they shouldn‘t call the PCM functions again unnecessarily from the callback itself; otherwise it may lead to a deadlock.

The hw_params constraints can be defined via either snd_pcm_ioplug_set_param_minmax() and snd_pcm_ioplug_set_param_list() functions after callingsnd_pcm_ioplug_create(). The former defines the minimal and maximal acceptable values for the given hw_params parameter (SND_PCM_IOPLUG_HW_XXX). This function can‘t be used for the format parameter. The latter function specifies the available parameter values as the list.

To clear the parameter constraints, call snd_pcm_ioplug_params_reset() function.

 

代码参考pcm_ac52.c

#include <stdio.h>
#include <string.h>
#include <unistd.h>
#include <alsa/asoundlib.h>
#include <alsa/pcm_external.h>
#include <alsa/pcm_plugin.h>

#define MIN_PERIOD 256
#define MAX_PERIOD 1024
#define MIN_CHANNELS 1
#define MAX_CHANNELS 6

struct fellow_ctx {
    snd_pcm_ioplug_t io;
    snd_pcm_t *slave;
    snd_pcm_format_t format;
    unsigned int channels;
    unsigned int rate;
    unsigned int frame_size;
    char *inbuf;
    char *outbuf;
    int outbuf_size;
    snd_pcm_uframes_t transfer;
    int remain;
    int filled;
    unsigned int slave_period_size;
    unsigned int slave_buffer_size;
    snd_pcm_hw_params_t *hw_params;
    FILE *dump_fp;
}

static void convert_data(struct fellow_ctx *rec)
{
    int bytes_per_frame = (snd_pcm_format_width(rec->format)     >> 3) * rec->channels;
    memcpy(rec->outbuf, rec->inbuf, rec->frame_size * bytes_per_frame);
    rec->remain = rec->outbuf_size / bytes_per_frame;
    rec->filled = 0;
}

static int write_out{snd_pcm_ioplug_t *io, struct_fellow_ctx *rec)
{
    int err, ofs = 0;
    int bytes_per_frame = (snd_pcm_format_width(rec->format)     >> 3) * rec->channels;
    if (!rec->remain)
        return 0;
    while (rec->remain) {
        err = snd_pcm_writei(rec->slave, rec->outbuf + ofs, rec->remain);
        if (err < 0) {
            if (err == -EPIPE)
                io->state = SND_PCM_STATE_XRUN;
            return err;
        } else if (!err) 
            break;
        if (rec->dump_fp)
            fwrite(rec->outbuf + ofs, 1, err * bytes_per_frame, rec->dump_fp);
        if (err < rec->remain)
            ofs += (rec->remain - err) * bytes_per_frame;
        rec->remain -= err;
    }
    if (rec->remain && ofs)
        memmove(rec->outbuf, rec->outbuf + ofs, rec->remain * bytes_per_frame);
    return 0;
}

static int fellow_drain(snd_pcm_ioplug_t *io)
{
    struct fellow_ctx *rec = io->private_data;
    int bytes_per_frame = (snd_pcm_format_width(rec->format)   >> 3) * rec->channels;
    int err;
    if (rec->filled) {
        if (err = write_out(io, rec) < 0)
            return err;
    memset(rec->inbuf + rec->filled * bytes_per_frame, 0, (rec->frame_size - rec->fileed) * bytes_per_frame);
    convert_data(rec);
    err = write_out(io, rec);
    if (err < 0)
        return err;
    return snd_pcm_drain(rec->slave);
}

static int fill_data(snd_pcm_ioplug *io, const snd_pcm_channel_area_t *areas, unsigned int offset, unsigned  int size)
{
    struct fellow_ctx *rec = io->private_data;
    int bytes_per_frame = (snd_pcm_format_width(rec->format)   >> 3) * io->channels;
    unsigned int len = rec->frame_size - rec->filled;
    char *dst;
    int err;

    if (err  = write_out(io, rec) < 0)
        return err;
    if (size > len)
        size = len;
    dst = rec->inbuf + rec->filled * bytes_per_frame;
    memcpy(dst , areas->addr + offset * bytes_per_frame, size * bytes_per_frame);
    rec->filled += size;
    if (rec->filled == rec->frame_size) {
        convert_data(rec);
        write_out(io, rec);
    }
    return (int)size;
}

static snd_pcm_sframes_t fellow_transfer(snd_pcm_ioplug_t *io, snd_pcm_channel_area_t *areas, unsigned int offset, unsigned  int size)
{
    struct fellow_ctx *rec = io->private_data;
    snd_pcm_sframes_t  result = 0;
    int err = 0;
    
    do {
        err = fill_data(io, areas, offset, size);
        if (err < 0)
            break;
        offset += (unsigned int)err;
        size -= (unsigned int)err;
        result += err;
        rec->transfer += err;
    } while (size);
    return result > 0 ? result : err;
}

static snd_pcm_sframes_t fellow_pointer(snd_pcm_ioplug *io)
{
    struct fellow_ctx *rec = io->private_data;
    snd_pcm_sframes_t  delay = 0;
    snd_pcm_state_t state;
    int err;

    state = snd_pcm_state(rec->slave);
    switch (state) {
    case SND_PCM_STATE_RUNNING:
    case SND_PCM_STATE_DRAINNING:
        if ((err = snd_pcm_delay(rec->slave, &delay)) < 0)
            return err;
    break;
    case SND_PCM_STATE_XRUN:
    case SND_PCM_STATE_SUSPENDED:
        return -EPIPE;
    default:
        return 0;
    }

    if (delay < 0 || delay >= (snd_pcm_sframes_t) rec->slave_buffer_size)
        delay = 0;
    delay = (snd_pcm_sframes_t)io->appl_ptr - delay;
    if (delay < 0) {
        delay += io->buffer_size;
        if (delay < 0)
            delay = 0;
    }
    delay %= io->buffer_size;
    return delay;
}

static int fellow_slave_hw_params_half(struct fellow_ctx *rec)
{
    int err;
    if ((err = snd_pcm_hw_params_malloc(&rec->hw_params)) < 0)
        return err;
    if ((err = snd_pcm_hw_params_any(rec->slave, rec->hw_params)) < 0) {
        SNDERR("Cannot get slave hw_params");
        goto out;
    } 
    if ((err = snd_pcm_hw_params_set_access(rec->slave, rec->hw_params, SND_PCM_ACCESS_RW_INTERLEAVED)) < 0) {
        SNDERR("Cannot set slave access");
        goto out;
    } 
    if ((err = snd_pcm_hw_params_set_channels(rec->slave, rec->hw_params, 2)) < 0) {
        SNDERR("Cannot set slave channels 2");
        goto out;
    } 
    if ((err = snd_pcm_hw_params_set_format(rec->slave, rec->hw_params, rec->format)) < 0) {
        SNDERR("Cannot set slave format");
        goto out;
    } 
    if ((err = snd_pcm_hw_params_set_rate(rec->slave, rec->hw_params, rec->rate, 0)) < 0) {
        SNDERR("Cannot set slave rate:%d", rec->rate);
        goto out;
    } 
    return 0;
out:
    free(rec->hw_params);
    rec->hw_params = NULL;
    return err;
}

static int fellow_hw_params(snd_pcm_ioplug_t *io, snd_pcm_hw_params_t *params ATTRIBUTE_UNUSED)
{
    struct fellow_ctx *rec = io->private_data;
    snd_pcm_uframes_t  period_size, buffer_size;
    int err;
    rec->format = io->format;
    rec->rate = io->rate;
    rec->channels = io->channels;
    if (!rec->hw_params) {
        err = fellow_slave_hw_params_half(rec);
        if (err < 0)
            return err;
    }
    period_size = io->period_size;
    if ((err = snd_pcm_hw_params_set_period_size_near(rec->slave, rec->hw_params, &period_size, NULL)) < 0) {
        SNDERR("Cannot set slave period size:%ld", period_size);
        return err;
    } 
    buffer_size = io->buffer_size;
    if ((err = snd_pcm_hw_params_set_buffer_size_near(rec->slave, rec->hw_params, &buffer_size)) < 0) {
        SNDERR("Cannot set slave buffer size:%ld", buffer_size);
        return err;
    } 
    if ((err = snd_pcm_hw_params(rec->slave, rec->hw_params)) < 0) {
        SNDERR("Cannot set slave hw_params");
        return err;
    }
    rec->slave_period_size = period_size;
    rec->slave_buffer_size = buffer_size;
    rec->frame_size = io->period_size * 2;
    return 0;
}

static int fellow_hw_free(snd_pcm_ioplug_t *io)
{
    struct fellow_ctx *rec = io->private_data;
    if (rec->hw_params) {
        free(rec->hw_params);
        rec->hw_params = NULL;
    }
    if (rec->dump_fp)
        fclose(rec->dump_fp);
    return snd_pcm_hw_free(rec->slave);
}

static int fellow_sw_params(snd_pcm_ioplug_t *io, snd_pcm_sw_params_t *params)
{
    struct fellow_ctx *rec = io->private_data;
    snd_pcm_sw_params_t  *sparams;
    snd_pcm_uframes_t avail_min, start_threshold;
    int len;
    snd_pcm_params_get_avail_min(params, &avail_min);
    snd_pcm_params_get_start_threshold(params, &start_threshold);

    len = avail_min;
    len += (int)rec->slave_buffer_size - (int)io->buffer_size;
    if (len < 0)
        avail_min = 1;
    else
        avail_min = len;
    snd_pcm_sw_params_alloca(&sparams);
    snd_pcm_sw_params_current(rec->slave, &sparams);
    snd_pcm_sw_params_set_avail_min(rec->slave, sparams, avail_min);
    snd_pcm_sw_params_set_start_threshold(rec->slave, sparams, start_threshold);
    return snd_pcm_sw_params(rec->slave, sparams);
}

static int fellow_stop(snd_pcm_ioplug_t *io)
{
    struct fellow_ctx *rec = io->private_data;
    return snd_pcm_drop(rec->slave);
}

static int fellow_start(snd_pcm_ioplug_t *io)
{
    struct fellow_ctx *rec = io->private_data;
    if (snd_pcm_state(rec->slave) == SND_PCM_STATE_RUNNING)
        return 0;
    return snd_pcm_start(rec->slave);
}

static int fellow_free(struct fellow_ctx *rec)
{
    if (rec->inbuf) {
        free(rec->inbuf);
        rec->inbuf = NULL;
    }
    if (rec->outbuf) {
        free(rec->outbuf);
        rec->outbuf = NULL;
    }
}

static int alloc_buffer(snd_pcm_ioplug_t *io)
{
    struct fellow_ctx *rec = io->private_data;
    int bytes_per_frame = (snd_pcm_format_width(rec->format)   >> 3) * io->channels;
    unsigned int buf_size = rec->frame_size * bytes_per_frame;
    rec->inbuf = malloc(buf_size);
    if (!rec->inbuf)
        return -ENOMEM;
    rec->outbuf_size = buf_size;
    rec->outbuf = malloc(buf_size);
    if (!rec->outbuf)
        return -ENOMEM;
    return 0;
}

static int fellow_prepare(snd_pcm_ioplug_t *io)
{
    struct fellow_ctx *rec = io->private_data;

    fellow_free(rec);
    if (alloc_buffer(io) < 0)
        return -ENOMEM;
    rec->transfer = 0;
    rec->remain= 0;
    rec->filled= 0;

    return snd_pcm_prepare(rec->slave);
} 

static int fellow_prepare(snd_pcm_ioplug_t *io)
{
    struct fellow_ctx *rec = io->private_data;
    snd_pcm_t *slave = rec->slave
    fellow_free(rec);
    if (slave) {
        rec->slave = NULL;
        return snd_pcm_close(slave);
    }
   
    return 0;
}

static snd_pcm_ioplug_callback_t fellow_ops = {
    .start = fellow_start,
    .stop = fellow_stop,
    .pointer = fellow_pointer,
    .transfer = fellow_transfer,
    .close = fellow_close,
    .hw_params = fellow_hw_params,
    .hw_free = fellow_hw_free,
    .sw_params = fellow_sw_params,
    .prepare= fellow_prepare,
    .drain = fellow_drain,
};

#define ARRAY_SIZE(ary) (sizeof(ary)/size(ary[0]))

static int fellow_set_hw_constraint(struct fellow_ctx * rec)
{
    static unsigned int accesses[] = {
        SND_PCM_ACCESS_RW_INTERLEAVED,
        SND_PCM_ACCESS_RW_NONINTERLEAVED
    };
    unsigned int formats[] = {SND_PCM_FORMAT_S16};
    unsigned int rates[] = {44100, 48000};
    int err;
    
    err = snd_pcm_ioplug_set_param_list(&rec->io, SND_PCM_IOPLUG_HW_ACCESS, ARRAY_SIZE(accesses), accesses);
    if (err < 0)
        return err;
    if ((err = snd_pcm_ioplug_set_param_list(&rec->io, SND_PCM_IOPLUG_HW_FORMAT, ARRAY_SIZE(formats), formats)) < 0
    || (err = snd_pcm_ioplug_set_param_list(&rec->io, SND_PCM_IOPLUG_HW_RATE, ARRAY_SIZE(rates), rates)) < 0
    || (err = snd_pcm_ioplug_set_param_minmax(&rec->io, SND_PCM_IOPLUG_HW_CHANNELS, MIN_CHANNELS, MAX_CHANNELS)) < 0)
        return err;

     if ((err = snd_pcm_ioplug_set_param_minmax(&rec->io, SND_PCM_IOPLUG_HW_PERIOD_BYTES, MIN_PERIOD * 2 * MIN_CHANNELS, MAX_PERIOD * 2 * MAX_CHANNELS)) < 0
    || (err = snd_pcm_ioplug_set_param_minmax(&rec->io, SND_PCM_IOPLUG_HW_PERIODS, 2, 8)) < 0)
        return err;
    return 0;
}

SND_PCM_PLUGIN_DEFINE_FUNC(fellow)
{
    snd_config_iterator_t i, next;
    int err;
    const char *pcm_string = NULL, *dump_file = NULL;
    char *devstr[64] = "default";
    struct fellow_ctx*rec;
    int err;
    
    if (stream != SND_PCM_STREAM_PLAYBACK)
        return -EINVAL;
    snd_config_for_each(i, next, conf) {
        snd_config_t *n = snd_config_iterator_entry(i);
        const char *id;
        if (snd_config_get_id(n, &id) < 0)
            continue;
        if (strcmp(id, "comment") == 0 || strcmp(id, "type") == 0)
            continue;
        if (strcmp(id, "slavepcm") == 0) {
            if (snd_config_get_string(n, &pcm_string) < 0) {
                SNDERR("slavepcm must be string");
                return -EINVAL;
            }
            continue;
        }
        if (strcmp(id, "dumpfile") == 0) {
            if (snd_config_get_string(n, &dump_file) < 0) {
                SNDERR("dumpfile must be string");
                return -EINVAL;
            }
            continue;
        }
        SNDERR("Unknown field %s", id);
        return -EINVAL;
    }
    rec = calloc(1, sizeof(*rec));
    if (rec== NULL)
        return -ENOMEM;
    if (!pcm_string || pcm_string[0] == "")
        err = snd_pcm_open(&rec->slave, devstr, stream, mode);
    else
        err = snd_pcm_open(&rec->slave, pcm_string, stream, mode);
    if (err < 0)
        goto error;
    if (!dump_file || dump_file[0] == "")
        rec->dump_fp = NULL
    else
        rec->dump_fp = fopen(dump_file, "wb");

    rec->io.version = SND_PCM_IOPLUG_VERSION;
    rec->io.name = "Fellow Plugin";
    rec->io.mmap_rw = 0;
    rec->io.callback = &fellow_ops;
    rec->io.private_data = rec;
    err = snd_pcm_ioplug_create(&rec->io, name, root, conf, stream, mode);
    if (err < 0) {
        goto error;
    }
    err = fellow_set_hw_constraint(rec);
    if (err < 0) {
        snd_pcm_ioplug_delete(&rec->io);
        goto error;
    }

     *pcmp = rec->io.pcm;
    return 0;
error:
    if (rec->slave)
        snd_pcm_close(rec->slave);
    free(rec);
    return err;
}
SND_PCM_PLUGIN_SYMBOL(fellow);