Merge pull request #857 from simonduq/contrib/tsch-timeslot-elements

Document and clean up TSCH timeslot timing elements

arch/cpu/cc2538/dev/cc2538-rf.c

@@ -1031,6 +1031,7 @@ get_object(radio_param_t param, void *dest, size_t size)
     if(size != sizeof(uint16_t *) || !dest) {
       return RADIO_RESULT_INVALID_VALUE;
     }
+    /* Assigned value: a pointer to the TSCH timing in usec */
     *(const uint16_t **)dest = tsch_timeslot_timing_us_10000;
     return RADIO_RESULT_OK;
   }

arch/cpu/cc26x0-cc13x0/rf-core/cc13xx-50kbps-tsch.c

@@ -57,7 +57,7 @@
 #define CC13XX_TSCH_DEFAULT_TS_TIMESLOT_LENGTH  40000
 
 /* TSCH timeslot timing (microseconds) */
-const uint16_t tsch_timing_cc13xx_50kbps[tsch_ts_elements_count] = {
+const tsch_timeslot_timing_usec tsch_timing_cc13xx_50kbps = {
   CC13XX_TSCH_DEFAULT_TS_CCA_OFFSET,
   CC13XX_TSCH_DEFAULT_TS_CCA,
   CC13XX_TSCH_DEFAULT_TS_TX_OFFSET,

arch/dev/cc1200/cc1200-802154g-863-870-fsk-50kbps.c

@@ -94,7 +94,7 @@ static const char rf_cfg_descriptor[] = "802.15.4g 863-870MHz MR-FSK mode #1";
                                                   )
 
 /* TSCH timeslot timing (mircoseconds) */
-static const uint16_t cc1200_50kbps_tsch_timing[tsch_ts_elements_count] = {
+static const tsch_timeslot_timing_usec cc1200_50kbps_tsch_timing = {
   CC1200_TSCH_DEFAULT_TS_CCA_OFFSET,
   CC1200_TSCH_DEFAULT_TS_CCA,
   CC1200_TSCH_DEFAULT_TS_TX_OFFSET,

arch/dev/cc1200/cc1200-868-4gfsk-1000kbps.c

@@ -86,7 +86,7 @@ static const char rf_cfg_descriptor[] = "868MHz 2-GFSK 1000 kbps";
                                                   )
 
 /* TSCH timeslot timing (in rtimer ticks) */
-static const uint16_t cc1200_1000kbps_tsch_timing[tsch_ts_elements_count] = {
+static const tsch_timeslot_timing_usec cc1200_1000kbps_tsch_timing = {
   CC1200_TSCH_DEFAULT_TS_CCA_OFFSET,
   CC1200_TSCH_DEFAULT_TS_CCA,
   CC1200_TSCH_DEFAULT_TS_TX_OFFSET,

arch/dev/cc1200/cc1200.c

@@ -1449,6 +1449,7 @@ get_object(radio_param_t param, void *dest, size_t size)
     if(size != sizeof(uint16_t *) || !dest) {
       return RADIO_RESULT_INVALID_VALUE;
     }
+    /* Assigned value: a pointer to the TSCH timing in usec */
     *(const uint16_t **)dest = CC1200_RF_CFG.tsch_timing;
     return RADIO_RESULT_OK;
   }

arch/dev/cc2420/cc2420-tsch-15ms.c

@@ -45,7 +45,7 @@
  * \brief 15ms TSCH timeslot timings, required for cc2420 platforms as
  * they are unable to keep up with the defulat 10ms timeslots.
  */
-const uint16_t tsch_timeslot_timing_us_15000[tsch_ts_elements_count] = {
+const tsch_timeslot_timing_usec tsch_timeslot_timing_us_15000= {
   1800, /* CCAOffset */
    128, /* CCA */
   4000, /* TxOffset */

arch/platform/zoul/platform.c

@@ -295,6 +295,7 @@ radio_delay_before_detect(void) {
 uint16_t *
 radio_tsch_timeslot_timing(void) {
   uint16_t *ret;
+  /* Get and return pointer to TSCH timings in usec */
   NETSTACK_RADIO.get_object(RADIO_CONST_TSCH_TIMING, &ret, sizeof(ret));
   return ret;
 }

os/dev/radio.h

@@ -185,11 +185,26 @@ enum {
   /* The maximum transmission power in dBm. */
   RADIO_CONST_TXPOWER_MAX,
 
+  /* A pointer to TSCH timings in micro-seconds (tsch_timeslot_timing_usec *) */
   RADIO_CONST_TSCH_TIMING,
+
+  /* The physical layer header+footer overhead in bytes, after SFD.
+   * On IEEE 802.15.4 at 2.4 GHz: 1 byte for len + 2 for CRC => 3 */
   RADIO_CONST_PHY_OVERHEAD,
+
+  /* The air time of one byte in usec, e.g. 32 for IEEE 802.15.4 at 2.4 GHz */
   RADIO_CONST_BYTE_AIR_TIME,
+
+  /* The delay in usec between a call to the radio API's transmit function and
+   * the end of SFD transmission */
   RADIO_CONST_DELAY_BEFORE_TX,
+
+  /* The delay in usec between turning on the radio and it being actually
+   * listening (able to hear a preamble) */
   RADIO_CONST_DELAY_BEFORE_RX,
+
+  /* The delay in usec between the end of SFD reception for an incoming frame
+   * and the radio API starting to return receiving_packet() != 0 */
   RADIO_CONST_DELAY_BEFORE_DETECT,
 };
 

os/net/mac/tsch/tsch-timeslot-timing.c

@@ -61,7 +61,7 @@
  * (TxOffset - (RxWait / 2)) instead
  */
 
-const uint16_t tsch_timeslot_timing_us_10000[tsch_ts_elements_count] = {
+const tsch_timeslot_timing_usec tsch_timeslot_timing_us_10000 = {
    1800, /* CCAOffset */
     128, /* CCA */
    2120, /* TxOffset */

os/net/mac/tsch/tsch-types.h

@@ -142,6 +142,12 @@ enum tsch_timeslot_timing_elements {
   tsch_ts_elements_count, /* Not a timing element */
 };
 
+/** \brief TSCH timeslot timing elements in rtimer ticks */
+typedef rtimer_clock_t tsch_timeslot_timing_ticks[tsch_ts_elements_count];
+
+/** \brief TSCH timeslot timing elements in micro-seconds */
+typedef uint16_t tsch_timeslot_timing_usec[tsch_ts_elements_count];
+
 /** \brief Stores data about an incoming packet */
 struct input_packet {
   uint8_t payload[TSCH_PACKET_MAX_LEN]; /* Packet payload */

os/net/mac/tsch/tsch.h

@@ -167,9 +167,9 @@ extern uint8_t tsch_current_channel;
 extern uint8_t tsch_hopping_sequence[TSCH_HOPPING_SEQUENCE_MAX_LEN];
 extern struct tsch_asn_divisor_t tsch_hopping_sequence_length;
 /* TSCH timeslot timing (in micro-second) */
-extern uint16_t tsch_timing_us[tsch_ts_elements_count];
+extern tsch_timeslot_timing_usec tsch_timing_us;
 /* TSCH timeslot timing (in rtimer ticks) */
-extern rtimer_clock_t tsch_timing[tsch_ts_elements_count];
+extern tsch_timeslot_timing_ticks tsch_timing;
 /* Statistics on the current session */
 extern unsigned long tx_count;
 extern unsigned long rx_count;
@@ -177,7 +177,7 @@ extern unsigned long sync_count;
 extern int32_t min_drift_seen;
 extern int32_t max_drift_seen;
 /* The TSCH standard 10ms timeslot timing */
-extern const uint16_t tsch_timeslot_timing_us_10000[tsch_ts_elements_count];
+extern const tsch_timeslot_timing_usec tsch_timeslot_timing_us_10000;
 
 /* TSCH processes */
 PROCESS_NAME(tsch_process);