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