From de8b39f6eb7ede89f7fa82e581563bb107e60ff1 Mon Sep 17 00:00:00 2001 From: Georgij Cernysiov Date: Wed, 13 Feb 2019 22:59:17 +0100 Subject: [PATCH] drivers: modem: receiver: rearrange and comment Rearranges functions to public and private groups, and adds missing function comments. Signed-off-by: Georgij Cernysiov --- drivers/modem/modem_receiver.c | 89 +++++++++++++++++++------- include/drivers/modem/modem_receiver.h | 40 ++++++++++++ 2 files changed, 105 insertions(+), 24 deletions(-) diff --git a/drivers/modem/modem_receiver.c b/drivers/modem/modem_receiver.c index 9886d79dd4c..89bc09579c6 100644 --- a/drivers/modem/modem_receiver.c +++ b/drivers/modem/modem_receiver.c @@ -26,15 +26,13 @@ LOG_MODULE_REGISTER(mdm_receiver, CONFIG_MODEM_LOG_LEVEL); static struct mdm_receiver_context *contexts[MAX_MDM_CTX]; -struct mdm_receiver_context *mdm_receiver_context_from_id(int id) -{ - if (id >= 0 && id < MAX_MDM_CTX) { - return contexts[id]; - } else { - return NULL; - } -} - +/** + * @brief Finds receiver context which manages provided device. + * + * @param *dev: device used by the receiver context. + * + * @retval Receiver context or NULL. + */ static struct mdm_receiver_context *context_from_dev(struct device *dev) { int i; @@ -48,11 +46,20 @@ static struct mdm_receiver_context *context_from_dev(struct device *dev) return NULL; } +/** + * @brief Persists receiver context if there is a free place. + * + * @note Amount of stored receiver contexts is determined by + * MAX_MDM_CTX. + * + * @param *ctx: receiver context to persist. + * + * @retval 0 if ok, < 0 if error. + */ static int mdm_receiver_get(struct mdm_receiver_context *ctx) { int i; - /* find a free modem_context */ for (i = 0; i < MAX_MDM_CTX; i++) { if (!contexts[i]) { contexts[i] = ctx; @@ -63,6 +70,15 @@ static int mdm_receiver_get(struct mdm_receiver_context *ctx) return -ENOMEM; } +/** + * @brief Drains UART. + * + * @note Discards remaining data. + * + * @param *ctx: receiver context. + * + * @retval None. + */ static void mdm_receiver_flush(struct mdm_receiver_context *ctx) { u8_t c; @@ -71,12 +87,21 @@ static void mdm_receiver_flush(struct mdm_receiver_context *ctx) return; } - /* Drain the fifo */ while (uart_fifo_read(ctx->uart_dev, &c, 1) > 0) { continue; } } +/** + * @brief Receiver UART interrupt handler. + * + * @note Fills contexts ring buffer with received data. + * When ring buffer is full the data is discarded. + * + * @param *uart_dev: uart device. + * + * @retval None. + */ static void mdm_receiver_isr(struct device *uart_dev) { struct mdm_receiver_context *ctx; @@ -108,6 +133,35 @@ static void mdm_receiver_isr(struct device *uart_dev) } } +/** + * @brief Configures receiver context and assigned device. + * + * @param *ctx: receiver context. + * + * @retval None. + */ +static void mdm_receiver_setup(struct mdm_receiver_context *ctx) +{ + if (!ctx) { + return; + } + + uart_irq_rx_disable(ctx->uart_dev); + uart_irq_tx_disable(ctx->uart_dev); + mdm_receiver_flush(ctx); + uart_irq_callback_set(ctx->uart_dev, mdm_receiver_isr); + uart_irq_rx_enable(ctx->uart_dev); +} + +struct mdm_receiver_context *mdm_receiver_context_from_id(int id) +{ + if (id >= 0 && id < MAX_MDM_CTX) { + return contexts[id]; + } else { + return NULL; + } +} + int mdm_receiver_recv(struct mdm_receiver_context *ctx, u8_t *buf, size_t size, size_t *bytes_read) { @@ -147,19 +201,6 @@ int mdm_receiver_send(struct mdm_receiver_context *ctx, return 0; } -static void mdm_receiver_setup(struct mdm_receiver_context *ctx) -{ - if (!ctx) { - return; - } - - uart_irq_rx_disable(ctx->uart_dev); - uart_irq_tx_disable(ctx->uart_dev); - mdm_receiver_flush(ctx); - uart_irq_callback_set(ctx->uart_dev, mdm_receiver_isr); - uart_irq_rx_enable(ctx->uart_dev); -} - int mdm_receiver_register(struct mdm_receiver_context *ctx, const char *uart_dev_name, u8_t *buf, size_t size) diff --git a/include/drivers/modem/modem_receiver.h b/include/drivers/modem/modem_receiver.h index 0ca80e25eb3..714cb3f9652 100644 --- a/include/drivers/modem/modem_receiver.h +++ b/include/drivers/modem/modem_receiver.h @@ -36,12 +36,52 @@ struct mdm_receiver_context { int data_rssi; }; +/** + * @brief Gets receiver context by id. + * + * @param id: receiver context id. + * + * @retval Receiver context or NULL. + */ struct mdm_receiver_context *mdm_receiver_context_from_id(int id); +/** + * @brief Get received data. + * + * @param *ctx: receiver context. + * @param *buf: buffer to copy the received data to. + * @param size: buffer size. + * @param *bytes_read: amount of received bytes + * + * @retval 0 if ok, < 0 if error. + */ int mdm_receiver_recv(struct mdm_receiver_context *ctx, u8_t *buf, size_t size, size_t *bytes_read); + +/** + * @brief Sends the data over specified receiver context. + * + * @param *ctx: receiver context. + * @param *buf: buffer with the data to send. + * @param size: the amount of data to send. + * + * @retval 0 if ok, < 0 if error. + */ int mdm_receiver_send(struct mdm_receiver_context *ctx, const u8_t *buf, size_t size); + +/** + * @brief Registers receiver context. + * + * @note Aquires receivers device, and prepares the context to be used. + * + * @param *ctx: receiver context to register. + * @param *uart_dev_name: communication device for the receiver context. + * @param *buf: rx buffer to use for received data. + * @param size: rx buffer size. + * + * @retval 0 if ok, < 0 if error. + */ int mdm_receiver_register(struct mdm_receiver_context *ctx, const char *uart_dev_name, u8_t *buf, size_t size);