mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
89c69c5450
The new `gnrc_tx_sync` module allows users of the GNRC network stack to
synchronize with the actual transmission of outgoing packets. This is directly
integrated into gnrc_sock. Hence, if `gnrc_tx_sync` is used, calls to e.g.
sock_udp_send() will block until the network stack has processed the message.
Use cases:
1. Prevent packet drop when sending at high rate
- If the application is sending faster than the stack can handle, the
message queues will overflow and outgoing packets are lost
2. Passing auxiliary data about the transmission back the stack
- When e.g. the number of required retransmissions, the transmission time
stamp, etc. should be made available to a user of an UDP sock, a
synchronization mechanism is needed
3. Simpler error reporting without footguns
- The current approach of using `core/msg` for passing up error messages is
difficult to use if other message come in. Currently, gnrc_sock is
busy-waiting and fetching messages from the message queue until the number
of expected status reports is received. It will enqueue all
non-status-report messages again at the end of the queue. This has
multiple issues:
- Busy waiting is especially in lower power scenarios with time slotted
MAC protocols harmful, as the CPU will remain active and consume
power even though the it could sleep until the TX slot is reached
- The status reports from the network stack are send to the user thread
blocking. If the message queue of the user thread is full, the network
stack would block until the user stack can fetch the messages. If
another higher priority thread would start sending a message, it
would busy wait for its status reports to completely come in. Hence,
the first thread doesn't get CPU time to fetch messages and unblock
the network stack. As a result, the system would lock up completely.
- Just adding the error/status code to the gnrc_tx_sync_t would preallocate
and reserve memory for the error reporting. That way gnrc_sock does not
need to search through the message queue for status reports and the
network stack does not need to block for the user thread fetching it.
140 lines
3.8 KiB
C
140 lines
3.8 KiB
C
/*
|
|
* Copyright (C) 2020 Otto-von-Guericke-Universität Magdeburg
|
|
*
|
|
* This file is subject to the terms and conditions of the GNU Lesser
|
|
* General Public License v2.1. See the file LICENSE in the top level
|
|
* directory for more details.
|
|
*/
|
|
|
|
/**
|
|
* @defgroup net_gnrc_tx_sync Helpers for synchronizing with transmission.
|
|
* @ingroup net_gnrc
|
|
* @brief This allows upper layers to wait for a transmission to complete
|
|
* (or fail) and for passing up data about the transmission.
|
|
* @{
|
|
*
|
|
* @file
|
|
* @brief Definitions for TX sync.
|
|
*
|
|
* @author Marian Buschsieweke <marian.buschsieweke@ovgu.de>
|
|
*/
|
|
#ifndef NET_GNRC_TX_SYNC_H
|
|
#define NET_GNRC_TX_SYNC_H
|
|
|
|
#include <errno.h>
|
|
#include <stdint.h>
|
|
|
|
#include "mutex.h"
|
|
#include "net/gnrc/pktbuf.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @brief TX synchronization data */
|
|
typedef struct {
|
|
mutex_t signal; /**< Mutex used for synchronization */
|
|
} gnrc_tx_sync_t;
|
|
|
|
/**
|
|
* @brief Helper to initialize a gnrc_tx_sync_t structure
|
|
*/
|
|
static inline gnrc_tx_sync_t gnrc_tx_sync_init(void)
|
|
{
|
|
gnrc_tx_sync_t result = { .signal = MUTEX_INIT_LOCKED };
|
|
return result;
|
|
}
|
|
|
|
/**
|
|
* @brief Build a TX sync snip
|
|
*
|
|
* @param[in,out] tx_sync TX sync structure the snip should hold
|
|
*
|
|
* @return The TX sync snip holing @p tx_sync
|
|
* @retval NULL Allocation Failed
|
|
*
|
|
* @note No need to initialize @p tx_sync, this function will do it for you.
|
|
*/
|
|
static inline gnrc_pktsnip_t * gnrc_tx_sync_build(gnrc_tx_sync_t *tx_sync)
|
|
{
|
|
*tx_sync = gnrc_tx_sync_init();
|
|
gnrc_pktsnip_t *snip = gnrc_pktbuf_add(NULL, NULL, 0, GNRC_NETTYPE_TX_SYNC);
|
|
if (!snip) {
|
|
return NULL;
|
|
}
|
|
snip->data = tx_sync;
|
|
return snip;
|
|
}
|
|
|
|
/**
|
|
* @brief Appends a newly allocated tx sync pktsnip to the end of the packet
|
|
*
|
|
* @param[in] pkt Packet to append TX sync pktsnip to
|
|
* @param[in,out] tx_sync TX sync structure to initialize and append
|
|
*
|
|
* @retval 0 Success
|
|
* @retval -ENOMEM Allocation failed
|
|
*
|
|
* @note No need to initialize @p tx_sync, this function will do it for you.
|
|
*/
|
|
static inline int gnrc_tx_sync_append(gnrc_pktsnip_t *pkt,
|
|
gnrc_tx_sync_t *tx_sync)
|
|
{
|
|
gnrc_pktsnip_t *snip = gnrc_tx_sync_build(tx_sync);
|
|
if (!snip) {
|
|
return -ENOMEM;
|
|
}
|
|
gnrc_pkt_append(pkt, snip);
|
|
return 0;
|
|
}
|
|
|
|
/**
|
|
* @brief Split off the TX sync snip and return it
|
|
* @param[in,out] pkt Packet to split off the TX sync snip
|
|
* @return The TX sync snip that no longer is part of @p pkt
|
|
* @retval NULL @p pkt contains no TX sync snip
|
|
*/
|
|
gnrc_pktsnip_t * gnrc_tx_sync_split(gnrc_pktsnip_t *pkt);
|
|
|
|
/**
|
|
* @brief Signal TX completion via the given tx sync packet snip
|
|
*
|
|
* @param[in] pkt The tx sync packet snip of the packet that was transmitted
|
|
*
|
|
* @pre Module gnrc_netttype_tx_sync is sued
|
|
* @pre `pkt->type == GNRC_NETTYPE_TX_SYNC`
|
|
*/
|
|
static inline void gnrc_tx_complete(gnrc_pktsnip_t *pkt)
|
|
{
|
|
assert(IS_USED(MODULE_GNRC_TX_SYNC) && (pkt->type == GNRC_NETTYPE_TX_SYNC));
|
|
gnrc_tx_sync_t *sync = pkt->data;
|
|
mutex_unlock(&sync->signal);
|
|
}
|
|
|
|
/**
|
|
* @brief Block until transmission of the corresponding packet has completed
|
|
* or failed
|
|
*
|
|
* @param[in,out] sync TX sync structure used for synchronization
|
|
*
|
|
* @pre @p sync has been added to the packet to synchronize with, e.g. via
|
|
* @ref gnrc_tx_sync_append
|
|
* @pre The packet linked to @p sync has been passed to the network stack
|
|
* for transmission. Otherwise this will block forever.
|
|
*
|
|
* @note If the transmission has already completed, this function will not
|
|
* block and return immediately instead.
|
|
*/
|
|
static inline void gnrc_tx_sync(gnrc_tx_sync_t *sync)
|
|
{
|
|
mutex_lock(&sync->signal);
|
|
}
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* NET_GNRC_TX_SYNC_H */
|
|
/** @} */
|