Contiki-NG
sixtop.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016, Yasuyuki Tanaka
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 copyright holder nor the names of its
14  * contributors may be used to endorse or promote products derived
15  * from this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
20  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
21  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
22  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28  * OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 /**
31  * \addtogroup link-layer
32  * @{
33  */
34 /**
35  * \defgroup sixtop 6TiSCH Operation Sublayer (6top)
36  * @{
37  */
38 /**
39  * \file
40  * 6TiSCH Operation Sublayer (6top) APIs
41  * \author
42  * Yasuyuki Tanaka <yasuyuki.tanaka@inf.ethz.ch>
43  */
44 
45 #ifndef _SIXTOP_H_
46 #define _SIXTOP_H_
47 
48 #include "net/mac/mac.h"
49 #include "net/linkaddr.h"
50 
51 #include "sixp-pkt.h"
52 
53 #define SIXTOP_SUBIE_ID 0xc9
54 
55 /**
56  * \brief Input Handler of Scheduling Function
57  * \param type 6P Message Type of an input packet
58  * \param code Code, 6P Command Identifier or Return Code, of an input packet
59  * \param body Body, "Other Fields", of an input packet
60  * \param body_len The length of body
61  * \param body src_addr Source address of an input packet
62  */
63 typedef void (* sixtop_sf_input)(sixp_pkt_type_t type,
64  sixp_pkt_code_t code,
65  const uint8_t *body,
66  uint16_t body_len,
67  const linkaddr_t *src_addr);
68 
69 /**
70  * \brief Timeout Handler of Scheduling Function
71  * \param cmd 6P Command (Identifier) in process under the transaction
72  * \param peer_addr The peer address of the transaction
73  */
74 typedef void (* sixtop_sf_timeout)(sixp_pkt_cmd_t cmd,
75  const linkaddr_t *peer_addr);
76 /**
77  * /brief Scheduling Function Driver
78  */
79 typedef struct {
80  uint8_t sfid; /**< SFID */
81  clock_time_t timeout_interval; /**< Timeout Value */
82  void (*init)(void); /**< Init Function */
83  sixtop_sf_input input; /**< Input Handler */
84  sixtop_sf_timeout timeout; /**< Transaction Timeout Handler */
85 } sixtop_sf_t;
86 /**
87  * \var sixtop_sf_t::sfid
88  * managed: 0x00-0xfe
89  * unmanaged: 0xf0-0xfe
90  * reserved: 0xff
91  */
92 
93 
94 /**
95  * \brief Add a Scheduling Function (SF) to 6top Sublayer
96  * \param sf The pointer to a Scheduling Function Driver
97  * \return 0 on success, -1 on failure
98  *
99  * If there is a SF whose SF is identical to one of a SF specified to this API,
100  * the addition will fail and -1 will be returned. If there is no room to
101  * another SF, -1 will be returned as well. You can specify how many SFs can be
102  * added with SIXTOP_CONF_MAX_SCHEDULING_FUNCTIONS.
103  */
104 int sixtop_add_sf(const sixtop_sf_t *sf);
105 
106 /**
107  * \brief Find a SF which has been added by SFID
108  * \param sfid Scheduling Function Identifier of a SF
109  * \return The pointer to a SF driver having the specified SFID on success, NULL
110  * on failure (not found)
111  */
112 const sixtop_sf_t *sixtop_find_sf(uint8_t sfid);
113 
114 /**
115  * \brief Output a 6P packet which is supposestored in packetbuf
116  * \param dest_addr Destination address of the outgoing packet
117  * \param callback MAC callback function to get a TX result
118  * \param arg The pointer to an argument which is returned with the MAC callback
119  */
120 void sixtop_output(const linkaddr_t *dest_addr,
121  mac_callback_t callback, void *arg);
122 
123 /**
124  * \brief Input a packet stored in packetbuf
125  */
126 void sixtop_input(void);
127 
128 /**
129  * \brief Initialize 6top module
130  * This initialization function removes all the SFs which has been installed
131  * into the 6top sub-layer. In addition, it invokes sixp_init().
132  */
133 void sixtop_init(void);
134 
135 /**
136  * \brief Initialize installed SFs which has been added in the system
137  * This function is supposed to be invoked every time the node gets associated.
138  */
139 void sixtop_init_sf(void);
140 
141 #endif /* !_SIXTOP_H_ */
142 /** @} */
143 /** @} */
void(* sixtop_sf_input)(sixp_pkt_type_t type, sixp_pkt_code_t code, const uint8_t *body, uint16_t body_len, const linkaddr_t *src_addr)
Input Handler of Scheduling Function.
Definition: sixtop.h:63
sixp_pkt_cmd_t
6P Command Identifiers
Definition: sixp-pkt.h:72
sixp_pkt_type_t
6P Message Types
Definition: sixp-pkt.h:62
/brief Scheduling Function Driver
Definition: sixtop.h:79
void sixtop_init_sf(void)
Initialize installed SFs which has been added in the system This function is supposed to be invoked e...
Definition: sixtop.c:274
Header file for the link-layer address representation
void(* sixtop_sf_timeout)(sixp_pkt_cmd_t cmd, const linkaddr_t *peer_addr)
Timeout Handler of Scheduling Function.
Definition: sixtop.h:74
const sixtop_sf_t * sixtop_find_sf(uint8_t sfid)
Find a SF which has been added by SFID.
Definition: sixtop.c:110
void sixtop_init(void)
Initialize 6top module This initialization function removes all the SFs which has been installed into...
Definition: sixtop.c:260
void sixtop_input(void)
Input a packet stored in packetbuf.
Definition: sixtop.c:203
uint8_t sfid
SFID.
Definition: sixtop.h:80
sixtop_sf_input input
Input Handler.
Definition: sixtop.h:83
6P Codes integrating Command IDs and Return Codes
Definition: sixp-pkt.h:103
int sixtop_add_sf(const sixtop_sf_t *sf)
Add a Scheduling Function (SF) to 6top Sublayer.
Definition: sixtop.c:74
void sixtop_output(const linkaddr_t *dest_addr, mac_callback_t callback, void *arg)
Output a 6P packet which is supposestored in packetbuf.
Definition: sixtop.c:125
6top Protocol (6P) Packet Manipulation APIs
sixtop_sf_timeout timeout
Transaction Timeout Handler.
Definition: sixtop.h:84
MAC driver header file
clock_time_t timeout_interval
Timeout Value.
Definition: sixtop.h:81