c_info.json code-generation output report
ST Edge AI Core Technology 2.2.0
r1.0
This article shows a brief example on how to use the generated
c_info.json output files before presenting their
structure (i.e. the associated json schema).
Usage of the output file
A very simple example of such file is provided here:
(the example uses a file created when generating code for Neural-Art
target, but the same process for searching information applies on
other targets)
This example has been generated by doing a “generate” on a small
model to be tested on stm32n6 with Neural-Art enabled. This command
generates a file st_ai_output/network_c_info.json:
stedgeai generate -m MYMODEL.tflite --target stm32n6 --st-neural-art my_profile@user_neural_art.jsonIt has then been completed by a “validate” step done by the user after loading the proper validation project on board.
stedgeai validate –m MYMODEL.tflite --target stm32n6 --mode target --desc serial:921600 --val-json st_ai_output/network_c_info.jsonBelow are shown a few information that can be found digging into this json file.
Generation information
Information about generation steps can be found in the
environment key.
In the example above, it is possible to see that the generation
corresponding to this file was done with a model
model__2025_04_16-16_09_48.tflite, that the generation
requested a “generate” for stm32n6 with use of the Neural-Art. It is
noted that the user requested to use the
--no-inputs-allocation, so the tool should not allocate
space for the inputs, it is the duty of the user to do so.
The options used for the Neural-Art compiler were (among others):
--mvei --cache-maintenance --enable-virtual-mem-pools --native-float --Ocache-opt --all-buffers-info --encrypt-weights
Memory usage
Looking at the memory_pools part of the json
provided, one can see that the user provided two memory pools:
cpuRAM2@ [0x34100000 - 0x34200000]- contains buffers 1,2,3,4,5
- all buffers use up to 10.048kB (=10289 bytes)
octoFlash@ [0x71000000 - 0x78000000].- contains buffers 6,7,8,9
- all buffers take 193 bytes
- all buffers from offset 0 to offset 193 bytes are encrypted.
(see
"attributes":"encryption")
- An additional pool is found in the json file (added in the file
by the tools because the user requested to use
--no-inputs-allocation)- This pool is not allocated by the tools (see
"user_allocated": true) - This pool has no address allocated by the tool
- This pool has a total size of 6144 (which is the size of the input buffer, as we will see below)
- This pool is not allocated by the tools (see
Finding characteristics of the I/O buffers of a model
An easy and efficient way to find where are the input/output buffers located is to:
- Read the
graphsentry of the json - At the current time, the first item always represent the main graph of execution.
- In the first graph, look at the
inputsandoutputsentries: those are the links to buffer IDs (to be found in thebufferspart of the JSON file)
In the example above, it is easy to see that the only input
buffer is buffer with ID=10, the only output buffer is
the buffer with ID=1.
Following the tracks… to the buffer part of the json, looking for
buffers where "id"=1 and "id"=10, we find
that:
- Output buffer (
id=1)- has a shape of
[1,32,64,5] - is 10240 bytes (10kB)
- is stored in memory pool with id=1:
cpuRAM2, at offset 0 from the base ofcpuRAM2.
- has a shape of
- Input buffer (
id=10) – this one is a bit special because it is not allocated by the tools- has a shape of
[1, 32, 64, 3] - is 6144 bytes long
- is stored in memory pool with id=3 (the one presented above, containing user-allocated buffers)
- has a shape of
Checking validation on target scores
As a validation has been done on this code, it is possible to
find “scores” for the validation by looking at the
validation entry.
For this model, we can see that the model seems to be well
supported by the tools: for the only output it has, it is observed
that when fed with the same inputs, and comparing the outputs of the
original “tflite” model vs the outputs of the
c-model-generated-by-stedgeai, the error is low. In particular, the
cos metric (cosine similarity) is very close to 1, and
l2r (L2 relative error) is very close to 0.
Fields description of the file
Overview
This section provides a detailed description of the JSON schema for the unified networks output format. The schema is designed to standardize the output format for tools information, ensuring consistency and ease of use.
Properties
Main properties are detailed here, a lot of them use references
to objects defined in the Definitions part below.
All the “Description” lines can be unfolded to show
greater details about the contents of each part of the JSON
file.
json_schema_version
Description: Specifies the version of the JSON schema.
- Type:
string - Pattern:
^[0-9]+\.[0-9]+ - Examples:
["1.2", "1.2.3"]
environment
Description: Information related to the used environment.
- Type:
object - $ref:
#/$defs/environment_desc
buffers
Description: Description of all allocated buffers.
- Type:
array - Items:
#/$defs/buffer
graphs
Description: List of all graphs of the network as an array.
- Type:
array - Items:
#/$defs/graph
memory_pools
Description: Description of all memory pools and their contents.
- Type:
array - Items:
#/$defs/mempool
memory_accesses
Description: Description of memory accesses per epoch per memory pool.
- Type:
array - Items:
#/$defs/memory_access
power_estimates
Description: Description of power consumption per epoch.
- Type:
array - Items:
#/$defs/power_estimate
validation
Description: Description of model validation.
- Type:
object - Properties:
- device: Where was the validation performed?
- Type:
string - Enum:
["VALIDATION_HOST", "VALIDATION_SIMULATOR", "VALIDATION_TARGET"]
- Type:
- val_error: Validation error.
- Type:
number
- Type:
- val_error_desc: Validation error description.
- Type:
string - Pattern:
^[a-zA-Z0-9_]+$
- Type:
- val_metrics: Validation metrics.
- Type:
array - Items:
#/$defs/val_metrics
- Type:
- device: Where was the validation performed?
- Required:
["device", "val_metrics"]
memory_footprint
Description: Description of memory footprint.
- Type:
object - Properties:
- activations: Activation size in bytes.
- Type:
integer
- Type:
- weights: Weights size in bytes.
- Type:
integer
- Type:
- io: Array of size 2 containing respectively
input size and output size, in bytes.
- Type:
array - Items:
integer
- Type:
- kernel_flash: Kernel flash in bytes.
- Type:
integer - Minimum:
0
- Type:
- kernel_ram: Kernel RAM in bytes.
- Type:
integer - Minimum:
0
- Type:
- series: Series name.
- Type:
string
- Type:
- toolchain: Toolchain used.
- Type:
string
- Type:
- toolchain_flash: Toolchain flash used in bytes.
- Type:
integer
- Type:
- toolchain_ram: Toolchain RAM used in bytes.
- Type:
integer
- Type:
- activations: Activation size in bytes.
aton_execution_time
Description: When doing validation with Neural-Art, time spent on each step during inference.
- Type:
array - Items:
#/$defs/aton_exec_t
Definitions ($defs)
original_details
Description: Details of original inputs/outputs data type & shape.
- Type:
object - Properties:
- name: Original layer name.
- Type:
string
- Type:
- data_format: Details of IO data formats.
- Type:
object - Properties:
- quantizer: Original IO quantizer type.
- Type:
string - Enum:
["NONE", "DOREFA", "UNIFORM"]
- Type:
- scale: Original IO scale.
- Type:
array - Items:
number
- Type:
- zero: Original IO zero.
- Type:
array - Items:
integer
- Type:
- type: Original IO type.
- Type:
string - Enum:
["FLOAT", "LUT_FLOAT", "SIGNED", "UNSIGNED", "BOOL", "STRING"]
- Type:
- size: Original IO type size.
- Type:
integer
- Type:
- quantizer: Original IO quantizer type.
- Type:
- shape: Original IO shapes.
- Type:
array - Items:
integer
- Type:
- shape_map: Original IO shapes map.
- Type:
array - Items:
string
- Type:
- c_shape_map: C-model IO shapes map.
- Type:
array - Items:
string
- Type:
- name: Original layer name.
exec_time
Description: Details of execution per node or per graph.
- Type:
object - Properties:
- counters: Counters per node.
- Type:
array - Items:
integer
- Type:
- cycles: Cycles per node.
- Type:
integer
- Type:
- cycles_by_macc: Cycles by MACC per node.
- Type:
number
- Type:
- duration_ms: Inference time per node (ms).
- Type:
number
- Type:
- percentage: Percentage of execution time per
node.
- Type:
number
- Type:
- counters: Counters per node.
environment_desc
Description: Info related to the used environment.
- Type:
object - Properties:
- tools: List of used tools.
- Type:
array - Items:
#/$defs/tool_desc
- Type:
- generated_model:
- $ref:
#/$defs/model_desc
- $ref:
- network_signature: Unique Identifier of
generated network model.
- Type:
string
- Type:
- target: Description of the target device used
for generation.
- Type:
string
- Type:
- test_name: Name of the test performed.
- Type:
string
- Type:
- tools: List of used tools.
- Required:
["tools", "generated_model", "network_signature"]
file_desc
Description: Descriptors for the files generated.
- Type:
object - Properties:
- name: Model Filename.
- Type:
string
- Type:
- signature: Unique Identifier of the file.
- Type:
string
- Type:
- name: Model Filename.
model_desc
Description: Descriptors for the initial model.
- Type:
object - Properties:
- name: Model name (Optional).
- Type:
string
- Type:
- type: Model type.
- Type:
string
- Type:
- size: Original IO type size.Model size.
- Type:
integer
- Type:
- n_params: Model number of parameters.
- Type:
integer
- Type:
- model_files:
- Type:
array - Items:
#/$defs/file_desc
- Type:
- generated_time: Time of launch of the tool.
- Type:
string - Format:
date-time - Examples:
["2025-03-20T16:19:49+0100", "%Y-%m-%dT%H:%M:%S%z"]
- Type:
- name: Model name (Optional).
- Required:
["model_files"]
tool_desc
Description: Used tools descriptors.
- Type:
object - Properties:
- name: Tool name.
- Type:
string
- Type:
- version: Version number starts with
3-dot-separated-numbers.
- Type:
string - Pattern:
^[0-9]+\.[0-9]+\.[0-9] - Examples:
["1.2.3", "2.3.5-985"]
- Type:
- arguments: Arguments/parameters given to the
tool.
- Type:
string
- Type:
- environment: Environment used to call the tool.
- Type:
array - Items:
string
- Type:
- input_model:
- $ref:
#/$defs/model_desc
- $ref:
- name: Tool name.
- Required:
["name", "version", "arguments", "input_model"]
val_metrics
Description: Validation metrics.
- Type:
object - Properties:
- acc: Validation accuracy.
- Type:
string - Pattern:
^(\\d+(\\.\\d+)?%)
- Type:
- cos: Cosine Similarity, bigger is better,
best=1, range=(0, 1].
- Type:
number
- Type:
- desc: Validation description.
- Type:
string - Pattern:
^[a-zA-Z0-9_]+$
- Type:
- l2r: L2 relative error.
- Type:
number
- Type:
- mae: Mean Absolute Error.
- Type:
number
- Type:
- mean: Mean value.
- Type:
number
- Type:
- nse: Nash-Sutcliffe efficiency criteria, bigger
is better, best=1, range=(-inf, 1].
- Type:
number
- Type:
- rmse: Root Mean Squared Error.
- Type:
number
- Type:
- std: Standard deviation.
- Type:
number
- Type:
- acc: Validation accuracy.
mempool
Description: Description of a memory pool & its contents.
- Type:
object - Properties:
- name: Memory pool name.
- Type:
string - Pattern:
^[a-zA-Z0-9_]+$
- Type:
- fname: Memory pool initializer filename.
- Type:
string - Pattern:
^[a-zA-Z0-9_ .-]+$
- Type:
- id: Mempool unique identifier.
- Type:
integer
- Type:
- alignment: Pool address alignment in bytes.
- Type:
integer - Minimum:
1
- Type:
- address: When ‘NULL’ or symbol means usemod
relative, decimal number >= 0 is absolute.
- Type:
string
- Type:
- offset_start: Offset in the memory where the
pool starts.
- Type:
integer
- Type:
- size_bytes: Full available size of the memory
pool, in bytes. -1 means the pool is created by tool.
- Type:
integer - Minimum:
-1
- Type:
- used_size_bytes: Total allocated size used in
the memory pool, in bytes.
- Type:
integer - Minimum:
0
- Type:
- rights: Equivalent of
TargetDescription.mem_access in Target Description Protocol
Documentation.
- Type:
string - Enum:
["ACC_UNDEF", "ACC_READ", "ACC_WRITE"]
- Type:
- cacheable: Equivalent of
TargetDescription.cacheable_val in Target Description Protocol
Documentation.
- Type:
string - Enum:
["CACHEABLE_UNDEF", "CACHEABLE_ON", "CACHEABLE_OFF"]
- Type:
- pipelined: Equivalent of
TargetDescription.pipelined_val in Target Description Protocol
Documentation.
- Type:
string - Enum:
["PIPELINED_UNDEF", "PIPELINED_ON", "PIPELINED_OFF"]
- Type:
- user_allocated: Is the memory pool
corresponding to a user-allocated memory region?
- Type:
boolean
- Type:
- persistent: A persistent memory pool shall not
be modified between inferences.
- Type:
boolean
- Type:
- attributes: Additional properties (extra-info
that are not mandatory).
- Type:
object - Properties:
- throughput: Equivalent of
TargetDescription.mem_prop_level in Target Description Protocol
Documentation.
- Type:
string - Enum:
["UNDEF", "LOW", "MID", "HIGH"]
- Type:
- latency:
- Type:
string - Enum:
["UNDEF", "LOW", "MID", "HIGH"]
- Type:
- byte_width: Memory bus access width.
- Type:
integer - Minimum:
0
- Type:
- freq_ratio: Memory frequency ratio compared to
accelerators.
- Type:
number - Minimum:
0
- Type:
- burst_max_length: Max Burst length.
- Type:
integer - Minimum:
0
- Type:
- burst_penalty: Initial Burst Penalty (# of
memory clock cycles).
- Type:
integer - Minimum:
0
- Type:
- read_power: Active read power for a single
byte_width access in mW.
- Type:
number - Minimum:
0
- Type:
- write_power: Active write power for a single
byte_width access in mW.
- Type:
number - Minimum:
0
- Type:
- use_for_initrs:
- Type:
boolean
- Type:
- score:
- Type:
integer - Minimum:
0
- Type:
- encryption: Encryption properties (one range
per memory pool).
- Type:
object - Properties:
- offset:
- Type:
integer - Minimum:
0 - Description: Offset in the memory pool for the first encrypted data address.
- Type:
- size:
- Type:
integer - Minimum:
0 - Description: Size of the encrypted data in bytes.
- Type:
- offset:
- Type:
- throughput: Equivalent of
TargetDescription.mem_prop_level in Target Description Protocol
Documentation.
- Required:
["throughput", "latency", "score"]
- Type:
- subpools: In case of merged pools, list of
contained pools IDs.
- Type:
array - Items:
integer
- Type:
- buffers: Array of buffers that are placed
within the memory pool.
- Type:
array - Items:
integer
- Type:
- name: Memory pool name.
- Required:
["name", "id", "alignment", "address", "offset_start", "size_bytes", "used_size_bytes", "buffers", "user_allocated", "persistent"]
buffer
Description: Description of a buffer properties.
- Type:
object - Properties:
- name: Buffer name.
- Type:
string - Pattern:
^[a-zA-Z0-9_]+$
- Type:
- id: Buffer unique identifier. In C models, it
is equal to the id passed by the inspection callback routine.
- Type:
integer
- Type:
- alignment: Buffer alignment in bytes.
- Type:
integer - Minimum:
1
- Type:
- mpool_id: ID of the pool where the buffer is
allocated.
- Type:
integer
- Type:
- offset_start: Memory offset in bytes where the
buffer starts. Relative address in memory.
- Type:
integer - Minimum:
-1
- Type:
- size_bytes: Size in bytes of the buffer.
- Type:
integer - Minimum:
0
- Type:
- is_param: True if the buffer is used for
parameters, false if used for activations.
- Type:
boolean
- Type:
- flags: A list of flags separated by
|character.- Type:
string
- Type:
- epochs: Epoch number the buffer is used in.
- Type:
object - Properties:
- start: Epoch start value.
- Type:
integer - Minimum:
0
- Type:
- end: Epoch end value.
- Type:
integer - Minimum:
0
- Type:
- start: Epoch start value.
- Type:
- shape: Shape of the buffer.
- Type:
array - Items:
integer
- Type:
- shape_map: Shape map labels of the buffer.
- Type:
array - Items:
string
- Type:
- channel_first: Is the buffer channel first?
- Type:
boolean
- Type:
- channel_last: Is the buffer channel last?
- Type:
boolean
- Type:
- batch: Used only if channel_first/last=false.
- Type:
integer - Minimum:
0
- Type:
- format: Buffer element format.
- Type:
string - Pattern:
^STAI_FORMAT_
- Type:
- nbits: Number of bits for each entry.
- Type:
integer - Minimum:
0
- Type:
- qmn: Qmn format descriptor. The sum of sign, m,
and n values gives the actual bit size of the format.
- Type:
object - Properties:
- m: Number of bits for the integer part
(excluding sign bit).
- Type:
integer
- Type:
- n: Number of fractional bits.
- Type:
integerNumber of fractional bits.
- Type:
- sign: Signed or not?
- Type:
integer - Minimum:
0 - Maximum:
1
- Type:
- m: Number of bits for the integer part
(excluding sign bit).
- Type:
- intq:
- Type:
object - Properties:
- axis: If -1: quantization per tensor.
Otherwise, axis of the channels.
- Type:
integer - Minimum:
-1
- Type:
- scales: Scale factors for the current buffer
(float values).
- Type:
array - Items:
number
- Type:
- offsets: Offset values for the current buffer.
- Type:
array - Items:
integer
- Type:
- axis: If -1: quantization per tensor.
Otherwise, axis of the channels.
- Type:
- name: Buffer name.
- Required:
["name", "id", "alignment", "offset_start", "size_bytes", "is_param", "epochs", "shape", "format", "nbits"]
graph_edge
Description: Description of an edge (object to show data flow between a buffer and a node, or between a node and a node).
- Type:
object - Properties:
- name: Name of the edge.
- Type:
string
- Type:
- id: Edge unique identifier.
- Type:
integer
- Type:
- edge_kind: Kind of edge: FLOW (just
dependency), MEMORY (with associated buffer allocated), and INTERNAL
(internal communication between Accelerators).
- Type:
string - Enum:
["EDGE_UNDEF", "EDGE_FLOW", "EDGE_MEMORY", "EDGE_INTERNAL"]
- Type:
- buffer: For MEMORY edge identifies the buffer
used.
- Type:
integer
- Type:
- start:
- Type:
object - Properties:
- node_id: Origin Node graph reference.
- Type:
integer
- Type:
- port: Output port number.
- Type:
integer
- Type:
- node_id: Origin Node graph reference.
- Type:
- end:
- Type:
object - Properties:
- node_id: Target Node graph reference.
- Type:
integer
- Type:
- port: Input port number.
- Type:
integer
- Type:
- node_id: Target Node graph reference.
- Type:
- attributes: A dictionary of additional
information to show as-is when showing the graph on a display.
- Type:
object - Properties:
- additional_info: Add any info for specifying
edge properties here.
- Type:
string
- Type:
- additional_info: Add any info for specifying
edge properties here.
- Type:
- name: Name of the edge.
- Required:
["id", "start", "end", "edge_kind"]
graph_node
Description: Graph description - an ordered list of steps to be drawn within a box of the graph representation.
- Type:
object - Properties:
- name: Name of the node.
- Type:
string - Pattern:
^[a-zA-Z0-9_]+$
- Type:
- id: Node unique identifier.
- Type:
integer
- Type:
- inputs: Input Buffer IDs.
- Type:
array - Items:
integer
- Type:
- outputs: Output Buffer IDs.
- Type:
array - Items:
integer
- Type:
- scratchs: Scratch Buffer IDs.
- Type:
array - Items:
integer
- Type:
- subgraph_nodes: All sub-nodes belonging to the
current graph.
- Type:
array - Items:
#/$defs/graph_node
- Type:
- mapping: Specifies if mapped on SW, on HW, on
EpochController, or hybrid SW/HW.
- Type:
string - Enum:
["NODE_UNDEF", "NODE_SW", "NODE_HW", "NODE_SW_HW", "NODE_EC"]
- Type:
- macc: Total MACC number for the current graph
node.
- Type:
integer - Minimum:
0
- Type:
- original_nodes: List of IDs of the original
model nodes (applicable for layers, for example).
- Type:
array - Items: Original model id or name as a string.
May be postfixed with
:<node_part>.- Type:
string
- Type:
- Type:
- exec_time:
- $ref:
#/$defs/exec_time
- $ref:
- description: Description of the graph node (can
be a layer type, for example, or epoch, or …).
- Type:
string
- Type:
- attributes: A map key-value strings where key
is the name of the attribute.
- Type:
object - AdditionalProperties:
string
- Type:
- sw_functions: List of SW functions mapping the
node (Available only on NODE_SW or NODE_SW_HW types).
- Type:
array - Items:
string
- Type:
- name: Name of the node.
- Required:
["name", "id", "inputs", "outputs", "scratchs", "mapping", "macc", "subgraph_nodes"]
graph
Description: Description of a network graph.
- Type:
object - Properties:
- name: Name of the graph.
- Type:
string - Pattern:
^[a-zA-Z0-9_]+$
- Type:
- id: Graph unique identifier.
- Type:
integer
- Type:
- inputs: Graph Input Buffer IDs.
- Type:
array - Items:
integer
- Type:
- outputs: Graph Output Buffer IDs.
- Type:
array - Items:
integer
- Type:
- nodes: A list of graph nodes entries.
- Type:
array - Items:
#/$defs/graph_node
- Type:
- edges: A list of graph edges entries.
- Type:
array - Items:
#/$defs/graph_edge
- Type:
- exec_time:
- $ref:
#/$defs/exec_time
- $ref:
- original_inputs: A list of original inputs.
- Type:
array - Items:
#/$defs/original_details
- Type:
- original_outputs: A list of original outputs.
- Type:
array - Items:
#/$defs/original_details
- Type:
- name: Name of the graph.
- Required:
["name", "id", "inputs", "outputs", "nodes", "edges"]
memory_access
Description: Memory accesses per epoch. (only relevant for Neural-Art)
- Type:
object - Properties:
- node_id: Node graph reference.
- Type:
integer
- Type:
- mpool_id: Memory Pool reference.
- Type:
integer
- Type:
- reads: Number of reads.
- Type:
integer - Minimum:
0
- Type:
- read_cycles: Number of cycles used for read
operations.
- Type:
integer - Minimum:
0
- Type:
- writes: Number of writes.
- Type:
integer - Minimum:
0
- Type:
- write_cycles: Number of cycles used for write
operations.
- Type:
integer - Minimum:
0
- Type:
- node_id: Node graph reference.
aton_exec_t
Description: Detail of the time spent on one epoch during inference on Neural-Art. (only relevant for Neural-Art)
- Type:
object - Properties:
- counters: Array of size 3 containing the time
spent in pre-hw, hw and post-op phases (in cycles)
- Type:
array - Items:
integer
- Type:
- cycles: Total number of cycles spent on an
epoch
- Type:
integer
- Type:
- duration_ms: Time spent on an epoch (in ms)
- Type:
float
- Type:
- percentage: Percentage of the total inference
time spent in this epoch
- Type:
float
- Type:
- cycles_by_macc: (deprecated) Total number of
cycles spent by macc (only applicable for sw epochs)
- Type:
integer
- Type:
- counters: Array of size 3 containing the time
spent in pre-hw, hw and post-op phases (in cycles)
power_estimate
Description: Power-related data per epoch (only relevant for Neural-Art)
- Type:
object - Properties:
- node_id: Node graph reference.
- Type:
integer
- Type:
- ops: Total ops number.
- Type:
integer - Minimum:
0
- Type:
- compute_cycles: Number of cycles used for
computation.
- Type:
integer - Minimum:
0
- Type:
- max_cycles: Maximum cycles.
- Type:
integer - Minimum:
0
- Type:
- average_acc_power_mw: Average Accelerators
(e.g., ATON) power used in mW.
- Type:
integer - Minimum:
0
- Type:
- average_memory_power_mw: Average power (in mW)
used for accessing the memories.
- Type:
integer - Minimum:
0
- Type:
- node_id: Node graph reference.
c_info.json code-generation output report
- r1.0
ST Edge AI Core Technology 2.2.0
Information in this document is provided solely in connection with ST products.
The contents of this document are subject to change without prior notice.
© Copyright STMicroelectronics 2025. All rights reserved. www.st.com