firmware: Implement the remaining audio buffer functions.

hackamp/firmware/src/audio_buffer.rs

@@ -1,3 +1,4 @@
+//! Audio buffer type to transfer audio data within different software/hardware components.
 #![warn(missing_docs)]
 
 use core::cell::{Cell, UnsafeCell};
@@ -8,9 +9,12 @@ use cortex_m::interrupt::{CriticalSection, Mutex};
 ///
 /// This translates two twice the number of values, as each sample contains two channels.
 pub const SAMPLES_PER_PACKET: usize = 48;
+/// Number of channels for all audio data.
 pub const CHANNELS: usize = 2;
+/// Number of packets that can be stored in each `AudioBuffer`.
 pub const PACKETS: usize = 3;
 
+/// Buffer for a single packet with audio data.
 pub type Packet = [u32; SAMPLES_PER_PACKET * CHANNELS];
 
 /// Type for audio packet buffering.
@@ -57,11 +61,16 @@ impl AudioBuffer {
     }
 
     /// Returns whether there are any buffers with valid data ready for reading.
-    pub fn read_data_available(&self, cs: &CriticalSection) -> bool {
+    pub fn can_read(&self, cs: &CriticalSection) -> bool {
         let inner = self.mutex.borrow(cs);
         inner.valid.get() != 0
     }
 
+    /// Borrows a single buffer for reading, returns `None` if no buffer with valid data is
+    /// available.
+    ///
+    /// The caller needs to return the buffer via `read_finished()` once the data has been
+    /// processed.
     pub fn borrow_read(&'static self, cs: &CriticalSection) -> Option<ReadPacket> {
         let inner = self.mutex.borrow(cs);
         let valid = inner.valid.get();
@@ -80,17 +89,24 @@ impl AudioBuffer {
         })
     }
 
-    pub fn read_finished(&'static self, _packet: ReadPacket, _cs: &CriticalSection) {
-        // TODO
-        panic!("Not yet implemented.");
+    /// Returns a buffer that was allocated via `borrow_read()` and marks it as empty.
+    pub fn read_finished(&'static self, packet: ReadPacket, cs: &CriticalSection) {
+        assert!((self as *const _) == (packet.buffer as *const _));
+        let inner = self.mutex.borrow(cs);
+        let index = packet.index;
+        inner.reading.set(inner.reading.get() & !(1 << index));
+        inner.invalid.set(inner.invalid.get() | (1 << index));
     }
 
     /// Returns whether there are any empty buffers ready for writing.
-    pub fn write_data_available(&self, cs: &CriticalSection) -> bool {
+    pub fn can_write(&self, cs: &CriticalSection) -> bool {
         let inner = self.mutex.borrow(cs);
         inner.invalid.get() != 0
     }
 
+    /// Borrows a single buffer for writing, returns `None` if no empty buffer is available.
+    ///
+    /// The caller needs to return the buffer via `write_finished()` once it was filled with data.
     pub fn borrow_write(&'static self, cs: &CriticalSection) -> Option<WritePacket> {
         let inner = self.mutex.borrow(cs);
         let invalid = inner.invalid.get();
@@ -109,20 +125,44 @@ impl AudioBuffer {
         })
     }
 
-    pub fn write_finished(&'static self, _packet: WritePacket, _cs: &CriticalSection) {
-        // TODO
-        panic!("Not yet implemented.");
+    /// Returns a buffer that was allocated via `borrow_write()` and marks it as ready for reading.
+    pub fn write_finished(&'static self, packet: WritePacket, cs: &CriticalSection) {
+        assert!((self as *const _) == (packet.buffer as *const _));
+        let inner = self.mutex.borrow(cs);
+        let index = packet.index;
+        inner.writing.set(inner.writing.get() & !(1 << index));
+        inner.valid.set(inner.valid.get() | (1 << index));
     }
 }
 
+/// Packet buffer that has been borrowed for reading (i.e., the buffer contains valid data).
 pub struct ReadPacket {
     buffer: &'static AudioBuffer,
     data: &'static Packet,
     index: usize,
 }
 
+impl AsRef<[u32]> for ReadPacket {
+    fn as_ref(&self) -> &[u32] {
+        self.data
+    }
+}
+
+/// Packet buffer that has been borrowed for writing (i.e., the buffer was previously empty).
 pub struct WritePacket {
     buffer: &'static AudioBuffer,
     data: &'static mut Packet,
     index: usize,
 }
+
+impl AsRef<[u32]> for WritePacket {
+    fn as_ref(&self) -> &[u32] {
+        self.data
+    }
+}
+
+impl AsMut<[u32]> for WritePacket {
+    fn as_mut(&mut self) -> &mut [u32] {
+        self.data
+    }
+}