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