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