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