From 8be446d0ea9bc57ac9753fd423c64b2b61f88de1 Mon Sep 17 00:00:00 2001 From: Simon Duquennoy Date: Sat, 14 Apr 2018 12:09:16 -0700 Subject: [PATCH] Doxygen for tsch-schedule.h --- os/net/mac/tsch/tsch-schedule.h | 105 +++++++++++++++++++++++++++----- 1 file changed, 89 insertions(+), 16 deletions(-) diff --git a/os/net/mac/tsch/tsch-schedule.h b/os/net/mac/tsch/tsch-schedule.h index 2a2cf5e25..9a9a7330f 100644 --- a/os/net/mac/tsch/tsch-schedule.h +++ b/os/net/mac/tsch/tsch-schedule.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__ */