trau_frame: Add doxygen documentation
diff --git a/include/osmocom/abis/trau_frame.h b/include/osmocom/abis/trau_frame.h
index 64bec2b..f2a7015 100644
--- a/include/osmocom/abis/trau_frame.h
+++ b/include/osmocom/abis/trau_frame.h
@@ -22,17 +22,26 @@
#include <stdint.h>
-/* 21 for FR/EFR, 25 for AMR, 15 for OM, 15 for data, 13 for E-data, 21 idle */
+/*! \defgroup trau_frame TRAU frame handling
+ * @{
+ *
+ * \file trau_frame.h
+ */
+
+/*! \brief Maximum number of C-bits in a TRAU frame:
+ * 21 for FR/EFR, 25 for AMR, 15 for OM, 15 for data, 13 for E-data, 21 idle */
#define MAX_C_BITS 25
-/* 260 for FR/EFR, 256 for AMR, 264 for OM, 288 for E-data */
+/*! \brief Maximum number of D-bits in a TRAU frame:
+ * 260 for FR/EFR, 256 for AMR, 264 for OM, 288 for E-data */
#define MAX_D_BITS 288
-/* for all speech frames */
+/*! \brief Maximum number of T-bits in a TRAU frame for all speech frames */
#define MAX_T_BITS 4
-/* for OM */
+/*! \brief Maximum number of S-bits in a TRAU frame for OM */
#define MAX_S_BITS 6
-/* for E-data */
+/*! \brief Maximum number of M-bits in a TRAU frame for E-data */
#define MAX_M_BITS 2
+/*! \brief a decoded TRAU frame, extracted C/D/T/S/M bits */
struct decoded_trau_frame {
uint8_t c_bits[MAX_C_BITS];
uint8_t d_bits[MAX_D_BITS];
@@ -61,4 +70,6 @@
uint8_t *trau_idle_frame(void);
+/* }@ */
+
#endif /* _TRAU_FRAME_H */
diff --git a/src/trau_frame.c b/src/trau_frame.c
index 6f9fe0b..4d7a74b 100644
--- a/src/trau_frame.c
+++ b/src/trau_frame.c
@@ -29,6 +29,12 @@
#include <osmocom/abis/subchan_demux.h>
#include <osmocom/core/logging.h>
+/*! \addtogroup trau_frame
+ * @{
+ *
+ * \file trau_frame.c
+ */
+
static uint32_t get_bits(const uint8_t *bitbuf, int offset, int num)
{
int i;
@@ -124,7 +130,10 @@
const uint8_t ft_fr_down_bits[] = { 1, 1, 1, 0, 0 };
const uint8_t ft_idle_down_bits[] = { 0, 1, 1, 1, 0 };
-/* modify an uplink TRAU frame so we can send it downlink */
+/*! \brief modify an uplink TRAU frame so we can send it downlink
+ * \param[in,out] fr the uplink TRAU frame that is to be converted
+ * \returns 0 in case of success, < 0 in caes of error
+ */
int trau_frame_up2down(struct decoded_trau_frame *fr)
{
uint8_t cbits5 = get_bits(fr->c_bits, 0, 5);
@@ -211,6 +220,11 @@
memcpy(trau_bits+316, fr->t_bits+0, 4);
}
+/*! \brief encode a TRAU frame from the decoded bits
+ * \param[out] trau_bits output buffer, will contain encoded bits
+ * \param[in] fr decoded trau frame structure
+ * \returns 0 in case of success, < 0 in case of error
+ */
int encode_trau_frame(uint8_t *trau_bits, const struct decoded_trau_frame *fr)
{
uint8_t cbits5 = get_bits(fr->c_bits, 0, 5);
@@ -254,6 +268,8 @@
static uint8_t encoded_idle_frame[TRAU_FRAME_BITS];
static int dbits_initted = 0;
+/*! \brief return pointer to global buffer containing a TRAU idle frame
+ */
uint8_t *trau_idle_frame(void)
{
/* only initialize during the first call */
@@ -284,3 +300,5 @@
}
return encoded_idle_frame;
}
+
+/* }@ */