ecc

Documentation

Overview

Package ecc implements the JAB Code forward-error-correction stage: systematic LDPC coding (hard- and soft-decision), the fixed byte (de)interleaving permutation, and the seeded PRNG they share. It is wire-compatible with the JAB Code reference library.

Index

• Constants
• func DecodeLDPCHard(data []byte, wc, wr int) (dec []byte, ok bool)
• func DecodeLDPCHardVariant(data []byte, wc, wr int, variant wire.Variant) (dec []byte, ok bool)
• func DecodeLDPCSigned(llr []float64, wc, wr int) (dec []byte, ok bool)
• func DecodeLDPCSoft(rel []float64, hard []byte, wc, wr int) (dec []byte, ok bool)
• func DecodeLDPCSoftVariant(rel []float64, hard []byte, wc, wr int, variant wire.Variant) (dec []byte, ok bool)
• func Deinterleave(data []byte)
• func DeinterleaveFloat(data []float64)
• func DeinterleaveFloatCopyVariant(data []float64, variant wire.Variant) []float64
• func DeinterleaveFloatVariant(data []float64, variant wire.Variant)
• func DeinterleavePermutation(n int, variant wire.Variant) []uint32
• func DeinterleaveVariant(data []byte, variant wire.Variant)
• func EncodeLDPC(data []byte, wc, wr int) []byte
• func EncodeLDPCVariant(data []byte, wc, wr int, variant wire.Variant) []byte
• func Interleave(data []byte)
• func InterleaveVariant(data []byte, variant wire.Variant)
• func LDPCSyndromeWeight(data []byte, wc, wr int) (unsatisfied, checks int, valid bool)
• func LeadingPivot(i, wr int) int
• func PivotSweep(wc, wr, capacity int, variant wire.Variant) []uint16
• type HardBlockLayout
  • func HardBlockSplit(length, wc, wr int) HardBlockLayout
  • func (layout HardBlockLayout) TrailingGrossSub() int
• type ParityRowLayout
  • func ParityRows(wc, wr, capacity int, variant wire.Variant) (ParityRowLayout, bool)

Constants

const ParityRowPad = math.MaxUint32

ParityRowPad marks an unused slot in a flattened parity row. A consumer must skip it rather than fold it in: repeating a real column would cancel in the row's parity but would still double-count that column anywhere the rows are tallied per bit.

const PivotNone = 0xFFFF

PivotNone marks a parity row the sweep found dependent on earlier rows. It is outside the column range any supported code can reach, so a transcript can carry it in the same field as a real pivot column.

Functions

func DecodeLDPCHard

func DecodeLDPCHard(data []byte, wc, wr int) (dec []byte, ok bool)

DecodeLDPCHard decodes a gross LDPC codeword of bit-per-byte values using hard-decision decoding and returns the recovered net message. It handles sub-blocks the same way as encoding; data is not modified.

A best-effort correction is attempted when a sub-block's syndrome fails; ok reports whether every sub-block satisfies its parity checks afterwards. When ok is false the message is known to be unreliable - the correction gave up, and parsing it can still succeed with a corrupted payload.

func DecodeLDPCHardVariant

func DecodeLDPCHardVariant(data []byte, wc, wr int, variant wire.Variant) (dec []byte, ok bool)

DecodeLDPCHardVariant is DecodeLDPCHard under the selected wire-format variant.

func DecodeLDPCSigned

func DecodeLDPCSigned(llr []float64, wc, wr int) (dec []byte, ok bool)

DecodeLDPCSigned decodes a gross codeword from additive signed channel evidence, positive for bit zero and negative for bit one. The evidence is consumed directly by belief propagation without the single-frame soft path's in-block variance normalization. The input is retained evidence and is never modified; hard decisions and all decoder work buffers are private copies.

func DecodeLDPCSoft

func DecodeLDPCSoft(rel []float64, hard []byte, wc, wr int) (dec []byte, ok bool)

DecodeLDPCSoft runs soft-decision (belief-propagation) decoding of a gross codeword: hard holds the initial hard bit decisions (one bit per byte) and rel the matching non-negative per-bit reliabilities. It returns the recovered net message (written to the front of hard) and whether every sub-block satisfied its parity checks afterwards. rel and hard must share the gross length; both are modified in place.

The data path calls this only after hard-decision decoding gives up, so a clean capture never reaches it.

func DecodeLDPCSoftVariant

func DecodeLDPCSoftVariant(rel []float64, hard []byte, wc, wr int, variant wire.Variant) (dec []byte, ok bool)

DecodeLDPCSoftVariant is DecodeLDPCSoft under the selected wire-format variant.

func Deinterleave

func Deinterleave(data []byte)

Deinterleave inverts Interleave in place.

func DeinterleaveFloat

func DeinterleaveFloat(data []float64)

DeinterleaveFloat applies the byte-deinterleaving permutation to a parallel slice, so soft-decision per-bit reliabilities track the bits they describe through the same shuffle.

func DeinterleaveFloatCopyVariant

func DeinterleaveFloatCopyVariant(data []float64, variant wire.Variant) []float64

DeinterleaveFloatCopyVariant returns a deinterleaved copy while retaining the neutral input order for another wire variant.

func DeinterleaveFloatVariant

func DeinterleaveFloatVariant(data []float64, variant wire.Variant)

DeinterleaveFloatVariant applies the selected variant's byte-deinterleaving permutation to a parallel float slice.

func DeinterleavePermutation

func DeinterleavePermutation(n int, variant wire.Variant) []uint32

DeinterleavePermutation returns where deinterleaving sends each element of a sequence of the given length: out[perm[i]] = data[i].

It depends only on the length and the variant, never on the data, so a consumer that applies the same shuffle repeatedly - or reproduces it somewhere the sequence itself never travels - builds it once and keeps it. The shuffle is serial by construction: each swap decides which element the next one may still move.

func DeinterleaveVariant

func DeinterleaveVariant(data []byte, variant wire.Variant)

DeinterleaveVariant is Deinterleave under the selected wire-format variant.

func EncodeLDPC

func EncodeLDPC(data []byte, wc, wr int) []byte

EncodeLDPC applies systematic LDPC encoding to a message of bit-per-byte values, returning the gross (parity followed by message) codeword, also as bit-per-byte values. wc and wr are the column and row weights of the parity-check matrix. Large messages are split into sub-blocks, exactly as the reference encoder does.

func EncodeLDPCVariant

func EncodeLDPCVariant(data []byte, wc, wr int, variant wire.Variant) []byte

EncodeLDPCVariant is EncodeLDPC under the selected wire-format variant.

func Interleave

func Interleave(data []byte)

Interleave shuffles data in place using a deterministic back-to-front Fisher-Yates pass driven by the seeded generator.

func InterleaveVariant

func InterleaveVariant(data []byte, variant wire.Variant)

InterleaveVariant is Interleave under the selected wire-format variant.

func LDPCSyndromeWeight

func LDPCSyndromeWeight(data []byte, wc, wr int) (unsatisfied, checks int, valid bool)

LDPCSyndromeWeight measures a complete gross message codeword without correcting or mutating it. It returns the number of unsatisfied independent parity checks, the number checked, and whether the code parameters and gross length form a legal data codeword.

func LeadingPivot

func LeadingPivot(i, wr int) int

LeadingPivot is the pivot column of parity row i in the leading Gallager block, where the block holds capacity/wr rows of wr consecutive ones.

Those rows have pairwise disjoint support, so none of them is ever modified before the sweep reaches it and each pivots at its own first column. A transcript therefore stores only the rows the permuted copies contribute.

func PivotSweep

func PivotSweep(wc, wr, capacity int, variant wire.Variant) []uint16

PivotSweep reports the pivot column each parity row of a message code takes during systematic reduction, or PivotNone where the row proved dependent.

The sweep is the only expensive part of building a decoder parity-check matrix, and it depends on nothing but the four arguments. Exposing it lets a consumer precompute the sequence once and rebuild the systematic matrix from the sparse Gallager source alone, which is cheap.

Types

type HardBlockLayout

type HardBlockLayout struct {
	Pg, Pn   int
	Blocks   int
	GrossSub int
	NetSub   int
	WC, WR   int
	Uniform  bool
	// contains filtered or unexported fields
}

HardBlockLayout is how one gross codeword splits for hard decoding: Blocks sub-blocks of GrossSub bits each, carrying NetSub message bits, correcting under the wc/wr the layout resolved.

Uniform reports that every sub-block has the same length, so all of them share one parity-check matrix. A non-uniform layout rebuilds the matrix for its shorter trailing block, which a batched corrector cannot express.

func HardBlockSplit

func HardBlockSplit(length, wc, wr int) HardBlockLayout

HardBlockSplit resolves the sub-block layout a gross codeword of the given bit length decodes under. It is the one place the split is derived, so a corrector that batches the blocks elsewhere cannot drift from the decoder.

func (HardBlockLayout) TrailingGrossSub

func (layout HardBlockLayout) TrailingGrossSub() int

TrailingGrossSub is the length of the trailing sub-block on a layout that did not divide evenly: the uniform length rounds down to a multiple of the row weight, and the last block absorbs everything the others left.

type ParityRowLayout

type ParityRowLayout struct {
	Rows   []uint32
	Degree int
	Height int
	Rank   int
}

ParityRowLayout is one code's parity-check matrix flattened for a consumer that cannot follow Go slices of slices: Rows holds Degree column indexes per parity row, so row j starts at j*Degree, and rows shorter than the maximum degree are padded with ParityRowPad.

func ParityRows

func ParityRows(wc, wr, capacity int, variant wire.Variant) (ParityRowLayout, bool)

ParityRows exposes the decoder's parity-check matrix in flattened form. It is the same cached matrix the host decoder uses, so a device corrector built from it is solving the identical system.