Docs / API reference / syn_process.h

syn_process.hv0.2.0

<synaptic/syn_process.h> holds the configuration structures for the built-in pre- and post-processing stages declared in syn_infer.h. Each stage that needs parameters takes a pointer to its matching structure as the config argument of syn_pipeline_add_preprocess() / syn_pipeline_add_postprocess(). The header also defines the two result-record layouts that classification and detection post-processors write: syn_classification_t and syn_bbox_t.

Note · Added in Phase 2

This header was added in Phase 2 (v0.2.0), alongside the implementations of the nine built-in processors — it supplements the ten frozen Phase 1 headers, which remain untouched. The processors are implemented, covered by the QEMU test suite (syn_process_suite, 15 tests), and verified live on the FRDM-MCXN947 (2026-07-12) by the face_detection pipeline.

Types & constants

Name	Kind	Description
`syn_normalize_config_t`	struct	Config for `syn_preprocess_image_normalize`. Fields: `float mean[4]`, `float std[4]`, `uint8_t channels`. Applies per-channel `(x - mean) / std`; uint8/int8 input, float32 output. `channels` must match the last input dimension (max 4).
`syn_quantize_config_t`	struct	Config for `syn_preprocess_quantize_int8`. Fields: `float scale`, `int32_t zero_point`. Computes `q = round(x / scale) + zero_point`; float32 input, int8 output.
`syn_dequantize_config_t`	struct	Config for `syn_postprocess_dequantize`. Fields: `float scale`, `int32_t zero_point`. Computes `x = (q - zero_point) * scale`; int8 input, float32 output. Also accepted (optionally) by `syn_postprocess_softmax` to dequantize int8 logits first.
`syn_mfcc_config_t`	struct	Config for `syn_preprocess_audio_mfcc`. Fields: `uint32_t sample_rate_hz`; `uint16_t frame_len` (samples per frame, power of two); `uint8_t num_mel` (mel filterbank size, e.g. 20); `uint8_t num_coeffs` (DCT coefficients kept, e.g. 10). Input is [1, N] float32 mono samples; output is [num_frames, num_coeffs] float32 with `num_frames = N / frame_len` (non-overlapping frames).
`syn_topk_config_t`	struct	Config for `syn_postprocess_top_k`. Field: `uint8_t k` — the number of top classifications to emit.
`syn_classification_t`	struct	Result element written by `syn_postprocess_argmax` (one entry) and `syn_postprocess_top_k` (k entries). Fields: `uint32_t index`, `float score`.
`syn_bbox_t`	struct	Detection-box layout consumed and produced by `syn_postprocess_nms`: the input tensor holds N consecutive `syn_bbox_t` entries (a float32 tensor), the output holds the kept boxes. Fields: `float x1`, `float y1`, `float x2`, `float y2`, `float score`, `float class_id`.
`syn_nms_config_t`	struct	Config for `syn_postprocess_nms` (greedy per-class non-maximum suppression). Fields: `float iou_threshold` (suppress overlap above this), `float score_threshold` (drop boxes below this first), `uint8_t max_boxes` (cap on emitted boxes).

Which stage takes which config

The stage symbols themselves are declared in syn_infer.h (the image-resize config, syn_resize_config_t, lives there too). This header supplies the remaining configs:

Stage	Config type	Config required?
`syn_preprocess_image_resize`	`syn_resize_config_t` (from `syn_infer.h`)	Yes
`syn_preprocess_image_normalize`	`syn_normalize_config_t`	Yes
`syn_preprocess_quantize_int8`	`syn_quantize_config_t`	Yes
`syn_preprocess_audio_mfcc`	`syn_mfcc_config_t`	Yes
`syn_postprocess_softmax`	`syn_dequantize_config_t`	Optional — pass it to dequantize int8 logits before the softmax; pass NULL for float32 input
`syn_postprocess_argmax`	—	No config; emits one `syn_classification_t`
`syn_postprocess_top_k`	`syn_topk_config_t`	Yes; emits k `syn_classification_t` entries
`syn_postprocess_nms`	`syn_nms_config_t`	Yes; input and output are `syn_bbox_t` arrays
`syn_postprocess_dequantize`	`syn_dequantize_config_t`	Yes

Usage

The vision front-end of the face_detection sample — resize, per-channel normalize, and quantize feeding an INT8 detector, with NMS applied to the decoded boxes:

#include <synaptic/syn_process.h>

/* Configs must stay valid for the pipeline's lifetime */
static syn_resize_config_t resize_cfg = { .w = 12, .h = 12 };
static syn_normalize_config_t norm_cfg = {
    .mean = { 127.5f, 127.5f, 127.5f },
    .std  = { 127.5f, 127.5f, 127.5f },
    .channels = 3,
};
static syn_quantize_config_t quant_cfg = {
    .scale = 1.0f / 127.0f, .zero_point = 0,
};

syn_pipeline_add_preprocess(pipe, syn_preprocess_image_resize, &resize_cfg);
syn_pipeline_add_preprocess(pipe, syn_preprocess_image_normalize, &norm_cfg);
syn_pipeline_add_preprocess(pipe, syn_preprocess_quantize_int8, &quant_cfg);
syn_pipeline_add_model(pipe, model);

/* After decoding raw scores into syn_bbox_t records: */
syn_nms_config_t nms_cfg = {
    .iou_threshold   = 0.5f,
    .score_threshold = 0.3f,
    .max_boxes       = 4,
};

Reading a classification result out of an argmax or top-k output tensor:

const syn_classification_t *top =
    (const syn_classification_t *)result.data;

printk("class %u (score %d.%02d)\n", top->index,
       (int)top->score, (int)(top->score * 100) % 100);

Notes

Implementation status: all nine built-in processors are implemented in v0.2.0 in src/preprocess/ and src/postprocess/, exercised by the QEMU test suite, and verified on the FRDM-MCXN947 board.
Lifetime: stage config pointers are stored by the pipeline, not copied — the structures must stay valid for the pipeline's lifetime (file-scope static works well).
MFCC simplifications: the front-end applies a Hamming window, FFT, mel filterbank, log, and DCT-II per frame. Documented simplifications versus a full speech front-end: frames are non-overlapping and there is no pre-emphasis filter.
Resize input layout: syn_preprocess_image_resize operates on [1, H, W, C] byte images with edge-aligned bilinear sampling.
Related: syn_infer.h for the stage symbols and pipeline API, Pre- & post-processing for the concept discussion, syn_hal_dsp.h for the DSP kernels the stages call into.

← Previoussyn_infer.h — scheduler Next →syn_hal_npu.h — NPU HAL