File gold_core.h¶

FileList > gold > gold_core.h

Go to the source code of this file

Gold code component API. More...

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

Classes¶

Public Functions¶

Macros¶

Detailed Description¶

CCSDS Command Link Gold Code Generator (CCSDS 415.0-G-1, section 5.2.2.4, Figure 5-1): two same-clocked Fibonacci LFSRs ("Register A" and "Register B"), each with its own fixed feedback-tap polynomial, XOR- combined chip-by-chip into a single 1023-chip (length=10) Gold code. The two m-sequences form a genuine "preferred pair" — their XOR family has a strict three-valued periodic autocorrelation/cross-correlation set {-1, -65, 63} (verified: see native/tests/test_gold_core.c). Register A's initial condition is "User dependent" per the standard — varying it walks the 2^length-1 XOR members of the family (1023 at length=10; the seed must be nonzero). The family itself has 2^length+1 members: those plus the two constituent m-sequences, which this generator does not emit because it always XORs both registers. Register B's taps and initial condition are both fixed by the standard.

Lifecycle: create -> generate/reset (repeatable) -> destroy

Example:

gold_state_t *obj = gold_create(934, 350, 567, 73, 10);
uint8_t chips[16];
gold_generate (obj, 16, chips, 16);
gold_destroy(obj);

Public Functions Documentation¶

function gold_create¶

Allocate and initialise a CCSDS-style Gold code generator. Two independent Fibonacci LFSRs of the same length free-run in lock-step; each output chip is the XOR of both registers' current top-bit (stagelength , i.e. bitlength-1 ). Both registers shift left one bit per chip: the new bit (parity of the tapped stages, read__before the shift) enters at stage 1 (bit 0), and the old stage-length bit is discarded after being XORed into the output. The sequence period is2^length - 1 for primitivetaps_a /taps_b . With the CCSDS default polynomials the two m-sequences form a genuine "preferred pair" — their XOR family has a strict three-valued periodic autocorrelation/cross-correlation set{-1, -65, 63} — so varyingseed_a (User dependent per the standard) walks the 2**length-1 XOR members of the Gold-code family while Register B stays fixed.

gold_state_t * gold_create (
    uint64_t taps_a,
    uint64_t seed_a,
    uint64_t taps_b,
    uint64_t seed_b,
    uint32_t length
) 

Parameters:

• taps_a Register A feedback-tap mask; bit k set means stage k+1 is XORed into the feedback. Default 934 (stages 2,3,6,8,9,10 — the CCSDS-fixed Register A polynomial x^10+x^9+x^8+x^6+x^3+x^2+1).
• seed_a Register A initial value; must be non-zero. Per CCSDS this is "User dependent" — each of the 2^length-1 nonzero values selects a different member of the family (1023 distinct codes at length=10, verified in test_gold_core.c). Default 350 is the worked example from CCSDS 415.0-G-1 Figure 5-2 (PN Code Library Table 1, Code Number 365).
• taps_b Register B feedback-tap mask, same bit convention as taps_a. Default 567 (stages 1,2,3,5,6,10 — the CCSDS-fixed Register B polynomial).
• seed_b Register B initial value; must be non-zero. Default 73 (stages 1,4,7 — CCSDS's fixed Register B initial value 1001001000, unique per the standard, not user-selectable).
• length Register width in bits, 1..64. CCSDS command link uses 10 (period 1023). Default 10.

Returns:

Heap-allocated state, or NULL on allocation failure or invalid arguments (zero seed, zero/out-of-range length).

Note:

Caller must call gold_destroy() when done.

>>> from doppler.wfm import Gold
>>> import numpy as np
>>> g = Gold()
>>> chips = g.generate(1023)
>>> chips.dtype
dtype('uint8')
>>> chips[:15].tolist()   # CCSDS Code #365 worked example
[0, 1, 0, 0, 0, 1, 0, 1, 1, 1, 0, 1, 1, 1, 1]
>>> int(chips.sum()), int((1 - chips).sum())   # 512 ones, 511 zeros
(512, 511)

function gold_destroy¶

Destroy a gold 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 gold_destroy (
    gold_state_t * state
) 

Parameters:

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

  >>> from doppler.wfm import Gold
  >>> g = Gold()
  >>> g.destroy()   # explicit teardown; no exception
  

function gold_generate¶

Generate n chips intoout and advance both LFSRs byn positions. Each element ofout is 0 or 1. Requesting more than one 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 gold_generate (
    gold_state_t * state,
    size_t n,
    uint8_t * out,
    size_t max_out
) 

Parameters:

• state Initialised Gold state returned by gold_create.
• n Number of chips to produce.
• out Output buffer of at least n uint8 elements; each element receives 0 or 1.
• max_out Capacity of out in elements. Emission stops there, so the return value is the number actually written.

Returns:

min(n, max_out) chips.

>>> from doppler.wfm import Gold
>>> import numpy as np
>>> g = Gold()
>>> chips = g.generate(1023)
>>> len(chips)
1023

function gold_generate_max_out¶

size_t gold_generate_max_out (
    gold_state_t * state
) 

function gold_get_state¶

Serialize both LFSR registers into blob .

void gold_get_state (
    const gold_state_t * state,
    void * blob
) 

function gold_reset¶

Reset Gold to its post-create state. Reloads both LFSR registers from their original seeds so the sequence restarts from chip 0. Useful for reproducible captures without re-allocating.

void gold_reset (
    gold_state_t * state
) 

Parameters:

• state Must be non-NULL.

  >>> from doppler.wfm import Gold
  >>> import numpy as np
  >>> g = Gold()
  >>> a = g.generate(8).copy()
  >>> g.reset()
  >>> np.array_equal(a, g.generate(8))
  True
  

function gold_set_state¶

Restore both registers; DP_OK, or DP_ERR_INVALID if rejected.

int gold_set_state (
    gold_state_t * state,
    const void * blob
) 

function gold_state_bytes¶

Serialized-state byte size.

size_t gold_state_bytes (
    const gold_state_t * state
) 

function gold_step¶

Advance both LFSRs one chip and return the XOR-combined output chip (0 or 1). Each register outputs its current stage- length bit (the top bit), computes its own feedback (parity of the tapped stages), and shifts left with the feedback bit entering at stage 1. Inlined so composing objects (e.g. a DSSS spreader) can pull chips in a tight hot loop without call overhead — mirrorspn_core.h 'spn_step() .

JM_FORCEINLINE uint8_t gold_step (
    gold_state_t * state
) 

Parameters:

• state Must be non-NULL.

Returns:

Output chip: 0 or 1.

Macro Definition Documentation¶

define GOLD_STATE_MAGIC¶

#define GOLD_STATE_MAGIC `DP_FOURCC ('G', 'O', 'L', 'D')`

define GOLD_STATE_VERSION¶

#define GOLD_STATE_VERSION `1u`

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