File acc_q8_core.h¶

FileList > acc_q8 > acc_q8_core.h

Go to the source code of this file

AccQ8 — a running 32-bit integer accumulator for Q8 (int8_t) samples. Internally sums each sample into a 32-bit accumulator, which can hold up to 2^24 maximum-magnitude Q8 samples before overflow. Use get() for a non-destructive read, or dump() to read-and-reset in one atomic call. More...

• #include "clib_common.h"
• #include "jm_perf.h"
• #include "dp_state.h"

Classes¶

Public Functions¶

Macros¶

Detailed Description¶

Lifecycle: create -> [step / steps / madd / reset]* -> [get / dump]* -> destroy

>>> from doppler.arith import AccQ8
>>> obj = AccQ8(0)
>>> obj.get()
0

Public Functions Documentation¶

function acc_q8_create¶

Allocate and initialise an AccQ8 accumulator. The accumulator starts at the supplied initial value and accepts Q8 (int8_t) samples via step(), steps(), or madd(). The 32-bit internal register handles up to roughly 16 million max-magnitude samples before wrap — sufficient for all standard DSP block sizes.

acc_q8_state_t * acc_q8_create (
    int32_t acc
) 

Parameters:

• acc Initial accumulator value (default: 0).

Returns:

Heap-allocated state, or NULL on allocation failure.

Note:

Caller must call acc_q8_destroy() when done.

>>> from doppler.arith import AccQ8
>>> obj = AccQ8(10)
>>> obj.get_acc()
10

function acc_q8_destroy¶

Destroy an AccQ8 instance and release all memory. Safe to call with NULL.

void acc_q8_destroy (
    acc_q8_state_t * state
) 

Parameters:

• state May be NULL.

>>> from doppler.arith import AccQ8
>>> obj = AccQ8(0)
>>> obj.destroy()

function acc_q8_dump¶

Return the accumulated value and atomically reset it to zero. Avoids the need for a separate reset() call when processing a stream of non-overlapping blocks.

int32_t acc_q8_dump (
    acc_q8_state_t * state
) 

Parameters:

• state Must be non-NULL.

Returns:

Accumulator value before the reset (int32_t).

>>> from doppler.arith import AccQ8
>>> import numpy as np
>>> obj = AccQ8(0)
>>> obj.steps(np.array([1, 2, 3, 4, 5], dtype=np.int8))
>>> obj.dump()
15
>>> obj.get()
0

function acc_q8_get¶

Return the current accumulated value without resetting it. Mirrors get_acc() but exposed under the name used consistently across all Acc-family objects in the Python API.

int32_t acc_q8_get (
    acc_q8_state_t * state
) 

Parameters:

• state Must be non-NULL.

Returns:

Current accumulator value (int32_t).

>>> from doppler.arith import AccQ8
>>> import numpy as np
>>> obj = AccQ8(0)
>>> obj.steps(np.array([10, 20, 30], dtype=np.int8))
>>> obj.get()
60

function acc_q8_get_acc¶

Read the current accumulator value without modifying it. Permits repeated snapshots of the running sum mid-stream.

int32_t acc_q8_get_acc (
    const acc_q8_state_t * state
) 

Parameters:

• state Must be non-NULL.

>>> from doppler.arith import AccQ8
>>> obj = AccQ8(0)
>>> obj.step(10)
>>> obj.get_acc()
10

function acc_q8_get_state¶

void acc_q8_get_state (
    const acc_q8_state_t * state,
    void * blob
) 

function acc_q8_madd¶

Multiply-accumulate over the shorter of the two arrays. Computes acc += sum( a[i] *b[i] ), widening int8_t inputs to int32_t before accumulation to prevent intermediate overflow.

void acc_q8_madd (
    acc_q8_state_t * state,
    const int8_t * a,
    size_t a_len,
    const int8_t * b,
    size_t b_len
) 

Parameters:

• state Must be non-NULL.
• a First input array (int8_t).
• a_len Number of elements in a.
• b Second input array (int8_t), same length as a.
• b_len Number of elements in b.

>>> from doppler.arith import AccQ8
>>> import numpy as np
>>> obj = AccQ8(0)
>>> a = np.array([10, 20, 30], dtype=np.int8)
>>> b = np.array([1, 2, 3], dtype=np.int8)
>>> obj.madd(a, b)
>>> obj.get()
140

function acc_q8_reset¶

Reset the accumulator to zero, mirroring the post-create state. Always resets to zero regardless of the original constructor value, so it is safe to call at the start of any new accumulation window.

void acc_q8_reset (
    acc_q8_state_t * state
) 

Parameters:

• state Must be non-NULL.

>>> from doppler.arith import AccQ8
>>> obj = AccQ8(0)
>>> obj.step(42)
>>> obj.reset()
>>> obj.get()
0

function acc_q8_set_acc¶

Overwrite the accumulator with a new value. Useful for applying a bias before a new accumulation window, or for restoring a checkpointed accumulator state.

void acc_q8_set_acc (
    acc_q8_state_t * state,
    int32_t val
) 

Parameters:

• state Must be non-NULL.
• val Replacement accumulator value.

>>> from doppler.arith import AccQ8
>>> obj = AccQ8(0)
>>> obj.set_acc(50)
>>> obj.get_acc()
50

function acc_q8_set_state¶

int acc_q8_set_state (
    acc_q8_state_t * state,
    const void * blob
) 

function acc_q8_state_bytes¶

size_t acc_q8_state_bytes (
    const acc_q8_state_t * state
) 

function acc_q8_step¶

Accumulate one Q8 sample into the running total. The sample is sign-extended to 32 bits before addition so negative samples correctly subtract from the accumulator.

JM_FORCEINLINE  JM_HOT void acc_q8_step (
    acc_q8_state_t * state,
    int8_t x
) 

Parameters:

• state Must be non-NULL.
• x Q8 input sample (int8_t, range [-128, 127]).

>>> from doppler.arith import AccQ8
>>> obj = AccQ8(0)
>>> obj.step(10)
>>> obj.step(20)
>>> obj.get()
30

function acc_q8_steps¶

Accumulate a contiguous block of Q8 samples. Equivalent to calling step() n times; the single loop is more amenable to auto-vectorisation than repeated method calls.

void acc_q8_steps (
    acc_q8_state_t * state,
    const int8_t * input,
    size_t n
) 

Parameters:

• state Must be non-NULL.
• input Input array of int8_t samples.
• n Number of samples in input.

>>> from doppler.arith import AccQ8
>>> import numpy as np
>>> obj = AccQ8(0)
>>> obj.steps(np.array([1, 2, 3, 4, 5], dtype=np.int8))
>>> obj.get()
15

Macro Definition Documentation¶

define ACC_Q8_STATE_MAGIC¶

#define ACC_Q8_STATE_MAGIC `DP_FOURCC ('A', 'C', 'C', '8')`

define ACC_Q8_STATE_VERSION¶

#define ACC_Q8_STATE_VERSION `1u`

The documentation for this class was generated from the following file native/inc/acc_q8/acc_q8_core.h