multicast_api.h

00001 /*
00002  * Copyright (c) 2012-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 #ifndef MULTICAST_API_H_
00018 #define MULTICAST_API_H_
00019 /**
00020  * \file multicast_api.h
00021  * \brief Multicast Trickle Forwarding API.
00022  * \section multi-init Init API:
00023  * - multicast_set_parameters(), Set trickle parameters.
00024  * \section multi-cnf Configure API:
00025  * - multicast_add_address(), Add new address to a multicast group and control trickle forwarding.
00026  * - multicast_free_address(), Remove supported multicast address from list.
00027  *
00028  * \section ZigBeeIP Trickle Setups for Multicast Init
00029  *
00030  * | Parameter         | VALUE |
00031  * | :---------------: | :---: |
00032  * | imin              | 10    |
00033  * | imax              | 0     |
00034  * | k                 | 20    |
00035  * | timer_expirations | 3     |
00036  * | window_expiration | 75    |
00037  *
00038  */
00039 
00040 #include "ns_types.h"
00041 
00042 #ifdef __cplusplus
00043 extern "C" {
00044 #endif
00045 
00046 /**
00047  * \brief Set new parameters for trickle multicast.
00048  * \deprecated
00049  *
00050  * \param i_min Minimum trickle timer interval in 50ms resolution: Imin = i_min * 50ms.
00051  * \param i_doublings Maximum trickle timer interval expressed as number of doublings of the minimum interval.
00052  * \param k Redundancy constant.
00053  * \param timer_expirations Number of trickle timer expirations before terminating the trickle process.
00054  * \param window_expiration The time window for keeping the state after the end of trickle process in 50ms resolution.
00055  *        NOTE: If window_expiration value is set too small an infinite retransmission loop may occur when using the trickle multicast.
00056  */
00057 void multicast_set_parameters(uint8_t i_min, uint8_t i_doublings, uint8_t k, uint8_t timer_expirations, uint16_t window_expiration);
00058 
00059 
00060 /**
00061  * \brief Add new address to multicast group.
00062  *
00063  * \deprecated Use setsockopt(SOCKET_IPV6_JOIN_GROUP) to join a group. Use
00064  * multicast_mpl_subscribe_domain() to control MPL behaviour.
00065  *
00066  * \param address_ptr Pointer to a 16-byte array that includes the address to be added.
00067  * \param use_trickle 0 = no trickle multicast forwarding, all other values = trickle multicast forwarding will be used with this address.
00068  *
00069  * \return 0 General error.
00070  * \return 1 Address updated.
00071  * \return 2 Address added.
00072  * \return 255 Link local not allowed when using multicast.
00073 *
00074  */
00075 uint8_t multicast_add_address(const uint8_t *address_ptr, uint8_t use_trickle);
00076 
00077 
00078 
00079 /**
00080  * \brief Free address from multicast group.
00081  * \deprecated Use setsockopt(SOCKET_IPV6_LEAVE_GROUP)
00082  *
00083  * \param address_ptr Pointer to a 16-byte array that includes the address to be removed.
00084  *
00085  * \return 0 will be returned on successful execution, other values indicate an error on removing the address.
00086  */
00087 uint8_t multicast_free_address(const uint8_t *address_ptr);
00088 
00089 /**
00090  * \brief Treat all Realm-local Domains as one
00091  *
00092  * If enabled on an interface, then all Realm-local scope multicasts will
00093  * be treated as if belonging to the All-MPL-Forwarders domain, rather than
00094  * the domain indicated by their destination address. This is non-standard
00095  * behaviour, not covered by the real MPL specification, but required by the
00096  * Thread specification.
00097  *
00098  * All devices in a realm should have this setting set the same. With the
00099  * setting on, reactive forwarding and control messages will not work.
00100  *
00101  * With this setting on, Realm-scope domains other than All-MPL-Forwarders
00102  * cannot be joined.
00103  *
00104  * This must be set before bringing up an interface, and then not be modified.
00105  *
00106  * \param interface_id interface id
00107  * \param enable true to enable domain unification
00108  *
00109  * \return 0 for success, negative on failure
00110  */
00111 int_fast8_t multicast_mpl_treat_realm_domains_as_one(int8_t interface_id, bool enable);
00112 
00113 /**
00114  * \brief Set default MPL Domain parameters
00115  *
00116  * Modifies the default parameters for MPL Domains using the specified
00117  * interface.
00118  *
00119  * This must be set before subscribing to any MPL Domains with default
00120  * parameters on that interface.
00121  *
00122  * Initial defaults are as specified by RFC 7731.
00123  *
00124  * \param interface_id interface id
00125  * \param proactive_forwarding              true to forward Data Messages when first received (default true)
00126  * \param seed_set_entry_lifetime           minimum seed set lifetime (seconds, default 1800 = 30 minutes)
00127  * \param data_message_imin                 minimum Trickle timer for Data Messages (ms, default ~= 10 * expected link latency)
00128  * \param data_message_imax                 maximum Trickle timer for Data Messages (ms, default = Imin)
00129  * \param data_message_k                    Trickle redundancy constant for Data Messages (default = 1)
00130  * \param data_message_timer_expirations    controls termination of retransmissions (default = 3)
00131  * \param control_message_imin              minimum Trickle timer for Control Messages (ms, default ~= 10 * worst-case link latency)
00132  * \param control_message_imax              maximum Trickle timer for Control Messages (ms, default = 5 minutes)
00133  * \param control_message_k                 Trickle redundancy constant for Control Messages (default = 1)
00134  * \param control_message_timer_expirations controls termination of retransmissions (default = 10); 0 disables control messages
00135  *
00136  * \return 0 for success, negative on failure
00137  */
00138 int_fast8_t multicast_mpl_set_default_parameters(int8_t interface_id,
00139                                                  bool proactive_forwarding,
00140                                                  uint16_t seed_set_entry_lifetime,
00141                                                  uint32_t data_message_imin,
00142                                                  uint32_t data_message_imax,
00143                                                  uint8_t data_message_k,
00144                                                  uint8_t data_message_timer_expirations,
00145                                                  uint32_t control_message_imin,
00146                                                  uint32_t control_message_imax,
00147                                                  uint8_t control_message_k,
00148                                                  uint8_t control_message_timer_expirations);
00149 
00150 /** Control selection of MPL Seed Identifier for packets we originate */
00151 typedef enum {
00152     MULTICAST_MPL_SEED_ID_DEFAULT = -256,               /** Default selection (used to make a domain use the interface's default) */
00153     MULTICAST_MPL_SEED_ID_MAC_SHORT = -1,               /** Use short MAC address if available (eg IEEE 802.15.4 interface's macShortAddress (16-bit)), else full MAC */
00154     MULTICAST_MPL_SEED_ID_MAC = -2,                     /** Use MAC padded to 64-bit (eg IEEE 802.15.4 interface's macExtendedAddress, or 48-bit Ethernet MAC followed by 2 zero pad bytes) */
00155     MULTICAST_MPL_SEED_ID_IID_EUI64 = -3,               /** Use 64-bit IPv6 IID based on EUI-64 (eg 02:11:22:ff:fe:00:00:00 for an Ethernet interface with MAC 00:11:22:00:00:00) */
00156     MULTICAST_MPL_SEED_ID_IID_SLAAC = -4,               /** Use 64-bit IPv6 IID that would be used for SLAAC */
00157     MULTICAST_MPL_SEED_ID_IPV6_SRC_FOR_DOMAIN = 0,      /** Use IPv6 source address selection to choose 128-bit Seed ID based on MPL Domain Address as destination */
00158     MULTICAST_MPL_SEED_ID_16_BIT = 2,                   /** Use a manually-specified 16-bit ID */
00159     MULTICAST_MPL_SEED_ID_64_BIT = 8,                   /** Use a manually-specified 64-bit ID */
00160     MULTICAST_MPL_SEED_ID_128_BIT = 16,                 /** Use a manually-specified 128-bit ID */
00161 } multicast_mpl_seed_id_mode_e;
00162 
00163 /**
00164  * \brief Set default MPL Seed Identifier
00165  *
00166  * Sets the default MPL Seed Identifier used when acting as an MPL Seed.
00167  *
00168  * \param interface_id interface id
00169  * \param seed_id_mode Seed ID selection mode
00170  * \param seed_id For positive (constant) types, pointer to Seed ID data
00171  *
00172  * \return 0 for success, negative on failure
00173  */
00174 int_fast8_t multicast_mpl_set_default_seed_id(int8_t interface_id,
00175                                               multicast_mpl_seed_id_mode_e seed_id_mode,
00176                                               const void *seed_id);
00177 
00178 /**
00179  * \brief Subscribe to an MPL Domain (RFC 7731)
00180  *
00181  * This subscribes to an MPL Domain with default parameters on the
00182  * specified interface. (At present there is no support for subscribing to
00183  * the same Domain on multiple interfaces)
00184  *
00185  * If the ALL_MPL_FORWARDERS Domain ff03::fc has not already been subscribed
00186  * to, this will automatically also subscribe to it with default parameters.
00187  *
00188  * Once 1 or more MPL Domains have been subscribed to on an interface,
00189  * multicast transmissions sent to a group with scope greater than link-local
00190  * on that interface will be sent using MPL.
00191  *
00192  * If the destination corresponds to a subscribed MPL Domain, it will be sent
00193  * to that MPL Domain (and hence forwarded only by other subscribers to that
00194  * domain).
00195  *
00196  * If the destination does not correspond to a subscribed MPL Domain, it will
00197  * be tunnelled, with the outer IP packet sent to the ALL_MPL_FORWARDERS Domain.
00198  *
00199  * Typical behaviour for ZigBee IP and Thread networks would be achieved by
00200  * subscribing to ff03::1, and enabling realm auto-subscription - [this is
00201  * done automatically when calling multicast_add_address?]
00202  *
00203  * \param interface_id interface id
00204  * \param address MPL Domain Address (IPv6 multicast address)
00205  * \param seed_id_mode Seed ID selection mode
00206  * \param seed_id For positive (constant) types, pointer to Seed ID data
00207  *
00208  * \return 0 for success, negative on failure
00209  */
00210 int8_t multicast_mpl_domain_subscribe(int8_t interface_id,
00211                                       const uint8_t address[16],
00212                                       multicast_mpl_seed_id_mode_e seed_id_mode,
00213                                       const void *seed_id);
00214 
00215 /**
00216  * \brief Subscribe to an MPL Domain (RFC 7731)
00217  *
00218  * This subscribes to an MPL Domain with default parameters on the
00219  * specified interface.
00220  *
00221  * If the ALL_MPL_FORWARDERS Domain ff03::fc has not already been subscribed
00222  * to, this will automatically also subscribe to it with default parameters.
00223  *
00224  * See multicast_mpl_subscribe_domain and multicast_set_default_parameters
00225  * for more information on parameters.
00226  */
00227 int8_t multicast_mpl_domain_subscribe_with_parameters
00228                                      (int8_t interface_id,
00229                                       const uint8_t address[16],
00230                                       multicast_mpl_seed_id_mode_e seed_id_mode,
00231                                       const void *seed_id,
00232                                       bool proactive_forwarding,
00233                                       uint16_t seed_set_entry_lifetime,
00234                                       uint32_t data_message_imin,
00235                                       uint32_t data_message_imax,
00236                                       uint8_t data_message_k,
00237                                       uint8_t data_message_timer_expirations,
00238                                       uint32_t control_message_imin,
00239                                       uint32_t control_message_imax,
00240                                       uint8_t control_message_k,
00241                                       uint8_t control_message_timer_expirations);
00242 
00243 /**
00244  * \brief Unsubscribe from an MPL Domain
00245  *
00246  * This subscribes from a previously-subscribed MPL Domain
00247  *
00248  * \param interface_id interface id
00249  * \param address MPL Domain Address (IPv6 multicast address)
00250  *
00251  * \return 0 for success, negative on failure
00252  */
00253 int8_t multicast_mpl_domain_unsubscribe(int8_t interface_id,
00254                                         const uint8_t address[16]);
00255 
00256 /**
00257  * \brief Set interface's master multicast forwarding control
00258  *
00259  * Multicast forwarding can occur between interfaces with multicast forwarding
00260  * enabled, according to forwarding records and scope rules controlled by the
00261  * functions below.
00262  *
00263  * If this call disables forwarding on the current proxying upstream interface,
00264  * proxying is disabled, and would need to be manually re-enabled later.
00265  *
00266  * Multicast forwarding state for an interface - forwarding records and scope level - are
00267  * retained even if its master forwarding switch is disabled, enabling the upkeep of backup
00268  * information.
00269  *
00270  * By default this flag is enabled.
00271  *
00272  * \param interface_id interface id
00273  * \param enable Enable / Disable multicast forwarding
00274  *
00275  * \return 0 for success, negative on failure
00276  */
00277 int8_t multicast_fwd_set_forwarding(int8_t interface_id, bool enable);
00278 
00279 /**
00280  * \brief Add multicast forwarding record to an interface
00281  *
00282  * This adds a group to the forwarding list on the specified interface.
00283  * Received multicast packets for the specified group will be forwarded onto
00284  * the specified interface from other interfaces, if multicast forwarding is enabled on
00285  * both incoming and outgoing interfaces, subject to a Reverse Path Forwarding
00286  * check on the source address, and usual scope rules.
00287  *
00288  * If a finite lifetime is set, the record will be removed after that many seconds.
00289  *
00290  * If an entry for the specified group already exists, its lifetime will
00291  * increased if it is lower than the value passed.
00292  *
00293  * \param interface_id interface id
00294  * \param group IPv6 multicast group address
00295  * \param lifetime The time in seconds to maintain the forwarding entry - 0xFFFFFFFF means infinite
00296  *
00297  * \return 0 for success, negative on failure
00298  */
00299 int8_t multicast_fwd_add(int8_t interface_id, const uint8_t group[16], uint32_t lifetime);
00300 
00301 /**
00302  * \brief Remove multicast forwarding record from an interface
00303  *
00304  * Delete a a group from the forwarding list on the specified interface.
00305  *
00306  * \param interface_id interface id
00307  * \param group IPv6 multicast group address
00308  *
00309  * \return 0 for success, negative on failure
00310  */
00311 int8_t multicast_fwd_remove(int8_t interface_id, const uint8_t group[16]);
00312 
00313 /**
00314  * \brief Set full multicast forwarding
00315  *
00316  * If enabled, all multicast packets of specified scope or greater will be
00317  * forwarded onto the specified interface from other interfaces, if multicast
00318  * forwarding is enabled on both incoming and outgoing interfaces, subject to a
00319  * Reverse Path Forwarding check on the source address.
00320  *
00321  * Setting this is equivalent to "multicast_fwd_add" being called for all
00322  * addresses with scope >= min_scope.
00323  *
00324  * This functionality is disabled by setting min_scope to 0x10 or greater (so
00325  * no packets can match).
00326  *
00327  * By default this is set to 0x5 (site-local) for all interfaces.
00328  *
00329  * \param interface_id interface id
00330  * \param min_scope minimum IPv6 scope value for forwarding (see RFC 4291)
00331  *
00332  * \return 0 for success, negative on failure
00333  */
00334 int8_t multicast_fwd_full_for_scope(int8_t interface_id, uint_fast8_t min_scope);
00335 
00336 /**
00337  * \brief Set upstream interface for MLD proxying
00338  *
00339  * This sets the upstream interface for MLD proxying. If set, the stack will
00340  * report group membership on that interface according to the forwarding lists
00341  * of the other interfaces with multicast forwarding enabled (ie it will send
00342  * MLD reports or equivalent on that upstream interface).
00343  *
00344  * Multicast forwarding must be enabled on the upstream interface.
00345  *
00346  * \param interface_id interface id, or -1 to disable
00347  *
00348  * \return 0 for success, negative on failure
00349  */
00350 int8_t multicast_fwd_set_proxy_upstream(int8_t interface_id);
00351 
00352 #ifdef __cplusplus
00353 }
00354 #endif
00355 #endif /* MULTICAST_API_H_ */