sound/pcm/buffer.c

/*-
 * SPDX-License-Identifier: BSD-2-Clause
 *
 * Copyright (c) 2005-2009 Ariff Abdullah <ariff@FreeBSD.org>
 * Portions Copyright (c) Ryan Beasley <ryan.beasley@gmail.com> - GSoC 2006
 * Copyright (c) 1999 Cameron Grant <cg@FreeBSD.org>
 * All rights reserved.
 * Copyright (c) 2025 The FreeBSD Foundation
 *
 * Portions of this software were developed by Christos Margiolis
 * <christos@FreeBSD.org> under sponsorship from the FreeBSD Foundation.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 */

#ifdef HAVE_KERNEL_OPTION_HEADERS
#include "opt_snd.h"
#endif

#include <sys/refcount.h>
#include <dev/sound/pcm/sound.h>

#include "feeder_if.h"

#define SND_USE_FXDIV
#define	SND_DECLARE_FXDIV
#include "snd_fxdiv_gen.h"

struct snd_dbuf *
sndbuf_create(struct pcm_channel *channel, uint32_t fmt, uint32_t spd,
    const char *desc)
{
	struct snd_dbuf *b;

	b = malloc(sizeof(*b), M_DEVBUF, M_WAITOK | M_ZERO);
	refcount_init(&b->refcount, 1);
	snprintf(b->name, SNDBUF_NAMELEN, "%s:%s", channel->name, desc);
	b->channel = channel;
	sndbuf_setfmt(b, fmt);
	sndbuf_setspd(b, spd);

	return b;
}

void
sndbuf_destroy(struct snd_dbuf *b)
{
	b->flags |= SNDBUF_F_DETACHED;
	sndbuf_rele(b);
}

void
sndbuf_ref(struct snd_dbuf *b)
{
	unsigned int count __diagused;

	CHN_LOCK(b->channel);
	count = refcount_acquire(&b->refcount);
	KASSERT(count > 0, ("sndbuf %p refcount 0", b));
	CHN_UNLOCK(b->channel);
}

void
sndbuf_rele(struct snd_dbuf *b)
{
	if (refcount_release(&b->refcount)) {
		sndbuf_free(b);
		KASSERT(refcount_load(&b->refcount) == 0,
		    ("sndbuf %p still referenced", b));
		free(b, M_DEVBUF);
	}
}

static bool
sndbuf_busy(struct snd_dbuf *b)
{
	CHN_LOCKASSERT(b->channel);

	return (refcount_load(&b->refcount) > 1 ||
	    (b->flags & SNDBUF_F_DETACHED) != 0 ||
	    /*
	     * XXX-MJ CHN_F_MMAP is not reliable, but for software buffers the
	     * refcount accurately reflects whether the buffer is mapped.
	     * Ensure that there is no in-flight DMA transfer by checking
	     * CHN_F_TRIGGERED.  This should really be checked at a higher
	     * layer, but this is tricky since chn_resizebuf() and
	     * sndbuf_resize() drop and reacquire the channel lock.
	     */
	    (b->channel->flags & (CHN_F_MMAP | CHN_F_TRIGGERED)) != 0);
}

static void
sndbuf_setmap(void *arg, bus_dma_segment_t *segs, int nseg, int error)
{
	struct snd_dbuf *b = (struct snd_dbuf *)arg;

	if (snd_verbose > 3) {
		printf("sndbuf_setmap %lx, %lx; ",
		    (unsigned long)segs[0].ds_addr,
		    (unsigned long)segs[0].ds_len);
		printf("%p -> %lx\n", b->buf, (unsigned long)segs[0].ds_addr);
	}
	if (error == 0)
		b->buf_addr = segs[0].ds_addr;
	else
		b->buf_addr = 0;
}

/*
 * Allocate memory for DMA buffer. If the device does not use DMA transfers,
 * the driver can call malloc(9) and sndbuf_setup() itself.
 */

int
sndbuf_alloc(struct snd_dbuf *b, bus_dma_tag_t dmatag, int dmaflags,
    unsigned int size)
{
	int ret;

	b->dmatag = dmatag;
	b->dmaflags = dmaflags | BUS_DMA_NOWAIT | BUS_DMA_COHERENT;
	b->maxsize = size;
	b->bufsize = b->maxsize;
	b->buf_addr = 0;
	b->flags |= SNDBUF_F_MANAGED;
	if (bus_dmamem_alloc(b->dmatag, (void **)&b->buf, b->dmaflags,
	    &b->dmamap)) {
		sndbuf_free(b);
		return (ENOMEM);
	}
	if (bus_dmamap_load(b->dmatag, b->dmamap, b->buf, b->maxsize,
	    sndbuf_setmap, b, BUS_DMA_NOWAIT) != 0 || b->buf_addr == 0) {
		sndbuf_free(b);
		return (ENOMEM);
	}

	ret = sndbuf_resize(b, 2, b->maxsize / 2);
	if (ret != 0)
		sndbuf_free(b);

	return (ret);
}

int
sndbuf_setup(struct snd_dbuf *b, void *buf, unsigned int size)
{
	b->flags &= ~SNDBUF_F_MANAGED;
	if (buf)
		b->flags |= SNDBUF_F_MANAGED;
	b->buf = buf;
	b->maxsize = size;
	b->bufsize = b->maxsize;
	return sndbuf_resize(b, 2, b->maxsize / 2);
}

void
sndbuf_free(struct snd_dbuf *b)
{
	free(b->tmpbuf, M_DEVBUF);
	free(b->shadbuf, M_DEVBUF);

	if (b->buf) {
		if (b->flags & SNDBUF_F_MANAGED) {
			if (b->buf_addr)
				bus_dmamap_unload(b->dmatag, b->dmamap);
			if (b->dmatag)
				bus_dmamem_free(b->dmatag, b->buf, b->dmamap);
		} else
			free(b->buf, M_DEVBUF);
	}
	seldrain(&b->sel);

	b->tmpbuf = NULL;
	b->shadbuf = NULL;
	b->buf = NULL;
	b->sl = 0;
	b->dmatag = NULL;
	b->dmamap = NULL;
}

#define SNDBUF_CACHE_SHIFT	5

int
sndbuf_resize(struct snd_dbuf *b, unsigned int blkcnt, unsigned int blksz)
{
	unsigned int bufsize, allocsize;
	uint8_t *tmpbuf;

	CHN_LOCK(b->channel);
	if (b->maxsize == 0)
		goto out;
	if (blkcnt == 0)
		blkcnt = b->blkcnt;
	if (blksz == 0)
		blksz = b->blksz;
	if (blkcnt < 2 || blksz < 16 || (blkcnt * blksz) > b->maxsize) {
		CHN_UNLOCK(b->channel);
		return EINVAL;
	}
	if (blkcnt == b->blkcnt && blksz == b->blksz)
		goto out;

	bufsize = blkcnt * blksz;

	if (bufsize > b->allocsize ||
	    bufsize < (b->allocsize >> SNDBUF_CACHE_SHIFT)) {
		if (sndbuf_busy(b)) {
			CHN_UNLOCK(b->channel);
			return (EBUSY);
		}
		allocsize = round_page(bufsize);
		CHN_UNLOCK(b->channel);
		tmpbuf = malloc(allocsize, M_DEVBUF, M_WAITOK);
		CHN_LOCK(b->channel);
		if (sndbuf_busy(b)) {
			CHN_UNLOCK(b->channel);
			free(tmpbuf, M_DEVBUF);
			return (EBUSY);
		}
		if (snd_verbose > 3)
			printf("%s(): b=%p %p -> %p [%d -> %d : %d]\n",
			    __func__, b, b->tmpbuf, tmpbuf,
			    b->allocsize, allocsize, bufsize);
		free(b->tmpbuf, M_DEVBUF);
		b->tmpbuf = tmpbuf;
		b->allocsize = allocsize;
	} else if (snd_verbose > 3)
		printf("%s(): b=%p %d [%d] NOCHANGE\n",
		    __func__, b, b->allocsize, b->bufsize);

	b->blkcnt = blkcnt;
	b->blksz = blksz;
	b->bufsize = bufsize;

	sndbuf_reset(b);
out:
	CHN_UNLOCK(b->channel);
	return 0;
}

int
sndbuf_remalloc(struct snd_dbuf *b, unsigned int blkcnt, unsigned int blksz)
{
        unsigned int bufsize, allocsize;
	uint8_t *buf, *tmpbuf, *shadbuf;

	if (blkcnt < 2 || blksz < 16)
		return EINVAL;

	CHN_LOCKASSERT(b->channel);

	bufsize = blksz * blkcnt;

	if (bufsize > b->allocsize ||
	    bufsize < (b->allocsize >> SNDBUF_CACHE_SHIFT)) {
		if (sndbuf_busy(b))
			return (EBUSY);
		allocsize = round_page(bufsize);
		CHN_UNLOCK(b->channel);
		buf = malloc(allocsize, M_DEVBUF, M_WAITOK);
		tmpbuf = malloc(allocsize, M_DEVBUF, M_WAITOK);
		shadbuf = malloc(allocsize, M_DEVBUF, M_WAITOK);
		CHN_LOCK(b->channel);
		if (sndbuf_busy(b)) {
			free(buf, M_DEVBUF);
			free(tmpbuf, M_DEVBUF);
			free(shadbuf, M_DEVBUF);
			return (EBUSY);
		}
		free(b->buf, M_DEVBUF);
		b->buf = buf;
		free(b->tmpbuf, M_DEVBUF);
		b->tmpbuf = tmpbuf;
		free(b->shadbuf, M_DEVBUF);
		b->shadbuf = shadbuf;
		if (snd_verbose > 3)
			printf("%s(): b=%p %d -> %d [%d]\n",
			    __func__, b, b->allocsize, allocsize, bufsize);
		b->allocsize = allocsize;
	} else if (snd_verbose > 3)
		printf("%s(): b=%p %d [%d] NOCHANGE\n",
		    __func__, b, b->allocsize, b->bufsize);

	b->blkcnt = blkcnt;
	b->blksz = blksz;
	b->bufsize = bufsize;
	b->maxsize = bufsize;
	b->sl = bufsize;

	sndbuf_reset(b);

	return 0;
}

/**
 * @brief Zero out space in buffer free area
 *
 * This function clears a chunk of @c length bytes in the buffer free area
 * (i.e., where the next write will be placed).
 *
 * @param b		buffer context
 * @param length	number of bytes to blank
 */
void
sndbuf_clear(struct snd_dbuf *b, unsigned int length)
{
	int i;
	uint8_t data, *p;

	if (length == 0)
		return;
	if (length > b->bufsize)
		length = b->bufsize;

	data = sndbuf_zerodata(b->fmt);
	i = sndbuf_getfreeptr(b);
	p = b->buf;
	for  (; length > 0; length--, i++)
		p[i % b->bufsize] = data;
}

/**
 * @brief Zap buffer contents, resetting "ready area" fields
 *
 * @param b	buffer context
 */
void
sndbuf_fillsilence(struct snd_dbuf *b)
{
	if (b->bufsize > 0)
		memset(b->buf, sndbuf_zerodata(b->fmt), b->bufsize);
	b->rp = 0;
	b->rl = b->bufsize;
}

void
sndbuf_fillsilence_rl(struct snd_dbuf *b, unsigned int rl)
{
	if (b->bufsize > 0)
		memset(b->buf, sndbuf_zerodata(b->fmt), b->bufsize);
	b->rp = 0;
	b->rl = min(b->bufsize, rl);
}

/**
 * @brief Reset buffer w/o flushing statistics
 *
 * This function just zeroes out buffer contents and sets the "ready length"
 * to zero.  This was originally to facilitate minimal playback interruption
 * (i.e., dropped samples) in SNDCTL_DSP_SILENCE/SKIP ioctls.
 *
 * @param b	buffer context
 */
void
sndbuf_softreset(struct snd_dbuf *b)
{
	b->rl = 0;
	if (b->buf && b->bufsize > 0)
		sndbuf_clear(b, b->bufsize);
}

void
sndbuf_reset(struct snd_dbuf *b)
{
	b->hp = 0;
	b->rp = 0;
	b->rl = 0;
	b->dl = 0;
	b->prev_total = 0;
	b->total = 0;
	b->xrun = 0;
	if (b->buf && b->bufsize > 0)
		sndbuf_clear(b, b->bufsize);
	sndbuf_clearshadow(b);
}

int
sndbuf_setfmt(struct snd_dbuf *b, uint32_t fmt)
{
	b->fmt = fmt;
	b->bps = AFMT_BPS(b->fmt);
	b->align = AFMT_ALIGN(b->fmt);
	return 0;
}

void
sndbuf_setspd(struct snd_dbuf *b, unsigned int spd)
{
	b->spd = spd;
}

void *
sndbuf_getbufofs(struct snd_dbuf *b, unsigned int ofs)
{
	KASSERT(ofs < b->bufsize, ("%s: ofs invalid %d", __func__, ofs));

	return b->buf + ofs;
}

unsigned int
sndbuf_runsz(struct snd_dbuf *b)
{
	return b->dl;
}

void
sndbuf_setrun(struct snd_dbuf *b, int go)
{
	b->dl = go? b->blksz : 0;
}

void
sndbuf_setxrun(struct snd_dbuf *b, unsigned int xrun)
{
	b->xrun = xrun;
}

unsigned int
sndbuf_getready(struct snd_dbuf *b)
{
	KASSERT((b->rl >= 0) && (b->rl <= b->bufsize), ("%s: b->rl invalid %d", __func__, b->rl));

	return b->rl;
}

unsigned int
sndbuf_getreadyptr(struct snd_dbuf *b)
{
	KASSERT((b->rp >= 0) && (b->rp <= b->bufsize), ("%s: b->rp invalid %d", __func__, b->rp));

	return b->rp;
}

unsigned int
sndbuf_getfree(struct snd_dbuf *b)
{
	KASSERT((b->rl >= 0) && (b->rl <= b->bufsize), ("%s: b->rl invalid %d", __func__, b->rl));

	return b->bufsize - b->rl;
}

unsigned int
sndbuf_getfreeptr(struct snd_dbuf *b)
{
	KASSERT((b->rp >= 0) && (b->rp <= b->bufsize), ("%s: b->rp invalid %d", __func__, b->rp));
	KASSERT((b->rl >= 0) && (b->rl <= b->bufsize), ("%s: b->rl invalid %d", __func__, b->rl));

	return (b->rp + b->rl) % b->bufsize;
}

uint64_t
sndbuf_getblocks(struct snd_dbuf *b)
{
	return b->total / b->blksz;
}

unsigned int
sndbuf_xbytes(unsigned int v, struct snd_dbuf *from, struct snd_dbuf *to)
{
	if (from == NULL || to == NULL || v == 0)
		return 0;

	return snd_xbytes(v, from->align * from->spd, to->align * to->spd);
}

uint8_t
sndbuf_zerodata(uint32_t fmt)
{
	if (fmt & (AFMT_SIGNED | AFMT_PASSTHROUGH))
		return (0x00);
	else if (fmt & AFMT_MU_LAW)
		return (0x7f);
	else if (fmt & AFMT_A_LAW)
		return (0x55);
	return (0x80);
}

/************************************************************/

/**
 * @brief Acquire buffer space to extend ready area
 *
 * This function extends the ready area length by @c count bytes, and may
 * optionally copy samples from another location stored in @c from.  The
 * counter @c snd_dbuf::total is also incremented by @c count bytes.
 *
 * @param b	audio buffer
 * @param from	sample source (optional)
 * @param count	number of bytes to acquire
 *
 * @retval 0	Unconditional
 */
int
sndbuf_acquire(struct snd_dbuf *b, uint8_t *from, unsigned int count)
{
	int l;

	KASSERT(count <= sndbuf_getfree(b), ("%s: count %d > free %d", __func__, count, sndbuf_getfree(b)));
	KASSERT((b->rl >= 0) && (b->rl <= b->bufsize), ("%s: b->rl invalid %d", __func__, b->rl));
	b->total += count;
	if (from != NULL) {
		while (count > 0) {
			l = min(count, b->bufsize - sndbuf_getfreeptr(b));
			bcopy(from, sndbuf_getbufofs(b, sndbuf_getfreeptr(b)), l);
			from += l;
			b->rl += l;
			count -= l;
		}
	} else
		b->rl += count;
	KASSERT((b->rl >= 0) && (b->rl <= b->bufsize), ("%s: b->rl invalid %d, count %d", __func__, b->rl, count));

	return 0;
}

/**
 * @brief Dispose samples from channel buffer, increasing size of ready area
 *
 * This function discards samples from the supplied buffer by advancing the
 * ready area start pointer and decrementing the ready area length.  If
 * @c to is not NULL, then the discard samples will be copied to the location
 * it points to.
 *
 * @param b	PCM channel sound buffer
 * @param to	destination buffer (optional)
 * @param count	number of bytes to discard
 *
 * @returns 0 unconditionally
 */
int
sndbuf_dispose(struct snd_dbuf *b, uint8_t *to, unsigned int count)
{
	int l;

	KASSERT(count <= sndbuf_getready(b), ("%s: count %d > ready %d", __func__, count, sndbuf_getready(b)));
	KASSERT((b->rl >= 0) && (b->rl <= b->bufsize), ("%s: b->rl invalid %d", __func__, b->rl));
	if (to != NULL) {
		while (count > 0) {
			l = min(count, b->bufsize - sndbuf_getreadyptr(b));
			bcopy(sndbuf_getbufofs(b, sndbuf_getreadyptr(b)), to, l);
			to += l;
			b->rl -= l;
			b->rp = (b->rp + l) % b->bufsize;
			count -= l;
		}
	} else {
		b->rl -= count;
		b->rp = (b->rp + count) % b->bufsize;
	}
	KASSERT((b->rl >= 0) && (b->rl <= b->bufsize), ("%s: b->rl invalid %d, count %d", __func__, b->rl, count));

	return 0;
}

/* count is number of bytes we want added to destination buffer */
int
sndbuf_feed(struct snd_dbuf *from, struct snd_dbuf *to, struct pcm_channel *channel, struct pcm_feeder *feeder, unsigned int count)
{
	unsigned int cnt, maxfeed;

	KASSERT(count > 0, ("can't feed 0 bytes"));

	if (sndbuf_getfree(to) < count)
		return (EINVAL);

	maxfeed = SND_FXROUND(SND_FXDIV_MAX, to->align);

	do {
		cnt = FEEDER_FEED(feeder, channel, to->tmpbuf,
		    min(count, maxfeed), from);
		if (cnt == 0)
			break;
		sndbuf_acquire(to, to->tmpbuf, cnt);
		count -= cnt;
	} while (count != 0);

	return (0);
}

/**
 * @brief Clear the shadow buffer by filling with samples equal to zero.
 *
 * @param b buffer to clear
 */
void
sndbuf_clearshadow(struct snd_dbuf *b)
{
	KASSERT(b != NULL, ("b is a null pointer"));
	KASSERT(b->sl >= 0, ("illegal shadow length"));

	if ((b->shadbuf != NULL) && (b->sl > 0))
		memset(b->shadbuf, sndbuf_zerodata(b->fmt), b->sl);
}

#ifdef OSSV4_EXPERIMENT
/**
 * @brief Return peak value from samples in buffer ready area.
 *
 * Peak ranges from 0-32767.  If channel is monaural, most significant 16
 * bits will be zero.  For now, only expects to work with 1-2 channel
 * buffers.
 *
 * @note  Currently only operates with linear PCM formats.
 *
 * @param b buffer to analyze
 * @param lpeak pointer to store left peak value
 * @param rpeak pointer to store right peak value
 */
void
sndbuf_getpeaks(struct snd_dbuf *b, int *lp, int *rp)
{
	uint32_t lpeak, rpeak;

	lpeak = 0;
	rpeak = 0;

	/**
	 * @todo fill this in later
	 */
}
#endif