File pn_core.h¶

FileList > inc > pn > pn_core.h

Go to the source code of this file

PN component API. More...

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

Classes¶

Public Types¶

Public Functions¶

Macros¶

Detailed Description¶

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

Example:

pn_state_t *obj = pn_create(96, 1, 7);
uint8_t y = pn_step(obj);
pn_destroy(obj);

Public Types Documentation¶

enum pn__core_8h_1a99fb83031ce9923c84392b4e92f956b5¶

PN state.

enum pn__core_8h_1a99fb83031ce9923c84392b4e92f956b5 {
    PN_GALOIS = 0,
    PN_FIBONACCI = 1
};

Allocate with pn_create(). LFSR realization: Galois (internal XOR) or Fibonacci (external XOR).

Public Functions Documentation¶

function pn_create¶

Allocate and initialise a maximal-length-sequence LFSR. The register is seeded from seed and will produce a pseudo-random binary sequence with period 2^length - 1 for any primitivepoly . Both Galois and Fibonacci realizations share the same primitive polynomial and therefore the same period; they differ only in chip ordering/phase.

pn_state_t * pn_create (
    uint64_t poly,
    uint64_t seed,
    uint32_t length,
    int lfsr
) 

Parameters:

• poly Galois feedback tap polynomial (right-shift convention). The LSB is the tap at position 0 (always 1 for a primitive poly); bit k=1 means tap at position k. Default 96 (0x60) is primitive for length=7, giving period 127. The Fibonacci taps are derived automatically so you only supply one value.
• seed Initial LFSR register state; must be non-zero (the all-zero state is a fixed point). Default 1.
• length Register width in bits, 1..64. The sequence period is 2^length - 1 for a primitive polynomial. Default 7.
• lfsr Realization: PN_GALOIS (0, default) or PN_FIBONACCI (1).

Returns:

Heap-allocated state, or NULL on allocation failure.

Note:

Caller must call pn_destroy() when done.

>>> from doppler.wfm import PN
>>> import numpy as np
>>> p = PN(poly=96, seed=1, length=7)
>>> chips = p.generate(127)
>>> chips.dtype
dtype('uint8')
>>> int(chips.sum())   # 64 ones per MLS period (2^(n-1))
64

function pn_destroy¶

Destroy a pn instance and release all memory. Idempotent when state is NULL; safe to call at any point in the lifecycle. After return the pointer is dangling — do not dereference it.

void pn_destroy (
    pn_state_t * state
) 

Parameters:

• state Pointer to heap-allocated state; may be NULL (no-op).

  >>> from doppler.wfm import PN
  >>> p = PN(poly=96, seed=1, length=7)
  >>> p.destroy()   # explicit teardown; no exception
  

function pn_generate¶

Generate n chips intoout and advance the LFSR byn positions. Each element ofout is 0 or 1. Requesting more than one MLS period is valid — the sequence simply wraps around. The Python binding returns a zero-copy NumPy uint8 view over a pre-allocated buffer; copy the result before calling generate again if you need a snapshot.

size_t pn_generate (
    pn_state_t * state,
    size_t n,
    uint8_t * out
) 

Parameters:

• state Initialised PN state returned by pn_create.
• n Number of chips to produce.
• out Output buffer of at least n uint8 elements; each element receives 0 or 1.

Returns:

n (the number of chips written; always equal to the request).

>>> from doppler.wfm import PN
>>> import numpy as np
>>> p = PN(poly=96, seed=1, length=7)
>>> chips = p.generate(127)
>>> chips[:8].tolist()
[1, 0, 0, 0, 0, 0, 1, 1]
>>> int(chips.sum())   # 64 ones per MLS period
64

function pn_generate_max_out¶

size_t pn_generate_max_out (
    pn_state_t * state
) 

function pn_get_state¶

Serialize the LFSR register into blob .

void pn_get_state (
    const pn_state_t * state,
    void * blob
) 

function pn_reset¶

Reset PN to its post-create state. Reloads the LFSR register from the original seed so the sequence restarts from chip 0. Useful for reproducible captures without re-allocating.

void pn_reset (
    pn_state_t * state
) 

Parameters:

• state Must be non-NULL.

  >>> from doppler.wfm import PN
  >>> import numpy as np
  >>> p = PN(poly=96, seed=1, length=7)
  >>> a = p.generate(8).copy()
  >>> p.reset()
  >>> np.array_equal(a, p.generate(8))
  True
  

function pn_set_state¶

Restore the register; DP_OK, or DP_ERR_INVALID if rejected.

int pn_set_state (
    pn_state_t * state,
    const void * blob
) 

function pn_state_bytes¶

Serialized-state byte size.

size_t pn_state_bytes (
    const pn_state_t * state
) 

function pn_step¶

Advance the LFSR one step and return the output chip (0 or 1). Both realizations output the register LSB and then shift right. Galois XORs the tap polynomial on a 1 output bit (internal feedback); Fibonacci computes the parity of all tapped positions and inserts it at the top (external feedback). Same primitive polynomial, same period. Inlined so per-sample modulators (e.g. synth's bpsk/qpsk data source) can pull chips in a tight hot loop without call overhead.

JM_FORCEINLINE uint8_t pn_step (
    pn_state_t * state
) 

Parameters:

• state Must be non-NULL.

Returns:

Output chip: 0 or 1 (register LSB before the shift).

Macro Definition Documentation¶

define PN_STATE_MAGIC¶

#define PN_STATE_MAGIC `DP_FOURCC ('P', 'N', '_', '_')`

define PN_STATE_VERSION¶

#define PN_STATE_VERSION `1u`

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