Home /Modules/cdma/cdma_link.h

cdma_link.h

cdma/common/include/cdma_link.h · 111 line(s) · c

/* SPDX-License-Identifier: MIT */
/* SLeeLa CDMA link-level model: AWGN, multipath, RAKE combining, power
 * control, and bit-error-rate evaluation.
 *
 * Reference / link-level simulation model only. This is NOT a conforming
 * baseband, NOT real-time DSP firmware, and conveys NO right to practice any
 * CDMA air-interface patent. See cdma/LEGAL-AND-SCOPE.md.
 */
#ifndef SLEELA_CDMA_LINK_H
#define SLEELA_CDMA_LINK_H

#include <stddef.h>
#include "cdma_common.h"

#ifdef __cplusplus
extern "C" {
#endif

/* Deterministic PRNG (xorshift128+ style) so simulations are reproducible
 * across runs and platforms without depending on the C library's rand(). */
typedef struct {
    unsigned long long s0;
    unsigned long long s1;
} cdma_rng;

/* Seed the generator. Any seed is accepted; 0 is remapped internally so the
 * state is never all-zero. */
void cdma_rng_seed(cdma_rng *rng, unsigned long long seed);

/* Uniform double in [0, 1). */
double cdma_rng_uniform(cdma_rng *rng);

/* Standard normal sample (mean 0, variance 1) via Box-Muller. */
double cdma_rng_gaussian(cdma_rng *rng);

/* A multipath profile: `taps` complex-free real path gains applied at integer
 * chip delays `delay[k]` (in chips). A single tap with gain 1.0 and delay 0 is
 * the ideal flat channel. At most CDMA_MAX_PATHS taps are honored. */
#define CDMA_MAX_PATHS 8
typedef struct {
    size_t count;
    double gain[CDMA_MAX_PATHS];
    size_t delay[CDMA_MAX_PATHS];
} cdma_multipath;

/* Initialize a flat (single-path, unit-gain, zero-delay) channel. */
void cdma_multipath_flat(cdma_multipath *mp);

/* Add one resolvable path. Returns -1 if the profile is full or `delay`
 * is not representable, else 0. */
int cdma_multipath_add(cdma_multipath *mp, double gain, size_t delay);

/* Pass a real chip stream `in` (length `length`) through the multipath
 * channel, writing `out` (also length `length`). Energy spilling past the end
 * of the window is dropped. `out` and `in` must not alias. Returns -1 on bad
 * arguments, else 0. */
int cdma_channel_multipath(double *out, const int *in, size_t length,
                           const cdma_multipath *mp);

/* Add white Gaussian noise with the given standard deviation (per chip) to a
 * real chip stream in place. Returns -1 on bad arguments, else 0. */
int cdma_channel_awgn(double *chips, size_t length, double sigma, cdma_rng *rng);

/* Convert a target Eb/N0 in dB (energy per bit to noise density) into the
 * per-chip noise standard deviation for a BPSK symbol spread over
 * `spreading_factor` unit-energy chips. Returns a non-negative sigma; a very
 * large Eb/N0 yields a small sigma (near-noiseless). */
double cdma_ebn0_to_sigma(double ebn0_db, size_t spreading_factor);

/* RAKE receiver: despread `rx` against `code` at each path delay in `mp` and
 * maximal-ratio-combine the fingers (weighted by path gain). Returns the
 * combined soft correlation; the hard decision is cdma_decide_symbol() of it.
 * Returns 0.0 and sets *ok (if non-NULL) to 0 on bad arguments. */
double cdma_rake_combine(const double *rx, size_t length, const int *code,
                         const cdma_multipath *mp, int *ok);

/* One end-to-end link trial for a single user over a shared channel of
 * `users` interferers:
 *   - each of `users` users spreads a random +/-1 symbol with a distinct
 *     Walsh/OVSF code index (0..users-1),
 *   - per-user transmit amplitude comes from `amplitude[]` (power control),
 *   - the sum passes through `mp` multipath and AWGN at `sigma`,
 *   - user 0 is recovered with a RAKE receiver.
 * Returns 1 if user 0's symbol was recovered correctly, 0 if not, -1 on error.
 * If `codes` is CDMA_CODE_WALSH uses Walsh codes, CDMA_CODE_OVSF uses OVSF. */
typedef enum { CDMA_CODE_WALSH = 0, CDMA_CODE_OVSF = 1 } cdma_code_kind;

int cdma_link_trial(size_t spreading_factor, size_t users,
                    const double *amplitude, cdma_code_kind codes,
                    const cdma_multipath *mp, double sigma, cdma_rng *rng);

/* Run `trials` independent link trials and return the measured bit-error rate
 * for user 0 (errors / trials). Returns a negative value on error. */
double cdma_link_ber(size_t spreading_factor, size_t users,
                     const double *amplitude, cdma_code_kind codes,
                     const cdma_multipath *mp, double sigma,
                     size_t trials, cdma_rng *rng);

/* Closed-loop power control step: given each user's measured received power
 * and a common target, nudge transmit amplitudes toward the target by
 * `step_db` dB per call (a simple fixed-step inner loop). Amplitudes are
 * updated in place and floored at a small positive value. Returns -1 on bad
 * arguments, else 0. */
int cdma_power_control_step(double *amplitude, const double *rx_power,
                            size_t users, double target_power, double step_db);

#ifdef __cplusplus
}
#endif
#endif