1 /* 2 * Copyright (c) 2019, The OpenThread Authors. 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 are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file includes the platform abstraction for Thread Radio Encapsulation Link (TREL) using an IPv6/UDP interface. 33 * 34 */ 35 36 #ifndef OPENTHREAD_PLATFORM_TREL_UDP6_H_ 37 #define OPENTHREAD_PLATFORM_TREL_UDP6_H_ 38 39 #include <stdint.h> 40 41 #include <openthread/error.h> 42 #include <openthread/instance.h> 43 #include <openthread/ip6.h> 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @addtogroup plat-trel 51 * 52 * @brief 53 * This module includes the platform abstraction for Thread Radio Encapsulation Link (TREL) using an IPv6/UDP 54 * interface. 55 * 56 * @{ 57 * 58 */ 59 60 /** 61 * This function initializes the TREL IPv6/UDP interface. 62 * 63 * This function is called before any other TREL platform functions. 64 * 65 * @param[in] aInstance The OpenThread instance structure. 66 * @param[in] aUnicastAddress The unicast address to add to interface and use as tx source and rx destination. 67 * @param[in] aUdpPort A UDP port number to use. 68 * 69 */ 70 void otPlatTrelUdp6Init(otInstance *aInstance, const otIp6Address *aUnicastAddress, uint16_t aUdpPort); 71 72 /** 73 * This function updates the unicast IPv6 address for TREL IPv6/UDP interface. 74 * 75 * The interface should only have one unicast IPv6 address. Calling this function replaces any previously set unicast 76 * IPv6 address (during initialization from `otPlatTrelUdp6Init` or earlier calls to `otPlatTrelUdp6UpdateAddress()`). 77 * 78 * @param[in] aInstance The OpenThread instance structure. 79 * @param[in] aUnicastAddress The unicast address to add to interface and use for as tx source and rx destination. 80 * 81 */ 82 void otPlatTrelUdp6UpdateAddress(otInstance *aInstance, const otIp6Address *aUnicastAddress); 83 84 /** 85 * This function subscribes the TREL IPv6/UDP interface to a new multicast address. 86 * 87 * This function may be called multiple times to subscribe to different addresses. The interface should accept/receive 88 * packets destined to any previously subscribed multicast address in addition to the unicast address added from the 89 * `otPlatTrelUdp6Init()` function when interface was initialized. 90 * 91 * @param[in] aInstance The OpenThread instance structure. 92 * @param[in] aMulticastAddress A multicast IPv6 address. 93 * 94 */ 95 void otPlatTrelUdp6SubscribeMulticastAddress(otInstance *aInstance, const otIp6Address *aMulticastAddress); 96 97 /** 98 * This function requests a packet to be sent to a given destination. 99 * 100 * @param[in] aInstance The OpenThread instance structure. 101 * @param[in] aBuffer A pointer to buffer containing the packet to send. 102 * @param[in] aLength Packet length (number of bytes). 103 * @param[in] aDestAddress The destination IPv6 address (can be a unicast or a multicast IPv6 address). 104 * 105 * @retval OT_ERROR_NONE The tx request was handled successfully. 106 * @retval OT_ERROR_ABORT The interface is not ready and tx was aborted 107 * 108 */ 109 otError otPlatTrelUdp6SendTo(otInstance * aInstance, 110 const uint8_t * aBuffer, 111 uint16_t aLength, 112 const otIp6Address *aDestAddress); 113 114 /** 115 * This function is a callback from platform to notify of a received packet. 116 * 117 * @note The buffer content (up to its specified length) may get changed during processing by OpenThread core (e.g., 118 * decrypted in place), so the platform implementation should expect that after returning from this function the 119 * packet @p aBuffer content may have been altered. 120 * 121 * @param[in] aInstance The OpenThread instance structure. 122 * @param[in] aBuffer A buffer containing the received packet. 123 * @param[in] aLength Packet length (number of bytes). 124 * 125 */ 126 extern void otPlatTrelUdp6HandleReceived(otInstance *aInstance, uint8_t *aBuffer, uint16_t aLength); 127 128 /** 129 * This optional function is intended for testing only. It changes the test mode status for TREL interface. 130 * 131 * This function requests TREL interface to be temporarily disabled or enabled. When disabled all traffic flow through 132 * the TREL interface should be silently dropped. 133 * 134 * A default weak implementation of this method is provided by OpenThread (returning NOT_IMPLEMENTED). 135 * 136 * @param[in] aInstance The OpenThread instance structure. 137 * @param[in] aEnable Indicates whether to enable/disable the TREL interface. 138 * 139 * @retval OT_ERROR_NONE Successfully changed the TREL interface test status (enabled/disabled). 140 * @retval OT_ERROR_FAILED Failed to enable the TREL interface. 141 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not provided by the platform. 142 * 143 */ 144 otError otPlatTrelUdp6SetTestMode(otInstance *aInstance, bool aEnable); 145 146 /** 147 * @} 148 * 149 */ 150 151 #ifdef __cplusplus 152 } // end of extern "C" 153 #endif 154 155 #endif // OPENTHREAD_PLATFORM_TREL_UDP6_H_ 156
