From 9c21efe78b5a0ce914c7701ce810ec2662f72e91 Mon Sep 17 00:00:00 2001 From: Mikko Markus Torni Date: Sat, 1 Apr 2017 14:17:04 +0300 Subject: [PATCH] Add comments to many functions --- srslte/lib/fec/cbsegm.c | 18 ++++++++- srslte/lib/fec/convcoder.c | 13 +++++++ srslte/lib/fec/rm_conv.c | 6 +++ srslte/lib/fec/rm_turbo.c | 23 ++++++++++++ srslte/lib/phch/pbch.c | 24 ++++++++++-- srslte/lib/phch/pdcch.c | 77 +++++++++++++++++++++++++++++++++++--- srslte/lib/phch/ra.c | 15 ++++++-- srslte/lib/phch/sch.c | 24 +++++++++++- srslte/lib/utils/bit.c | 16 ++++++++ 9 files changed, 201 insertions(+), 15 deletions(-) diff --git a/srslte/lib/fec/cbsegm.c b/srslte/lib/fec/cbsegm.c index bbd2c174a..26ba1cc6a 100644 --- a/srslte/lib/fec/cbsegm.c +++ b/srslte/lib/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;iR 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/srslte/lib/fec/rm_conv.c b/srslte/lib/fec/rm_conv.c index f994c96fa..402e7708c 100644 --- a/srslte/lib/fec/rm_conv.c +++ b/srslte/lib/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/srslte/lib/fec/rm_turbo.c b/srslte/lib/fec/rm_turbo.c index 5856a4e46..2b2bf0b58 100644 --- a/srslte/lib/fec/rm_turbo.c +++ b/srslte/lib/fec/rm_turbo.c @@ -240,6 +240,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) @@ -284,6 +298,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/srslte/lib/phch/pbch.c b/srslte/lib/phch/pbch.c index 4c5416ab3..c997e96b4 100644 --- a/srslte/lib/phch/pbch.c +++ b/srslte/lib/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/srslte/lib/phch/pdcch.c b/srslte/lib/phch/pdcch.c index 4ab576287..99f56aec3 100644 --- a/srslte/lib/phch/pdcch.c +++ b/srslte/lib/phch/pdcch.c @@ -56,7 +56,13 @@ void srslte_pdcch_set_cfi(srslte_pdcch_t *q, uint32_t cfi) { set_cfi(q, cfi); } -/** Initializes the PDCCH transmitter and receiver */ +/** + * Initializes the PDCCH transmitter and receiver structure + * + * @param[out] q PDCCH structure to initialize + * @param[in] regs PDCCH structure stores a reference to regs + * @param[in] cell PDCCH structure stores a copy of cell + */ int srslte_pdcch_init(srslte_pdcch_t *q, srslte_regs_t *regs, srslte_cell_t cell) { int ret = SRSLTE_ERROR_INVALID_INPUTS; uint32_t i; @@ -172,6 +178,16 @@ void srslte_pdcch_free(srslte_pdcch_t *q) { } +/** + * Calculate DCI locations in UE-specific space and set CFI + * + * @param[out] c Buffer of length max_candidates for storing calculated DCI locations + * @param[in] max_candidates Size of buffer c + * @param[in] cfi Control Format Indicator. Affects length of PDCCH, thus there's more locations + * @param[in] nsubframe Subframe to calculate DCI locations for + * @param[in] rnti Destination RNTI + * @return Number of DCI locations stored in c + */ uint32_t srslte_pdcch_ue_locations(srslte_pdcch_t *q, srslte_dci_location_t *c, uint32_t max_candidates, uint32_t nsubframe, uint32_t cfi, uint16_t rnti) { @@ -229,10 +245,19 @@ uint32_t srslte_pdcch_ue_locations_ncce(uint32_t nof_cce, srslte_dci_location_t /** + * Calculate DCI locations for common search space and set PDCCH CFI + * * 36.213 9.1.1 - * Computes up to max_candidates candidates in the common search space + * First sets Control Format Indicator. + * Then computes up to max_candidates candidates in the common search space * for DCI messages and saves them in the structure pointed by c. * Returns the number of candidates saved in the array c. + * + * @param[inout] q PDCCH information. q->cfi is set to cfi. + * @param[out] c Buffer of length max_candidates for storing calculated DCI locations + * @param[in] max_candidates Size of buffer c + * @param[in] cfi Control Format Indicator. Affects length of PDCCH, thus there's more locations. Also it is copied to q->cfi + * @return Number of DCI locations stored in c */ uint32_t srslte_pdcch_common_locations(srslte_pdcch_t *q, srslte_dci_location_t *c, uint32_t max_candidates, uint32_t cfi) @@ -241,6 +266,14 @@ uint32_t srslte_pdcch_common_locations(srslte_pdcch_t *q, srslte_dci_location_t return srslte_pdcch_common_locations_ncce(q->nof_cce, c, max_candidates); } +/** + * Calculate DCI locations for common search space + * + * @param[out] c Buffer of length max_candidates for storing calculated DCI locations + * @param[in] max_candidates Size of buffer c + * @param[in] cfi Control Format Indicator. Affects length of PDCCH, thus there's more locations + * @return Number of DCI locations stored in c + */ uint32_t srslte_pdcch_common_locations_ncce(uint32_t nof_cce, srslte_dci_location_t *c, uint32_t max_candidates) { uint32_t i, l, L, k; @@ -447,7 +480,12 @@ int srslte_pdcch_extract_llr(srslte_pdcch_t *q, cf_t *sf_symbols, cf_t *ce[SRSLT } - +/** + * Unpacks RNTI into a bit array and XORs with bit array in crc + * + * @param[in] crc Location to XOR unpacked RNTI to + * @param[in] rnti RNTI to unpack and XOR + */ static void crc_set_mask_rnti(uint8_t *crc, uint16_t rnti) { uint32_t i; uint8_t mask[16]; @@ -461,6 +499,14 @@ static void crc_set_mask_rnti(uint8_t *crc, uint16_t rnti) { } } +/** + * Appends CRC to a packed DCI message. Applies convolution encoding. Does not do rate matching. + * + * @param[in] data Unpacked bit array. MSB first. + * @param[in] nof_bits Length of data array + * @param[out] coded_data Output unpacked bit array. Size (nof_bits+16)*3 + * @param[in] rnti Destination RNTI + */ void srslte_pdcch_dci_encode_conv(srslte_pdcch_t *q, uint8_t *data, uint32_t nof_bits, uint8_t *coded_data, uint16_t rnti) { srslte_convcoder_t encoder; int poly[3] = { 0x6D, 0x4F, 0x57 }; @@ -475,8 +521,21 @@ void srslte_pdcch_dci_encode_conv(srslte_pdcch_t *q, uint8_t *data, uint32_t nof srslte_convcoder_encode(&encoder, data, coded_data, nof_bits + 16); } -/** 36.212 5.3.3.2 to 5.3.3.4 - * TODO: UE transmit antenna selection CRC mask +/** + * Appends CRC to a packed DCI message. Applies convolution encoding. Does rate matching. + * + * 36.212 5.3.3.2 to 5.3.3.4 + * @TODO: UE transmit antenna selection CRC mask + * + * @param[in] data Unpacked bit array. MSB first. + * @param[in] nof_bits Length of data array + * @param[in] E Rate match to this size buffer + * @param[out] e Output unpacked bit array. Size E + * @param[in] rnti Destination RNTI + * @return Error code + */ +/** + * */ int srslte_pdcch_dci_encode(srslte_pdcch_t *q, uint8_t *data, uint8_t *e, uint32_t nof_bits, uint32_t E, uint16_t rnti) @@ -512,6 +571,14 @@ int srslte_pdcch_dci_encode(srslte_pdcch_t *q, uint8_t *data, uint8_t *e, uint32 * If the same location is provided in multiple messages, the encoded bits will be overwritten. * * @TODO: Use a bitmask and CFI to ensure message locations are valid and old messages are not overwritten. + * + * @param[in] q PDCCH parameters + * @param[in] msg Input DCI message buffer + * @param[in] location + * @param[in] rnti Destination RNTI + * @param[out] sf_symbols Pointers to all symbols in a subframe for all antenna ports + * @param[in] nsubframe Current subframe index. Affects scrambling and UE-specific DCI message locations + * @param[in] cfi Control Format Indicator */ int srslte_pdcch_encode(srslte_pdcch_t *q, srslte_dci_msg_t *msg, srslte_dci_location_t location, uint16_t rnti, cf_t *sf_symbols[SRSLTE_MAX_PORTS], uint32_t nsubframe, uint32_t cfi) diff --git a/srslte/lib/phch/ra.c b/srslte/lib/phch/ra.c index 3a5b67a40..050130bda 100644 --- a/srslte/lib/phch/ra.c +++ b/srslte/lib/phch/ra.c @@ -268,7 +268,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 */ +/** 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. + */ static int 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; uint32_t bitmask; @@ -381,7 +385,7 @@ static int dl_dci_to_grant_prb_allocation(srslte_ra_dl_dci_t *dci, srslte_ra_dl_ 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) { @@ -415,7 +419,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/srslte/lib/phch/sch.c b/srslte/lib/phch/sch.c index 4cc3da883..6a44954f7 100644 --- a/srslte/lib/phch/sch.c +++ b/srslte/lib/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/srslte/lib/utils/bit.c b/srslte/lib/utils/bit.c index c6a9ef6cc..660cead9c 100644 --- a/srslte/lib/utils/bit.c +++ b/srslte/lib/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;