Contiki-NG
Loading...
Searching...
No Matches
tsch-queue.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2014, SICS Swedish ICT.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright
11 * notice, this list of conditions and the following disclaimer in the
12 * documentation and/or other materials provided with the distribution.
13 * 3. Neither the name of the Institute nor the names of its contributors
14 * may be used to endorse or promote products derived from this software
15 * without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
18 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
21 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 * SUCH DAMAGE.
28 *
29 * This file is part of the Contiki operating system.
30 *
31 */
32
33/**
34 * \addtogroup tsch
35 * @{
36 * \file
37 * TSCH queues
38*/
39
40#ifndef TSCH_QUEUE_H_
41#define TSCH_QUEUE_H_
42
43/********** Includes **********/
44
45#include "contiki.h"
46#include "lib/ringbufindex.h"
47#include "net/linkaddr.h"
48#include "net/mac/mac.h"
49
50/***** External Variables *****/
51
52/* Broadcast and EB virtual neighbors */
53extern struct tsch_neighbor *n_broadcast;
54extern struct tsch_neighbor *n_eb;
55
56/********** Functions *********/
57
58/**
59 * \brief Add a TSCH neighbor queue
60 * \param addr The link-layer address of the neighbor to be added
61 */
62struct tsch_neighbor *tsch_queue_add_nbr(const linkaddr_t *addr);
63/**
64 * \brief Get a TSCH neighbor
65 * \param addr The link-layer address of the neighbor we are looking for
66 * \return A pointer to the neighbor queue, NULL if not found
67 */
68struct tsch_neighbor *tsch_queue_get_nbr(const linkaddr_t *addr);
69/**
70 * \brief Get the TSCH time source (we currently assume there is only one)
71 * \return The neighbor queue associated to the time source
72 */
74/**
75 * \brief Get the address of a neighbor.
76 * \return The link-layer address of the neighbor.
77 */
78linkaddr_t *tsch_queue_get_nbr_address(const struct tsch_neighbor *);
79/**
80 * \brief Update TSCH time source
81 * \param new_addr The address of the new TSCH time source
82 */
83int tsch_queue_update_time_source(const linkaddr_t *new_addr);
84/**
85 * \brief Add packet to neighbor queue. Use same lockfree implementation as ringbuf.c (put is atomic)
86 * \param addr The address of the targetted neighbor, &tsch_broadcast_address for broadcast
87 * \param max_transmissions The number of MAC retries
88 * \param sent The MAC packet sent callback
89 * \param ptr The MAC packet send callback parameter
90 * \return The newly created packet if any, NULL otherwise
91 */
92struct tsch_packet *tsch_queue_add_packet(const linkaddr_t *addr, uint8_t max_transmissions,
93 mac_callback_t sent, void *ptr);
94/**
95 * \brief Returns the number of packets currently in all TSCH queues
96 * \return The number of packets currently in all TSCH queues
97 */
99/**
100 * \brief Returns the number of packets currently a given neighbor queue (by pointer)
101 * \param n The neighbor we are interested in
102 * \return The number of packets in the neighbor's queue
103 */
104int tsch_queue_nbr_packet_count(const struct tsch_neighbor *n);
105/**
106 * \brief Remove first packet from a neighbor queue. The packet is stored in a separate
107 * dequeued packet list, for later processing.
108 * \param n The neighbor queue
109 * \return The packet that was removed if any, NULL otherwise
110 */
112/**
113 * \brief Free a packet
114 * \param p The packet to be freed
115 */
116void tsch_queue_free_packet(struct tsch_packet *p);
117/**
118 * \brief Flush packets to a specific address
119 * \param addr The address of the neighbor whose packets to free
120 */
121void tsch_queue_free_packets_to(const linkaddr_t *addr);
122/**
123 * \brief Updates neighbor queue state after a transmission
124 * \param n The neighbor queue we just sent from
125 * \param p The packet that was just sent
126 * \param link The TSCH link used for Tx
127 * \param mac_tx_status The MAC status (see mac.h)
128 * \return 1 if the packet remains in queue after the call, 0 if it was removed
129 */
130int tsch_queue_packet_sent(struct tsch_neighbor *n, struct tsch_packet *p, struct tsch_link *link, uint8_t mac_tx_status);
131/**
132 * \brief Reset neighbor queues module
133 */
134void tsch_queue_reset(void);
135/**
136 * \brief Deallocate all neighbors with empty queue
137 */
139/**
140 * \brief Is the neighbor queue empty?
141 * \param n The neighbor queue
142 * \return 1 if empty, 0 otherwise
143 */
144int tsch_queue_is_empty(const struct tsch_neighbor *n);
145/**
146 * \brief Returns the first packet that can be sent from a queue on a given link
147 * \param n The neighbor queue
148 * \param link The link
149 * \return The next packet to be sent for the neighbor on the given link, if any, else NULL
150 */
151struct tsch_packet *tsch_queue_get_packet_for_nbr(const struct tsch_neighbor *n, struct tsch_link *link);
152/**
153 * \brief Returns the first packet that can be sent to a given address on a given link
154 * \param addr The target link-layer address
155 * \param link The link
156 * \return The next packet to be sent for to the given address on the given link, if any, else NULL
157 */
158struct tsch_packet *tsch_queue_get_packet_for_dest_addr(const linkaddr_t *addr, struct tsch_link *link);
159/**
160 * \brief Gets the head packet of any neighbor queue with zero backoff counter.
161 * \param n A pointer where to store the neighbor queue to be used for Tx
162 * \param link The link to be used for Tx
163 * \return The packet if any, else NULL
164 */
166/**
167 * \brief Is the neighbor backoff timer expired?
168 * \param n The neighbor queue
169 * \return 1 if the backoff has expired (neighbor ready to transmit on a shared link), 0 otherwise
170 */
171int tsch_queue_backoff_expired(const struct tsch_neighbor *n);
172/**
173 * \brief Reset neighbor backoff
174 * \param n The neighbor queue
175 */
177/**
178 * \brief Increment backoff exponent of a given neighbor queue, pick a new window
179 * \param n The neighbor queue
180 */
182/**
183 * \brief Decrement backoff window for the queue(s) able to Tx to a given address
184 * \param dest_addr The target address, &tsch_broadcast_address for broadcast
185 */
186void tsch_queue_update_all_backoff_windows(const linkaddr_t *dest_addr);
187/**
188 * \brief Initialize TSCH queue module
189 */
190void tsch_queue_init(void);
191
192#endif /* TSCH_QUEUE_H_ */
193/** @} */
struct tsch_packet * tsch_queue_get_packet_for_dest_addr(const linkaddr_t *addr, struct tsch_link *link)
Returns the first packet that can be sent to a given address on a given link.
Definition tsch-queue.c:453
struct tsch_neighbor * tsch_queue_get_nbr(const linkaddr_t *addr)
Get a TSCH neighbor.
Definition tsch-queue.c:110
void tsch_queue_free_unused_neighbors(void)
Deallocate all neighbors with empty queue.
Definition tsch-queue.c:398
struct tsch_neighbor * tsch_queue_get_time_source(void)
Get the TSCH time source (we currently assume there is only one)
Definition tsch-queue.c:120
void tsch_queue_update_all_backoff_windows(const linkaddr_t *dest_addr)
Decrement backoff window for the queue(s) able to Tx to a given address.
Definition tsch-queue.c:520
void tsch_queue_free_packet(struct tsch_packet *p)
Free a packet.
Definition tsch-queue.c:314
int tsch_queue_global_packet_count(void)
Returns the number of packets currently in all TSCH queues.
Definition tsch-queue.c:279
struct tsch_packet * tsch_queue_get_packet_for_nbr(const struct tsch_neighbor *n, struct tsch_link *link)
Returns the first packet that can be sent from a queue on a given link.
Definition tsch-queue.c:425
int tsch_queue_update_time_source(const linkaddr_t *new_addr)
Update TSCH time source.
Definition tsch-queue.c:142
struct tsch_packet * tsch_queue_add_packet(const linkaddr_t *addr, uint8_t max_transmissions, mac_callback_t sent, void *ptr)
Add packet to neighbor queue.
Definition tsch-queue.c:229
int tsch_queue_backoff_expired(const struct tsch_neighbor *n)
Is the neighbor backoff timer expired?
Definition tsch-queue.c:488
int tsch_queue_nbr_packet_count(const struct tsch_neighbor *n)
Returns the number of packets currently a given neighbor queue (by pointer)
Definition tsch-queue.c:286
void tsch_queue_reset(void)
Reset neighbor queues module.
Definition tsch-queue.c:380
int tsch_queue_packet_sent(struct tsch_neighbor *n, struct tsch_packet *p, struct tsch_link *link, uint8_t mac_tx_status)
Updates neighbor queue state after a transmission.
Definition tsch-queue.c:337
struct tsch_neighbor * tsch_queue_add_nbr(const linkaddr_t *addr)
Add a TSCH neighbor queue.
Definition tsch-queue.c:81
void tsch_queue_init(void)
Initialize TSCH queue module.
Definition tsch-queue.c:538
struct tsch_packet * tsch_queue_get_unicast_packet_for_any(struct tsch_neighbor **n, struct tsch_link *link)
Gets the head packet of any neighbor queue with zero backoff counter.
Definition tsch-queue.c:464
void tsch_queue_free_packets_to(const linkaddr_t *addr)
Flush packets to a specific address.
Definition tsch-queue.c:324
struct tsch_packet * tsch_queue_remove_packet_from_queue(struct tsch_neighbor *n)
Remove first packet from a neighbor queue.
Definition tsch-queue.c:296
int tsch_queue_is_empty(const struct tsch_neighbor *n)
Is the neighbor queue empty?
Definition tsch-queue.c:418
void tsch_queue_backoff_inc(struct tsch_neighbor *n)
Increment backoff exponent of a given neighbor queue, pick a new window.
Definition tsch-queue.c:503
linkaddr_t * tsch_queue_get_nbr_address(const struct tsch_neighbor *n)
Get the address of a neighbor.
Definition tsch-queue.c:135
void tsch_queue_backoff_reset(struct tsch_neighbor *n)
Reset neighbor backoff.
Definition tsch-queue.c:495
Header file for the link-layer address representation.
MAC driver header file.
Header file for the ringbufindex library.
TSCH neighbor information.
Definition tsch-types.h:109
TSCH packet information.
Definition tsch-types.h:97
static uip_ds6_addr_t * addr
Pointer to a nbr cache entry.
Definition uip-nd6.c:107