This is an automated email from the ASF dual-hosted git repository.

xiaoxiang781216 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git

commit fb68221c0edd6968721b6f0cc29e0119b82b6737
Author: guliangzeng <[email protected]>
AuthorDate: Tue Nov 25 14:22:10 2025 +0800

    !audio: add a userdata member to struct ap_buffer_s
    
    An application that copies its own data blocks into apbs has to find
    the block again when AUDIO_MSG_DEQUEUE hands the apb back.  Without a
    field for it, the application keeps a table from apb to block that
    must match the buffer count and is searched on every dequeue.
    
    Add userdata for that purpose, and describe it in the audio
    documentation.  The audio subsystem never reads or writes it, and
    apb_alloc() clears it.
    
    BREAKING CHANGE: struct ap_buffer_s grows by one pointer.  No member
    moves, but code that lays out an apb itself, such as the callers of
    the i2schar read()/write() interface, no longer matches a kernel built
    with the other header.  Quick fix: rebuild the kernel and every
    application that includes nuttx/audio/audio.h.
    
    Signed-off-by: guliangzeng <[email protected]>
---
 Documentation/os/audio/index.rst | 6 ++++++
 include/nuttx/audio/audio.h      | 1 +
 2 files changed, 7 insertions(+)

diff --git a/Documentation/os/audio/index.rst b/Documentation/os/audio/index.rst
index 8008d800f52..cf95440c599 100644
--- a/Documentation/os/audio/index.rst
+++ b/Documentation/os/audio/index.rst
@@ -153,6 +153,12 @@ expressed in bytes; the format is a property of the 
stream, expressed as a rate.
 Their ratio only determines how much audio one buffer represents, and the audio
 subsystem does not constrain it.
 
+``struct ap_buffer_s`` has a ``userdata`` pointer that the audio subsystem
+never reads or writes, and that ``apb_alloc()`` clears.  An application that
+copies its own data blocks into apbs can store the block there before
+``AUDIOIOC_ENQUEUEBUFFER``, and get it back from the apb that
+``AUDIO_MSG_DEQUEUE`` returns, instead of keeping its own apb-to-block table.
+
 .. note::
    ``AUDIOIOC_GETBUFFERINFO`` is a query, but in the upper half it also records
    the reported buffer count for use as the shared ring depth.  A lower half
diff --git a/include/nuttx/audio/audio.h b/include/nuttx/audio/audio.h
index 55118d0e815..00dff6f8a72 100644
--- a/include/nuttx/audio/audio.h
+++ b/include/nuttx/audio/audio.h
@@ -788,6 +788,7 @@ struct ap_buffer_s
   uint16_t              flags;      /* Buffer flags */
   uint16_t              crefs;      /* Number of reference counts */
   FAR uint8_t           *samp;      /* Offset of the first sample */
+  FAR void              *userdata;  /* For the application, unused by the OS */
 };
 
 /* Structure defining the messages passed to a listening audio thread

Reply via email to