Merge pull request #421 from simonduq/contrib/tsch-doxygen
Doxygen documentation for TSCH
This commit is contained in:
Simon Duquennoy
GitHub
commit
443759ed8c
@ -44,15 +44,30 @@
|
||||
|
||||
/***** External Variables *****/
|
||||
|
||||
/* The neighbor last used as our time source */
|
||||
/** \brief The neighbor last used as our time source */
|
||||
extern struct tsch_neighbor *last_timesource_neighbor;
|
||||
|
||||
/********** Functions *********/
|
||||
|
||||
/**
|
||||
* \brief Updates timesync information for a given neighbor
|
||||
* \param n The neighbor
|
||||
* \param time_delta_asn ASN time delta since last synchronization, i.e. number of slots elapsed
|
||||
* \param drift_correction The measured drift in ticks since last synchronization
|
||||
*/
|
||||
void tsch_timesync_update(struct tsch_neighbor *n, uint16_t time_delta_asn, int32_t drift_correction);
|
||||
|
||||
/**
|
||||
* \brief Computes time compensation for a given point in the future
|
||||
* \param delta_ticks The number of ticks in the future we want to calculate compensation for
|
||||
* \return The time compensation
|
||||
*/
|
||||
int32_t tsch_timesync_adaptive_compensate(rtimer_clock_t delta_ticks);
|
||||
|
||||
/**
|
||||
* \brief Gives the estimated clock drift w.r.t. the time source in PPM (parts per million)
|
||||
* \return The time drift in PPM
|
||||
*/
|
||||
long int tsch_adaptive_timesync_get_drift_ppm(void);
|
||||
|
||||
#endif /* __TSCH_ADAPTIVE_TIMESYNC_H__ */
|
||||
|
||||
@ -48,13 +48,13 @@
|
||||
|
||||
/************ Types ***********/
|
||||
|
||||
/* The ASN is an absolute slot number over 5 bytes. */
|
||||
/** \brief The ASN is an absolute slot number over 5 bytes. */
|
||||
struct tsch_asn_t {
|
||||
uint32_t ls4b; /* least significant 4 bytes */
|
||||
uint8_t ms1b; /* most significant 1 byte */
|
||||
};
|
||||
|
||||
/* For quick modulo operation on ASN */
|
||||
/** \brief For quick modulo operation on ASN */
|
||||
struct tsch_asn_divisor_t {
|
||||
uint16_t val; /* Divisor value */
|
||||
uint16_t asn_ms1b_remainder; /* Remainder of the operation 0x100000000 / val */
|
||||
@ -62,37 +62,37 @@ struct tsch_asn_divisor_t {
|
||||
|
||||
/************ Macros **********/
|
||||
|
||||
/* Initialize ASN */
|
||||
/** \brief Initialize ASN */
|
||||
#define TSCH_ASN_INIT(asn, ms1b_, ls4b_) do { \
|
||||
(asn).ms1b = (ms1b_); \
|
||||
(asn).ls4b = (ls4b_); \
|
||||
} while(0);
|
||||
|
||||
/* Increment an ASN by inc (32 bits) */
|
||||
/** \brief Increment an ASN by inc (32 bits) */
|
||||
#define TSCH_ASN_INC(asn, inc) do { \
|
||||
uint32_t new_ls4b = (asn).ls4b + (inc); \
|
||||
if(new_ls4b < (asn).ls4b) { (asn).ms1b++; } \
|
||||
(asn).ls4b = new_ls4b; \
|
||||
} while(0);
|
||||
|
||||
/* Decrement an ASN by inc (32 bits) */
|
||||
/** \brief Decrement an ASN by inc (32 bits) */
|
||||
#define TSCH_ASN_DEC(asn, dec) do { \
|
||||
uint32_t new_ls4b = (asn).ls4b - (dec); \
|
||||
if(new_ls4b > (asn).ls4b) { (asn).ms1b--; } \
|
||||
(asn).ls4b = new_ls4b; \
|
||||
} while(0);
|
||||
|
||||
/* Returns the 32-bit diff between asn1 and asn2 */
|
||||
/** \brief Returns the 32-bit diff between asn1 and asn2 */
|
||||
#define TSCH_ASN_DIFF(asn1, asn2) \
|
||||
((asn1).ls4b - (asn2).ls4b)
|
||||
|
||||
/* Initialize a struct asn_divisor_t */
|
||||
/** \brief Initialize a struct asn_divisor_t */
|
||||
#define TSCH_ASN_DIVISOR_INIT(div, val_) do { \
|
||||
(div).val = (val_); \
|
||||
(div).asn_ms1b_remainder = ((0xffffffff % (val_)) + 1) % (val_); \
|
||||
} while(0);
|
||||
|
||||
/* Returns the result (16 bits) of a modulo operation on ASN,
|
||||
/** \brief Returns the result (16 bits) of a modulo operation on ASN,
|
||||
* with divisor being a struct asn_divisor_t */
|
||||
#define TSCH_ASN_MOD(asn, div) \
|
||||
((uint16_t)((asn).ls4b % (div).val) \
|
||||
|
||||
@ -70,7 +70,7 @@
|
||||
|
||||
/************ Types ***********/
|
||||
|
||||
/* Structure for a log. Union of different types of logs */
|
||||
/** \brief Structure for a log. Union of different types of logs */
|
||||
struct tsch_log_t {
|
||||
enum { tsch_log_tx,
|
||||
tsch_log_rx,
|
||||
@ -107,21 +107,31 @@ struct tsch_log_t {
|
||||
|
||||
/********** Functions *********/
|
||||
|
||||
/* Prepare addition of a new log.
|
||||
* Returns pointer to log structure if success, NULL otherwise */
|
||||
/**
|
||||
* \brief Prepare addition of a new log.
|
||||
* \return A pointer to log structure if success, NULL otherwise
|
||||
*/
|
||||
struct tsch_log_t *tsch_log_prepare_add(void);
|
||||
/* Actually add the previously prepared log */
|
||||
/**
|
||||
* \brief Actually add the previously prepared log
|
||||
*/
|
||||
void tsch_log_commit(void);
|
||||
/* Initialize log module */
|
||||
/**
|
||||
* \brief Initialize log module
|
||||
*/
|
||||
void tsch_log_init(void);
|
||||
/* Process pending log messages */
|
||||
/**
|
||||
* \brief Process pending log messages
|
||||
*/
|
||||
void tsch_log_process_pending(void);
|
||||
/* Stop logging module */
|
||||
/**
|
||||
* \brief Stop logging module
|
||||
*/
|
||||
void tsch_log_stop(void);
|
||||
|
||||
/************ Macros **********/
|
||||
|
||||
/* Use this macro to add a log to the queue (will be printed out
|
||||
/** \brief Use this macro to add a log to the queue (will be printed out
|
||||
* later, after leaving interrupt context) */
|
||||
#define TSCH_LOG_ADD(log_type, init_code) do { \
|
||||
struct tsch_log_t *log = tsch_log_prepare_add(); \
|
||||
|
||||
@ -390,8 +390,7 @@ tsch_packet_update_eb(uint8_t *buf, int buf_size, uint8_t tsch_sync_ie_offset)
|
||||
struct ieee802154_ies ies;
|
||||
ies.ie_asn = tsch_current_asn;
|
||||
ies.ie_join_priority = tsch_join_priority;
|
||||
frame80215e_create_ie_tsch_synchronization(buf+tsch_sync_ie_offset, buf_size-tsch_sync_ie_offset, &ies);
|
||||
return 1;
|
||||
return frame80215e_create_ie_tsch_synchronization(buf+tsch_sync_ie_offset, buf_size-tsch_sync_ie_offset, &ies) != -1;
|
||||
}
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/* Parse a IEEE 802.15.4e TSCH Enhanced Beacon (EB) */
|
||||
|
||||
@ -46,18 +46,56 @@
|
||||
|
||||
/********** Functions *********/
|
||||
|
||||
/* Construct enhanced ACK packet and return ACK length */
|
||||
/**
|
||||
* \brief Construct Enhanced ACK packet
|
||||
* \param buf The buffer where to build the EACK
|
||||
* \param buf_size The buffer size
|
||||
* \param dest_addr The link-layer address of the neighbor we are ACKing
|
||||
* \param seqno The sequence number we are ACKing
|
||||
* \param drift The time offset in usec measured at Rx of the packer we are ACKing
|
||||
* \param nack Value of the NACK bit
|
||||
* \return The length of the packet that was created. -1 if failure.
|
||||
*/
|
||||
int tsch_packet_create_eack(uint8_t *buf, uint16_t buf_size,
|
||||
const linkaddr_t *dest_addr, uint8_t seqno,
|
||||
int16_t drift, int nack);
|
||||
/* Parse enhanced ACK packet, extract drift and nack */
|
||||
/**
|
||||
* \brief Parse enhanced ACK packet
|
||||
* \param buf The buffer where to parse the EACK from
|
||||
* \param buf_size The buffer size
|
||||
* \param seqno The sequence number we are expecting
|
||||
* \param frame The frame structure where to store parsed fields
|
||||
* \param ies The IE structure where to store parsed IEs
|
||||
* \param hdr_len A pointer where to store the length of the parsed header
|
||||
* \return 1 if the EACK is correct and acknowledges the specified frame, 0 otherwise
|
||||
*/
|
||||
int tsch_packet_parse_eack(const uint8_t *buf, int buf_size,
|
||||
uint8_t seqno, frame802154_t *frame, struct ieee802154_ies *ies, uint8_t *hdr_len);
|
||||
/* Create an EB packet */
|
||||
/**
|
||||
* \brief Create an EB packet directly in packetbuf
|
||||
* \param hdr_len A pointer where to store the length of the created header
|
||||
* \param tsch_sync_ie_ptr A pointer where to store the address of the TSCH synchronization IE
|
||||
* \return The total length of the EB
|
||||
*/
|
||||
int tsch_packet_create_eb(uint8_t *hdr_len, uint8_t *tsch_sync_ie_ptr);
|
||||
/* Update ASN in EB packet */
|
||||
/**
|
||||
* \brief Update ASN in EB packet
|
||||
* \param buf The buffer that contains the EB
|
||||
* \param buf_size The buffer size
|
||||
* \param tsch_sync_ie_offset The offset of the TSCH synchronization IE, in which the ASN is to be written
|
||||
* \return 1 if success, 0 otherwise
|
||||
*/
|
||||
int tsch_packet_update_eb(uint8_t *buf, int buf_size, uint8_t tsch_sync_ie_offset);
|
||||
/* Parse EB and extract ASN and join priority */
|
||||
/**
|
||||
* \brief Parse EB
|
||||
* \param buf The buffer where to parse the EB from
|
||||
* \param buf_size The buffer sizecting
|
||||
* \param frame The frame structure where to store parsed fields
|
||||
* \param ies The IE structure where to store parsed IEs
|
||||
* \param hdrlen A pointer where to store the length of the parsed header
|
||||
* \param frame_without_mic When set, the security MIC will not be parsed
|
||||
* \return The length of the parsed EB
|
||||
*/
|
||||
int tsch_packet_parse_eb(const uint8_t *buf, int buf_size,
|
||||
frame802154_t *frame, struct ieee802154_ies *ies,
|
||||
uint8_t *hdrlen, int frame_without_mic);
|
||||
|
||||
@ -53,50 +53,128 @@ extern struct tsch_neighbor *n_eb;
|
||||
|
||||
/********** Functions *********/
|
||||
|
||||
/* Add a TSCH neighbor */
|
||||
/**
|
||||
* \brief Add a TSCH neighbor queue
|
||||
* \param addr The link-layer address of the neighbor to be added
|
||||
*/
|
||||
struct tsch_neighbor *tsch_queue_add_nbr(const linkaddr_t *addr);
|
||||
/* Get a TSCH neighbor */
|
||||
/**
|
||||
* \brief Get a TSCH neighbor
|
||||
* \param addr The link-layer address of the neighbor we are looking for
|
||||
* \return A pointer to the neighbor queue, NULL if not found
|
||||
*/
|
||||
struct tsch_neighbor *tsch_queue_get_nbr(const linkaddr_t *addr);
|
||||
/* Get a TSCH time source (we currently assume there is only one) */
|
||||
/**
|
||||
* \brief Get the TSCH time source (we currently assume there is only one)
|
||||
* \return The neighbor queue associated to the time source
|
||||
*/
|
||||
struct tsch_neighbor *tsch_queue_get_time_source(void);
|
||||
/* Update TSCH time source */
|
||||
/**
|
||||
* \brief Update TSCH time source
|
||||
* \param new_addr The address of the new TSCH time source
|
||||
*/
|
||||
int tsch_queue_update_time_source(const linkaddr_t *new_addr);
|
||||
/* Add packet to neighbor queue. Use same lockfree implementation as ringbuf.c (put is atomic) */
|
||||
/**
|
||||
* \brief Add packet to neighbor queue. Use same lockfree implementation as ringbuf.c (put is atomic)
|
||||
* \param addr The address of the targetted neighbor, &tsch_broadcast_address for broadcast
|
||||
* \param max_transmissions The number of MAC retries
|
||||
* \param sent The MAC packet sent callback
|
||||
* \param ptr The MAC packet send callback parameter
|
||||
* \return The newly created packet if any, NULL otherwise
|
||||
*/
|
||||
struct tsch_packet *tsch_queue_add_packet(const linkaddr_t *addr, uint8_t max_transmissions,
|
||||
mac_callback_t sent, void *ptr);
|
||||
/* Returns the number of packets currently in any TSCH queue */
|
||||
/**
|
||||
* \brief Returns the number of packets currently in all TSCH queues
|
||||
* \return The number of packets currently in all TSCH queues
|
||||
*/
|
||||
int tsch_queue_global_packet_count(void);
|
||||
/* Returns the number of packets currently a given neighbor queue */
|
||||
/**
|
||||
* \brief Returns the number of packets currently a given neighbor queue
|
||||
* \param addr The link-layer address of the neighbor we are interested in
|
||||
* \return The number of packets in the neighbor's queue
|
||||
*/
|
||||
int tsch_queue_packet_count(const linkaddr_t *addr);
|
||||
/* Remove first packet from a neighbor queue. The packet is stored in a separate
|
||||
* dequeued packet list, for later processing. Return the packet. */
|
||||
/**
|
||||
* \brief Remove first packet from a neighbor queue. The packet is stored in a separate
|
||||
* dequeued packet list, for later processing.
|
||||
* \param n The neighbor queue
|
||||
* \return The packet that was removed if any, NULL otherwise
|
||||
*/
|
||||
struct tsch_packet *tsch_queue_remove_packet_from_queue(struct tsch_neighbor *n);
|
||||
/* Free a packet */
|
||||
/**
|
||||
* \brief Free a packet
|
||||
* \param p The packet to be freed
|
||||
*/
|
||||
void tsch_queue_free_packet(struct tsch_packet *p);
|
||||
/* Updates neighbor queue state after a transmission */
|
||||
/**
|
||||
* \brief Updates neighbor queue state after a transmission
|
||||
* \param n The neighbor queue we just sent from
|
||||
* \param p The packet that was just sent
|
||||
* \param link The TSCH link used for Tx
|
||||
* \param mac_tx_status The MAC status (see mac.h)
|
||||
* \return 1 if the packet remains in queue after the call, 0 if it was removed
|
||||
*/
|
||||
int tsch_queue_packet_sent(struct tsch_neighbor *n, struct tsch_packet *p, struct tsch_link *link, uint8_t mac_tx_status);
|
||||
/* Reset neighbor queues */
|
||||
/**
|
||||
* \brief Reset neighbor queues module
|
||||
*/
|
||||
void tsch_queue_reset(void);
|
||||
/* Deallocate neighbors with empty queue */
|
||||
/**
|
||||
* \brief Deallocate all neighbors with empty queue
|
||||
*/
|
||||
void tsch_queue_free_unused_neighbors(void);
|
||||
/* Is the neighbor queue empty? */
|
||||
/**
|
||||
* \brief Is the neighbor queue empty?
|
||||
* \param n The neighbor queue
|
||||
* \return 1 if empty, 0 otherwise
|
||||
*/
|
||||
int tsch_queue_is_empty(const struct tsch_neighbor *n);
|
||||
/* Returns the first packet from a neighbor queue */
|
||||
/**
|
||||
* \brief Returns the first packet that can be sent from a queue on a given link
|
||||
* \param n The neighbor queue
|
||||
* \param link The link
|
||||
* \return The next packet to be sent for the neighbor on the given link, if any, else NULL
|
||||
*/
|
||||
struct tsch_packet *tsch_queue_get_packet_for_nbr(const struct tsch_neighbor *n, struct tsch_link *link);
|
||||
/* Returns the head packet from a neighbor queue (from neighbor address) */
|
||||
/**
|
||||
* \brief Returns the first packet that can be sent to a given address on a given link
|
||||
* \param addr The target link-layer address
|
||||
* \param link The link
|
||||
* \return The next packet to be sent for to the given address on the given link, if any, else NULL
|
||||
*/
|
||||
struct tsch_packet *tsch_queue_get_packet_for_dest_addr(const linkaddr_t *addr, struct tsch_link *link);
|
||||
/* Returns the head packet of any neighbor queue with zero backoff counter.
|
||||
* Writes pointer to the neighbor in *n */
|
||||
/**
|
||||
* \brief Gets the head packet of any neighbor queue with zero backoff counter.
|
||||
* \param n A pointer where to store the neighbor queue to be used for Tx
|
||||
* \param link The link to be used for Tx
|
||||
* \return The packet if any, else NULL
|
||||
*/
|
||||
struct tsch_packet *tsch_queue_get_unicast_packet_for_any(struct tsch_neighbor **n, struct tsch_link *link);
|
||||
/* May the neighbor transmit over a share link? */
|
||||
/**
|
||||
* \brief Is the neighbor backoff timer expired?
|
||||
* \param n The neighbor queue
|
||||
* \return 1 if the backoff has expired (neighbor ready to transmit on a shared link), 0 otherwise
|
||||
*/
|
||||
int tsch_queue_backoff_expired(const struct tsch_neighbor *n);
|
||||
/* Reset neighbor backoff */
|
||||
/**
|
||||
* \brief Reset neighbor backoff
|
||||
* \param n The neighbor queue
|
||||
*/
|
||||
void tsch_queue_backoff_reset(struct tsch_neighbor *n);
|
||||
/* Increment backoff exponent, pick a new window */
|
||||
/**
|
||||
* \brief Increment backoff exponent of a given neighbor queue, pick a new window
|
||||
* \param n The neighbor queue
|
||||
*/
|
||||
void tsch_queue_backoff_inc(struct tsch_neighbor *n);
|
||||
/* Decrement backoff window for all queues directed at dest_addr */
|
||||
/**
|
||||
* \brief Decrement backoff window for the queue(s) able to Tx to a given address
|
||||
* \param dest_addr The target address, &tsch_broadcast_address for broadcast
|
||||
*/
|
||||
void tsch_queue_update_all_backoff_windows(const linkaddr_t *dest_addr);
|
||||
/* Initialize TSCH queue module */
|
||||
/**
|
||||
* \brief Initialize TSCH queue module
|
||||
*/
|
||||
void tsch_queue_init(void);
|
||||
|
||||
#endif /* __TSCH_QUEUE_H__ */
|
||||
|
||||
@ -47,20 +47,35 @@
|
||||
|
||||
/********** Functions *********/
|
||||
|
||||
/* Keep-alives packet sent callback.
|
||||
* To use, set #define TSCH_CALLBACK_KA_SENT tsch_rpl_callback_ka_sent */
|
||||
/**
|
||||
* \brief Report statiscs from KA packet sent in RPL.
|
||||
* To use, set TSCH_CALLBACK_KA_SENT to tsch_rpl_callback_ka_sent
|
||||
* \param status The packet sent status
|
||||
* \param transmissions The total number of transmissions
|
||||
*/
|
||||
void tsch_rpl_callback_ka_sent(int status, int transmissions);
|
||||
/* To use, set #define TSCH_CALLBACK_JOINING_NETWORK tsch_rpl_callback_joining_network */
|
||||
/**
|
||||
* \brief Let RPL know that TSCH joined a new network.
|
||||
* To use, set TSCH_CALLBACK_JOINING_NETWORK to tsch_rpl_callback_joining_network
|
||||
*/
|
||||
void tsch_rpl_callback_joining_network(void);
|
||||
/* Upon leaving a TSCH network, perform a local repair
|
||||
* (cleanup neighbor state, reset Trickle timer etc)
|
||||
* To use, set #define TSCH_CALLBACK_LEAVING_NETWORK tsch_rpl_callback_leaving_network */
|
||||
/**
|
||||
* \brief Let RPL know that TSCH joined a new network. Triggers a local repair.
|
||||
* To use, set TSCH_CALLBACK_LEAVING_NETWORK to tsch_rpl_callback_leaving_network
|
||||
*/
|
||||
void tsch_rpl_callback_leaving_network(void);
|
||||
/* Set TSCH EB period based on current RPL DIO period.
|
||||
* To use, set #define RPL_CALLBACK_NEW_DIO_INTERVAL tsch_rpl_callback_new_dio_interval */
|
||||
/**
|
||||
* \brief Set TSCH EB period based on current RPL DIO period.
|
||||
* To use, set RPL_CALLBACK_NEW_DIO_INTERVAL to tsch_rpl_callback_new_dio_interval
|
||||
* \param dio_interval The new DIO interval in clock ticks
|
||||
*/
|
||||
void tsch_rpl_callback_new_dio_interval(clock_time_t dio_interval);
|
||||
/* Set TSCH time source based on current RPL preferred parent.
|
||||
* To use, set #define RPL_CALLBACK_PARENT_SWITCH tsch_rpl_callback_parent_switch */
|
||||
/**
|
||||
* \brief Set TSCH time source based on current RPL preferred parent.
|
||||
* To use, set RPL_CALLBACK_PARENT_SWITCH to tsch_rpl_callback_parent_switch
|
||||
* \param old The old RPL parent
|
||||
* \param new The new RPL parent
|
||||
*/
|
||||
void tsch_rpl_callback_parent_switch(rpl_parent_t *old, rpl_parent_t *new);
|
||||
|
||||
#endif /* __TSCH_RPL_H__ */
|
||||
|
||||
@ -45,42 +45,115 @@
|
||||
|
||||
/********** Functions *********/
|
||||
|
||||
/* Module initialization, call only once at startup. Returns 1 is success, 0 if failure. */
|
||||
/**
|
||||
* \brief Module initialization, call only once at init
|
||||
* \return 1 if success, 0 if failure
|
||||
*/
|
||||
int tsch_schedule_init(void);
|
||||
/* Create a 6TiSCH minimal schedule */
|
||||
/**
|
||||
* \brief Create a 6tisch minimal schedule with length TSCH_SCHEDULE_DEFAULT_LENGTH
|
||||
*/
|
||||
void tsch_schedule_create_minimal(void);
|
||||
/* Prints out the current schedule (all slotframes and links) */
|
||||
/**
|
||||
* \brief Prints out the current schedule (all slotframes and links)
|
||||
*/
|
||||
void tsch_schedule_print(void);
|
||||
|
||||
/* Adds and returns a slotframe (NULL if failure) */
|
||||
|
||||
/**
|
||||
* \brief Creates and adds a new slotframe
|
||||
* \param handle the slotframe handle
|
||||
* \param size the slotframe size
|
||||
* \return the new slotframe, NULL if failure
|
||||
*/
|
||||
struct tsch_slotframe *tsch_schedule_add_slotframe(uint16_t handle, uint16_t size);
|
||||
/* Looks for a slotframe from a handle */
|
||||
|
||||
/**
|
||||
* \brief Looks up a slotframe by handle
|
||||
* \param handle the slotframe handle
|
||||
* \return the slotframe with required handle, if any. NULL otherwise.
|
||||
*/
|
||||
struct tsch_slotframe *tsch_schedule_get_slotframe_by_handle(uint16_t handle);
|
||||
/* Removes a slotframe Return 1 if success, 0 if failure */
|
||||
|
||||
/**
|
||||
* \brief Removes a slotframe
|
||||
* \param slotframe The slotframe to be removed
|
||||
* \return 1 if success, 0 if failure
|
||||
*/
|
||||
int tsch_schedule_remove_slotframe(struct tsch_slotframe *slotframe);
|
||||
/* Removes all slotframes, resulting in an empty schedule */
|
||||
|
||||
/**
|
||||
* \brief Removes all slotframes, resulting in an empty schedule
|
||||
* \return 1 if success, 0 if failure
|
||||
*/
|
||||
int tsch_schedule_remove_all_slotframes(void);
|
||||
|
||||
/* Returns next slotframe */
|
||||
struct tsch_slotframe *tsch_schedule_slotframes_next(struct tsch_slotframe *sf);
|
||||
/* Adds a link to a slotframe, return a pointer to it (NULL if failure) */
|
||||
/**
|
||||
* \brief Adds a link to a slotframe
|
||||
* \param slotframe The slotframe that will contain the new link
|
||||
* \param link_options The link options, as a bitfield (LINK_OPTION_* flags)
|
||||
* \param link_type The link type (advertising, normal)
|
||||
* \param address The link address of the intended destination. Use &tsch_broadcast_address for a slot towards any neighbor
|
||||
* \param timeslot The link timeslot within the slotframe
|
||||
* \param channel_offset The link channel offset
|
||||
* \return A pointer to the new link, NULL if failure
|
||||
*/
|
||||
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);
|
||||
/* Looks for a link from a handle */
|
||||
/**
|
||||
* \brief Looks for a link from a handle
|
||||
* \param handle The target handle
|
||||
* \return The link with required handle, if any. Otherwise, NULL
|
||||
*/
|
||||
struct tsch_link *tsch_schedule_get_link_by_handle(uint16_t handle);
|
||||
/* Looks within a slotframe for a link with a given timeslot */
|
||||
|
||||
/**
|
||||
* \brief Looks within a slotframe for a link with a given timeslot
|
||||
* \param slotframe The desired slotframe
|
||||
* \param timeslot The desired timeslot
|
||||
* \return The link if found, NULL otherwise
|
||||
*/
|
||||
struct tsch_link *tsch_schedule_get_link_by_timeslot(struct tsch_slotframe *slotframe, uint16_t timeslot);
|
||||
/* Removes a link. Return 1 if success, 0 if failure */
|
||||
|
||||
/**
|
||||
* \brief Removes a link
|
||||
* \param slotframe The slotframe the link belongs to
|
||||
* \param l The link to be removed
|
||||
* \return 1 if success, 0 if failure
|
||||
*/
|
||||
int tsch_schedule_remove_link(struct tsch_slotframe *slotframe, struct tsch_link *l);
|
||||
/* Removes a link from slotframe and timeslot. Return a 1 if success, 0 if failure */
|
||||
|
||||
/**
|
||||
* \brief Removes a link from a slotframe and timeslot
|
||||
* \param slotframe The slotframe where to look for the link
|
||||
* \param timeslot The timeslot where to look for the link within the target slotframe
|
||||
* \return 1 if success, 0 if failure
|
||||
*/
|
||||
int tsch_schedule_remove_link_by_timeslot(struct tsch_slotframe *slotframe, uint16_t timeslot);
|
||||
|
||||
/* Returns the next active link after a given ASN, and a backup link (for the same ASN, with Rx flag) */
|
||||
|
||||
/**
|
||||
* \brief Returns the next active link after a given ASN, and a backup link (for the same ASN, with Rx flag)
|
||||
* \param asn The base ASN, from which we look for the next active link
|
||||
* \param time_offset A pointer to uint16_t where to store the time offset between base ASN and link found
|
||||
* \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
|
||||
* \return The next active link if any, NULL otherwise
|
||||
*/
|
||||
struct tsch_link * tsch_schedule_get_next_active_link(struct tsch_asn_t *asn, uint16_t *time_offset,
|
||||
struct tsch_link **backup_link);
|
||||
/* Access to slotframe list */
|
||||
|
||||
/**
|
||||
* \brief Access the first item in the list of slotframes
|
||||
* \return The first slotframe in the schedule if any, NULL otherwise
|
||||
*/
|
||||
struct tsch_slotframe *tsch_schedule_slotframe_head(void);
|
||||
|
||||
/**
|
||||
* \brief Access the next item in the list of slotframes
|
||||
* \param sf The current slotframe (item in the list)
|
||||
* \return The next slotframe if any, NULL otherwise
|
||||
*/
|
||||
struct tsch_slotframe *tsch_schedule_slotframe_next(struct tsch_slotframe *sf);
|
||||
|
||||
#endif /* __TSCH_SCHEDULE_H__ */
|
||||
|
||||
@ -58,19 +58,45 @@ extern clock_time_t last_sync_time;
|
||||
|
||||
/********** Functions *********/
|
||||
|
||||
/* Returns a 802.15.4 channel from an ASN and channel offset */
|
||||
/**
|
||||
* Returns a 802.15.4 channel from an ASN and channel offset. Basically adds
|
||||
* The offset to the ASN and performs a hopping sequence lookup.
|
||||
*
|
||||
* \param asn A given ASN
|
||||
* \param channel_offset A given channel offset
|
||||
* \return The resulting channel
|
||||
*/
|
||||
uint8_t tsch_calculate_channel(struct tsch_asn_t *asn, uint8_t channel_offset);
|
||||
/* Is TSCH locked? */
|
||||
/**
|
||||
* Checks if the TSCH lock is set. Accesses to global structures outside of
|
||||
* interrupts must be done through the lock, unless the sturcutre has
|
||||
* atomic read/write
|
||||
*
|
||||
* \return 1 if the lock is taken, 0 otherwise
|
||||
*/
|
||||
int tsch_is_locked(void);
|
||||
/* Lock TSCH (no link operation) */
|
||||
/**
|
||||
* Takes the TSCH lock. When the lock is taken, slot operation will be skipped
|
||||
* until release.
|
||||
*
|
||||
* \return 1 if the lock was successfully taken, 0 otherwise
|
||||
*/
|
||||
int tsch_get_lock(void);
|
||||
/* Release TSCH lock */
|
||||
/**
|
||||
* Releases the TSCH lock.
|
||||
*/
|
||||
void tsch_release_lock(void);
|
||||
/* Set global time before starting slot operation,
|
||||
* with a rtimer time and an ASN */
|
||||
/**
|
||||
* Set global time before starting slot operation, with a rtimer time and an ASN
|
||||
*
|
||||
* \param next_slot_start the time to the start of the next slot, in rtimer ticks
|
||||
* \param next_slot_asn the ASN of the next slot
|
||||
*/
|
||||
void tsch_slot_operation_sync(rtimer_clock_t next_slot_start,
|
||||
struct tsch_asn_t *next_slot_asn);
|
||||
/* Start actual slot operation */
|
||||
/**
|
||||
* Start actual slot operation
|
||||
*/
|
||||
void tsch_slot_operation_start(void);
|
||||
|
||||
#endif /* __TSCH_SLOT_OPERATION_H__ */
|
||||
|
||||
@ -53,10 +53,10 @@
|
||||
|
||||
/********** Data types **********/
|
||||
|
||||
/* 802.15.4e link types.
|
||||
* LINK_TYPE_ADVERTISING_ONLY is an extra one: for EB-only links. */
|
||||
/** \brief 802.15.4e link types. LINK_TYPE_ADVERTISING_ONLY is an extra one: for EB-only links. */
|
||||
enum link_type { LINK_TYPE_NORMAL, LINK_TYPE_ADVERTISING, LINK_TYPE_ADVERTISING_ONLY };
|
||||
|
||||
/** \brief An IEEE 802.15.4-2015 TSCH link (also called cell or slot) */
|
||||
struct tsch_link {
|
||||
/* Links are stored as a list: "next" must be the first field */
|
||||
struct tsch_link *next;
|
||||
@ -83,7 +83,7 @@ struct tsch_link {
|
||||
void *data;
|
||||
};
|
||||
|
||||
/* 802.15.4e slotframe (contains links) */
|
||||
/** \brief 802.15.4e slotframe (contains links) */
|
||||
struct tsch_slotframe {
|
||||
/* Slotframes are stored as a list: "next" must be the first field */
|
||||
struct tsch_slotframe *next;
|
||||
@ -96,7 +96,7 @@ struct tsch_slotframe {
|
||||
LIST_STRUCT(links_list);
|
||||
};
|
||||
|
||||
/* TSCH packet information */
|
||||
/** \brief TSCH packet information */
|
||||
struct tsch_packet {
|
||||
struct queuebuf *qb; /* pointer to the queuebuf to be sent */
|
||||
mac_callback_t sent; /* callback for this packet */
|
||||
@ -108,7 +108,7 @@ struct tsch_packet {
|
||||
uint8_t tsch_sync_ie_offset; /* Offset within the frame used for quick update of EB ASN and join priority */
|
||||
};
|
||||
|
||||
/* TSCH neighbor information */
|
||||
/** \brief TSCH neighbor information */
|
||||
struct tsch_neighbor {
|
||||
/* Neighbors are stored as a list: "next" must be the first field */
|
||||
struct tsch_neighbor *next;
|
||||
@ -127,7 +127,7 @@ struct tsch_neighbor {
|
||||
struct ringbufindex tx_ringbuf;
|
||||
};
|
||||
|
||||
/* TSCH timeslot timing elements. Used to index timeslot timing
|
||||
/** \brief TSCH timeslot timing elements. Used to index timeslot timing
|
||||
* of different units, such as rtimer tick or micro-second */
|
||||
enum tsch_timeslot_timing_elements {
|
||||
tsch_ts_cca_offset,
|
||||
@ -145,7 +145,7 @@ enum tsch_timeslot_timing_elements {
|
||||
tsch_ts_elements_count, /* Not a timing element */
|
||||
};
|
||||
|
||||
/* Stores data about an incoming packet */
|
||||
/** \brief Stores data about an incoming packet */
|
||||
struct input_packet {
|
||||
uint8_t payload[TSCH_PACKET_MAX_LEN]; /* Packet payload */
|
||||
struct tsch_asn_t rx_asn; /* ASN when the packet was received */
|
||||
|
||||
@ -180,21 +180,57 @@ PROCESS_NAME(tsch_pending_events_process);
|
||||
|
||||
/********** Functions *********/
|
||||
|
||||
/* The the TSCH join priority */
|
||||
/**
|
||||
* Set the TSCH join priority (JP)
|
||||
*
|
||||
* \param jp the new join priority
|
||||
*/
|
||||
void tsch_set_join_priority(uint8_t jp);
|
||||
/* The period at which EBs are sent */
|
||||
/**
|
||||
* Set the period at wich TSCH enhanced beacons (EBs) are sent. The period can
|
||||
* not be set to exceed TSCH_MAX_EB_PERIOD. Set to 0 to stop sending EBs.
|
||||
* Actual transmissions are jittered, spaced by a random number within
|
||||
* [period*0.75, period[
|
||||
*
|
||||
* \param period The period in Clock ticks.
|
||||
*/
|
||||
void tsch_set_eb_period(uint32_t period);
|
||||
/* The keep-alive timeout */
|
||||
/**
|
||||
* Set the desynchronization timeout after which a node sends a unicasst
|
||||
* keep-alive (KA) to its time source. Set to 0 to stop sending KAs. The
|
||||
* actual timeout is a random number within
|
||||
* [timeout*0.9, timeout[
|
||||
*
|
||||
* \param timeout The timeout in Clock ticks.
|
||||
*/
|
||||
void tsch_set_ka_timeout(uint32_t timeout);
|
||||
/* Set the node as PAN coordinator */
|
||||
/**
|
||||
* Set the node as PAN coordinator
|
||||
*
|
||||
* \param enable 1 to be coordinator, 0 to be a node
|
||||
*/
|
||||
void tsch_set_coordinator(int enable);
|
||||
/* Set the pan as secured or not */
|
||||
/**
|
||||
* Enable/disable security. If done at the coordinator, the Information
|
||||
* will be included in EBs, and all nodes will adopt the same security level.
|
||||
* Enabling requires compilation with LLSEC802154_ENABLED set.
|
||||
* Note: when LLSEC802154_ENABLED is set, nodes boot with security enabled.
|
||||
*
|
||||
* \param enable 1 to enable security, 0 to disable it
|
||||
*/
|
||||
void tsch_set_pan_secured(int enable);
|
||||
/* Set TSCH to send a keepalive message after TSCH_KEEPALIVE_TIMEOUT */
|
||||
/**
|
||||
* Schedule a keep-alive transmission within [timeout*0.9, timeout[
|
||||
* @see tsch_set_ka_timeout
|
||||
*/
|
||||
void tsch_schedule_keepalive(void);
|
||||
/* Set TSCH to send a keepalive message immediately */
|
||||
/**
|
||||
* Schedule a keep-alive immediately
|
||||
*/
|
||||
void tsch_schedule_keepalive_immediately(void);
|
||||
/* Leave the TSCH network */
|
||||
/**
|
||||
* Leave the TSCH network we are currently in
|
||||
*/
|
||||
void tsch_disassociate(void);
|
||||
|
||||
#endif /* __TSCH_H__ */
|
||||
|
||||
Loading…
Reference in New Issue
Block a user