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 OT_POSIX_APP_VENDOR_INTERFACE_HPP_
35 #define OT_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 namespace ot {
45 namespace Posix {
46 
47 /**
48  * Defines a vendor interface to the Radio Co-processor (RCP).
49  *
50  */
51 class VendorInterface : public ot::Spinel::SpinelInterface
52 {
53 public:
54     /**
55      * Initializes the object.
56      *
57      * @param[in] aRadioUrl  RadioUrl parsed from radio url.
58      *
59      */
60     VendorInterface(const Url::Url &aRadioUrl);
61 
62     /**
63      * This destructor deinitializes the object.
64      *
65      */
66     ~VendorInterface(void);
67 
68     /**
69      * Initializes the interface to the Radio Co-processor (RCP).
70      *
71      * @note This method should be called before reading and sending spinel frames to the interface.
72      *
73      * @param[in] aCallback         Callback on frame received
74      * @param[in] aCallbackContext  Callback context
75      * @param[in] aFrameBuffer      A reference to a `RxFrameBuffer` object.
76      *
77      * @retval OT_ERROR_NONE       The interface is initialized successfully
78      * @retval OT_ERROR_ALREADY    The interface is already initialized.
79      * @retval OT_ERROR_FAILED     Failed to initialize the interface.
80      *
81      */
82     otError Init(ReceiveFrameCallback aCallback, void *aCallbackContext, RxFrameBuffer &aFrameBuffer);
83 
84     /**
85      * Deinitializes the interface to the RCP.
86      *
87      */
88     void Deinit(void);
89 
90     /**
91      * Encodes and sends a spinel frame to Radio Co-processor (RCP) over the socket.
92      *
93      * @param[in] aFrame   A pointer to buffer containing the spinel frame to send.
94      * @param[in] aLength  The length (number of bytes) in the frame.
95      *
96      * @retval OT_ERROR_NONE     Successfully encoded and sent the spinel frame.
97      * @retval OT_ERROR_BUSY     Failed due to another operation is on going.
98      * @retval OT_ERROR_NO_BUFS  Insufficient buffer space available to encode the frame.
99      * @retval OT_ERROR_FAILED   Failed to call the SPI driver to send the frame.
100      *
101      */
102     otError SendFrame(const uint8_t *aFrame, uint16_t aLength);
103 
104     /**
105      * Waits for receiving part or all of spinel frame within specified interval.
106      *
107      * @param[in] aTimeoutUs  The timeout value in microseconds.
108      *
109      * @retval OT_ERROR_NONE             Part or all of spinel frame is received.
110      * @retval OT_ERROR_RESPONSE_TIMEOUT No spinel frame is received within @p aTimeout.
111      *
112      */
113     otError WaitForFrame(uint64_t aTimeoutUs);
114 
115     /**
116      * Updates the file descriptor sets with file descriptors used by the radio driver.
117      *
118      * @param[in,out]   aMainloopContext  A pointer to the mainloop context containing fd_sets.
119      *
120      */
121     void UpdateFdSet(void *aMainloopContext);
122 
123     /**
124      * Performs radio driver processing.
125      *
126      * @param[in]   aMainloopContext  A pointer to the mainloop context containing fd_sets.
127      *
128      */
129     void Process(const void *aMainloopContext);
130 
131     /**
132      * Returns the bus speed between the host and the radio.
133      *
134      * @returns  Bus speed in bits/second.
135      *
136      */
137     uint32_t GetBusSpeed(void) const;
138 
139     /**
140      * Hardware resets the RCP.
141      *
142      * @retval OT_ERROR_NONE            Successfully reset the RCP.
143      * @retval OT_ERROR_NOT_IMPLEMENT   The hardware reset is not implemented.
144      *
145      */
146     otError HardwareReset(void);
147 
148     /**
149      * Returns the RCP interface metrics.
150      *
151      * @returns The RCP interface metrics.
152      *
153      */
154     const otRcpInterfaceMetrics *GetRcpInterfaceMetrics(void) const;
155 
156     /**
157      * Indicates whether or not the given interface matches this interface name.
158      *
159      * @param[in] aInterfaceName A pointer to the interface name.
160      *
161      * @retval TRUE   The given interface name matches this interface name.
162      * @retval FALSE  The given interface name doesn't match this interface name.
163      */
IsInterfaceNameMatch(const char * aInterfaceName)164     static bool IsInterfaceNameMatch(const char *aInterfaceName)
165     {
166         static const char *kInterfaceName = OPENTHREAD_POSIX_CONFIG_SPINEL_VENDOR_INTERFACE_URL_PROTOCOL_NAME;
167         return (strncmp(aInterfaceName, kInterfaceName, strlen(kInterfaceName)) == 0);
168     }
169 };
170 
171 } // namespace Posix
172 } // namespace ot
173 
174 #endif // OT_POSIX_APP_VENDOR_INTERFACE_HPP_
175