1 /*
2  * Copyright (c) 2020-2023, Texas Instruments Incorporated
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
7  * are met:
8  *
9  * *  Redistributions of source code must retain the above copyright
10  *    notice, this list of conditions and the following disclaimer.
11  *
12  * *  Redistributions in binary form must reproduce the above copyright
13  *    notice, this list of conditions and the following disclaimer in the
14  *    documentation and/or other materials provided with the distribution.
15  *
16  * *  Neither the name of Texas Instruments Incorporated nor the names of
17  *    its contributors may be used to endorse or promote products derived
18  *    from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 
33 #ifndef ti_drivers_RCL_h__include
34 #define ti_drivers_RCL_h__include
35 
36 #include <stdint.h>
37 #include <stddef.h>
38 
39 #include <ti/drivers/rcl/LRF.h>
40 #include <ti/drivers/rcl/RCL_Types.h>
41 #include <ti/drivers/rcl/RCL_Client.h>
42 #include <ti/drivers/rcl/RCL_Event.h>
43 #include <ti/drivers/rcl/RCL_Command.h>
44 #include <ti/drivers/rcl/RCL_Buffer.h>
45 #include <ti/drivers/rcl/RCL_Scheduler.h>
46 
47 #include <ti/drivers/rcl/hal/hal.h>
48 
49 #include <ti/drivers/dpl/SemaphoreP.h>
50 
51 /**
52  * @brief RCL power state
53  *
54  * Tracks when the RCL core has requested standby to be disallowed to the power driver.
55  */
56 typedef enum {
57     RCL_standbyAllow = 0,
58     RCL_standbyDisallow,
59 } RCL_PowerState;
60 
61 /**
62  * @brief Global shared driver state
63  */
64 typedef struct RCL_s {
65     uint8_t                   numClients;
66     uint8_t                   powerNotifyEnableCount;
67     LRF_RadioState            lrfState;
68     RCL_PowerState            powerState;
69     const LRF_Config         *lrfConfig;
70     RCL_Command              *nextCmd;
71     RCL_Command              *doneCmd;
72 } RCL;
73 
74 /**
75  * @brief Initializes the RCL driver state
76  *
77  * Resets global state and initialize hardware.
78  *
79  * @note Must be called before using any other RCL API
80  */
81 void RCL_init(void);
82 
83 /**
84  * @brief Initializes an RCL client instance
85  *
86  * @param[in] c - Client object struct to be initialized
87  * @param[in] lrfConfig - Radio configuration to be used by client
88  *
89  * @return Instance %RCL_Handle handle or NULL
90  */
91 RCL_Handle RCL_open(RCL_Client *c, const LRF_Config *lrfConfig);
92 
93 /**
94  * @brief Closes client instance and deallocates open resources
95  *
96  * @param[in] h - Client handle
97  */
98 void RCL_close(RCL_Handle h);
99 
100 /**
101  * @brief Request RCL power notifications
102  */
103 void RCL_openPowerNotifications(void);
104 
105 /**
106  * @brief Remove RCL power notification request
107  */
108 void RCL_closePowerNotifications(void);
109 
110 /**
111  * @brief Submit RCL command object to be scheduled for execution
112  *
113  * This API returns immediately with either %RCL_CommandStatus_Error or the asynchronous
114  * current state of the command.
115  *
116  * @param[in] h - Client handle
117  * @param[in] c - Command handle
118  *
119  * @return %RCL_CommandStatus result of the submission
120  */
121 RCL_CommandStatus RCL_Command_submit(RCL_Handle h, RCL_Command_Handle c);
122 
123 /**
124  * @brief Wait for a submitted command to complete.
125  *
126  * Uses %SemaphoreP_pend to block in the callers context.
127  *
128  * @pre This function must be called from a task context, with interrupts enabled.
129  *
130  * @param[in] c - Client handle
131  */
132 RCL_CommandStatus RCL_Command_pend(RCL_Command_Handle c);
133 
134 /**
135  * @brief Stop a command
136  *
137  * Sends the message to try to stop a command. When the function returns, the command may still be
138  * running. Depending on the stop type, the command may stop after some time. %RCL_Command_pend
139  * may be used to wait for the command to finish.
140  *
141  * @param c [in] - Command handle
142  * @param stopType [in] - Stop type; telling which situations the command will stop
143  *
144  * @return Status of the command; if the command is not finished, a wait is needed.
145  */
146 RCL_CommandStatus RCL_Command_stop(RCL_Command_Handle c, RCL_StopType stopType);
147 
148 /**
149  * @brief Get the last valid RSSI value.
150  *
151  * This API returns the last valid RSSI value or a specific error status if the last obtained RSSI
152  * value is no longer valid.
153  *
154  * @return Returns RSSI value, or LRF_RSSI_INVALID if the last obtained RSSI value is no longer valid
155  * or if the radio is unavailable (e.g. in the middle of a Tx operation).
156  */
157 int8_t RCL_readRssi(void);
158 
159 #endif
160