6top: refactoring

- support draft-ietf-6tisch-6top-protocol-03
- reconsider file structure and file names
- make sf-simple part of example
- update sixtop/README.md
- apply C-DAC copyright notice
- bugfix + cleanup

core/net/mac/frame802154e-ie.c

@@ -61,7 +61,7 @@ enum ieee802154e_payload_ie_id {
   PAYLOAD_IE_ESDU = 0,
   PAYLOAD_IE_MLME,
   PAYLOAD_IE_VENDOR,
-  PAYLOAD_IE_IANA_IETF,
+  PAYLOAD_IE_IETF,
   PAYLOAD_IE_LIST_TERMINATION = 0xf,
 };
 
@@ -81,8 +81,8 @@ enum ieee802154e_mlme_long_subie_id {
   MLME_LONG_IE_TSCH_CHANNEL_HOPPING_SEQUENCE = 0x9,
 };
 
-enum ieee802154e_iana_ietf_subie_id {
-  IANA_IETF_IE_6TOP = 0x00,
+enum ieee802154e_ietf_subie_id {
+  IETF_IE_6TOP = 0x00,
 };
 
 #define WRITE16(buf, val) \
@@ -200,11 +200,11 @@ frame80215e_create_ie_payload_list_termination(uint8_t *buf, int len,
 
 /* Payload IE. 6top. Used to nest sub-IEs */
 int
-frame80215e_create_ie_iana_ietf(uint8_t *buf, int len, struct ieee802154_ies *ies)
+frame80215e_create_ie_ietf(uint8_t *buf, int len, struct ieee802154_ies *ies)
 {
   int ie_len = ies->sixtop_ie_content_len;
   if(len >= 2 + ie_len && ies != NULL) {
-    create_payload_ie_descriptor(buf, PAYLOAD_IE_IANA_IETF, ie_len);
+    create_payload_ie_descriptor(buf, PAYLOAD_IE_IETF, ie_len);
     return 2 + ie_len;
   } else {
     return -1;
@@ -548,15 +548,25 @@ frame802154e_parse_information_elements(const uint8_t *buf, uint8_t buf_size,
             len = 0; /* Reset len as we want to read subIEs and not jump over them */
             PRINTF("frame802154e: entering MLME ie with len %u\n", nested_mlme_len);
             break;
-          case PAYLOAD_IE_IANA_IETF:
-            /* Now expect 'len' bytes of Sixtop sub-IEs */
+          case PAYLOAD_IE_IETF:
             switch(*buf) {
-            case IANA_IETF_IE_6TOP:
-              ies->sixtop_ie_content_ptr = buf + 1;
-              ies->sixtop_ie_content_len = len - 1;
-              break;
-            default:
-              PRINTF("frame802154e: unsupported IANA-IETF sub-IE %u\n", *buf);
+              case IETF_IE_6TOP:
+                /*
+                 * buf points to the Sub-ID field, a one-octet field, now;
+                 * advance it by one and use the result as the head pointer of
+                 * 6top IE Content.
+                 */
+                ies->sixtop_ie_content_ptr = buf + 1;
+                /*
+                 * Similarly as above, subtract 1 (one octet) from len, which
+                 * includes the length of Sub-ID field, and use the result as
+                 * the length of 6top IE Content.
+                 */
+                ies->sixtop_ie_content_len = len - 1;
+                break;
+              default:
+                PRINTF("frame802154e: unsupported IETF sub-IE %u\n", *buf);
+                break;
             }
             break;
           case PAYLOAD_IE_LIST_TERMINATION:

core/net/mac/frame802154e-ie.h

@@ -101,7 +101,7 @@ int frame80215e_create_ie_header_list_termination_2(uint8_t *buf, int len,
 int frame80215e_create_ie_payload_list_termination(uint8_t *buf, int len,
     struct ieee802154_ies *ies);
 /* Payload IE. 6top. Used to nest sub-IEs */
-int frame80215e_create_ie_iana_ietf(uint8_t *buf, int len,
+int frame80215e_create_ie_ietf(uint8_t *buf, int len,
     struct ieee802154_ies *ies);
 /* Payload IE. MLME. Used to nest sub-IEs */
 int frame80215e_create_ie_mlme(uint8_t *buf, int len,

core/net/mac/tsch/sixtop/README.md

@@ -1,64 +1,94 @@
+# [EXPERIMENTAL] 6TiSCH Operation Sublayer (6top)
 
+## Overview
 
+6TiSCH Operation Sublayer (6top), a logical link layer in the 6TiSCH
+architecture, provides the abstraction of an IP link over a TSCH MAC layer (IEEE
+802.15.4e). The functionality of 6top is to facilitate the dynamic cell
+negotiation with one-hop neighbors.
 
-# 6TiSCH Operation Sublayer (6top)
+This is a Contiki implementation of 6top, developed by:
 
-## **Overview**
-
-6TiSCH Operation Sublayer (6top), a logical link layer in the 6TiSCH architecture,  provides the abstraction of an IP link over a TSCH MAC layer (IEEE 802.15.4e). The functionality of 6top is to facilitate the dynamic cell negotiation with one-hop neighbors.
-
-This is a Contiki implementation of 6top, which defines how to handle a 2-step 6top transaction on a basic RPL+TSCH network.
+- Shalu R, CDAC, shalur@cdac.in, github user: [shalurajendran](https://github.com/shalurajendran)
+- Lijo Thomas, CDAC, lijo@cdac.in
+- Yasuyuki Tanaka
 
-Developed by:
+It supports 6P of [draft-03](draft-ietf-6tisch-6top-protocol-03) except for
+concurrent 6P transactions described in [Section
+4.3.3](https://tools.ietf.org/html/draft-ietf-6tisch-6top-protocol-03#section-4.3.3).
 
-- Shalu R, CDAC, shalur@cdac.in, github user:  [shalurajendran](https://github.com/shalurajendran)
-- Lijo Thomas, CDAC, lijo@cdac.in
+## Code Structure
 
-## **Features**
+6P is implemented in:
+- `core/net/mac/tsch/sixtop/sixtop.[ch]`: provides 6top APIs
+- `core/net/mac/tsch/sixtop/sixp.[ch]`: has charge of 6P other than packet manipulation
+- `core/net/mac/tsch/sixtop/sixp-packet[ch]`: provides 6P packet creater and parser
 
-This implementation includes:
+## Configuration Paramters
 
-- 6top protocol(6P)
-  - 6P Add
-  - 6P Delete
-- 2-step 6top Transaction
+- `SIXTOP_CONF_MAX_SCHEDULE_FUNCTIONS`: the maximum number of SFs in 6top
+- `SIXTOP_CONF_6P_MAX_TRANSACTIONS`: the maximum number of transactions in process
+- `SIXTOP_CONF_6P_MAX_NEIGHBORS`: the maximum number of 6P neighbor states
 
-The code has been tested on Zolertia Z1 (z1, tested in cooja only) platform.
+## Caveat
 
-## **Code structure**
+At this moment, allocated 6P neighbor states never be deleted since 6P has no
+way to decide to delete them. 6P neighbor state consists of SeqNum to be used
+for a next reqeust, GTX, and GRX.
 
-The 6top frame format is included in:
+Once the number of 6P neighbor states reaches to the `SIXTOP_6P_MAX_NEIGHBORS`,
+a transaction with a new neighbor may fail due to failure in allocating a 6P
+neighbor state or schedule generation inconsistency.
 
-- core/net/mac/frame802154-ie.[ch]: Modified to include Sixtop Information Elements
+## Example
 
-6top is implemented in:
+An example using 6top is provided under `examples/ipv6/rpl-tsch-sxitop/`.
 
-- core/net/mac/tsch/sixtop/sixtop.[ch]: 6top interface and 6top protocol(6P addition and deletion), handling of 6P Requests and Response
+A simple Schedule Function (SF) is implemented in `sf-simple.[ch]`. This SF does
+not have bandwidth monitoring mechanism nor bandwidth adaptation
+mechanism. Instead, the SF provides APIs so that a user process can add or
+remove cells dynamically. A sample user process implementation using the SF is
+found in `node-sixtop.c`, which is tested with `rpl-tsch-sixtop-z1.csc`.
 
-TSCH file modified:
+## Using 6top
 
-- core/net/mac/tsch/tsch.[ch]: Modified to include Sixtop module
+In order to use 6top with your system, `sixtop` module must be built together in
+addition to [TSCH](../).
 
+Enable TSCH, then set 1 to `TSCH_CONF_WITH_SIXTOP`, typically, in your
+`project-conf.h`:
 
-## **Using 6top**
+```C
+#undef TSCH_CONF_WITH_SIXTOP
+#define TSCH_CONF_WITH_SIXTOP 1
+```
 
-A simple 6top+TSCH+RPL example is included under examples/ipv6/rpl-tsch-sixtop. Currently this application triggers the 6P transactions, later the 6top Scheduling Function (SF) may be implemented for the purpose.
+Next, add `sixtop` into `MODULES` in your Makefile:
 
-To use 6top, make sure your platform supports TSCH and have sufficient memory.
+```Makefile
+MODULES += core/net/mac/tsch/sixtop
+```
 
-To add 6top to your application, first include the Sixtop module in your Makefile with:
+For now, the simple SF mentioned above is only one SF shipped in the code
+base. You may have to implement your own SF.
 
-  MODULES += core/net/mac/tsch/sixtop
+## Implementing a Schedule Function
 
-Also enable the sixtop functionalities in your project-conf.h file with
+Schedule Function (SF) is represented with `sixtop_sf_t`, which defined in
+`sixtop.h`. An SF can be added into 6top by `sixtop_add_sf()`. After the
+addition, a handler defined in `sixtop_sf_t` is invoked on a correspondent
+event, for example, reception of a 6P request or timeout of an ongoing
+transaction.
 
-	#undef TSCH_CONF_WITH_SIXTOP
-
-	#define TSCH_CONF_WITH_SIXTOP 1
+SF can send a 6P packet by `sixp_send()`. After every Add or Delete operation,
+SF needs to advance schedule generation counter associated with the peer by
+`sixp_advance_generation()`, counter which is maintaeind by 6P. Otherwise, SF
+will not able to perform any command request other than Clear due to schedule
+generation inconsistency.
 
-## **Additional documentation**
+## References
 
 1. [IETF 6TiSCH Working Group](https://datatracker.ietf.org/wg/6tisch)
-2. [6TiSCH 6top Protocol (6P)](https://tools.ietf.org/pdf/draft-ietf-6tisch-6top-protocol-02.pdf)
+2. [6top Protocol (6P)](https://tools.ietf.org/html/draft-ietf-6tisch-6top-protocol)