Skip to content

Commit

Permalink
extmod/machine_i2s: Factor comments, some enums and macros.
Browse files Browse the repository at this point in the history
Signed-off-by: Damien George <damien@micropython.org>
  • Loading branch information
dpgeorge committed Oct 20, 2023
1 parent 46ae3b5 commit 91a3f18
Show file tree
Hide file tree
Showing 5 changed files with 52 additions and 188 deletions.
46 changes: 46 additions & 0 deletions extmod/machine_i2s.c
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,52 @@

#include "extmod/modmachine.h"

// The I2S class has 3 modes of operation:
//
// Mode1: Blocking
// - readinto() and write() methods block until the supplied buffer is filled (read) or emptied (write)
// - this is the default mode of operation
//
// Mode2: Non-Blocking
// - readinto() and write() methods return immediately
// - buffer filling and emptying happens asynchronously to the main MicroPython task
// - a callback function is called when the supplied buffer has been filled (read) or emptied (write)
// - non-blocking mode is enabled when a callback is set with the irq() method
// - implementation of asynchronous background operations is port specific
//
// Mode3: Asyncio
// - implements the stream protocol
// - asyncio mode is enabled when the ioctl() function is called
// - the state of the internal ring buffer is used to detect that I2S samples can be read or written
//
// The samples contained in the app buffer supplied for the readinto() and write() methods have the following convention:
// Mono: little endian format
// Stereo: little endian format, left channel first
//
// I2S terms:
// "frame": consists of two audio samples (Left audio sample + Right audio sample)
//
// Misc:
// - for Mono configuration:
// - readinto method: samples are gathered from the L channel only
// - write method: every sample is output to both the L and R channels
// - for readinto method the I2S hardware is read using 8-byte frames
// (this is standard for almost all I2S hardware, such as MEMS microphones)

#define NUM_I2S_USER_FORMATS (4)
#define I2S_RX_FRAME_SIZE_IN_BYTES (8)

typedef enum {
MONO,
STEREO
} format_t;

typedef enum {
BLOCKING,
NON_BLOCKING,
ASYNCIO
} io_mode_t;

// Arguments for I2S() constructor and I2S.init().
enum {
ARG_sck,
Expand Down
49 changes: 1 addition & 48 deletions ports/esp32/machine_i2s.c
Original file line number Diff line number Diff line change
Expand Up @@ -29,47 +29,16 @@

#include "py/mphal.h"

#if MICROPY_PY_MACHINE_I2S

#include "driver/i2s.h"
#include "soc/i2s_reg.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/queue.h"
#include "esp_task.h"

// The I2S module has 3 modes of operation:
//
// Mode1: Blocking
// - readinto() and write() methods block until the supplied buffer is filled (read) or emptied (write)
// - this is the default mode of operation
//
// Mode2: Non-Blocking
// - readinto() and write() methods return immediately.
// - buffer filling and emptying happens asynchronously to the main MicroPython task
// - a callback function is called when the supplied buffer has been filled (read) or emptied (write)
// - non-blocking mode is enabled when a callback is set with the irq() method
// Notes on this port's specific implementation of I2S:
// - a FreeRTOS task is created to implement the asynchronous background operations
// - a FreeRTOS queue is used to transfer the supplied buffer to the background task
//
// Mode3: Asyncio
// - implements the stream protocol
// - asyncio mode is enabled when the ioctl() function is called
// - the I2S event queue is used to detect that I2S samples can be read or written from/to DMA memory
//
// The samples contained in the app buffer supplied for the readinto() and write() methods have the following convention:
// Mono: little endian format
// Stereo: little endian format, left channel first
//
// I2S terms:
// "frame": consists of two audio samples (Left audio sample + Right audio sample)
//
// Misc:
// - for Mono configuration:
// - readinto method: samples are gathered from the L channel only
// - write method: every sample is output to both the L and R channels
// - for readinto method the I2S hardware is read using 8-byte frames
// (this is standard for almost all I2S hardware, such as MEMS microphones)
// - all sample data transfers use DMA

#define I2S_TASK_PRIORITY (ESP_TASK_PRIO_MIN + 1)
Expand All @@ -82,20 +51,6 @@
// The size of 240 bytes is an engineering optimum that balances transfer performance with an acceptable use of heap space
#define SIZEOF_TRANSFORM_BUFFER_IN_BYTES (240)

#define NUM_I2S_USER_FORMATS (4)
#define I2S_RX_FRAME_SIZE_IN_BYTES (8)

typedef enum {
MONO,
STEREO
} format_t;

typedef enum {
BLOCKING,
NON_BLOCKING,
ASYNCIO
} io_mode_t;

typedef enum {
I2S_TX_TRANSFER,
I2S_RX_TRANSFER,
Expand Down Expand Up @@ -510,5 +465,3 @@ STATIC void mp_machine_i2s_irq_update(machine_i2s_obj_t *self) {
}

MP_REGISTER_ROOT_POINTER(struct _machine_i2s_obj_t *machine_i2s_obj[I2S_NUM_AUTO]);

#endif // MICROPY_PY_MACHINE_I2S
49 changes: 2 additions & 47 deletions ports/mimxrt/machine_i2s.c
Original file line number Diff line number Diff line change
Expand Up @@ -37,38 +37,8 @@
#include "fsl_edma.h"
#include "fsl_sai.h"

#if MICROPY_PY_MACHINE_I2S
// The I2S module has 3 modes of operation:
//
// Mode1: Blocking
// - readinto() and write() methods block until the supplied buffer is filled (read) or emptied (write)
// - this is the default mode of operation
//
// Mode2: Non-Blocking
// - readinto() and write() methods return immediately
// - buffer filling and emptying happens asynchronously to the main MicroPython task
// - a callback function is called when the supplied buffer has been filled (read) or emptied (write)
// - non-blocking mode is enabled when a callback is set with the irq() method
// - the DMA callback is used to implement the asynchronous background operations
//
// Mode3: Asyncio
// - implements the stream protocol
// - asyncio mode is enabled when the ioctl() function is called
// - the state of the internal ring buffer is used to detect that I2S samples can be read or written
//
// The samples contained in the app buffer supplied for the readinto() and write() methods have the following convention:
// Mono: little endian format
// Stereo: little endian format, left channel first
//
// I2S terms:
// "frame": consists of two audio samples (Left audio sample + Right audio sample)
//
// Misc:
// - for Mono configuration:
// - readinto method: samples are gathered from the L channel only
// - write method: every sample is output to both the L and R channels
// - for readinto method the I2S hardware is read using 8-byte frames
// (this is standard for almost all I2S hardware, such as MEMS microphones)
// Notes on this port's specific implementation of I2S:
// - the DMA callback is used to implement the asynchronous background operations, for non-blocking mode
// - all 3 Modes of operation are implemented using the peripheral drivers in the NXP MCUXpresso SDK
// - all sample data transfers use DMA
// - the DMA ping-pong buffer needs to be aligned to a cache line size of 32 bytes. 32 byte
Expand All @@ -88,8 +58,6 @@
#define NON_BLOCKING_RATE_MULTIPLIER (4)
#define SIZEOF_NON_BLOCKING_COPY_IN_BYTES (SIZEOF_HALF_DMA_BUFFER_IN_BYTES * NON_BLOCKING_RATE_MULTIPLIER)

#define NUM_I2S_USER_FORMATS (4)
#define I2S_RX_FRAME_SIZE_IN_BYTES (8)
#define SAI_CHANNEL_0 (0)
#define SAI_NUM_AUDIO_CHANNELS (2U)

Expand All @@ -105,17 +73,6 @@ typedef enum {
TX,
} i2s_mode_t;

typedef enum {
MONO,
STEREO
} format_t;

typedef enum {
BLOCKING,
NON_BLOCKING,
ASYNCIO
} io_mode_t;

typedef enum {
TOP_HALF,
BOTTOM_HALF
Expand Down Expand Up @@ -766,5 +723,3 @@ STATIC void mp_machine_i2s_irq_update(machine_i2s_obj_t *self) {
}

MP_REGISTER_ROOT_POINTER(struct _machine_i2s_obj_t *machine_i2s_obj[MICROPY_HW_I2S_NUM]);

#endif // MICROPY_PY_MACHINE_I2S
47 changes: 2 additions & 45 deletions ports/rp2/machine_i2s.c
Original file line number Diff line number Diff line change
Expand Up @@ -37,37 +37,8 @@
#include "hardware/dma.h"
#include "hardware/irq.h"

// The I2S class has 3 modes of operation:
//
// Mode1: Blocking
// - readinto() and write() methods block until the supplied buffer is filled (read) or emptied (write)
// - this is the default mode of operation
//
// Mode2: Non-Blocking
// - readinto() and write() methods return immediately
// - buffer filling and emptying happens asynchronously to the main MicroPython task
// - a callback function is called when the supplied buffer has been filled (read) or emptied (write)
// - non-blocking mode is enabled when a callback is set with the irq() method
// - the DMA IRQ handler is used to implement the asynchronous background operations
//
// Mode3: Asyncio
// - implements the stream protocol
// - asyncio mode is enabled when the ioctl() function is called
// - the state of the internal ring buffer is used to detect that I2S samples can be read or written
//
// The samples contained in the app buffer supplied for the readinto() and write() methods have the following convention:
// Mono: little endian format
// Stereo: little endian format, left channel first
//
// I2S terms:
// "frame": consists of two audio samples (Left audio sample + Right audio sample)
//
// Misc:
// - for Mono configuration:
// - readinto method: samples are gathered from the L channel only
// - write method: every sample is output to both the L and R channels
// - for readinto method the I2S hardware is read using 8-byte frames
// (this is standard for almost all I2S hardware, such as MEMS microphones)
// Notes on this port's specific implementation of I2S:
// - the DMA IRQ handler is used to implement the asynchronous background operations, for non-blocking mode
// - the PIO is used to drive the I2S bus signals
// - all sample data transfers use non-blocking DMA
// - the DMA controller is configured with 2 DMA channels in chained mode
Expand All @@ -86,9 +57,6 @@
#define NON_BLOCKING_RATE_MULTIPLIER (4)
#define SIZEOF_NON_BLOCKING_COPY_IN_BYTES (SIZEOF_HALF_DMA_BUFFER_IN_BYTES * NON_BLOCKING_RATE_MULTIPLIER)

#define NUM_I2S_USER_FORMATS (4)
#define I2S_RX_FRAME_SIZE_IN_BYTES (8)

#define SAMPLES_PER_FRAME (2)
#define PIO_INSTRUCTIONS_PER_BIT (2)

Expand All @@ -97,17 +65,6 @@ typedef enum {
TX
} i2s_mode_t;

typedef enum {
MONO,
STEREO
} format_t;

typedef enum {
BLOCKING,
NON_BLOCKING,
ASYNCIO
} io_mode_t;

typedef enum {
GP_INPUT = 0,
GP_OUTPUT = 1
Expand Down
49 changes: 1 addition & 48 deletions ports/stm32/machine_i2s.c
Original file line number Diff line number Diff line change
Expand Up @@ -33,39 +33,8 @@
#include "pin.h"
#include "dma.h"

#if MICROPY_PY_MACHINE_I2S

// The I2S module has 3 modes of operation:
//
// Mode1: Blocking
// - readinto() and write() methods block until the supplied buffer is filled (read) or emptied (write)
// - this is the default mode of operation
//
// Mode2: Non-Blocking
// - readinto() and write() methods return immediately
// - buffer filling and emptying happens asynchronously to the main MicroPython task
// - a callback function is called when the supplied buffer has been filled (read) or emptied (write)
// - non-blocking mode is enabled when a callback is set with the irq() method
// Notes on this port's specific implementation of I2S:
// - the DMA callbacks (1/2 complete and complete) are used to implement the asynchronous background operations
//
// Mode3: Asyncio
// - implements the stream protocol
// - asyncio mode is enabled when the ioctl() function is called
// - the state of the internal ring buffer is used to detect that I2S samples can be read or written
//
// The samples contained in the app buffer supplied for the readinto() and write() methods have the following convention:
// Mono: little endian format
// Stereo: little endian format, left channel first
//
// I2S terms:
// "frame": consists of two audio samples (Left audio sample + Right audio sample)
//
// Misc:
// - for Mono configuration:
// - readinto method: samples are gathered from the L channel only
// - write method: every sample is output to both the L and R channels
// - for readinto method the I2S hardware is read using 8-byte frames
// (this is standard for almost all I2S hardware, such as MEMS microphones)
// - all 3 Modes of operation are implemented using the HAL I2S Generic Driver
// - all sample data transfers use DMA
// - the DMA controller is configured in Circular mode to fulfil continuous and gapless sample flows
Expand All @@ -86,20 +55,6 @@
#define NON_BLOCKING_RATE_MULTIPLIER (4)
#define SIZEOF_NON_BLOCKING_COPY_IN_BYTES (SIZEOF_HALF_DMA_BUFFER_IN_BYTES * NON_BLOCKING_RATE_MULTIPLIER)

#define NUM_I2S_USER_FORMATS (4)
#define I2S_RX_FRAME_SIZE_IN_BYTES (8)

typedef enum {
MONO,
STEREO
} format_t;

typedef enum {
BLOCKING,
NON_BLOCKING,
ASYNCIO
} io_mode_t;

typedef enum {
TOP_HALF,
BOTTOM_HALF
Expand Down Expand Up @@ -618,5 +573,3 @@ STATIC void mp_machine_i2s_irq_update(machine_i2s_obj_t *self) {
}

MP_REGISTER_ROOT_POINTER(struct _machine_i2s_obj_t *machine_i2s_obj[MICROPY_HW_MAX_I2S]);

#endif // MICROPY_PY_MACHINE_I2S

0 comments on commit 91a3f18

Please sign in to comment.