1 /* 2 * Copyright (c) 2022, 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 vendor interface to radio (RCP). 32 */ 33 34 #ifndef POSIX_APP_VENDOR_INTERFACE_HPP_ 35 #define POSIX_APP_VENDOR_INTERFACE_HPP_ 36 37 #include "openthread-posix-config.h" 38 39 #include <openthread/openthread-system.h> 40 41 #include "platform-posix.h" 42 #include "lib/spinel/spinel_interface.hpp" 43 44 #if OPENTHREAD_POSIX_CONFIG_RCP_BUS == OT_POSIX_RCP_BUS_VENDOR 45 46 namespace ot { 47 namespace Posix { 48 49 /** 50 * This class defines a vendor interface to the Radio Co-processor (RCP). 51 * 52 */ 53 class VendorInterface 54 { 55 public: 56 /** 57 * This constructor initializes the object. 58 * 59 * @param[in] aCallback A reference to a `Callback` object. 60 * @param[in] aCallbackContext The context pointer passed to the callback. 61 * @param[in] aFrameBuffer A reference to a `RxFrameBuffer` object. 62 * 63 */ 64 VendorInterface(Spinel::SpinelInterface::ReceiveFrameCallback aCallback, 65 void * aCallbackContext, 66 Spinel::SpinelInterface::RxFrameBuffer & aFrameBuffer); 67 68 /** 69 * This destructor deinitializes the object. 70 * 71 */ 72 ~VendorInterface(void); 73 74 /** 75 * This method initializes the interface to the Radio Co-processor (RCP). 76 * 77 * @note This method should be called before reading and sending spinel frames to the interface. 78 * 79 * @param[in] aRadioUrl Arguments parsed from radio url. 80 * 81 * @retval OT_ERROR_NONE The interface is initialized successfully. 82 * @retval OT_ERROR_ALREADY The interface is already initialized. 83 * @retval OT_ERROR_INVALID_ARGS The UART device or executable cannot be found or failed to open/run. 84 * 85 */ 86 otError Init(const Url::Url &aRadioUrl); 87 88 /** 89 * This method deinitializes the interface to the RCP. 90 * 91 */ 92 void Deinit(void); 93 94 /** 95 * This method encodes and sends a spinel frame to Radio Co-processor (RCP) over the socket. 96 * 97 * @param[in] aFrame A pointer to buffer containing the spinel frame to send. 98 * @param[in] aLength The length (number of bytes) in the frame. 99 * 100 * @retval OT_ERROR_NONE Successfully encoded and sent the spinel frame. 101 * @retval OT_ERROR_BUSY Failed due to another operation is on going. 102 * @retval OT_ERROR_NO_BUFS Insufficient buffer space available to encode the frame. 103 * @retval OT_ERROR_FAILED Failed to call the SPI driver to send the frame. 104 * 105 */ 106 otError SendFrame(const uint8_t *aFrame, uint16_t aLength); 107 108 /** 109 * This method waits for receiving part or all of spinel frame within specified interval. 110 * 111 * @param[in] aTimeoutUs The timeout value in microseconds. 112 * 113 * @retval OT_ERROR_NONE Part or all of spinel frame is received. 114 * @retval OT_ERROR_RESPONSE_TIMEOUT No spinel frame is received within @p aTimeout. 115 * 116 */ 117 otError WaitForFrame(uint64_t aTimeoutUs); 118 119 /** 120 * This method updates the file descriptor sets with file descriptors used by the radio driver. 121 * 122 * @param[inout] aReadFdSet A reference to the read file descriptors. 123 * @param[inout] aWriteFdSet A reference to the write file descriptors. 124 * @param[inout] aMaxFd A reference to the max file descriptor. 125 * @param[inout] aTimeout A reference to the timeout. 126 * 127 */ 128 void UpdateFdSet(fd_set &aReadFdSet, fd_set &aWriteFdSet, int &aMaxFd, struct timeval &aTimeout); 129 130 /** 131 * This method performs radio driver processing. 132 * 133 * @param[in] aContext The context containing fd_sets. 134 * 135 */ 136 void Process(const RadioProcessContext &aContext); 137 138 /** 139 * This method returns the bus speed between the host and the radio. 140 * 141 * @returns Bus speed in bits/second. 142 * 143 */ 144 uint32_t GetBusSpeed(void) const; 145 146 /** 147 * This method is called when RCP failure detected and resets internal states of the interface. 148 * 149 */ 150 void OnRcpReset(void); 151 152 /** 153 * This method is called when RCP is reset to recreate the connection with it. 154 * 155 * @retval OT_ERROR_NONE Reset the connection successfully. 156 * @retval OT_ERROR_FAILED Failed to reset the connection. 157 * 158 */ 159 otError ResetConnection(void); 160 161 /** 162 * This method returns the RCP interface metrics. 163 * 164 * @returns The RCP interface metrics. 165 * 166 */ 167 const otRcpInterfaceMetrics *GetRcpInterfaceMetrics(void); 168 }; 169 170 } // namespace Posix 171 } // namespace ot 172 173 #endif // OPENTHREAD_POSIX_CONFIG_RCP_BUS == OT_POSIX_RCP_BUS_VENDOR 174 #endif // POSIX_APP_VENDOR_INTERFACE_HPP_ 175