update/extend doxygen documentation

It's a pity that even with this patch we still are fare away from having
the whole API documented.  However, at least we have a more solid
foundation.  Updates not only extend the documentation, but also make
sure it is rendered properly in the doxygen HTML.

Change-Id: I1344bd1a6869fb00de7c1899a8db93bba9bafce3

1 files changed, 100 insertions, 0 deletions

diff --git a/src/gsm/gsm0808.c b/src/gsm/gsm0808.c
index 04c2f018..c96dc779 100644
--- a/src/gsm/gsm0808.c
+++ b/src/gsm/gsm0808.c
@@ -24,9 +24,22 @@
 #include <osmocom/gsm/protocol/gsm_08_08.h>
 #include <osmocom/gsm/gsm48.h>
 
+/*! \addtogroup gsm0808
+ *  @{
+ *  \brief Helper functions regarding the TS 08.08 / 48.008 A interface
+ */
+
 #define BSSMAP_MSG_SIZE 512
 #define BSSMAP_MSG_HEADROOM 128
 
+/*! \brief Create "Complete L3 Info" for AoIP
+ *  \param[in] msg_l3 msgb containing Layer 3 Message
+ *  \param[in] nc Mobile Network Code
+ *  \param[in] cc Mobile Country Code
+ *  \param[in] lac Location Area Code
+ *  \param[in] _ci Cell Identity
+ *  \param[in] scl Speech Codec List
+ *  \returns callee-allocated msgb with Complete L3 Info message */
 struct msgb *gsm0808_create_layer3_aoip(const struct msgb *msg_l3, uint16_t nc,
 					uint16_t cc, int lac, uint16_t _ci,
 					const struct gsm0808_speech_codec_list
@@ -68,12 +81,21 @@ struct msgb *gsm0808_create_layer3_aoip(const struct msgb *msg_l3, uint16_t nc,
 	return msg;
 }
 
+/*! \brief Create "Complete L3 Info" for A
+ *  \param[in] msg_l3 msgb containing Layer 3 Message
+ *  \param[in] nc Mobile Network Code
+ *  \param[in] cc Mobile Country Code
+ *  \param[in] lac Location Area Code
+ *  \param[in] _ci Cell Identity
+ *  \returns callee-allocated msgb with Complete L3 Info message */
 struct msgb *gsm0808_create_layer3(struct msgb *msg_l3, uint16_t nc,
 				   uint16_t cc, int lac, uint16_t _ci)
 {
 	return gsm0808_create_layer3_aoip(msg_l3, nc, cc, lac, _ci, NULL);
 }
 
+/*! \brief Create BSSMAP RESET message
+ *  \returns callee-allocated msgb with BSSMAP Reset message */
 struct msgb *gsm0808_create_reset(void)
 {
 	uint8_t cause = GSM0808_CAUSE_EQUIPMENT_FAILURE;
@@ -89,6 +111,8 @@ struct msgb *gsm0808_create_reset(void)
 	return msg;
 }
 
+/*! \brief Create BSSMAP RESET ACK message
+ *  \returns callee-allocated msgb with BSSMAP Reset ACK message */
 struct msgb *gsm0808_create_reset_ack(void)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -102,6 +126,8 @@ struct msgb *gsm0808_create_reset_ack(void)
 	return msg;
 }
 
+/*! \brief Create BSSMAP Clear Complete message
+ *  \returns callee-allocated msgb with BSSMAP Clear Complete message */
 struct msgb *gsm0808_create_clear_complete(void)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -116,6 +142,9 @@ struct msgb *gsm0808_create_clear_complete(void)
 	return msg;
 }
 
+/*! \brief Create BSSMAP Clear Command message
+ *  \param[in] reason TS 08.08 cause value
+ *  \returns callee-allocated msgb with BSSMAP Clear Command message */
 struct msgb *gsm0808_create_clear_command(uint8_t reason)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -130,6 +159,10 @@ struct msgb *gsm0808_create_clear_command(uint8_t reason)
 	return msg;
 }
 
+/*! \brief Create BSSMAP Cipher Mode Command message
+ *  \param[in] ei Mandatory Encryption Information
+ *  \param[in] cipher_response_mode optional 1-byte Cipher Response Mode
+ *  \returns callee-allocated msgb with BSSMAP Cipher Mode Command message */
 struct msgb *gsm0808_create_cipher(const struct gsm0808_encrypt_info *ei,
 				   const uint8_t *cipher_response_mode)
 {
@@ -163,6 +196,10 @@ struct msgb *gsm0808_create_cipher(const struct gsm0808_encrypt_info *ei,
 	return msg;
 }
 
+/*! \brief Create BSSMAP Cipher Mode Complete message
+ *  \param[in] layer3 L3 Message to be included
+ *  \param[in] alg_id Chosen Encrpytion Algorithm
+ *  \returns callee-allocated msgb with BSSMAP Cipher Mode Complete message */
 struct msgb *gsm0808_create_cipher_complete(struct msgb *layer3, uint8_t alg_id)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -188,6 +225,9 @@ struct msgb *gsm0808_create_cipher_complete(struct msgb *layer3, uint8_t alg_id)
 	return msg;
 }
 
+/*! \brief Create BSSMAP Cipher Mode Reject message
+ *  \param[in] reason TS 08.08 cause value
+ *  \returns callee-allocated msgb with BSSMAP Cipher Mode Reject message */
 struct msgb *gsm0808_create_cipher_reject(uint8_t cause)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -202,6 +242,12 @@ struct msgb *gsm0808_create_cipher_reject(uint8_t cause)
 	return msg;
 }
 
+/*! \brief Create BSSMAP Classmark Update message
+ *  \param[in] cm2 Classmark 2
+ *  \param[in] cm2_len length (in octets) of \a cm2
+ *  \param[in] cm3 Classmark 3
+ *  \param[in] cm3_len length (in octets) of \a cm3
+ *  \returns callee-allocated msgb with BSSMAP Classmark Update message */
 struct msgb *gsm0808_create_classmark_update(const uint8_t *cm2, uint8_t cm2_len,
 					     const uint8_t *cm3, uint8_t cm3_len)
 {
@@ -221,6 +267,9 @@ struct msgb *gsm0808_create_classmark_update(const uint8_t *cm2, uint8_t cm2_len
 	return msg;
 }
 
+/*! \brief Create BSSMAP SAPI N Reject message
+ *  \param[in] link_id Link Identifier
+ *  \returns callee-allocated msgb with BSSMAP SAPI N Reject message */
 struct msgb *gsm0808_create_sapi_reject(uint8_t link_id)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -237,6 +286,13 @@ struct msgb *gsm0808_create_sapi_reject(uint8_t link_id)
 	return msg;
 }
 
+/*! \brief Create BSSMAP Assignment Request message
+ *  \param[in] ct Channel Type
+ *  \param[in] cic Circuit Identity Code (Classic A only)
+ *  \param[in] ss Socket Address of MSC-side RTP socket (AoIP only)
+ *  \param[in] scl Speech Codec List (AoIP only)
+ *  \param[in] ci Call Identifier (Optional, LCLS)
+ *  \returns callee-allocated msgb with BSSMAP Assignment Request message */
 struct msgb *gsm0808_create_ass(const struct gsm0808_channel_type *ct,
 				const uint16_t *cic,
 				const struct sockaddr_storage *ss,
@@ -293,6 +349,15 @@ struct msgb *gsm0808_create_ass(const struct gsm0808_channel_type *ct,
 	return msg;
 }
 
+/*! \brief Create BSSMAP Assignment Completed message
+ *  \param[in] rr_cause GSM 04.08 RR Cause value
+ *  \param[in] chosen_channel Chosen Channel
+ *  \param[in] encr_alg_id Encryption Algorithm ID
+ *  \param[in] speech_mode Speech Mode
+ *  \param[in] ss Socket Address of BSS-side RTP socket
+ *  \param[in] sc Speech Codec (current)
+ *  \param[in] scl Speech Codec List (permitted)
+ *  \returns callee-allocated msgb with BSSMAP Assignment Complete message */
 struct msgb *gsm0808_create_ass_compl(uint8_t rr_cause, uint8_t chosen_channel,
 				      uint8_t encr_alg_id, uint8_t speech_mode,
 				      const struct sockaddr_storage *ss,
@@ -342,6 +407,12 @@ struct msgb *gsm0808_create_ass_compl(uint8_t rr_cause, uint8_t chosen_channel,
 	return msg;
 }
 
+/*! \brief Create BSSMAP Assignment Completed message
+ *  \param[in] rr_cause GSM 04.08 RR Cause value
+ *  \param[in] chosen_channel Chosen Channel
+ *  \param[in] encr_alg_id Encryption Algorithm ID
+ *  \param[in] speech_mode Speech Mode
+ *  \returns callee-allocated msgb with BSSMAP Assignment Complete message */
 struct msgb *gsm0808_create_assignment_completed(uint8_t rr_cause,
 						 uint8_t chosen_channel,
 						 uint8_t encr_alg_id,
@@ -351,6 +422,11 @@ struct msgb *gsm0808_create_assignment_completed(uint8_t rr_cause,
 					speech_mode, NULL, NULL, NULL);
 }
 
+/*! \brief Create BSSMAP Assignment Failure message
+ *  \param[in] cause BSSMAP Cause value
+ *  \param[in] rr_cause GSM 04.08 RR Cause value
+ *  \param[in] scl Optional Speech Cdec List (AoIP)
+ *  \returns callee-allocated msgb with BSSMAP Assignment Failure message */
 struct msgb *gsm0808_create_ass_fail(uint8_t cause, const uint8_t *rr_cause,
 				     const struct gsm0808_speech_codec_list
 				     *scl)
@@ -380,12 +456,19 @@ struct msgb *gsm0808_create_ass_fail(uint8_t cause, const uint8_t *rr_cause,
 	return msg;
 }
 
+/*! \brief Create BSSMAP Assignment Failure message
+ *  \param[in] cause BSSMAP Cause value
+ *  \param[in] rr_cause GSM 04.08 RR Cause value
+ *  \returns callee-allocated msgb with BSSMAP Assignment Failure message */
 struct msgb *gsm0808_create_assignment_failure(uint8_t cause,
 					       uint8_t *rr_cause)
 {
 	return gsm0808_create_ass_fail(cause, rr_cause, NULL);
 }
 
+/*! \brief Create BSSMAP Clear Request message
+ *  \param[in] cause BSSMAP Cause value
+ *  \returns callee-allocated msgb with BSSMAP Clear Request message */
 struct msgb *gsm0808_create_clear_rqst(uint8_t cause)
 {
 	struct msgb *msg;
@@ -402,6 +485,12 @@ struct msgb *gsm0808_create_clear_rqst(uint8_t cause)
 	return msg;
 }
 
+/*! \brief Create BSSMAP PAGING message
+ *  \param[in] imsi Mandatory paged IMSI in string representation
+ *  \param[in] tmsi Optional paged TMSI
+ *  \param[in] cil Cell Identity List (where to page)
+ *  \param[in] chan_needed Channel Type needed
+ *  \returns callee-allocated msgb with BSSMAP PAGING message */
 struct msgb *gsm0808_create_paging(const char *imsi, const uint32_t *tmsi,
 				   const struct gsm0808_cell_id_list *cil,
 				   const uint8_t *chan_needed)
@@ -454,6 +543,9 @@ struct msgb *gsm0808_create_paging(const char *imsi, const uint32_t *tmsi,
 	return msg;
 }
 
+/*! \brief Prepend a DTAP header to given Message Buffer
+ *  \param[in] msgb Message Buffer
+ *  \param[in] link_id Link Identifier */
 void gsm0808_prepend_dtap_header(struct msgb *msg, uint8_t link_id)
 {
 	uint8_t *hh = msgb_push(msg, 3);
@@ -462,6 +554,10 @@ void gsm0808_prepend_dtap_header(struct msgb *msg, uint8_t link_id)
 	hh[2] = msg->len - 3;
 }
 
+/*! \brief Create BSSMAP DTAP message
+ *  \param[in] msg_l3 Messge Buffer containing Layer3 message
+ *  \param[in] link_id Link Identifier
+ *  \returns callee-allocated msgb with BSSMAP DTAP message */
 struct msgb *gsm0808_create_dtap(struct msgb *msg_l3, uint8_t link_id)
 {
 	struct dtap_header *header;
@@ -722,6 +818,7 @@ static const struct value_string gsm0808_msgt_names[] = {
 	{ 0, NULL }
 };
 
+/*! \brief Return string name of BSSMAP Message Type */
 const char *gsm0808_bssmap_name(uint8_t msg_type)
 {
 	return get_value_string(gsm0808_msgt_names, msg_type);
@@ -733,7 +830,10 @@ static const struct value_string gsm0808_bssap_names[] = {
 	{ 0, NULL }
 };
 
+/*! \brief Return string name of BSSAP Message Type */
 const char *gsm0808_bssap_name(uint8_t msg_type)
 {
 	return get_value_string(gsm0808_bssap_names, msg_type);
 }
+
+/*! @} */