rpp/include/rpp/sci.h

   1 /**
   2  * Serial Communication Interface RPP API header file.
   3  *
   4  * @file sci.h
   5  *
   6  * @copyright Copyright (C) 2013-2015 Czech Technical University in Prague
   7  *
   8  * @author Carlos Jenkins <carlos@jenkins.co.cr>
   9  */
  10
  11
  12 #ifndef __RPP_SCI_H
  13 #define __RPP_SCI_H
  14
  15 #include <stdarg.h>
  16 #include "types.h"
  17
  18 /**
  19  * SCI module initialization.
  20  *
  21  * Call this method before using this module. The default baudrate is
  22  * initialized to 115200. It can be changed later by calling
  23  * rpp_sci_setup().
  24  *
  25  * This function is not thread safe. Do not call it from multiple threads.
  26  *
  27  * @return SUCCESS if initialization successful.\n
  28  *         FAILURE if module already initialized.
  29  */
  30 int8_t rpp_sci_init();
  31
  32
  33 /**
  34  * SCI module setup.
  35  *
  36  * The function is thread safe.
  37  *
  38  * Configure the SCI module.
  39  *
  40  * @param[in] baud      Baud rate for the SCI. Tested values are 9600 and 115200
  41  *                      Default is 9600. If 0 is provided default is used.
  42  *
  43  * @return TRUE if baud rate is a known value.\n
  44  *         FALSE otherwise.
  45  */
  46 boolean_t rpp_sci_setup(uint32_t baud);
  47
  48
  49 // Generic API
  50 /**
  51  * Number of bytes available on input buffer.
  52  *
  53  * The function is thread safe.
  54  *
  55  * Get the number of bytes (characters) available for reading from the serial
  56  * port. This is data that's already arrived and stored in the SCI input buffer.
  57  *
  58  * @return [0-MAX_BUFFER_LEN] The number of bytes available to read.
  59  */
  60 uint16_t rpp_sci_available();
  61
  62
  63 /**
  64  * Read n number of bytes from input buffer.
  65  *
  66  * The function is thread safe.
  67  *
  68  * Transfer given amount of bytes from SCI input buffer into given buffer.
  69  * Buffer should be at least as large as the amount of data requested.
  70  *
  71  * This is a blocking call.
  72  *
  73  * Will block until requested amount of data is available.
  74  *
  75  * @param[in] amount    Amount/number of bytes to read.
  76  * @param[out] buffer   Pointer to buffer where to store data.
  77  *
  78  * @return SUCCESS when all data was transfered.
  79  */
  80 int8_t rpp_sci_read(uint32_t amount, uint8_t *buffer);
  81
  82
  83 /**
  84  * Read n number of bytes from input buffer if possible.
  85  *
  86  * The function is thread safe.
  87  *
  88  * Transfer given amount of bytes from SCI input buffer into given buffer.
  89  * Buffer should be at least as large as the amount of data requested.
  90  *
  91  * This is a non-blocking call.
  92  *
  93  * This function will only succeed if requested amount of data is present
  94  * already in the input buffer.
  95  *
  96  * @param[in] amount    Amount/number of bytes to read.
  97  * @param[out] buffer   Pointer to buffer where to store data.
  98  *
  99  * @return SUCCESS if the requested amount of data could be transfered.\n
 100  *         FAILURE if requested amount of data is unavailable.
 101  */
 102 int8_t rpp_sci_read_nb(uint32_t amount, uint8_t *buffer);
 103
 104
 105 /**
 106  * Write n number of bytes to the output buffer.
 107  *
 108  * The function is thread safe.
 109  *
 110  * Transfer given amount of bytes from given buffer to the SCI output buffer.
 111  * Data buffer should be at least as large as the amount of data requested to be
 112  * sent.
 113  *
 114  * This is a blocking call.
 115  *
 116  * This will block if SCI output buffer is full waiting until some space is
 117  * freed.
 118  *
 119  * @param[in] amount    Amount/number of bytes to send.
 120  * @param[in] data      Pointer to buffer from where to read data.
 121  *
 122  * @return SUCCESS when all data was transfered.
 123  */
 124 int8_t rpp_sci_write(uint32_t amount, uint8_t *data);
 125
 126
 127 /**
 128  * Write n number of bytes to the output buffer if possible.
 129  *
 130  * The function is thread safe.
 131  *
 132  * Transfer given amount of bytes from given buffer to the SCI output buffer.
 133  * Data buffer should be at least as large as the amount of data requested to be
 134  * sent.
 135  *
 136  * This is a non-blocking call.
 137  *
 138  * This is a best effort call, that means that this will try to put the maximum
 139  * amount of data into the output buffer until it's full or all the requested
 140  * amount of data could be transfered. If output buffer is blocked by another
 141  * process this function will not wait to acquire the lock for the buffer.
 142  *
 143  * @param[in] amount    Amount/number of bytes to send.
 144  * @param[in] data      Pointer to buffer from where to read data.
 145  *
 146  * @return SUCCESS if the requested amount of data could be transfered to the
 147  *                 output buffer.\n
 148  *         FAILURE if the SCI output buffer was locked by another process or
 149  *                 not all the bytes requested to send could be transfered.
 150  */
 151 int8_t rpp_sci_write_nb(uint32_t amount, uint8_t *data);
 152
 153
 154 /**
 155  * Flush incomming or outgoing buffers.
 156  *
 157  * The function is thread safe.
 158  *
 159  * This is a blocking call.
 160  *
 161  * This will block if another process is writing to or reading data from the
 162  * selected buffer to flush until this process releases the lock on the buffer.
 163  *
 164  * @param[in] buff      TRUE to flush incomming buffer.
 165  *                      FALSE to flush outgoing buffer.
 166  *
 167  * @return SUCCESS if flushed buffer had some data.\n
 168  *         FAILURE if flushed buffer had no data left.
 169  */
 170 int8_t rpp_sci_flush(boolean_t buff);
 171
 172
 173
 174 /**
 175  * C style printk using RPP SCI module.
 176  *
 177  * The function is not thread safe.
 178  *
 179  * This call is intended to be used from interrupt only.
 180  * Function blocks until whole string was sent to the SCI output, therefore
 181  * it should be used with care. Frequent usage is for debugging.
 182  *
 183  * This function will wait until all the bytes are sent to the SCI output.
 184  * Implementation uses vsnprintf() from stdio.h using a fixed
 185  * MAX_BUFFER_LEN bytes buffer.
 186  *
 187  * @param[in] format    C string that contains a format string that follows the
 188  *                      same specifications as format in printf (see stdio.h's
 189  *                      printf for details).
 190  * @param[in] ...       (additional arguments) Depending on the format string,
 191  *                      the function may expect a sequence of additional
 192  *                      arguments, each containing a value to be used to replace
 193  *                      a format specifier in the format string (or a pointer to
 194  *                      a storage location).
 195  *                      There should be at least as many of these arguments as
 196  *                      the number of values specified in the format specifiers.
 197  *                      Additional arguments are ignored by the function.
 198  *
 199  * @return SUCCESS when string was sent
 200  *         FAILURE when an error occurred
 201  */
 202 int32_t rpp_sci_printk(const char *format, ...);
 203
 204
 205 /**
 206  * C style printk using RPP SCI module.
 207  *
 208  * The function is not thread safe.
 209  *
 210  * This call is intended to be used from interrupt only.
 211  * Function tries to append string to the output buffer.
 212  *
 213  * Implementation uses vsnprintf() from stdio.h using a fixed
 214  * MAX_BUFFER_LEN bytes buffer.
 215  *
 216  * @param[in] format    C string that contains a format string that follows the
 217  *                      same specifications as format in printf (see stdio.h's
 218  *                      printf for details).
 219  * @param[in] ...       (additional arguments) Depending on the format string,
 220  *                      the function may expect a sequence of additional
 221  *                      arguments, each containing a value to be used to replace
 222  *                      a format specifier in the format string (or a pointer to
 223  *                      a storage location).
 224  *                      There should be at least as many of these arguments as
 225  *                      the number of values specified in the format specifiers.
 226  *                      Additional arguments are ignored by the function.
 227  *
 228  * @return The number of characters that have been written to the buffer.
 229  *          If an error occurs, a negative number is returned.
 230  */
 231 int32_t rpp_sci_printkb(const char *format, ...);
 232
 233
 234 // C style API
 235 /**
 236  * C style printf using RPP SCI module.
 237  *
 238  * The function is thread safe.
 239  *
 240  * This is a blocking call.
 241  *
 242  * This function will wait until all the bytes are sent to the SCI output
 243  * buffer. Implementation uses vsnprintf() from stdio.h using a fixed
 244  * MAX_BUFFER_LEN bytes buffer.
 245  *
 246  * @param[in] format    C string that contains a format string that follows the
 247  *                      same specifications as format in printf (see stdio.h's
 248  *                      printf for details).
 249  * @param[in] ...       (additional arguments) Depending on the format string,
 250  *                      the function may expect a sequence of additional
 251  *                      arguments, each containing a value to be used to replace
 252  *                      a format specifier in the format string (or a pointer to
 253  *                      a storage location).
 254  *                      There should be at least as many of these arguments as
 255  *                      the number of values specified in the format specifiers.
 256  *                      Additional arguments are ignored by the function.
 257  *
 258  * @return The number of characters that would have been written if the buffer
 259  *          had been sufficiently large, not counting the terminating null
 260  *          character. If an encoding error occurs, a negative number is
 261  *          returned. Please note that only when this returned value is
 262  *          non-negative and less than the buffer size, the string has been
 263  *          completely written.
 264  */
 265 int32_t rpp_sci_printf(const char *format, ...);
 266
 267
 268 /**
 269  * C style vprintf using RPP SCI module.
 270  *
 271  * The function is thread safe.
 272  *
 273  * This is a blocking call.
 274  *
 275  * This function will wait until all the bytes are sent to the SCI output
 276  * buffer. Implementation uses vsnprintf() from stdio.h using a fixed
 277  * MAX_BUFFER_LEN bytes buffer.
 278  *
 279  * @param[in] format    C string that contains a format string that follows the
 280  *                      same specifications as format in printf (see stdio.h's
 281  *                      printf for details).
 282  * @param[in] args       (additional arguments) Depending on the format string,
 283  *                      the function may expect a sequence of additional
 284  *                      arguments, each containing a value to be used to replace
 285  *                      a format specifier in the format string (or a pointer to
 286  *                      a storage location).
 287  *                      There should be at least as many of these arguments as
 288  *                      the number of values specified in the format specifiers.
 289  *                      Additional arguments are ignored by the function.
 290  *
 291  * @return The number of characters that would have been written if the buffer
 292  *          had been sufficiently large, not counting the terminating null
 293  *          character. If an encoding error occurs, a negative number is
 294  *          returned. Please note that only when this returned value is
 295  *          non-negative and less than the buffer size, the string has been
 296  *          completely written.
 297  */
 298 int32_t rpp_sci_vprintf(const char *format, va_list args);
 299
 300
 301 /**
 302  * C style putc (put character) using RPP SCI module.
 303  *
 304  * The function is not thread safe.
 305  *
 306  * This is a blocking call.
 307  *
 308  * This function will wait until the given byte is put into SCI output buffer if
 309  * it is full.
 310  *
 311  * @param[in] byte      Byte to put into SCI output buffer.
 312  *
 313  * @return SUCCESS when the given byte could be transfered.
 314  */
 315 int8_t rpp_sci_putc(uint8_t byte);
 316
 317
 318 /**
 319  * C style getc (get character) using RPP SCI module.
 320  *
 321  * The function is not thread safe.
 322  *
 323  * This is a blocking call.
 324  *
 325  * This function will wait until a byte is available in the SCI input buffer if
 326  * it is empty.
 327  *
 328  * @note The byte is promoted to an int16_t in order to accommodate for
 329  * FAILURE/EOF/-1 if an error occurs. This is in order to conform with C getc,
 330  * but should never happen in current implementation because this is a blocking
 331  * call and will always wait for one byte to be available in the input buffer.
 332  * Nevertheless, if user compiles it's programs against POSIX FreeRTOS for
 333  * Simulation then the compatibility layers makes it possible to return EOF so
 334  * user expecting to run in Simulation should always check for FAILURE.
 335  *
 336  * @return [0-255] The byte read from the SCI input buffer.\n
 337  *         FAILURE If and error occurred.
 338  */
 339 int16_t rpp_sci_getc();
 340
 341
 342
 343 #endif /* __RPP_SCI_H */