1 /* 2 * Copyright (C) 2018 GreenWaves Technologies 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef __PMSIS_DRIVERS_UART_H__ 18 #define __PMSIS_DRIVERS_UART_H__ 19 20 //#include "pmsis/pmsis_types.h" 21 #include "hal_pmsis_types.h" 22 23 /** 24 * @ingroup groupDrivers 25 */ 26 27 /** 28 * @defgroup UART UART 29 * 30 * \brief UART Universal Asynchronous Receiver Transmitter 31 * 32 * This API provides support for transferring data between an external UART 33 * device and the processor running this driver. 34 * 35 */ 36 37 /** 38 * @addtogroup UART 39 * @{ 40 */ 41 42 /** 43 * \struct pi_uart_conf 44 * 45 * \brief UART device configuration structure. 46 * 47 * This structure is used to pass the desired UART configuration to the runtime 48 * when opening the device. 49 */ 50 struct pi_uart_conf 51 { 52 uint32_t baudrate_bps; /*!< Required baudrate, in baud per second. */ 53 uint8_t stop_bit_count; /*!< Number of stop bits, 1 stop bit (default) or 54 2 stop bits */ 55 uint8_t parity_mode; /*!< 1 to activate it, 0 to deactivate it. */ 56 uint8_t word_size; /*!< Word size, in bits. */ 57 uint8_t enable_rx; /*!< 1 to activate reception, 0 to deactivate it. */ 58 uint8_t enable_tx; /*!< 1 to activate transmission, 0 to deactivate it. */ 59 uint8_t uart_id; /*!< Uart interface ID. */ 60 uint8_t use_ctrl_flow; /*!< 1 to activate control flow. */ 61 uint8_t is_usart; /*!< 1 to activate usart */ 62 }; 63 64 /** 65 * \enum pi_uart_stop_bits 66 * 67 * \brief Stop bits enum. 68 */ 69 enum pi_uart_stop_bits 70 { 71 PI_UART_STOP_BITS_ONE = 0, /*!< One stop bit. */ 72 PI_UART_STOP_BITS_TWO = 1 /*!< Two stop bits. */ 73 }; 74 75 /** 76 * \enum pi_uart_parity_mode 77 * 78 * \brief Parity mode enum. 79 */ 80 enum pi_uart_parity_mode 81 { 82 PI_UART_PARITY_DISABLE = 0, /*!< Disable parity mode. */ 83 PI_UART_PARITY_ENABLE = 1 /*!< Enable parity mode. */ 84 }; 85 86 /** 87 * \enum pi_uart_word_size 88 * 89 * \brief Bit length of each word. 90 */ 91 enum pi_uart_word_size 92 { 93 PI_UART_WORD_SIZE_5_BITS = 0, /*!< 5 bits length. */ 94 PI_UART_WORD_SIZE_6_BITS = 1, /*!< 6 bits length. */ 95 PI_UART_WORD_SIZE_7_BITS = 2, /*!< 7 bits length. */ 96 PI_UART_WORD_SIZE_8_BITS = 3 /*!< 8 bits length. */ 97 }; 98 99 100 /** 101 * \enum pi_uart_ioctl_cmd 102 * 103 * \brief UART ioctl commands. 104 * 105 * UART ioctl commands to configure, enable device. 106 */ 107 enum pi_uart_ioctl_cmd 108 { 109 /** 110 * \brief Setup UART device. 111 * 112 * Setup UART with given conf. 113 * The parameter for this command is a struct pi_uart_conf. 114 * 115 * \param conf Pointer to struct pi_uart_conf. 116 */ 117 PI_UART_IOCTL_CONF_SETUP = 0, 118 /** 119 * \brief Abort RX transfers. 120 * 121 * Disable RX channel, abort current RX transfert, 122 * and flush all pending transferts. 123 * 124 * \note This function disables reception channel after clearing UDMA 125 * channels. In order to send again data, the reception channel 126 * must re-enabled. 127 */ 128 PI_UART_IOCTL_ABORT_RX = 1, 129 /** 130 * \brief Abort TX transfers. 131 * 132 * Disable TX channel, abort current TX transfert, 133 * and flush all pending transferts. 134 * 135 * \note This function disables transmission channel after clearing UDMA 136 * channels. In order to send again data, the transmission channel 137 * must re-enabled. 138 */ 139 PI_UART_IOCTL_ABORT_TX = 2, 140 /** 141 * \brief Enable reception. 142 * 143 * This command enables reception on UART device. 144 */ 145 PI_UART_IOCTL_ENABLE_RX = 3, 146 /** 147 * \brief Enable transmission. 148 * 149 * This command enables transmission on UART device. 150 */ 151 PI_UART_IOCTL_ENABLE_TX = 4 152 }; 153 154 /** 155 * \brief UART cluster request structure. 156 * 157 * This structure is used by the runtime to manage a cluster remote copy with 158 * the UART. It must be instantiated once for each copy and must be kept 159 * alive until the copy is finished. It can be instantiated as a normal 160 * variable, for example as a global variable, a local one on the stack, 161 * or through a memory allocator. 162 */ 163 typedef struct pi_cl_uart_req_s pi_cl_uart_req_t; 164 165 /** 166 * \brief Initialize a UART configuration with default values. 167 * 168 * This function can be called to get default values for all parameters before 169 * setting some of them. 170 * The structure containing the configuration must be kept alive until the uart 171 * device is opened. 172 * 173 * \param conf Pointer to the UART configuration. 174 */ 175 void pi_uart_conf_init(struct pi_uart_conf *conf); 176 177 /** 178 * \brief Open a UART device. 179 * 180 * This function must be called before the UART device can be used. 181 * It will do all the needed configuration to make it usable and initialize 182 * the handle used to refer to this opened device when calling other functions. 183 * 184 * \param device Pointer to device structure of the device to open. 185 * 186 * \retval 0 If the operation is successfull. 187 * \retval ERRNO An error code otherwise. 188 * 189 * \note This structure is allocated by the called and must be kept alive until the 190 * device is closed. 191 */ 192 int pi_uart_open(struct pi_device *device); 193 194 /** 195 * \brief Close an opened UART device. 196 * 197 * This function can be called to close an opened UART device once it is 198 * not needed anymore, in order to free all allocated resources. Once this 199 * function is called, the device is not accessible anymore and must be opened 200 * again before being used. 201 * 202 * \param device Pointer to device structure of the device to close. 203 */ 204 void pi_uart_close(struct pi_device *device); 205 206 /** 207 * \brief Dynamically change device configuration. 208 * 209 * This function allows to send different commands to UART device. 210 * The commands are listed above, cf. enum pi_uart_ioctl_cmd. 211 * 212 * \param device Pointer to device descriptor of the UART device. 213 * \param cmd Ioctl command. 214 * \param arg Ioctl command args. 215 * 216 * \retval -1 If wrong ioctl command. 217 * \retval Value Otherwise return value depending on ioctl command. 218 */ 219 int pi_uart_ioctl(struct pi_device *device, uint32_t cmd, void *arg); 220 221 /** 222 * \brief Write data to an UART. 223 * 224 * This writes data to the specified UART. 225 * The caller is blocked until the transfer is finished. 226 * Depending on the chip, there may be some restrictions on the memory which 227 * can be used. Check the chip-specific documentation for more details. 228 * 229 * \param device Pointer to device descriptor of the UART device. 230 * \param buffer Pointer to data buffer. 231 * \param size Size of data to copy in bytes. 232 * 233 * \retval 0 If operation is successfull. 234 * \retval ERRNO An error code otherwise. 235 */ 236 int pi_uart_write(struct pi_device *device, void *buffer, uint32_t size); 237 238 /** 239 * \brief Read data from an UART. 240 * 241 * This reads data from the specified UART. 242 * The caller is blocked until the transfer is finished. 243 * Depending on the chip, there may be some restrictions on the memory which 244 * can be used. Check the chip-specific documentation for more details. 245 * 246 * \param device Pointer to device descriptor of the UART device. 247 * \param buffer Pointer to data buffer. 248 * \param size Size of data to copy in bytes. 249 * 250 * \retval 0 If operation is successfull. 251 * \retval ERRNO An error code otherwise. 252 */ 253 int pi_uart_read(struct pi_device *device, void *buffer, uint32_t size); 254 255 /** 256 * \brief Write a byte to an UART. 257 * 258 * This writes a byte to the specified UART. 259 * The caller is blocked until the transfer is finished. 260 * 261 * \param device Pointer to device descriptor of the UART device. 262 * \param byte Pointer to data buffer. 263 * 264 * \retval 0 If operation is successfull. 265 * \retval ERRNO An error code otherwise. 266 */ 267 int pi_uart_write_byte(struct pi_device *device, uint8_t *byte); 268 269 /** 270 * \brief Read a byte from an UART. 271 * 272 * This reads a byte from the specified UART. 273 * The caller is blocked until the transfer is finished. 274 * 275 * \param device Pointer to device descriptor of the UART device. 276 * \param byte Pointer to data buffer. 277 * 278 * \retval 0 If operation is successfull. 279 * \retval ERRNO An error code otherwise. 280 */ 281 int pi_uart_read_byte(struct pi_device *device, uint8_t *byte); 282 283 /** 284 * \brief Write data to an UART asynchronously. 285 * 286 * This writes data to the specified UART asynchronously. 287 * A task must be specified in order to specify how the caller should be 288 * notified when the transfer is finished. 289 * Depending on the chip, there may be some restrictions on the memory which 290 * can be used. Check the chip-specific documentation for more details. 291 * 292 * \param device Pointer to device descriptor of the UART device. 293 * \param buffer Pointer to data buffer. 294 * \param size Size of data to copy in bytes. 295 * \param callback Event task used to notify the end of transfer. See the 296 * documentation of pi_task_t for more details. 297 * 298 * \retval 0 If operation is successfull. 299 * \retval ERRNO An error code otherwise. 300 */ 301 int pi_uart_write_async(struct pi_device *device, void *buffer, uint32_t size, 302 pi_task_t* callback); 303 304 /** 305 * \brief Read data from an UART asynchronously. 306 * 307 * This reads data from the specified UART asynchronously. 308 * A task must be specified in order to specify how the caller should be 309 * notified when the transfer is finished. 310 * Depending on the chip, there may be some restrictions on the memory which 311 * can be used. Check the chip-specific documentation for more details. 312 * 313 * \param device Pointer to device descriptor of the UART device. 314 * \param buffer Pointer to data buffer. 315 * \param size Size of data to copy in bytes. 316 * \param callback Event task used to notify the end of transfer. See the 317 * documentation of pi_task_t for more details. 318 * 319 * \retval 0 If operation is successfull. 320 * \retval ERRNO An error code otherwise. 321 */ 322 int pi_uart_read_async(struct pi_device *device, void *buffer, uint32_t size, 323 pi_task_t* callback); 324 325 /** 326 * \brief Write a byte to an UART asynchronously. 327 * 328 * This writes a byte to the specified UART asynchronously. 329 * A task must be specified in order to specify how the caller should be 330 * notified when the transfer is finished. 331 * 332 * \param device Pointer to device descriptor of the UART device. 333 * \param byte Pointer to data buffer. 334 * \param callback Event task used to notify the end of transfer. See the 335 * documentation of pi_task_t for more details. 336 * 337 * \retval 0 If operation is successfull. 338 * \retval ERRNO An error code otherwise. 339 */ 340 int pi_uart_write_byte_async(struct pi_device *device, uint8_t *byte, pi_task_t* callback); 341 342 343 /** 344 * \brief Write data to an UART from cluster side. 345 * 346 * This function implements the same feature as pi_uart_write but can be called 347 * from cluster side in order to expose the feature on the cluster. 348 * A pointer to a request structure must be provided so that the runtime can 349 * properly do the remote call. 350 * 351 * \param device Pointer to device descriptor of the UART device. 352 * \param buffer Pointer to data buffer. 353 * \param size Size of data to copy in bytes. 354 * \param req Request structure used for termination. 355 * 356 * \retval 0 If operation is successfull. 357 * \retval ERRNO An error code otherwise. 358 */ 359 int pi_cl_uart_write(pi_device_t *device, void *buffer, uint32_t size, pi_cl_uart_req_t *req); 360 361 /** 362 * \brief Write a byte to an UART from cluster side. 363 * 364 * This function implements the same feature as pi_uart_write_byte but can be 365 * called from cluster side in order to expose the feature on the cluster. 366 * A pointer to a request structure must be provided so that the runtime can 367 * properly do the remote call. 368 * 369 * \param device Pointer to device descriptor of the UART device. 370 * \param byte Pointer to data buffer. 371 * \param req Request structure used for termination. 372 * 373 * \retval 0 If operation is successfull. 374 * \retval ERRNO An error code otherwise. 375 */ 376 int pi_cl_uart_write_byte(pi_device_t *device, uint8_t *byte, pi_cl_uart_req_t *req); 377 378 /** 379 * \brief Wait until the specified UART cluster write request has finished. 380 * 381 * This blocks the calling core until the specified cluster remote copy is 382 * finished. 383 * 384 * \param req Request structure used for termination. 385 */ 386 //static inline void pi_cl_uart_write_wait(pi_cl_uart_req_t *req); 387 388 /** 389 * \brief Read a byte from an UART from cluster side. 390 * 391 * This function implements the same feature as pi_uart_read_byte but can be 392 * called from cluster side in order to expose the feature on the cluster. 393 * A pointer to a request structure must be provided so that the runtime can 394 * properly do the remote call. 395 * 396 * \param device Pointer to device descriptor of the UART device. 397 * \param buffer Pointer to data buffer. 398 * \param size Size of data to copy in bytes. 399 * \param req Request structure used for termination. 400 * 401 * \retval 0 If operation is successfull. 402 * \retval ERRNO An error code otherwise. 403 */ 404 int pi_cl_uart_read(pi_device_t *device, void *buffer, uint32_t size, pi_cl_uart_req_t *req); 405 406 /** 407 * \brief Read a byte from an UART. 408 * 409 * This reads a byte from the specified UART. 410 * The caller is blocked until the transfer is finished. 411 * 412 * \param device Pointer to device descriptor of the UART device. 413 * \param byte Pointer to data buffer. 414 * \param req Request structure used for termination. 415 * 416 * \retval 0 If operation is successfull. 417 * \retval ERRNO An error code otherwise. 418 */ 419 int pi_cl_uart_read_byte(pi_device_t *device, uint8_t *byte, pi_cl_uart_req_t *req); 420 421 /** 422 * \brief Wait until the specified UART cluster read request has finished. 423 * 424 * This blocks the calling core until the specified cluster remote copy is 425 * finished. 426 * 427 * \param req Request structure used for termination. 428 */ 429 //static inline void pi_cl_uart_read_wait(pi_cl_uart_req_t *req); 430 431 /** 432 * @} 433 */ 434 435 #endif /* __PMSIS_DRIVERS_UART_H__ */ 436