Contiki-NG
tsch-schedule.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 scheduling engine
38*/
39
40#ifndef TSCH_SCHEDULE_H_
41#define TSCH_SCHEDULE_H_
42
43/********** Includes **********/
44
45#include "contiki.h"
46#include "net/linkaddr.h"
47
48/********** Functions *********/
49
50/**
51 * \brief Module initialization, call only once at init
52 * \return 1 if success, 0 if failure
53 */
54int tsch_schedule_init(void);
55/**
56 * \brief Create a 6tisch minimal schedule with length TSCH_SCHEDULE_DEFAULT_LENGTH
57 */
59/**
60 * \brief Prints out the current schedule (all slotframes and links)
61 */
62void tsch_schedule_print(void);
63
64
65/**
66 * \brief Creates and adds a new slotframe
67 * \param handle the slotframe handle
68 * \param size the slotframe size
69 * \return the new slotframe, NULL if failure
70 */
71struct tsch_slotframe *tsch_schedule_add_slotframe(uint16_t handle, uint16_t size);
72
73/**
74 * \brief Looks up a slotframe by handle
75 * \param handle the slotframe handle
76 * \return the slotframe with required handle, if any. NULL otherwise.
77 */
79
80/**
81 * \brief Removes a slotframe
82 * \param slotframe The slotframe to be removed
83 * \return 1 if success, 0 if failure
84 */
86
87/**
88 * \brief Removes all slotframes, resulting in an empty schedule
89 * \return 1 if success, 0 if failure
90 */
92
93/**
94 * \brief Adds a link to a slotframe
95 * \param slotframe The slotframe that will contain the new link
96 * \param link_options The link options, as a bitfield (LINK_OPTION_* flags)
97 * \param link_type The link type (advertising, normal)
98 * \param address The link address of the intended destination. Use &tsch_broadcast_address for a slot towards any neighbor
99 * \param timeslot The link timeslot within the slotframe
100 * \param channel_offset The link channel offset
101 * \param do_remove Whether to remove an old link at this timeslot and channel offset
102 * \return A pointer to the new link, NULL if failure
103 */
104struct tsch_link *tsch_schedule_add_link(struct tsch_slotframe *slotframe,
105 uint8_t link_options, enum link_type link_type, const linkaddr_t *address,
106 uint16_t timeslot, uint16_t channel_offset, uint8_t do_remove);
107/**
108* \brief Looks for a link from a handle
109* \param handle The target handle
110* \return The link with required handle, if any. Otherwise, NULL
111*/
112struct tsch_link *tsch_schedule_get_link_by_handle(uint16_t handle);
113
114/**
115 * \brief Looks within a slotframe for a link with a given timeslot and channel offset
116 * \param slotframe The desired slotframe
117 * \param timeslot The desired timeslot
118 * \param channel_offset The desired channel offset
119 * \return The link if found, NULL otherwise
120 */
122 uint16_t timeslot, uint16_t channel_offset);
123
124/**
125 * \brief Looks within a slotframe for a link with a given timeslot
126 * \param slotframe The desired slotframe
127 * \param timeslot The desired timeslot
128 * \return The link if found, NULL otherwise
129 */
131 uint16_t timeslot);
132
133/**
134 * \brief Removes a link
135 * \param slotframe The slotframe the link belongs to
136 * \param l The link to be removed
137 * \return 1 if success, 0 if failure
138 */
139int tsch_schedule_remove_link(struct tsch_slotframe *slotframe, struct tsch_link *l);
140
141/**
142 * \brief Removes a link from a slotframe and timeslot + channel offset
143 * \param slotframe The slotframe where to look for the link
144 * \param timeslot The timeslot where to look for the link within the target slotframe
145 * \param channel_offset The channel offset where to look for the link within the target slotframe
146 * \return 1 if success, 0 if failure
147 */
149 uint16_t timeslot, uint16_t channel_offset);
150
151/**
152 * \brief Returns the next active link after a given ASN, and a backup link (for the same ASN, with Rx flag)
153 * \param asn The base ASN, from which we look for the next active link
154 * \param time_offset A pointer to uint16_t where to store the time offset between base ASN and link found
155 * \param backup_link A pointer where to write the address of a backup link, to be executed should the original be no longer active at wakeup
156 * \return The next active link if any, NULL otherwise
157 */
158struct tsch_link * tsch_schedule_get_next_active_link(struct tsch_asn_t *asn, uint16_t *time_offset,
159 struct tsch_link **backup_link);
160
161/**
162 * \brief Access the first item in the list of slotframes
163 * \return The first slotframe in the schedule if any, NULL otherwise
164 */
166
167/**
168 * \brief Access the next item in the list of slotframes
169 * \param sf The current slotframe (item in the list)
170 * \return The next slotframe if any, NULL otherwise
171 */
173
174#endif /* TSCH_SCHEDULE_H_ */
175/** @} */
int tsch_schedule_init(void)
Module initialization, call only once at init.
struct tsch_slotframe * tsch_schedule_get_slotframe_by_handle(uint16_t handle)
Looks up a slotframe by handle.
struct tsch_link * tsch_schedule_get_next_active_link(struct tsch_asn_t *asn, uint16_t *time_offset, struct tsch_link **backup_link)
Returns the next active link after a given ASN, and a backup link (for the same ASN,...
struct tsch_link * tsch_schedule_add_link(struct tsch_slotframe *slotframe, uint8_t link_options, enum link_type link_type, const linkaddr_t *address, uint16_t timeslot, uint16_t channel_offset, uint8_t do_remove)
Adds a link to a slotframe.
int tsch_schedule_remove_slotframe(struct tsch_slotframe *slotframe)
Removes a slotframe.
struct tsch_slotframe * tsch_schedule_slotframe_head(void)
Access the first item in the list of slotframes.
void tsch_schedule_create_minimal(void)
Create a 6tisch minimal schedule with length TSCH_SCHEDULE_DEFAULT_LENGTH.
struct tsch_link * tsch_schedule_get_link_by_handle(uint16_t handle)
Looks for a link from a handle.
int tsch_schedule_remove_all_slotframes(void)
Removes all slotframes, resulting in an empty schedule.
struct tsch_link * tsch_schedule_get_link_by_timeslot(struct tsch_slotframe *slotframe, uint16_t timeslot)
Looks within a slotframe for a link with a given timeslot.
int tsch_schedule_remove_link_by_offsets(struct tsch_slotframe *slotframe, uint16_t timeslot, uint16_t channel_offset)
Removes a link from a slotframe and timeslot + channel offset.
void tsch_schedule_print(void)
Prints out the current schedule (all slotframes and links)
struct tsch_link * tsch_schedule_get_link_by_offsets(struct tsch_slotframe *slotframe, uint16_t timeslot, uint16_t channel_offset)
Looks within a slotframe for a link with a given timeslot and channel offset.
link_type
802.15.4e link types.
Definition: tsch-types.h:54
struct tsch_slotframe * tsch_schedule_add_slotframe(uint16_t handle, uint16_t size)
Creates and adds a new slotframe.
Definition: tsch-schedule.c:73
int tsch_schedule_remove_link(struct tsch_slotframe *slotframe, struct tsch_link *l)
Removes a link.
struct tsch_slotframe * tsch_schedule_slotframe_next(struct tsch_slotframe *sf)
Access the next item in the list of slotframes.
Header file for the link-layer address representation.
The ASN is an absolute slot number over 5 bytes.
Definition: tsch-asn.h:48
802.15.4e slotframe (contains links)
Definition: tsch-types.h:84