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 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] aCallback         A reference to a `Callback` object.
58      * @param[in] aCallbackContext  The context pointer passed to the callback.
59      * @param[in] aFrameBuffer      A reference to a `RxFrameBuffer` object.
60      *
61      */
62     VendorInterface(Spinel::SpinelInterface::ReceiveFrameCallback aCallback,
63                     void                                         *aCallbackContext,
64                     Spinel::SpinelInterface::RxFrameBuffer       &aFrameBuffer);
65 
66     /**
67      * This destructor deinitializes the object.
68      *
69      */
70     ~VendorInterface(void);
71 
72     /**
73      * Initializes the interface to the Radio Co-processor (RCP).
74      *
75      * @note This method should be called before reading and sending spinel frames to the interface.
76      *
77      * @param[in] aRadioUrl  Arguments parsed from radio url.
78      *
79      * @retval OT_ERROR_NONE          The interface is initialized successfully.
80      * @retval OT_ERROR_ALREADY       The interface is already initialized.
81      * @retval OT_ERROR_INVALID_ARGS  The UART device or executable cannot be found or failed to open/run.
82      *
83      */
84     otError Init(const Url::Url &aRadioUrl);
85 
86     /**
87      * Deinitializes the interface to the RCP.
88      *
89      */
90     void Deinit(void);
91 
92     /**
93      * Encodes and sends a spinel frame to Radio Co-processor (RCP) over the socket.
94      *
95      * @param[in] aFrame   A pointer to buffer containing the spinel frame to send.
96      * @param[in] aLength  The length (number of bytes) in the frame.
97      *
98      * @retval OT_ERROR_NONE     Successfully encoded and sent the spinel frame.
99      * @retval OT_ERROR_BUSY     Failed due to another operation is on going.
100      * @retval OT_ERROR_NO_BUFS  Insufficient buffer space available to encode the frame.
101      * @retval OT_ERROR_FAILED   Failed to call the SPI driver to send the frame.
102      *
103      */
104     otError SendFrame(const uint8_t *aFrame, uint16_t aLength);
105 
106     /**
107      * Waits for receiving part or all of spinel frame within specified interval.
108      *
109      * @param[in] aTimeoutUs  The timeout value in microseconds.
110      *
111      * @retval OT_ERROR_NONE             Part or all of spinel frame is received.
112      * @retval OT_ERROR_RESPONSE_TIMEOUT No spinel frame is received within @p aTimeout.
113      *
114      */
115     otError WaitForFrame(uint64_t aTimeoutUs);
116 
117     /**
118      * Updates the file descriptor sets with file descriptors used by the radio driver.
119      *
120      * @param[in,out]   aMainloopContext  A pointer to the mainloop context containing fd_sets.
121      *
122      */
123     void UpdateFdSet(void *aMainloopContext);
124 
125     /**
126      * Performs radio driver processing.
127      *
128      * @param[in]   aMainloopContext  A pointer to the mainloop context containing fd_sets.
129      *
130      */
131     void Process(const void *aMainloopContext);
132 
133     /**
134      * Returns the bus speed between the host and the radio.
135      *
136      * @returns  Bus speed in bits/second.
137      *
138      */
139     uint32_t GetBusSpeed(void) const;
140 
141     /**
142      * Hardware resets the RCP.
143      *
144      * @retval OT_ERROR_NONE            Successfully reset the RCP.
145      * @retval OT_ERROR_NOT_IMPLEMENT   The hardware reset is not implemented.
146      *
147      */
148     otError HardwareReset(void);
149 
150     /**
151      * Returns the RCP interface metrics.
152      *
153      * @returns The RCP interface metrics.
154      *
155      */
156     const otRcpInterfaceMetrics *GetRcpInterfaceMetrics(void) const;
157 };
158 
159 } // namespace Posix
160 } // namespace ot
161 
162 #endif // POSIX_APP_VENDOR_INTERFACE_HPP_
163