1 /* 2 * Copyright (c) 2021 Chipsea Technologies (Shenzhen) Corp., Ltd. All rights reserved. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 #ifndef _BLE_KE_TASK_H 16 #define _BLE_KE_TASK_H 17 18 /** 19 **************************************************************************************** 20 * @defgroup TASK Task and Process 21 * @ingroup KERNEL 22 * @brief Task management module. 23 * 24 * This module implements the functions used for managing tasks. 25 * 26 * @{ 27 **************************************************************************************** 28 */ 29 30 /* 31 * INCLUDE FILES 32 **************************************************************************************** 33 */ 34 #include <stdint.h> // standard integer 35 #include <stdbool.h> // standard boolean 36 37 #include "ble_ip_config.h" // stack configuration 38 #include "compiler.h" // compiler defines, INLINE 39 #include "ble_ke_msg.h" // kernel message defines 40 41 /* Default Message handler code to handle several message type in same handler. */ 42 #define KE_MSG_DEFAULT_HANDLER (0xFFFF) 43 /* Invalid task */ 44 #define KE_TASK_INVALID (0xFFFF) 45 /* Used to know if a message is not present in kernel queue */ 46 #define KE_MSG_NOT_IN_QUEUE ((struct co_list_hdr *) 0xFFFFFFFF) 47 48 /// Status of ke_task API functions 49 enum KE_TASK_STATUS 50 { 51 KE_TASK_OK = 0, 52 KE_TASK_FAIL, 53 KE_TASK_UNKNOWN, 54 KE_TASK_CAPA_EXCEEDED, 55 KE_TASK_ALREADY_EXISTS, 56 }; 57 58 59 #define BLE_MSG_T(msg) ((ke_task_id_t)((msg) >> 8)) 60 #define BLE_MSG_I(msg) ((msg) & ((1<<8)-1)) 61 62 /// Format of a task message handler function 63 typedef int (*ke_msg_func_t)(ke_msg_id_t const msgid, void const *param, 64 ke_task_id_t const dest_id, ke_task_id_t const src_id); 65 66 /// Macro for message handler function declaration or definition 67 #define KE_MSG_HANDLER(msg_name, param_struct) __STATIC int msg_name##_handler(ke_msg_id_t const msgid, \ 68 param_struct const *param, \ 69 ke_task_id_t const dest_id, \ 70 ke_task_id_t const src_id) 71 72 #define KE_MSG_HANDLER_NO_STATIC(msg_name, param_struct) int msg_name##_handler(ke_msg_id_t const msgid, \ 73 param_struct const *param, \ 74 ke_task_id_t const dest_id, \ 75 ke_task_id_t const src_id) 76 77 /// Macro for message handlers table declaration or definition 78 #define KE_MSG_HANDLER_TAB(task) __STATIC const struct ke_msg_handler task##_msg_handler_tab[] = 79 80 /// Element of a message handler table. 81 struct ke_msg_handler 82 { 83 /// Id of the handled message. 84 ke_msg_id_t id; 85 /// Pointer to the handler function for the msgid above. 86 ke_msg_func_t func; 87 }; 88 89 /// Element of a state handler table. 90 struct ke_state_handler 91 { 92 /// Pointer to the message handler table of this state. 93 const struct ke_msg_handler *msg_table; 94 /// Number of messages handled in this state. 95 uint16_t msg_cnt; 96 }; 97 98 /// Task descriptor grouping all information required by the kernel for the scheduling. 99 struct ke_task_desc 100 { 101 /// Pointer to the message handler table 102 const struct ke_msg_handler* msg_handler_tab; 103 /// Pointer to the state table (one element for each instance). 104 ke_state_t* state; 105 /// Maximum index of supported instances of the task. 106 uint16_t idx_max; 107 /// Number of messages handled 108 uint16_t msg_cnt; 109 }; 110 111 #ifdef CFG_AON 112 typedef struct 113 { 114 struct ke_task_desc const * p_desc; 115 } aon_ke_task_elem; 116 #endif //CFG_AON 117 118 /* 119 * FUNCTION PROTOTYPES 120 **************************************************************************************** 121 */ 122 123 124 /** 125 **************************************************************************************** 126 * @brief Initialize Kernel task module. 127 **************************************************************************************** 128 */ 129 void ke_task_init(void); 130 131 /** 132 **************************************************************************************** 133 * @brief Create a task. 134 * 135 * @param[in] task_type Task type. 136 * @param[in] p_task_desc Pointer to task descriptor. 137 * 138 * @return Status 139 **************************************************************************************** 140 */ 141 uint8_t ke_task_create(uint8_t task_type, struct ke_task_desc const * p_task_desc); 142 143 /** 144 **************************************************************************************** 145 * @brief Delete a task. 146 * 147 * @param[in] task_type Task type. 148 * 149 * @return Status 150 **************************************************************************************** 151 */ 152 uint8_t ke_task_delete(uint8_t task_type); 153 154 /** 155 **************************************************************************************** 156 * @brief Retrieve the state of a task. 157 * 158 * @param[in] id Task id. 159 * 160 * @return Current state of the task 161 **************************************************************************************** 162 */ 163 ke_state_t ke_state_get(ke_task_id_t const id); 164 165 /** 166 **************************************************************************************** 167 * @brief Set the state of the task identified by its Task Id. 168 * 169 * In this function we also handle the SAVE service: when a task state changes we 170 * try to activate all the messages currently saved in the save queue for the given 171 * task identifier. 172 * 173 * @param[in] id Identifier of the task instance whose state is going to be modified 174 * @param[in] state_id New State 175 * 176 **************************************************************************************** 177 */ 178 void ke_state_set(ke_task_id_t const id, ke_state_t const state_id); 179 180 /** 181 **************************************************************************************** 182 * @brief Generic message handler to consume message without handling it in the task. 183 * 184 * @param[in] msgid Id of the message received (probably unused) 185 * @param[in] param Pointer to the parameters of the message. 186 * @param[in] dest_id TaskId of the receiving task. 187 * @param[in] src_id TaskId of the sending task. 188 * 189 * @return KE_MSG_CONSUMED 190 **************************************************************************************** 191 */ 192 int ke_msg_discard(ke_msg_id_t const msgid, void const *param, 193 ke_task_id_t const dest_id, ke_task_id_t const src_id); 194 195 /** 196 **************************************************************************************** 197 * @brief Generic message handler to consume message without handling it in the task. 198 * 199 * @param[in] msgid Id of the message received (probably unused) 200 * @param[in] param Pointer to the parameters of the message. 201 * @param[in] dest_id TaskId of the receiving task. 202 * @param[in] src_id TaskId of the sending task. 203 * 204 * @return KE_MSG_CONSUMED 205 **************************************************************************************** 206 */ 207 int ke_msg_save(ke_msg_id_t const msgid, void const *param, 208 ke_task_id_t const dest_id, ke_task_id_t const src_id); 209 210 211 212 /** 213 **************************************************************************************** 214 * @brief This function flushes all messages, currently pending in the kernel for a 215 * specific task. 216 * 217 * @param[in] task The Task Identifier that shall be flushed. 218 **************************************************************************************** 219 */ 220 void ke_task_msg_flush(ke_task_id_t task); 221 222 223 /** 224 **************************************************************************************** 225 * @brief Check validity of a task. If task type or task instance does not exist, 226 * return invalid task 227 * 228 * @param[in] task Task Identifier to check. 229 * 230 * @return Task identifier if valid, invalid identifier else. 231 **************************************************************************************** 232 */ 233 ke_task_id_t ke_task_check(ke_task_id_t task); 234 235 /// @} TASK 236 237 #endif // _BLE_KE_TASK_H 238 239