From d734ef977b3125cac12c288105d607d1302b6420 Mon Sep 17 00:00:00 2001
From: Mikko Markus Torni <mikko.markus.torni@iki.fi>
Date: Sat, 1 Apr 2017 14:17:04 +0300
Subject: [PATCH] Add comments to many functions
---
lib/src/phy/fec/cbsegm.c | 18 +++++++++++++++++-
lib/src/phy/fec/convcoder.c | 13 +++++++++++++
lib/src/phy/fec/rm_conv.c | 6 ++++++
lib/src/phy/fec/rm_turbo.c | 23 +++++++++++++++++++++++
lib/src/phy/phch/pbch.c | 24 ++++++++++++++++++++----
lib/src/phy/phch/ra.c | 14 ++++++++++++--
lib/src/phy/phch/sch.c | 24 ++++++++++++++++++++++--
lib/src/phy/utils/bit.c | 16 ++++++++++++++++
8 files changed, 129 insertions(+), 9 deletions(-)
diff --git a/lib/src/phy/fec/cbsegm.c b/lib/src/phy/fec/cbsegm.c
index 6370abca0..dc4c19209 100644
--- a/lib/src/phy/fec/cbsegm.c
+++ b/lib/src/phy/fec/cbsegm.c
@@ -48,7 +48,13 @@ const uint32_t tc_cb_sizes[SRSLTE_NOF_TC_CB_SIZES] = { 40, 48, 56, 64, 72, 80, 8
4800, 4864, 4928, 4992, 5056, 5120, 5184, 5248, 5312, 5376, 5440, 5504,
5568, 5632, 5696, 5760, 5824, 5888, 5952, 6016, 6080, 6144 };
-/* Calculate Codeblock Segmentation as in Section 5.1.2 of 36.212 */
+/**
+ * Calculate Codeblock Segmentation parameters as in Section 5.1.2 of 36.212
+ *
+ * @param[out] s Output of code block segmentation calculation
+ * @param[in] tbs Input Transport Block Size in bits. CRC's will be added to this
+ * @return Error code
+ */
int srslte_cbsegm(srslte_cbsegm_t *s, uint32_t tbs) {
uint32_t Bp, B, idx1;
int ret;
@@ -104,6 +110,8 @@ int srslte_cbsegm(srslte_cbsegm_t *s, uint32_t tbs) {
/*
* Finds index of minimum K>=long_cb in Table 5.1.3-3 of 36.212
+ *
+ * @return I_TBS or error code
*/
int srslte_cbsegm_cbindex(uint32_t long_cb) {
int j = 0;
@@ -120,6 +128,8 @@ int srslte_cbsegm_cbindex(uint32_t long_cb) {
/*
* Returns Turbo coder interleaver size for Table 5.1.3-3 (36.212) index
+ *
+ * @return Code block size in bits or error code
*/
int srslte_cbsegm_cbsize(uint32_t index) {
if (index < SRSLTE_NOF_TC_CB_SIZES) {
@@ -129,6 +139,12 @@ int srslte_cbsegm_cbsize(uint32_t index) {
}
}
+/**
+ * Check is code block size is valid for LTE Turbo Code
+ *
+ * @param[in] size Size of code block in bits
+ * @return true if Code Block size is allowed
+ */
bool srslte_cbsegm_cbsize_isvalid(uint32_t size) {
for (int i=0;i<SRSLTE_NOF_TC_CB_SIZES;i++) {
if (tc_cb_sizes[i] == size) {
diff --git a/lib/src/phy/fec/convcoder.c b/lib/src/phy/fec/convcoder.c
index 260ce1e33..bc71d63f1 100644
--- a/lib/src/phy/fec/convcoder.c
+++ b/lib/src/phy/fec/convcoder.c
@@ -33,6 +33,19 @@
#include "srslte/phy/fec/convcoder.h"
#include "parity.h"
+/**
+ * Convolution encodes according to given parameters.
+ *
+ * q->R is rate
+ * q->tail_biting enables tail biting
+ * q->K is a parameter for tail biting
+ *
+ * @param[in] q Convolution coder parameters
+ * @param[in] input Unpacked bit array. Size frame_length
+ * @param[out] output Unpacked bit array. Size q->R*frame_length if q->tail_biting, else q->R*(frame_length + q->K - 1)
+ * @param[in] frame_length Number of bits in input_array
+ * @return Number of bits in output
+ */
int srslte_convcoder_encode(srslte_convcoder_t *q, uint8_t *input, uint8_t *output, uint32_t frame_length) {
uint32_t sr;
uint32_t i,j;
diff --git a/lib/src/phy/fec/rm_conv.c b/lib/src/phy/fec/rm_conv.c
index ddf38d274..9c02d97e3 100644
--- a/lib/src/phy/fec/rm_conv.c
+++ b/lib/src/phy/fec/rm_conv.c
@@ -39,6 +39,12 @@ uint8_t RM_PERM_CC_INV[NCOLS] =
{ 16, 0, 24, 8, 20, 4, 28, 12, 18, 2, 26, 10, 22, 6, 30, 14, 17, 1, 25, 9,
21, 5, 29, 13, 19, 3, 27, 11, 23, 7, 31, 15 };
+/**
+ * Rate matching for convolution encoder
+ *
+ * @param[in] input Unpacked bit array. Size in_len
+ * @param[output] output Unpacked bit array. Size out_len <= in_len
+ */
int srslte_rm_conv_tx(uint8_t *input, uint32_t in_len, uint8_t *output, uint32_t out_len) {
uint8_t tmp[3 * NCOLS * NROWS_MAX];
diff --git a/lib/src/phy/fec/rm_turbo.c b/lib/src/phy/fec/rm_turbo.c
index 312d5c930..23929fff3 100644
--- a/lib/src/phy/fec/rm_turbo.c
+++ b/lib/src/phy/fec/rm_turbo.c
@@ -245,6 +245,20 @@ void srslte_rm_turbo_gentables() {
}
+/**
+ * Rate matching for LTE Turbo Coder
+ *
+ * @param[out] w_buff Preallocated softbuffer
+ * @param[in] systematic Input code block in a byte array
+ * @param[in] parity Input code turbo coder parity bits in a byte array
+ * @param[out] output Rate matched output array of size out_len
+ * @param out_len Output buffer size to be filled with as many FEC bits as fit
+ * @param w_offset Start writing to output at this bit offset
+ * @param cb_idx Code block index. Used to lookup interleaver parameters
+ * @param rv_idx Redundancy Version Index. Indexed offset of FEC bits to copy
+ *
+ * @return Error code
+ */
int srslte_rm_turbo_tx_lut(uint8_t *w_buff, uint8_t *systematic, uint8_t *parity, uint8_t *output,
uint32_t cb_idx, uint32_t out_len,
uint32_t w_offset, uint32_t rv_idx)
@@ -289,6 +303,15 @@ int srslte_rm_turbo_tx_lut(uint8_t *w_buff, uint8_t *systematic, uint8_t *parity
}
}
+/**
+ * Undoes rate matching for LTE Turbo Coder. Expands rate matched buffer to full size buffer.
+ *
+ * @param[in] input Input buffer of size in_len
+ * @param[out] output Output buffer of size 3*srslte_cbsegm_cbsize(cb_idx)+12
+ * @param[in] cb_idx Code block table index
+ * @param[in] rv_idx Redundancy Version from DCI control message
+ * @return Error code
+ */
int srslte_rm_turbo_rx_lut(int16_t *input, int16_t *output, uint32_t in_len, uint32_t cb_idx, uint32_t rv_idx)
{
diff --git a/lib/src/phy/phch/pbch.c b/lib/src/phy/phch/pbch.c
index bff7b0619..783ae1e04 100644
--- a/lib/src/phy/phch/pbch.c
+++ b/lib/src/phy/phch/pbch.c
@@ -111,6 +111,10 @@ int srslte_pbch_cp(cf_t *input, cf_t *output, srslte_cell_t cell, bool put) {
* Returns the number of symbols written to slot1_data
*
* 36.211 10.3 section 6.6.4
+ *
+ * @param[in] pbch PBCH complex symbols to place in slot1_data
+ * @param[out] slot1_data Complex symbol buffer for slot1
+ * @param[in] cell Cell configuration
*/
int srslte_pbch_put(cf_t *pbch, cf_t *slot1_data, srslte_cell_t cell) {
return srslte_pbch_cp(pbch, slot1_data, cell, true);
@@ -122,6 +126,10 @@ int srslte_pbch_put(cf_t *pbch, cf_t *slot1_data, srslte_cell_t cell) {
* Returns the number of symbols written to pbch
*
* 36.211 10.3 section 6.6.4
+ *
+ * @param[in] slot1_data Complex symbols for slot1
+ * @param[out] pbch Extracted complex PBCH symbols
+ * @param[in] cell Cell configuration
*/
int srslte_pbch_get(cf_t *slot1_data, cf_t *pbch, srslte_cell_t cell) {
return srslte_pbch_cp(slot1_data, pbch, cell, false);
@@ -244,8 +252,12 @@ void srslte_pbch_free(srslte_pbch_t *q) {
}
-/** Unpacks MIB from PBCH message.
- * msg buffer must be 24 byte length at least
+/**
+ * Unpacks MIB from PBCH message.
+ *
+ * @param[in] msg PBCH in an unpacked bit array of size 24
+ * @param[out] sfn System frame number
+ * @param[out] cell MIB information about PHICH and system bandwidth will be saved here
*/
void srslte_pbch_mib_unpack(uint8_t *msg, srslte_cell_t *cell, uint32_t *sfn) {
int phich_res;
@@ -289,8 +301,12 @@ void srslte_pbch_mib_unpack(uint8_t *msg, srslte_cell_t *cell, uint32_t *sfn) {
}
}
-/** Unpacks MIB from PBCH message.
- * msg buffer must be 24 byte length at least
+/**
+ * Packs MIB to PBCH message.
+ *
+ * @param[out] payload Output unpacked bit array of size 24
+ * @param[in] sfn System frame number
+ * @param[in] cell Cell configuration to be encoded in MIB
*/
void srslte_pbch_mib_pack(srslte_cell_t *cell, uint32_t sfn, uint8_t *payload) {
int bw, phich_res = 0;
diff --git a/lib/src/phy/phch/ra.c b/lib/src/phy/phch/ra.c
index cd07e997f..976a669f4 100644
--- a/lib/src/phy/phch/ra.c
+++ b/lib/src/phy/phch/ra.c
@@ -295,6 +295,11 @@ uint32_t srslte_ra_dl_grant_nof_re(srslte_ra_dl_grant_t *grant, srslte_cell_t ce
return nof_re;
}
+/** Compute PRB allocation for Downlink as defined in 7.1.6 of 36.213
+ * Decode dci->type?_alloc to grant
+ * This function only reads dci->type?_alloc and dci->alloc_type fields.
+ * This function only writes grant->prb_idx and grant->nof_prb.
+ */
/** Compute PRB allocation for Downlink as defined in 7.1.6 of 36.213 */
int srslte_ra_dl_dci_to_grant_prb_allocation(srslte_ra_dl_dci_t *dci, srslte_ra_dl_grant_t *grant, uint32_t nof_prb) {
int i, j;
@@ -427,7 +432,7 @@ int srslte_ra_dl_dci_to_grant_prb_allocation(srslte_ra_dl_dci_t *dci, srslte_ra_
return SRSLTE_SUCCESS;
}
-static int dl_fill_ra_mcs(srslte_ra_mcs_t *mcs, uint32_t nprb) {
+int dl_fill_ra_mcs(srslte_ra_mcs_t *mcs, uint32_t nprb) {
uint32_t i_tbs = 0;
int tbs = -1;
if (mcs->idx < 10) {
@@ -461,7 +466,12 @@ static int dl_fill_ra_mcs(srslte_ra_mcs_t *mcs, uint32_t nprb) {
return tbs;
}
-/* Modulation order and transport block size determination 7.1.7 in 36.213 */
+/* Modulation order and transport block size determination 7.1.7 in 36.213
+ * This looks at DCI type, type of RNTI and reads fields dci->type?_alloc, dci->mcs_idx,
+ * dci->dci_is_1a and dci->dci_is_1c
+ * Reads global variable last_dl_tbs if mcs>=29
+ * Writes global variable last_dl_tbs if mcs<29
+ * */
static int dl_dci_to_grant_mcs(srslte_ra_dl_dci_t *dci, srslte_ra_dl_grant_t *grant, bool crc_is_crnti) {
uint32_t n_prb=0;
int tbs = -1;
diff --git a/lib/src/phy/phch/sch.c b/lib/src/phy/phch/sch.c
index b7a5cfc28..ba4c8951b 100644
--- a/lib/src/phy/phch/sch.c
+++ b/lib/src/phy/phch/sch.c
@@ -314,8 +314,18 @@ static int encode_tb(srslte_sch_t *q,
-/* Decode a transport block according to 36.212 5.3.2
+/**
+ * Decode a transport block according to 36.212 5.3.2
*
+ * @param[in] q
+ * @param[inout] softbuffer Initialized softbuffer
+ * @param[in] cb_segm Code block segmentation parameters
+ * @param[in] e_bits Input transport block
+ * @param[in] Qm Modulation type
+ * @param[in] rv Redundancy Version. Indicates which part of FEC bits is in input buffer
+ * @param[out] softbuffer Initialized output softbuffer
+ * @param[out] data Decoded transport block
+ * @return negative if error in parameters or CRC error in decoding
*/
static int decode_tb(srslte_sch_t *q,
srslte_softbuffer_rx_t *softbuffer, srslte_cbsegm_t *cb_segm,
@@ -351,7 +361,7 @@ static int decode_tb(srslte_sch_t *q,
if (cb_segm->C > softbuffer->max_cb) {
fprintf(stderr, "Error number of CB (%d) exceeds soft buffer size (%d CBs)\n", cb_segm->C, softbuffer->max_cb);
- return -1;
+ return SRSLTE_ERROR;
}
if (cb_segm->C>0) {
@@ -489,6 +499,16 @@ int srslte_dlsch_decode(srslte_sch_t *q, srslte_pdsch_cfg_t *cfg, srslte_softbuf
e_bits, data);
}
+/**
+ * Encode transport block. Segments into code blocks, adds channel coding, and does rate matching.
+ *
+ * @param[in] q Initialized
+ * @param[in] cfg Encoding parameters
+ * @param[inout] softbuffer Initialized softbuffer
+ * @param[in] data Byte array of data. Size is implicit in cfg->cb_segm
+ * @param e_bits
+ * @return Error code
+ */
int srslte_dlsch_encode(srslte_sch_t *q, srslte_pdsch_cfg_t *cfg, srslte_softbuffer_tx_t *softbuffer,
uint8_t *data, uint8_t *e_bits)
{
diff --git a/lib/src/phy/utils/bit.c b/lib/src/phy/utils/bit.c
index a5fcb400f..9ef53c35a 100644
--- a/lib/src/phy/utils/bit.c
+++ b/lib/src/phy/utils/bit.c
@@ -209,6 +209,15 @@ bitarray_copy(const unsigned char *src_org, int src_offset, int src_len,
}
}
+/**
+ * Copy bits from src to dst, with offsets and length in bits
+ *
+ * @param[out] dst Output array
+ * @param[in] src Input array
+ * @param dst_offset Output array write offset in bits
+ * @param src_offset Input array read offset in bits
+ * @param nof_bits Number of bits to copy
+ */
void srslte_bit_copy(uint8_t *dst, uint32_t dst_offset, uint8_t *src, uint32_t src_offset, uint32_t nof_bits)
{
static const uint8_t mask_dst[] =
@@ -247,6 +256,13 @@ void srslte_bit_unpack_l(uint64_t value, uint8_t **bits, int nof_bits)
*bits += nof_bits;
}
+/**
+ * Unpacks nof_bits from LSBs of value in MSB order to *bits. Advances pointer past unpacked bits.
+ *
+ * @param[in] value nof_bits lowest order bits will be unpacked in MSB order
+ * @param[in] nof_bits Number of bits to unpack
+ * @param[out] bits Points to buffer pointer. The buffer pointer will be advanced by nof_bits
+ */
void srslte_bit_unpack(uint32_t value, uint8_t **bits, int nof_bits)
{
int i;
--
GitLab