VSF中的流模块

流模块单独分出来讲是因为内容相对比较多，而且也有一定难度。流模块可以对应数据的生产者/消费者模型，生产者可以向流里写数据（生产数据），消费者从流里读取数据（消费数据）。并且，通过回调接口，可以实现自动流控。VSF中的流模块的实现，也可以用来阐述面向对象的编程思想，因为流只是一个抽象类，实际使用的是具体的fifo流、buffer流或者multibuf流等具体内存结构实现的流。所以，流只是一个标准接口，如果一个模块支持流接口的话，就可以很方便的和其他支持流接口的模块对接。比如，wave播放模块的输入流，可以接到文件流，对应播放本地的wav文件；也可以接到http流，对用播放网上的wav文件，而wave播放模块并不需要在意流的来源。

下面介绍一下流的接口，和实现自动流控的原理：

struct vsf_stream_cb_t
{
    void *param;
    void (*on_inout)(void *param);
    void (*on_connect)(void *param);
    void (*on_disconnect)(void *param);
};

struct vsf_stream_t
{
    // user_mem points to user structure, eg queue/fifo
    struct vsf_stream_op_t const *op;

    // callback_tx is notification for tx end of the stream
    // when rx end read the data out, will notify the tx end
    struct vsf_stream_cb_t callback_tx;
    // callback_rx is notification for rx end of the stream
    // when tx end write the data in, will notify the rx end
    struct vsf_stream_cb_t callback_rx;
    bool tx_ready;
    bool rx_ready;
    bool overflow;
};

vsf_err_t stream_init(struct vsf_stream_t *stream);
vsf_err_t stream_fini(struct vsf_stream_t *stream);
uint32_t stream_write(struct vsf_stream_t *stream, struct vsf_buffer_t *buffer);
uint32_t stream_read(struct vsf_stream_t *stream, struct vsf_buffer_t *buffer);
uint32_t stream_get_data_size(struct vsf_stream_t *stream);
uint32_t stream_get_free_size(struct vsf_stream_t *stream);
uint32_t stream_get_wbuf(struct vsf_stream_t *stream, uint8_t **ptr);
uint32_t stream_get_rbuf(struct vsf_stream_t *stream, uint8_t **ptr);
void stream_connect_rx(struct vsf_stream_t *stream);
void stream_connect_tx(struct vsf_stream_t *stream);
void stream_disconnect_rx(struct vsf_stream_t *stream);
void stream_disconnect_tx(struct vsf_stream_t *stream);

上面是流的数据结构，和操作接口。初始化和读写函数一看就能明白，stream_get_data_size是得到流里的数据大小，stream_get_free_size是得到流里的空余空间大小。stream_get_wbuf和stream_get_rbuf用于得到当前的读写指针，只在非常特殊的情况下使用。stream_connect_XX和stream_disconnect_XX是流的接收或者发送端的连接或者断开。vsf_stream_t中，callback_XX是接收或者发送端设置的回调函数，当流的一端连接/断开/读写数据的时候，通过回调接口通知流的另一端。

基于callback，就可以实现流控，生产者写入数据到流的时候，会通知消费者去消费数据；消费者消费了数据的时候，也会通知生产者。生产者可以通过stream_get_free_size来得到流里空余空间的小大，只有大于生产者一次可产生的数据的时候（比如对于全速USB，就是64字节的最大ep大小），生产者才会产生数据。如果空余空间不够的话，生产者只需要等待消费者消费数据后，再次通知生产者，然后生产者再判断是否有足够的空余空间。当然，实现流控的前提是生产者可以控制数据的产生。

流的实现：

uint32_t stream_read(struct vsf_stream_t *stream, struct vsf_buffer_t *buffer)
{
    uint32_t count = stream->op->read(stream, buffer);

    if (stream->tx_ready && (stream->callback_tx.on_inout != NULL) && count)
    {
        stream->callback_tx.on_inout(stream->callback_tx.param);
    }
    return count;
}

uint32_t stream_write(struct vsf_stream_t *stream, struct vsf_buffer_t *buffer)
{
    uint32_t count = stream->op->write(stream, buffer);

    if (count < buffer->size)
    {
        stream->overflow = true;
    }
    if (stream->rx_ready && (stream->callback_rx.on_inout != NULL) && count)
    {
        stream->callback_rx.on_inout(stream->callback_rx.param);
    }
    return count;
}

这里只是简单用读写接口举例，实际的读写操作，有op参数里指定的读写接口实现。代码里，也只是简单调用op指定的读写接口，然后判断是否溢出以及是否需要调用回调接口。

流结构中，并没有指定缓冲的数据结构，因为应用可以根据实际应用需求，来选择缓冲类型。这里用最常用的fifo流来举例：

struct vsf_fifostream_t
{
    struct vsf_stream_t stream;
    struct vsf_fifo_t mem;
};

static void fifo_stream_init(struct vsf_stream_t *stream)
{
    struct vsf_fifostream_t *fifostream = (struct vsf_fifostream_t *)stream;
    vsf_fifo_init(&fifostream->mem);
}

static uint32_t fifo_stream_get_data_length(struct vsf_stream_t *stream)
{
    struct vsf_fifostream_t *fifostream = (struct vsf_fifostream_t *)stream;
    return vsf_fifo_get_data_length(&fifostream->mem);
}

static uint32_t
fifo_stream_write(struct vsf_stream_t *stream, struct vsf_buffer_t *buffer)
{
    struct vsf_fifostream_t *fifostream = (struct vsf_fifostream_t *)stream;
    return vsf_fifo_push(&fifostream->mem, buffer->size, buffer->buffer);
}

static uint32_t
fifo_stream_read(struct vsf_stream_t *stream, struct vsf_buffer_t *buffer)
{
    struct vsf_fifostream_t *fifostream = (struct vsf_fifostream_t *)stream;
    return vsf_fifo_pop(&fifostream->mem, buffer->size, buffer->buffer);
}

const struct vsf_stream_op_t fifostream_op =
{
    .init = fifo_stream_init,
    .fini = fifo_stream_init,
    .write = fifo_stream_write,
    .read = fifo_stream_read,
    .get_data_length = fifo_stream_get_data_length,
    .get_avail_length = fifo_stream_get_avail_length,
    .get_wbuf = fifo_stream_get_wbuf,
    .get_rbuf = fifo_stream_get_rbuf,
};

这里只是列举了几个函数。fifo流继承自vsf_stream_t，并且指定了fifo的缓冲类型。fifostream_op里指定了fifo流的各种操作接口，实际实现只是简单调用fifo模块的对应接口。可以把vsf_fifostream_t强制类型转换为vsf_stream_t，就可以使用标准的流接口了。实际可以通过宏来实现各种不同类型的流的强制转换：

#define STREAM_INIT(s)          stream_init((struct vsf_stream_t *)(s))
#define STREAM_FINI(s)          stream_fini((struct vsf_stream_t *)(s))
#define STREAM_WRITE(s, b)      stream_write((struct vsf_stream_t *)(s), (b))
#define STREAM_READ(s, b)       stream_read((struct vsf_stream_t *)(s), (b))
#define STREAM_GET_DATA_SIZE(s) stream_get_data_size((struct vsf_stream_t *)(s))
#define STREAM_GET_FREE_SIZE(s) stream_get_free_size((struct vsf_stream_t *)(s))
#define STREAM_GET_WBUF(s, p)   stream_get_wbuf((struct vsf_stream_t *)(s), (p))
#define STREAM_GET_RBUF(s, p)   stream_get_rbuf((struct vsf_stream_t *)(s), (p))
#define STREAM_CONNECT_RX(s)    stream_connect_rx((struct vsf_stream_t *)(s))
#define STREAM_CONNECT_TX(s)    stream_connect_tx((struct vsf_stream_t *)(s))
#define STREAM_DISCONNECT_RX(s) stream_disconnect_rx((struct vsf_stream_t *)(s))
#define STREAM_DISCONNECT_TX(s) stream_disconnect_tx((struct vsf_stream_t *)(s))

和标准接口只是大小写的区别。