1 // Copyright (C) 2022 Beken Corporation 2 // 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 #pragma once 16 #include <driver/mailbox_types.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /* @brief Overview about this API header 23 * 24 */ 25 26 /** 27 * @brief MAILBOX API 28 * @defgroup bk_api_mailbox MAILBOX API group 29 * @{ 30 */ 31 32 /** 33 * @brief Init the MAILBOX driver 34 * 35 * This API init the resoure common to all MAILBOXs: 36 * - Init MAILBOX driver control register 37 * - Configure MAILBOX interrupt handling function 38 * 39 * This API should be called before any other MAILBOX APIs. 40 * 41 * @return 42 * - BK_OK: succeed 43 * - others: other errors. 44 */ 45 bk_err_t bk_mailbox_init(void); 46 47 /** 48 * @brief Deinit the MAILBOX driver 49 * 50 * This API free all resource related to MAILBOX. 51 * 52 * @return 53 * - BK_OK: succeed 54 * - others: other errors. 55 */ 56 bk_err_t bk_mailbox_deinit(void); 57 /** 58 * @brief Configure the MAILBOX cmd and data. 59 * 60 * This API is used to configure data. 61 * Write parameters to variables as required by the structure, mailbox_data_t. 62 * 63 * example: 64 * mailbox_data_t send_data; 65 * uint32_t param0 = 123456; 66 * uint32_t param1 = 111; 67 * uint32_t param2 = 666; 68 * uint32_t param3 = 888; 69 * mailbox_set_param(&send_data, param0, param1, param2, param3); 70 * 71 * @return 72 * - BK_OK: succeed 73 * - others: other errors. 74 */ 75 bk_err_t bk_mailbox_set_param(mailbox_data_t *data, uint32_t p0, uint32_t p1, uint32_t p2, uint32_t p3); 76 77 /** 78 * @brief Register the callback function for MAILBOX 79 * 80 * @attention src : Associated with the CPU that needs to send data 81 * dst : Associated with the CPU of the current code 82 * execution system 83 * callback: After receiving the data, it is transmitted to 84 * the correspongding processing function. 85 * example: 86 * The current code runs in CPU0 and receives data from CPU1. 87 * 88 * src = MAILBOX_CPU1; 89 * dst = MAILBOX_CPU0; 90 * callback = receive_from_CPU_1; 91 * 92 * @return 93 * - BK_OK: succeed 94 * - BK_ERR_MAILBOX_SRC_DST: MAILBOX data transmission direction error 95 * - BK_ERR_MAILBOX_CALLBACK: Insufficient space or wrong format of registered function, etc 96 * - others: other errors. 97 */ 98 bk_err_t bk_mailbox_recv_callback_register(mailbox_endpoint_t src, mailbox_endpoint_t dst, mailbox_callback_t callback); 99 100 /** 101 * @brief Unregister the callback function for MAILBOX 102 * 103 * @attention src : Associated with the CPU that needs to send data 104 * dst : Associated with the CPU of the current code 105 * execution system 106 * callback: After receiving the data, it is transmitted to 107 * the correspongding processing function. 108 * example: 109 * The current code runs in CPU0 and receives data from CPU1. 110 * 111 * src = MAILBOX_CPU1 112 * dst = MAILBOX_CPU0 113 * 114 * @return 115 * - BK_OK: succeed 116 * - BK_ERR_MAILBOX_SRC_DST: MAILBOX data transmission direction error. 117 * - BK_ERR_MAILBOX_CALLBACK: Callback function is not registered. 118 * - others: other errors. 119 */ 120 bk_err_t bk_mailbox_recv_callback_unregister(mailbox_endpoint_t src, mailbox_endpoint_t dst); 121 122 /** 123 * @brief Unregister the callback function for MAILBOX 124 * 125 * @attention Before sending data, need to use the mailbox_set_param() 126 * to configure the data format. 127 * 128 * example: 129 * The current code runs in CPU0 and send data to CPU1. 130 * 131 * src = MAILBOX_ENDPOINT_CPU0 132 * dst = MAILBOX_CPU1 133 * data : mbx ('by mailbox_set_param(&mbx, p0, p1, p2, p3)') 134 * 135 * @return 136 * - BK_OK: succeed 137 * - BK_ERR_MAILBOX_SRC_DST: MAILBOX data transmission direction error. 138 * - BK_ERR_MAILBOX_BOX: No empty box store data. 139 * - BK_ERR_MAILBOX_TIMEOUT: Timeout waiting for the opposite end to fetch data. 140 * - others: other errors. 141 */ 142 bk_err_t bk_mailbox_send(mailbox_data_t *data, mailbox_endpoint_t src, mailbox_endpoint_t dst, void *arg); 143 144 /** 145 * @} 146 */ 147 #ifdef __cplusplus 148 } 149 #endif 150 151 152