Noodle
Loading...
Searching...
No Matches
noodle.h File Reference
Public API

Public Noodle API for small CNN/ML inference on microcontrollers. More...

#include <stdint.h>
#include <stddef.h>
#include "noodle_config.h"
#include "noodle_fs.h"
#include "noodle_buffer.h"
Include dependency graph for noodle.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  Conv
 File-backed convolution parameter bundle. More...
struct  ConvFile
 File-backed convolution parameter bundle alias. More...
struct  ConvMem
 Memory-backed convolution parameter bundle. More...
struct  ConvProgmem
 Near-PROGMEM convolution parameter bundle. More...
struct  Pool
 Valid-pooling parameter bundle. More...
struct  FCN
 File-backed fully connected parameter bundle. More...
struct  FCNFile
 File-backed fully connected parameter bundle alias. More...
struct  FCNMem
 Memory-backed fully connected parameter bundle. More...
struct  FCNProgmem
 Far-PROGMEM fully connected parameter bundle for AVR. More...

Macros

#define NULL   0

Typedefs

typedef unsigned char byte
 Arduino-compatible byte alias for non-Arduino builds.
typedef void(* CBFPtr) (float progress)
 Progress callback used by long-running layer routines.

Enumerations

enum  Activation : uint8_t { ACT_NONE = 0 , ACT_RELU = 1 , ACT_SOFTMAX = 2 }
 Activation applied after bias where supported. More...

Functions

static float noodle_pgm_float (const float *p, uint32_t idx)
 Read a float from normal memory or near AVR PROGMEM.
bool noodle_fs_init (uint8_t clk_pin, uint8_t cmd_pin, uint8_t d0_pin)
 Initialize SD_MMC with explicit 1-bit pins, or default-init other backends.
bool noodle_fs_init (uint8_t clk_pin, uint8_t cmd_pin, uint8_t d0_pin, uint8_t d1_pin, uint8_t d2_pin, uint8_t d3_pin)
 Initialize SD_MMC with explicit 4-bit pins, or default-init other backends.
bool noodle_fs_init ()
 Initialize the selected filesystem backend with default settings.
bool noodle_fs_init (uint8_t cs_pin)
 Initialize the selected filesystem backend with an SPI chip-select pin.
bool noodle_fs_init (uint8_t cs_pin, SPIClass &spi, uint8_t sck_mhz)
 Initialize SdFat with an explicit SPI bus and clock speed.
void noodle_read_top_line (const char *fn, char *line, size_t maxlen)
 Read the first line from a text file.
void noodle_delete_file (const char *fn)
 Delete a file through the selected filesystem backend.
size_t noodle_read_bytes_until (NDL_File &file, char terminator, char *buffer, size_t length)
 Read bytes until a terminator or until the buffer is full.
void noodle_write_float (NDL_File &f, float d)
 Write a float using NOODLE_FILE_FORMAT.
float noodle_read_float (NDL_File &f)
 Read a float using NOODLE_FILE_FORMAT.
byte noodle_read_byte (NDL_File &f)
 Read a byte using NOODLE_FILE_FORMAT.
void noodle_write_byte (NDL_File &f, byte d)
 Write a byte using NOODLE_FILE_FORMAT.
void noodle_setup_temp_buffers (void *b1, void *b2)
 Install caller-owned internal scratch buffers.
void noodle_setup_temp_buffers (void *b2)
 Install only the caller-owned accumulation scratch buffer.
void noodle_temp_buffers_free (void)
 Release automatically allocated internal scratch buffers.
float * noodle_create_buffer (uint16_t size)
 Allocate a raw byte buffer and return it as a float pointer.
void noodle_delete_buffer (float *buffer)
 Free a buffer allocated by noodle_create_buffer().
void noodle_array_to_file (float *array, const char *fn, uint16_t n)
 Write a float array to a file.
void noodle_grid_to_file (byte *grid, const char *fn, uint16_t n)
 Write an n x n byte grid to a file in row-major order.
void noodle_grid_to_file (float *grid, const char *fn, uint16_t n)
 Write an n x n float grid to a file in row-major order.
void noodle_array_from_file (const char *fn, float *buffer, uint16_t K)
 Read a float array from a file.
void noodle_grid_from_file (const char *fn, byte *buffer, uint16_t K)
 Read a K x K grid into a byte buffer.
void noodle_grid_from_file (const char *fn, int8_t *buffer, uint16_t K)
 Read a K x K grid into an int8 buffer.
void noodle_grid_from_file (const char *fn, float *buffer, uint16_t K)
 Read a K x K grid into a float buffer.
File-backed layers

File-backed convolution APIs read packed input tensors from files, stream parameters from files or memory/PROGMEM, and write packed output tensors to a file. They return the output width/length, or 0 on allocation/open/shape failure.

uint16_t noodle_conv_byte (const char *in_fn, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run file-to-file 2D convolution on byte input feature maps.
uint16_t noodle_conv_float (const char *in_fn, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run file-to-file 2D convolution on float input feature maps.
uint16_t noodle_conv_float (const char *in_fn, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, uint16_t W, const ConvMem &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run file-to-file 2D convolution with memory-backed parameters.
uint16_t noodle_conv_float (const char *in_fn, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, uint16_t W, const ConvProgmem &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run file-to-file 2D convolution with near-PROGMEM parameters.
uint16_t noodle_conv1d (const char *in_fn, uint16_t n_inputs, const char *out_fn, uint16_t n_outputs, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run file-to-file 1D convolution with file-backed parameters and pooling.
uint16_t noodle_conv1d (const char *in_fn, uint16_t n_inputs, const char *out_fn, uint16_t n_outputs, uint16_t W, const Conv &conv, CBFPtr progress_cb=0)
 Run file-to-file 1D convolution with file-backed parameters.
uint16_t noodle_conv1d (const char *in_fn, uint16_t n_inputs, const char *out_fn, uint16_t n_outputs, uint16_t W, const ConvMem &conv, CBFPtr progress_cb=0)
 Run file-to-file 1D convolution with memory-backed parameters.
uint16_t noodle_dwconv_float (const char *in_fn, uint16_t n_channels, const char *out_fn, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run file-to-file depthwise 2D convolution with file-backed parameters.
uint16_t noodle_dwconv_float (const char *in_fn, uint16_t n_channels, const char *out_fn, uint16_t W, const ConvProgmem &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run file-to-file depthwise 2D convolution with near-PROGMEM parameters.
uint16_t noodle_fcn (const int8_t *input, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, const FCNFile &fcn, CBFPtr progress_cb=0)
 Run a fully connected layer from int8 memory to a file.
uint16_t noodle_fcn (const byte *input, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, const FCNFile &fcn, CBFPtr progress_cb=0)
 Run a fully connected layer from byte memory to a file.
uint16_t noodle_fcn (const char *in_fn, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, const FCNFile &fcn, CBFPtr progress_cb=0)
 Run a fully connected layer from a file to a file.
NoodleBuffer RAM-to-RAM layers

These overloads read input from input->data, grow output with noodle_buffer_require(), and write the result into output->data. They return the output width/length or output count, and return 0 on null input, null storage, invalid shape, allocation failure, or a failing lower-level layer.

uint16_t noodle_conv_float (NoodleBuffer *input, uint16_t n_inputs, uint16_t n_outputs, NoodleBuffer *output, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run 2D convolution using file-backed parameters.
uint16_t noodle_conv_float (NoodleBuffer *input, uint16_t n_inputs, uint16_t n_outputs, NoodleBuffer *output, uint16_t W, const ConvMem &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run 2D convolution using memory-backed parameters.
uint16_t noodle_conv_float (NoodleBuffer *input, uint16_t n_inputs, uint16_t n_outputs, NoodleBuffer *output, uint16_t W, const ConvProgmem &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run 2D convolution using near-PROGMEM parameters.
uint16_t noodle_conv1d (NoodleBuffer *input, uint16_t n_inputs, NoodleBuffer *output, uint16_t n_outputs, uint16_t W, const ConvMem &conv, CBFPtr progress_cb=0)
 Run 1D convolution using memory-backed parameters.
uint16_t noodle_conv1d (NoodleBuffer *input, uint16_t n_inputs, NoodleBuffer *output, uint16_t n_outputs, uint16_t W, const ConvMem &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run 1D convolution using memory-backed parameters and pooling.
uint16_t noodle_dwconv_float (NoodleBuffer *input, uint16_t n_channels, NoodleBuffer *output, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run depthwise 2D convolution using file-backed parameters.
uint16_t noodle_dwconv_float (NoodleBuffer *input, uint16_t n_channels, NoodleBuffer *output, uint16_t W, const ConvMem &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run depthwise 2D convolution using memory-backed parameters.
uint16_t noodle_dwconv_float (NoodleBuffer *input, uint16_t n_channels, NoodleBuffer *output, uint16_t W, const ConvProgmem &conv, const Pool &pool, CBFPtr progress_cb=0)
 Run depthwise 2D convolution using near-PROGMEM parameters.
uint16_t noodle_conv_transpose_float (NoodleBuffer *input, uint16_t n_inputs, uint16_t n_outputs, NoodleBuffer *output, uint16_t W, const ConvMem &conv, CBFPtr progress_cb=0)
 Run 2D transpose convolution using memory-backed parameters.
uint16_t noodle_fcn (NoodleBuffer *input, uint16_t n_inputs, uint16_t n_outputs, NoodleBuffer *output, const FCNMem &fcn, CBFPtr progress_cb=0)
 Run a fully connected layer using memory-backed parameters.
uint16_t noodle_fcn (NoodleBuffer *input, uint16_t n_inputs, uint16_t n_outputs, NoodleBuffer *output, const FCNFile &fcn, CBFPtr progress_cb=0)
 Run a fully connected layer using file-backed parameters.
uint16_t noodle_fcn (NoodleBuffer *input, uint16_t n_inputs, uint16_t n_outputs, NoodleBuffer *output, const FCNProgmem &fcn, CBFPtr progress_cb=0)
 Run a fully connected layer using far-PROGMEM parameters.
uint16_t noodle_fcn (const byte *input, uint16_t n_inputs, uint16_t n_outputs, NoodleBuffer *output, const FCNFile &fcn, CBFPtr progress_cb=0)
 Run a fully connected layer from byte memory to a NoodleBuffer.
uint16_t noodle_fcn (const int8_t *input, uint16_t n_inputs, uint16_t n_outputs, NoodleBuffer *output, const FCNFile &fcn, CBFPtr progress_cb=0)
 Run a fully connected layer from int8 memory to a NoodleBuffer.
uint16_t noodle_fcn (const char *in_fn, uint16_t n_inputs, uint16_t n_outputs, NoodleBuffer *output, const FCNFile &fcn, CBFPtr progress_cb=0)
 Run a fully connected layer from a file to a NoodleBuffer.
uint16_t noodle_fcn_progmem (NoodleBuffer *input, uint16_t n_inputs, uint16_t n_outputs, NoodleBuffer *output, const float *weight, const float *bias, Activation act, CBFPtr progress_cb=0)
 Run a fully connected layer using near-PROGMEM weights.
uint16_t noodle_flat (const char *in_fn, NoodleBuffer *output, uint16_t V, uint16_t n_filters)
 Flatten a packed file tensor into a NoodleBuffer.
uint16_t noodle_flat (NoodleBuffer *input, NoodleBuffer *output, uint16_t V, uint16_t n_filters)
 Flatten a packed NoodleBuffer tensor into HWC-like order.
uint16_t noodle_reshape (NoodleBuffer *src_hwc, NoodleBuffer *dst_chw, uint16_t W, uint16_t C)
 Convert HWC-like NoodleBuffer data to packed channel-first data.
uint16_t noodle_gap (NoodleBuffer *inout, uint16_t C, uint16_t W)
 Apply global average pooling in place on packed channel-first maps.
uint16_t noodle_gmp (NoodleBuffer *inout, uint16_t C, uint16_t W)
 Apply global max pooling in place on packed channel-first data.
uint16_t noodle_soft_max (NoodleBuffer *input_output, uint16_t n)
 Apply numerically stabilized softmax in place on a NoodleBuffer.
uint16_t noodle_sigmoid (NoodleBuffer *input_output, uint16_t n)
 Apply sigmoid in place on a NoodleBuffer.
float noodle_sigmoidf (float x)
 Compute sigmoid for one scalar.
uint16_t noodle_logit (NoodleBuffer *input_output, uint16_t n)
 Apply logistic sigmoid in place on a NoodleBuffer.
uint16_t noodle_relu (NoodleBuffer *input_output, uint16_t n)
 Apply ReLU in place on a NoodleBuffer.
void noodle_find_max (NoodleBuffer *input, uint16_t n, float &max_val, uint16_t &max_idx)
 Find the maximum value and its index in a NoodleBuffer vector.
uint16_t noodle_bn1d (NoodleBuffer *x, uint16_t N, const float *gamma, const float *beta, const float *mean, const float *var, float eps)
 Apply 1D batch normalization in place to a NoodleBuffer vector.
uint16_t noodle_bn1d (NoodleBuffer *x, uint16_t N, const float *bn_params, float eps)
 Apply 1D batch normalization from a packed parameter array.
uint16_t noodle_bn1d_relu (NoodleBuffer *x, uint16_t N, const float *gamma, const float *beta, const float *mean, const float *var, float eps)
 Apply 1D batch normalization followed by ReLU in place.
uint16_t noodle_bn1d_relu (NoodleBuffer *x, uint16_t N, const float *bn_params, float eps)
 Apply packed 1D batch normalization followed by ReLU in place.
uint16_t noodle_bn2d (NoodleBuffer *x, uint16_t C, uint16_t W, const float *gamma, const float *beta, const float *mean, const float *var, float eps)
 Apply 2D channel-wise batch normalization in place.
uint16_t noodle_bn2d (NoodleBuffer *x, uint16_t C, uint16_t W, const float *bn_params, float eps)
 Apply 2D channel-wise batch normalization from packed parameters.
uint16_t noodle_bn2d_relu (NoodleBuffer *x, uint16_t C, uint16_t W, const float *gamma, const float *beta, const float *mean, const float *var, float eps)
 Apply 2D channel-wise batch normalization followed by ReLU.
uint16_t noodle_bn2d_relu (NoodleBuffer *x, uint16_t C, uint16_t W, const float *bn_params, float eps)
 Apply packed 2D batch normalization followed by ReLU.
uint16_t noodle_bn (NoodleBuffer *x, uint16_t C, uint16_t W, const float *gamma, const float *beta, const float *mean, const float *var, float eps)
 Backward-compatible alias for noodle_bn2d().
uint16_t noodle_bn (NoodleBuffer *x, uint16_t C, uint16_t W, const float *bn_params, float eps)
 Backward-compatible alias for packed-parameter noodle_bn2d().
uint16_t noodle_bn_relu (NoodleBuffer *x, uint16_t C, uint16_t W, const float *gamma, const float *beta, const float *mean, const float *var, float eps)
 Backward-compatible alias for noodle_bn2d_relu().
uint16_t noodle_bn_relu (NoodleBuffer *x, uint16_t C, uint16_t W, const float *bn_params, float eps)
 Backward-compatible alias for packed-parameter noodle_bn2d_relu().

Detailed Description

Public Noodle API for small CNN/ML inference on microcontrollers.

Noodle provides compact convolution, depthwise convolution, transpose convolution, fully connected, pooling, activation, batch-normalization, and tensor-layout helpers. The public RAM-to-RAM layer functions use NoodleBuffer so tensor storage can grow automatically. Raw float pointers are kept for small math utilities, simple file utilities, and private implementation helpers declared in noodle_internal.h.

Unless a function says otherwise, feature maps use channel-first packed storage:

  • 2D tensors: [C][W][W].
  • 1D tensors: [C][W].
  • 2D convolution weights: [O][I][K][K].
  • 1D convolution weights: [O][I][K].
  • Depthwise convolution weights: [C][K][K].
  • Fully connected weights: [O][I].

File-backed APIs use the scalar encoding selected by NOODLE_FILE_FORMAT. Text mode stores one scalar at a time; binary mode stores raw scalar bytes in the same packed order.

Internal convolution scratch buffers are allocated and grown on demand by default. The legacy noodle_setup_temp_buffers() overloads can still install fixed caller-owned buffers; when they are used, Noodle treats those pointers as external memory with unknown capacity and never resizes or frees them.

Macro Definition Documentation

◆ NULL

#define NULL   0

Typedef Documentation

◆ byte

typedef unsigned char byte

Arduino-compatible byte alias for non-Arduino builds.