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_MAX32655_SEMA_H_ 28 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32655_SEMA_H_ 29 30 /* **** Includes **** */ 31 #include "mxc_device.h" 32 #include "mxc_sys.h" 33 #include "sema_regs.h" 34 #include "sema_reva.h" 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /** 41 * @defgroup sema Semaphore (SEMA) 42 * @ingroup periphlibs 43 * @{ 44 */ 45 46 /* **** Function Prototypes **** */ 47 48 /** 49 * @brief The callback routine used by the MXC_SEMA_ReadBoxAsync() and 50 * MXC_SEMA_WriteBoxAsync functions to indicate the operation has completed. 51 * 52 * @param result The error code (if any) of the read/write operation. 53 * See \ref MXC_Error_Codes for the list of error codes. 54 */ 55 typedef void (*mxc_sema_complete_cb_t)(int result); 56 57 /** 58 * @brief Initialize the semaphore peripheral 59 * @return #E_NO_ERROR if semaphore initialized. 60 */ 61 int MXC_SEMA_Init(void); 62 63 /** 64 * @brief Attempt to get a semaphore. 65 * @param sema Number of semaphore you are trying to get. 66 * @return #E_NO_ERROR if semaphore acquired. #E_BUSY if semaphore is already locked. 67 */ 68 int MXC_SEMA_GetSema(unsigned sema); 69 70 /** 71 * @brief Check a semaphore. 72 * @param sema Number of semaphore you want to check. 73 * @return #E_NO_ERROR if semaphore is free. #E_BUSY if semaphore is already locked. 74 * @note Will not be atomic if you call this function and then attempt to MXC_SEMA_GetSema(). 75 */ 76 int MXC_SEMA_CheckSema(unsigned sema); 77 78 /** 79 * @brief Check all semaphores. 80 * @return Status of all semaphores. Each semaphore will be represented by 1 bit. 81 * @note Will not be atomic if you call this function and then attempt to MXC_SEMA_GetSema(). 82 */ 83 uint32_t MXC_SEMA_Status(void); 84 85 /** 86 * @brief Frees the semaphore. 87 * @param sema Number of semaphore want to free. 88 */ 89 void MXC_SEMA_FreeSema(unsigned sema); 90 91 /** 92 * @brief Shutdown the semaphore peripheral 93 * @return #E_NO_ERROR if semaphore released. 94 */ 95 int MXC_SEMA_Shutdown(void); 96 97 /** 98 * @brief Initialize the mailboxes 99 * @return #E_NO_ERROR if mailboxes initialized. 100 */ 101 int MXC_SEMA_InitBoxes(void); 102 103 /** 104 * @brief Read from the mailbox 105 * @details Will only read data currently available. 106 * @param data Buffer to store the data from the mailbox. 107 * @param len Number of bytes to read from the mailbox. 108 * @return #E_NO_ERROR if data read properly. 109 */ 110 int MXC_SEMA_ReadBox(uint8_t *data, unsigned len); 111 112 /** 113 * @brief Write to the mailbox 114 * @details Will only write in the space currently available. 115 * @param data Data to write to the mailbox. 116 * @param len Number of bytes to write to the mailbox. 117 * @return #E_NO_ERROR if data written properly. 118 */ 119 int MXC_SEMA_WriteBox(const uint8_t *data, unsigned len); 120 121 /** 122 * @brief Semaphore interrupt handler 123 * @return #E_NO_ERROR if interrupt handled properly. 124 */ 125 int MXC_SEMA_Handler(void); 126 127 /** 128 * @brief Read asynchronously from the mailbox 129 * @details Non-blocking read. Will only read data currently available. 130 * @param cb Callback function, called once the read is complete. 131 * @param data Buffer to store the data from the mailbox. 132 * @param len Number of bytes to read from the mailbox. 133 * @return #E_NO_ERROR if data read properly. 134 */ 135 int MXC_SEMA_ReadBoxAsync(mxc_sema_complete_cb_t cb, uint8_t *data, unsigned len); 136 137 /** 138 * @brief Write asynchronously to the mailbox 139 * @param cb Callback function, called once the write is complete. 140 * @param data Data to write to the mailbox. 141 * @param len Number of bytes to write to the mailbox. 142 * @return #E_NO_ERROR if data written properly. 143 */ 144 int MXC_SEMA_WriteBoxAsync(mxc_sema_complete_cb_t cb, const uint8_t *data, unsigned len); 145 146 /**@} end of group sema */ 147 148 #ifdef __cplusplus 149 } 150 #endif 151 152 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32655_SEMA_H_ 153
