rpl_control.h

00001 /*
00002  * Copyright (c) 2015-2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef RPL_CONTROL_H_
00019 #define RPL_CONTROL_H_
00020 
00021 #ifdef HAVE_RPL
00022 
00023 #include "ns_list.h"
00024 #include "ipv6_stack/ipv6_routing_table.h"
00025 
00026 struct rpl_instance;
00027 struct rpl_dodag_conf;
00028 struct rpl_dodag;
00029 struct buffer;
00030 struct protocol_interface_info_entry;
00031 struct rpl_dodag_info_t;
00032 
00033 typedef enum rpl_event {
00034     RPL_EVENT_DAO_DONE,         /* Simplistic trigger for bootstrap advance - a DAO registration completed */
00035     RPL_EVENT_LOCAL_REPAIR_START, /* RPL start scanning new parent by multicast DIS user can disable beacon request responser here*/
00036     RPL_EVENT_LOCAL_REPAIR_NO_MORE_DIS, /* RPL not sending DIS anymore user can report bootstrap error */
00037 } rpl_event_t;
00038 
00039 typedef void rpl_domain_callback_t(rpl_event_t event, void *handle);
00040 
00041 typedef struct rpl_domain
00042 {
00043     NS_LIST_HEAD_INCOMPLETE(struct rpl_instance) instances;
00044     ns_list_link_t link;
00045     /* For non-storing mode, we have to assume a "downstream" interface -
00046      * routing headers contain global addresses that we won't know, and we have
00047      * to assume they're on link on an assumed interface.
00048      */
00049     int8_t non_storing_downstream_interface;
00050     /* As part of shutdown, we can force entering leaf mode */
00051     bool force_leaf;
00052     rpl_domain_callback_t *callback;
00053     void *cb_handle;
00054 } rpl_domain_t;
00055 
00056 /* Configuration parameters for a DODAG, obtained through DIO DODAG Configuration options */
00057 typedef struct rpl_dodag_conf
00058 {
00059     bool authentication:1;
00060     unsigned path_control_size:3;
00061     uint8_t dio_interval_min;               /* log2 milliseconds */
00062     uint8_t dio_interval_doublings;
00063     uint8_t dio_redundancy_constant;
00064     uint8_t default_lifetime;               /* lifetime units */
00065     uint16_t dag_max_rank_increase;
00066     uint16_t min_hop_rank_increase;
00067     uint16_t objective_code_point;
00068     uint16_t lifetime_unit;                 /* seconds */
00069 } rpl_dodag_conf_t;
00070 
00071 /* Descriptor for a route from a DIO Route Information option.
00072  * Used to hold the "master copy" in the DODAG structure - the table for the
00073  * current DODAG is used to populate routes in our system routing table, and to
00074  * form our own DIOs.
00075  * Not used directly for next hop determination - this is done via the system
00076  * routing table, which has per-parent information including parent preferences,
00077  * reachability/probing info, etc.
00078  */
00079 typedef struct rpl_dio_route
00080 {
00081     uint32_t lifetime;                              /* Lifetime in seconds */
00082     ns_list_link_t link;
00083     bool age;                                       /* Do we age the lifetime? */
00084     uint8_t hold_count;                             /* Hold count for relaying 0 lifetime */
00085     uint8_t flags;                                  /* Flags byte (inc. pref) */
00086     uint8_t prefix_len_bytes;                       /* Prefix length (bytes) - padding preserved when relaying */
00087     uint8_t prefix_len;                             /* Prefix length (bits) */
00088     uint8_t prefix[];                               /* Variable-length prefix */
00089 } rpl_dio_route_t;
00090 
00091 typedef NS_LIST_HEAD (rpl_dio_route_t, link) rpl_dio_route_list_t;
00092 
00093 /******************************* RPL internal API ****************************/
00094 void *rpl_alloc(uint16_t size);
00095 void *rpl_realloc(void *p, uint16_t old_size, uint16_t new_size);
00096 void rpl_free(void *p, uint16_t size);
00097 void rpl_control_transmit(struct rpl_domain *domain, struct protocol_interface_info_entry *cur, uint8_t code, struct buffer *buf, const uint8_t *dst);
00098 void rpl_control_transmit_multicast_dio(struct rpl_domain *domain, struct rpl_instance *instance, uint8_t instance_id, uint8_t dodag_version, uint16_t rank, uint8_t g_mop_prf, uint8_t dtsn, const uint8_t dodagid[16], const struct rpl_dodag_conf *conf);
00099 void rpl_control_transmit_dio(struct rpl_domain *domain, struct protocol_interface_info_entry *cur, uint8_t instance_id, uint8_t dodag_version, uint16_t rank, uint8_t g_mop_prf, uint8_t dtsn, struct rpl_dodag *dodag, const uint8_t dodagid[16], const struct rpl_dodag_conf *conf, const uint8_t *dst);
00100 bool rpl_control_transmit_dao(struct rpl_domain *domain, struct protocol_interface_info_entry *cur, struct rpl_instance *instance, uint8_t instance_id, uint8_t dao_sequence, const uint8_t dodagid[16], const uint8_t *opts, uint16_t opts_size, const uint8_t *dst);
00101 void rpl_control_disable_ra_routes(struct rpl_domain *domain);
00102 void rpl_control_event(struct rpl_domain *domain, rpl_event_t event);
00103 
00104 /*********************** RPL control API to rest of system *******************/
00105 
00106 /* Memory configuration */
00107 void rpl_control_set_memory_limits(size_t soft_limit, size_t hard_limit);
00108 
00109 /* Timer routines */
00110 void rpl_control_fast_timer(uint16_t ticks);
00111 void rpl_control_slow_timer(uint16_t seconds);
00112 
00113 /* Packet handlers, and other data flow callback indications */
00114 struct buffer *rpl_control_handler(struct buffer *buf);
00115 struct buffer *rpl_control_source_route_error_handler(struct buffer *buf, struct protocol_interface_info_entry *cur);
00116 
00117 /* Manually send DIS packets for bootstrap */
00118 void rpl_control_transmit_dis(struct rpl_domain *domain, struct protocol_interface_info_entry *cur, uint8_t pred, uint8_t instance_id, const uint8_t *dodagid, const uint8_t version, const uint8_t *dst);
00119 bool rpl_control_have_dodag(struct rpl_domain *domain);
00120 
00121 /* APIs used to manipulate configuration at the root */
00122 struct rpl_dodag *rpl_control_create_dodag_root(rpl_domain_t *domain, uint8_t instance_id, const uint8_t *dodagid, const rpl_dodag_conf_t *conf, uint16_t rank, uint8_t g_mop_prf);
00123 void rpl_control_delete_dodag_root(rpl_domain_t *domain, struct rpl_dodag *dodag);
00124 void rpl_control_update_dodag_route(struct rpl_dodag *dodag, const uint8_t *prefix, uint8_t prefix_len, uint8_t flags, uint32_t lifetime, bool age);
00125 void rpl_control_update_dodag_prefix(struct rpl_dodag *dodag, const uint8_t *prefix, uint8_t prefix_len, uint8_t flags, uint32_t lifetime, uint32_t preftime, bool age);
00126 void rpl_control_increment_dodag_version(struct rpl_dodag *dodag);
00127 void rpl_control_set_dodag_pref(struct rpl_dodag *dodag, uint8_t pref);
00128 void rpl_control_increment_dtsn(struct rpl_dodag *dodag);
00129 
00130 /* Force leaf behaviour on a domain - useful before shutdown, and in conjunction with poison */
00131 void rpl_control_force_leaf(rpl_domain_t *domain, bool leaf);
00132 
00133 /* Manually send poison on all existing instances a few times */
00134 void rpl_control_poison(rpl_domain_t *domain, uint8_t poison_count);
00135 
00136 /* APIs to create domains and map them to interfaces */
00137 rpl_domain_t *rpl_control_create_domain(void);
00138 void rpl_control_delete_domain(rpl_domain_t *domain);
00139 void rpl_control_set_domain_on_interface(struct protocol_interface_info_entry *cur, rpl_domain_t *domain, bool downstream);
00140 void rpl_control_remove_domain_from_interface(struct protocol_interface_info_entry *cur);
00141 void rpl_control_set_callback(rpl_domain_t *domain, rpl_domain_callback_t callback, void *cb_handle);
00142 
00143 /* Target publishing */
00144 void rpl_control_publish_host_address(rpl_domain_t *domain, const uint8_t addr[16], uint32_t lifetime);
00145 void rpl_control_unpublish_address(rpl_domain_t *domain, const uint8_t addr[16]);
00146 
00147 /* Configure and return the routing lookup predicate for a specified RPL instance ID */
00148 ipv6_route_predicate_fn_t *rpl_control_get_route_predicate(rpl_domain_t *domain, uint8_t instance_id, const uint8_t src[16], const uint8_t dst[16]);
00149 
00150 /* Diagnostic APIs */
00151 void rpl_control_print(route_print_fn_t *print_fn);
00152 
00153 struct rpl_instance *rpl_control_enumerate_instances(rpl_domain_t *domain, struct rpl_instance *instance);
00154 struct rpl_instance *rpl_control_lookup_instance(rpl_domain_t *domain, uint8_t instance_id, const uint8_t *dodagid);
00155 bool rpl_control_get_instance_dao_target_count(rpl_domain_t *domain, uint8_t instance_id, const uint8_t *dodagid, uint16_t *target_count);
00156 bool rpl_control_read_dodag_info(const struct rpl_instance *instance, struct rpl_dodag_info_t *dodag_info);
00157 const rpl_dodag_conf_t *rpl_control_get_dodag_config(const struct rpl_instance *instance);
00158 const uint8_t *rpl_control_preferred_parent_addr(const struct rpl_instance *instance, bool global);
00159 
00160 #else /* HAVE_RPL */
00161 
00162 #define rpl_control_fast_timer(ticks) ((void) 0)
00163 #define rpl_control_slow_timer(seconds) ((void) 0)
00164 #define rpl_control_remove_domain_from_interface(cur) ((void) 0)
00165 
00166 #endif /* HAVE_RPL */
00167 
00168 #endif /* RPL_CONTROL_H_ */