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 * This file includes definitions for the spinel interface to Radio Co-processor (RCP) 32 * 33 */ 34 35 #ifndef SPINEL_SPINEL_INTERFACE_HPP_ 36 #define SPINEL_SPINEL_INTERFACE_HPP_ 37 38 #include "spinel-config.h" 39 40 #include "lib/spinel/multi_frame_buffer.hpp" 41 #include "lib/spinel/radio_spinel_metrics.h" 42 #include "lib/spinel/spinel.h" 43 44 namespace ot { 45 namespace Spinel { 46 47 class SpinelInterface 48 { 49 public: 50 enum 51 { 52 kMaxFrameSize = OPENTHREAD_LIB_SPINEL_RX_FRAME_BUFFER_SIZE, ///< Maximum buffer size. 53 }; 54 55 /** 56 * Defines a receive frame buffer to store received spinel frame(s). 57 * 58 * @note The receive frame buffer is an `Spinel::MultiFrameBuffer` and therefore it is capable of storing multiple 59 * frames in a FIFO queue manner. 60 * 61 */ 62 typedef MultiFrameBuffer<kMaxFrameSize> RxFrameBuffer; 63 64 typedef void (*ReceiveFrameCallback)(void *aContext); 65 66 /** 67 * Initializes the interface to the Radio Co-processor (RCP) 68 * 69 * @note This method should be called before reading and sending spinel frames to the interface. 70 * 71 * @param[in] aCallback Callback on frame received 72 * @param[in] aCallbackContext Callback context 73 * @param[in] aFrameBuffer A reference to a `RxFrameBuffer` object. 74 * 75 * @retval OT_ERROR_NONE The interface is initialized successfully 76 * @retval OT_ERROR_ALREADY The interface is already initialized. 77 * @retval OT_ERROR_FAILED Failed to initialize the interface. 78 * 79 */ 80 virtual otError Init(ReceiveFrameCallback aCallback, void *aCallbackContext, RxFrameBuffer &aFrameBuffer) = 0; 81 82 /** 83 * Deinitializes the interface to the RCP. 84 * 85 */ 86 virtual void Deinit(void) = 0; 87 88 /** 89 * Encodes and sends a spinel frame to Radio Co-processor (RCP) over the socket. 90 * 91 * @param[in] aFrame A pointer to buffer containing the spinel frame to send. 92 * @param[in] aLength The length (number of bytes) in the frame. 93 * 94 * @retval OT_ERROR_NONE Successfully encoded and sent the spinel frame. 95 * @retval OT_ERROR_BUSY Failed due to another operation is on going. 96 * @retval OT_ERROR_NO_BUFS Insufficient buffer space available to encode the frame. 97 * @retval OT_ERROR_FAILED Failed to call the SPI driver to send the frame. 98 * 99 */ 100 virtual otError SendFrame(const uint8_t *aFrame, uint16_t aLength) = 0; 101 102 /** 103 * Waits for receiving part or all of spinel frame within specified interval. 104 * 105 * @param[in] aTimeout The timeout value in microseconds. 106 * 107 * @retval OT_ERROR_NONE Part or all of spinel frame is received. 108 * @retval OT_ERROR_RESPONSE_TIMEOUT No spinel frame is received within @p aTimeout. 109 * 110 */ 111 virtual otError WaitForFrame(uint64_t aTimeoutUs) = 0; 112 113 /** 114 * Updates the file descriptor sets with file descriptors used by the radio driver. 115 * 116 * @param[in,out] aMainloopContext A pointer to the mainloop context. 117 * 118 */ 119 virtual void UpdateFdSet(void *aMainloopContext) = 0; 120 121 /** 122 * Performs radio driver processing. 123 * 124 * @param[in] aMainloopContext A pointer to the mainloop context. 125 * 126 */ 127 virtual void Process(const void *aMainloopContext) = 0; 128 129 /** 130 * Returns the bus speed between the host and the radio. 131 * 132 * @returns Bus speed in bits/second. 133 * 134 */ 135 virtual uint32_t GetBusSpeed(void) const = 0; 136 137 /** 138 * Hardware resets the RCP. 139 * 140 * @retval OT_ERROR_NONE Successfully reset the RCP. 141 * @retval OT_ERROR_NOT_IMPLEMENT The hardware reset is not implemented. 142 * 143 */ 144 virtual otError HardwareReset(void) = 0; 145 146 /** 147 * Returns the RCP interface metrics. 148 * 149 * @returns The RCP interface metrics. 150 * 151 */ 152 virtual const otRcpInterfaceMetrics *GetRcpInterfaceMetrics(void) const = 0; 153 154 /** 155 * Marks destructor virtual method. 156 * 157 */ 158 virtual ~SpinelInterface() = default; 159 160 protected: 161 enum : uint8_t 162 { 163 kSpinelInterfaceTypeHdlc = 1, ///< The type of Spinel HDLC interface. 164 kSpinelInterfaceTypeSpi = 2, ///< The type of Spinel SPI interface. 165 kSpinelInterfaceTypeVendor = 3, ///< The type of Spinel Vendor interface. 166 }; 167 168 /** 169 * Indicates whether or not the frame is the Spinel SPINEL_CMD_RESET frame. 170 * 171 * @param[in] aFrame A pointer to buffer containing the spinel frame. 172 * @param[in] aLength The length (number of bytes) in the frame. 173 * 174 * @retval true If the frame is a Spinel SPINEL_CMD_RESET frame. 175 * @retval false If the frame is not a Spinel SPINEL_CMD_RESET frame. 176 * 177 */ IsSpinelResetCommand(const uint8_t * aFrame,uint16_t aLength)178 bool IsSpinelResetCommand(const uint8_t *aFrame, uint16_t aLength) 179 { 180 const uint8_t kSpinelResetCommandLength = 2; 181 bool resetCmd = false; 182 183 if (aLength >= kSpinelResetCommandLength) 184 { 185 #ifndef OPENTHREAD_CONFIG_MULTIPAN_RCP_ENABLE 186 // Validate the iid. 187 if (!((aFrame[0] & SPINEL_HEADER_IID_MASK) == SPINEL_HEADER_IID_0)) 188 { 189 goto exit; 190 } 191 #endif 192 193 // Validate the header flag by masking out the iid bits as it is validated above. 194 if (!((aFrame[0] & ~SPINEL_HEADER_IID_MASK) == SPINEL_HEADER_FLAG)) 195 { 196 goto exit; 197 } 198 199 // Validate the reset command. 200 if (!(aFrame[1] == SPINEL_CMD_RESET)) 201 { 202 goto exit; 203 } 204 205 resetCmd = true; 206 } 207 208 exit: 209 return resetCmd; 210 } 211 }; 212 213 } // namespace Spinel 214 } // namespace ot 215 216 #endif // SPINEL_SPINEL_INTERFACE_HPP_ 217
