1 /** 2 * \file 3 * 4 * \brief Control Area Network(CAN) functionality declaration. 5 * 6 * Copyright (c) 2016-2018 Microchip Technology Inc. and its subsidiaries. 7 * 8 * \asf_license_start 9 * 10 * \page License 11 * 12 * Subject to your compliance with these terms, you may use Microchip 13 * software and any derivatives exclusively with Microchip products. 14 * It is your responsibility to comply with third party license terms applicable 15 * to your use of third party software (including open source software) that 16 * may accompany Microchip software. 17 * 18 * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, 19 * WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, 20 * INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, 21 * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL MICROCHIP BE 22 * LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL 23 * LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE 24 * SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE 25 * POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE FULLEST EXTENT 26 * ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY 27 * RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY, 28 * THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE. 29 * 30 * \asf_license_stop 31 * 32 */ 33 34 #ifndef HAL_CAN_ASYNC_H_INCLUDED 35 #define HAL_CAN_ASYNC_H_INCLUDED 36 37 #include <hpl_can.h> 38 #include <hpl_can_async.h> 39 #include <utils_assert.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 /** 45 * \addtogroup doc_driver_hal_can_async 46 * 47 *@{ 48 */ 49 50 /** 51 * \brief CAN Asynchronous descriptor 52 * 53 * The CAN descriptor forward declaration. 54 */ 55 struct can_async_descriptor; 56 57 /** 58 * Callback for CAN interrupt 59 */ 60 typedef void (*can_cb_t)(struct can_async_descriptor *const descr); 61 62 /** 63 * \brief CAN callbacks 64 */ 65 struct can_callbacks { 66 can_cb_t tx_done; 67 can_cb_t rx_done; 68 void (*irq_handler)(struct can_async_descriptor *const descr, enum can_async_interrupt_type type); 69 }; 70 71 /** 72 * \brief CAN descriptor 73 */ 74 struct can_async_descriptor { 75 struct _can_async_device dev; /*!< CAN HPL device descriptor */ 76 struct can_callbacks cb; /*!< CAN Interrupt Callbacks handler */ 77 }; 78 79 /** 80 * \brief Initialize CAN. 81 * 82 * This function initializes the given CAN descriptor. 83 * 84 * \param[in, out] descr A CAN descriptor to initialize. 85 * \param[in] hw The pointer to hardware instance. 86 * 87 * \return Initialization status. 88 */ 89 int32_t can_async_init(struct can_async_descriptor *const descr, void *const hw); 90 91 /** 92 * \brief Deinitialize CAN. 93 * 94 * This function deinitializes the given CAN descriptor. 95 * 96 * \param[in, out] descr The CAN descriptor to deinitialize. 97 * 98 * \return De-initialization status. 99 */ 100 int32_t can_async_deinit(struct can_async_descriptor *const descr); 101 102 /** 103 * \brief Enable CAN 104 * 105 * This function enables CAN by the given can descriptor. 106 * 107 * \param[in] descr The CAN descriptor to enable. 108 * 109 * \return Enabling status. 110 */ 111 int32_t can_async_enable(struct can_async_descriptor *const descr); 112 113 /** 114 * \brief Disable CAN 115 * 116 * This function disables CAN by the given can descriptor. 117 * 118 * \param[in] descr The CAN descriptor to disable. 119 * 120 * \return Disabling status. 121 */ 122 int32_t can_async_disable(struct can_async_descriptor *const descr); 123 124 /** 125 * \brief Read a CAN message 126 * 127 * \param[in] descr The CAN descriptor to read message. 128 * \param[in] msg The CAN message to read to. 129 * 130 * \return The status of read message. 131 */ 132 int32_t can_async_read(struct can_async_descriptor *const descr, struct can_message *msg); 133 134 /** 135 * \brief Write a CAN message 136 * 137 * \param[in] descr The CAN descriptor to write message. 138 * \param[in] msg The CAN message to write. 139 * 140 * \return The status of write message. 141 */ 142 int32_t can_async_write(struct can_async_descriptor *const descr, struct can_message *msg); 143 144 /** 145 * \brief Register CAN callback function to interrupt 146 * 147 * \param[in] descr The CAN descriptor 148 * \param[in] type Callback type 149 * \param[in] cb A callback function, passing NULL will de-register any 150 * registered callback 151 * 152 * \return The status of callback assignment. 153 */ 154 int32_t can_async_register_callback(struct can_async_descriptor *const descr, enum can_async_callback_type type, 155 FUNC_PTR cb); 156 157 /** 158 * \brief Return number of read errors 159 * 160 * This function returns the number of read errors. 161 * 162 * \param[in] descr The CAN descriptor pointer 163 * 164 * \return The number of read errors. 165 */ 166 uint8_t can_async_get_rxerr(struct can_async_descriptor *const descr); 167 168 /** 169 * \brief Return number of write errors 170 * 171 * This function returns the number of write errors. 172 * 173 * \param[in] descr The CAN descriptor pointer 174 * 175 * \return The number of write errors. 176 */ 177 uint8_t can_async_get_txerr(struct can_async_descriptor *const descr); 178 179 /** 180 * \brief Set CAN to the specified mode 181 * 182 * This function sets CAN to a specified mode. 183 * 184 * \param[in] descr The CAN descriptor pointer 185 * \param[in] mode The CAN operation mode 186 * 187 * \return Status of the operation. 188 */ 189 int32_t can_async_set_mode(struct can_async_descriptor *const descr, enum can_mode mode); 190 191 /** 192 * \brief Set CAN Filter 193 * 194 * This function sets CAN to a specified mode. 195 * 196 * \param[in] descr The CAN descriptor pointer 197 * \param[in] index Index of Filter list 198 * \param[in] fmt CAN Indentify Type 199 * \param[in] filter CAN Filter struct, NULL for clear filter 200 * 201 * \return Status of the operation. 202 */ 203 int32_t can_async_set_filter(struct can_async_descriptor *const descr, uint8_t index, enum can_format fmt, 204 struct can_filter *filter); 205 206 /** 207 * \brief Retrieve the current driver version 208 * 209 * \return The current driver version. 210 */ 211 uint32_t can_async_get_version(void); 212 213 /**@}*/ 214 215 #ifdef __cplusplus 216 } 217 #endif 218 219 #endif /* HAL_CAN_ASYNC_H_INCLUDED */ 220