1 /** 2 * @file sema.h 3 * @brief Semaphore (SEMA) function prototypes and data types. 4 */ 5 6 /****************************************************************************** 7 * 8 * Copyright (C) 2022-2023 Maxim Integrated Products, Inc. (now owned by 9 * Analog Devices, Inc.), 10 * Copyright (C) 2023-2024 Analog Devices, Inc. 11 * 12 * Licensed under the Apache License, Version 2.0 (the "License"); 13 * you may not use this file except in compliance with the License. 14 * You may obtain a copy of the License at 15 * 16 * http://www.apache.org/licenses/LICENSE-2.0 17 * 18 * Unless required by applicable law or agreed to in writing, software 19 * distributed under the License is distributed on an "AS IS" BASIS, 20 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 * See the License for the specific language governing permissions and 22 * limitations under the License. 23 * 24 ******************************************************************************/ 25 26 /* Define to prevent redundant inclusion */ 27 #ifndef LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32690_SEMA_H_ 28 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32690_SEMA_H_ 29 30 /* **** Includes **** */ 31 #include "mxc_device.h" 32 #include "mxc_sys.h" 33 #include "sema_regs.h" 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 /** 40 * @defgroup sema Semaphore (SEMA) 41 * @ingroup periphlibs 42 * @{ 43 */ 44 45 /* **** Function Prototypes **** */ 46 47 /** 48 * @brief The callback routine used by the MXC_SEMA_ReadBoxAsync() and 49 * MXC_SEMA_WriteBoxAsync functions to indicate the operation has completed. 50 * 51 * @param result The error code (if any) of the read/write operation. 52 * See \ref MXC_Error_Codes for the list of error codes. 53 */ 54 typedef void (*mxc_sema_complete_cb_t)(int result); 55 56 /** 57 * @brief Initialize the semaphore peripheral 58 * @return #E_NO_ERROR if semaphore initialized. 59 */ 60 int MXC_SEMA_Init(void); 61 62 /** 63 * @brief Attempt to get a semaphore. 64 * @param sema Number of semaphore you are trying to get. 65 * @return #E_NO_ERROR if semaphore acquired. #E_BUSY if semaphore is already locked. 66 */ 67 int MXC_SEMA_GetSema(unsigned sema); 68 69 /** 70 * @brief Check a semaphore. 71 * @param sema Number of semaphore you want to check. 72 * @return #E_NO_ERROR if semaphore is free. #E_BUSY if semaphore is already locked. 73 * @note Will not be atomic if you call this function and then attempt to MXC_SEMA_GetSema(). 74 */ 75 int MXC_SEMA_CheckSema(unsigned sema); 76 77 /** 78 * @brief Check all semaphores. 79 * @return Status of all semaphores. Each semaphore will be represented by 1 bit. 80 * @note Will not be atomic if you call this function and then attempt to MXC_SEMA_GetSema(). 81 */ 82 uint32_t MXC_SEMA_Status(void); 83 84 /** 85 * @brief Frees the semaphore. 86 * @param sema Number of semaphore want to free. 87 */ 88 void MXC_SEMA_FreeSema(unsigned sema); 89 90 /** 91 * @brief Shutdown the semaphore peripheral 92 * @return #E_NO_ERROR if semaphore released. 93 */ 94 int MXC_SEMA_Shutdown(void); 95 96 /** 97 * @brief Initialize the mailboxes 98 * @return #E_NO_ERROR if mailboxes initialized. 99 */ 100 int MXC_SEMA_InitBoxes(void); 101 102 /** 103 * @brief Read from the mailbox 104 * @details Will only read data currently available. 105 * @param data Buffer to store the data from the mailbox. 106 * @param len Number of bytes to read from the mailbox. 107 * @return #E_NO_ERROR if data read properly. 108 */ 109 int MXC_SEMA_ReadBox(uint8_t *data, unsigned len); 110 111 /** 112 * @brief Write to the mailbox 113 * @details Will only write in the space currently available. 114 * @param data Data to write to the mailbox. 115 * @param len Number of bytes to write to the mailbox. 116 * @return #E_NO_ERROR if data written properly. 117 */ 118 int MXC_SEMA_WriteBox(const uint8_t *data, unsigned len); 119 120 /** 121 * @brief Semaphore interrupt handler 122 * @return #E_NO_ERROR if interrupt handled properly. 123 */ 124 int MXC_SEMA_Handler(void); 125 126 /** 127 * @brief Read asynchronously from the mailbox 128 * @details Non-blocking read. Will only read data currently available. 129 * @param cb Callback function, called once the read is complete. 130 * @param data Buffer to store the data from the mailbox. 131 * @param len Number of bytes to read from the mailbox. 132 * @return #E_NO_ERROR if data read properly. 133 */ 134 int MXC_SEMA_ReadBoxAsync(mxc_sema_complete_cb_t cb, uint8_t *data, unsigned len); 135 136 /** 137 * @brief Write asynchronously to the mailbox 138 * @param cb Callback function, called once the write is complete. 139 * @param data Data to write to the mailbox. 140 * @param len Number of bytes to write to the mailbox. 141 * @return #E_NO_ERROR if data written properly. 142 */ 143 int MXC_SEMA_WriteBoxAsync(mxc_sema_complete_cb_t cb, const uint8_t *data, unsigned len); 144 145 /**@} end of group sema */ 146 147 #ifdef __cplusplus 148 } 149 #endif 150 151 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32690_SEMA_H_ 152
