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