Docs / API reference / syn_prof.h

syn_prof.hv0.1.0

<synaptic/syn_prof.h> is the profiling and diagnostics API. It captures a per-inference breakdown — preprocess, NPU, and postprocess time, total latency, peak tensor-arena usage, and NPU utilization — into a single syn_prof_result_t. Timing is derived from the Zephyr cycle counter (k_cycle_get_32()), converted to microseconds. The syn prof shell command is a thin wrapper over this API.

Types & constants

Name	Kind	Description
`syn_prof_result_t`	struct	Profile of the last completed inference: `total_us` (end-to-end latency), `preprocess_us`, `npu_us`, `postprocess_us` (per-stage times), `ipc_overhead_us` (inter-core overhead; reserved, always 0 until IPC lands), `mem_peak_bytes` (tensor-arena high-water mark from `syn_mem` stats), `npu_utilization_pct` (NPU time as a percentage of total).

Functions

Signature	Description
`int syn_prof_enable(void)`	Enable profiling and clear any previous result. Returns 0.
`int syn_prof_disable(void)`	Disable profiling; stage marks become no-ops. Returns 0.
`int syn_prof_get_last(syn_prof_result_t *result)`	Copy the profile of the last completed inference into `*result`. Returns 0 on success, `-EINVAL` if `result` is NULL, `-ENOENT` if no profiled inference has completed yet.
`void syn_prof_print_summary(void)`	Log a formatted breakdown of the last result (total, per-stage times, memory peak, NPU utilization) via the Zephyr logging subsystem. Logs "No profiling data available" if there is no result.
`int syn_prof_enable_layer_trace(void)`	Enable per-layer timing. Still returns `-ENOTSUP` as of Phase 2 — layer tracing requires per-layer NPU callbacks from the Neutron SDK integration.
`int syn_prof_get_layer_time(uint32_t layer_index, uint32_t *us)`	Fetch the execution time of one layer. Returns `-EINVAL` if `us` is NULL, otherwise writes 0 to `*us` and returns `-ENOTSUP` (unchanged in Phase 2).

Usage

Enable profiling before running an inference, then read the breakdown afterwards:

#include <synaptic/syn_prof.h>

syn_prof_result_t prof;

syn_prof_enable();

/* ... run an inference via syn_infer.h ... */

if (syn_prof_get_last(&prof) == 0) {
    printk("total %u us (pre %u, npu %u, post %u), peak %u B\n",
           prof.total_us, prof.preprocess_us, prof.npu_us,
           prof.postprocess_us, prof.mem_peak_bytes);
} else {
    /* -ENOENT: no profiled inference has completed yet */
    syn_prof_print_summary();
}

Notes

Status · Stage marks wired in as of Phase 2

The implementation (src/core/syn_prof.c) contains internal stage-mark helpers (syn_prof_mark_start, syn_prof_mark_preprocess_done, syn_prof_mark_npu_done, syn_prof_mark_end, declared in the private syn_prof_internal.h). In v0.1.0 no inference path called them, so syn_prof_get_last() always returned -ENOENT. As of Phase 2 (v0.2.0) the pipeline executor in syn_infer.c fires the marks at every stage boundary, so any inference run through the scheduler produces a result — verified live on the FRDM-MCXN947. The mark helpers are still not part of the public API; do not call them from application code.

Times are computed with k_cyc_to_us_ceil32(), so each stage value is rounded up to the next microsecond.
mem_peak_bytes is sampled at end-of-inference from syn_mem_get_stats() — it reflects the tensor-arena peak, not total system RAM.
npu_utilization_pct is simply npu_us * 100 / total_us; on the software stub backends it measures the simulated NPU stage.
Only the most recent result is stored; each profiled inference overwrites the previous one.

← Previoussyn_hal_dma.h — DMA HAL Next →syn_ipc.h — inter-core IPC