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 // C style API
 153 /**
 154  * C style printf using RPP SCI module.
 155  *
 156  * This is a blocking call.
 157  *
 158  * This function will wait until all the bytes are sent to the SCI output
 159  * buffer. Implementation uses vsnprintf() from stdio.h using a fixed
 160  * MAX_BUFFER_LEN bytes buffer.
 161  *
 162  * @param[in] format    C string that contains a format string that follows the
 163  *                      same specifications as format in printf (see stdio.h's
 164  *                      printf for details).
 165  * @param[in] ...       (additional arguments) Depending on the format string,
 166  *                      the function may expect a sequence of additional
 167  *                      arguments, each containing a value to be used to replace
 168  *                      a format specifier in the format string (or a pointer to
 169  *                      a storage location).
 170  *                      There should be at least as many of these arguments as
 171  *                      the number of values specified in the format specifiers.
 172  *                      Additional arguments are ignored by the function.
 173  *
 174  * @return The number of characters that would have been written if the buffer
 175  *          had been sufficiently large, not counting the terminating null
 176  *          character. If an encoding error occurs, a negative number is
 177  *          returned. Please note that only when this returned value is
 178  *          non-negative and less than the buffer size, the string has been
 179  *          completely written.
 180  */
 181 int32_t rpp_sci_printf(const char* format, ...);
 182 int32_t __rpp_sci_printf(const char* format, va_list args);
 183
 184
 185 /**
 186  * C style putc (put character) using RPP SCI module.
 187  *
 188  * This is a blocking call.
 189  *
 190  * This function will wait until the given byte is put into SCI output buffer if
 191  * it is full.
 192  *
 193  * @param[in] byte      Byte to put into SCI output buffer.
 194  *
 195  * @return SUCCESS when the given byte could be transfered.
 196  */
 197 int8_t rpp_sci_putc(uint8_t byte);
 198
 199
 200 /**
 201  * C style getc (get character) using RPP SCI module.
 202  *
 203  * This is a blocking call.
 204  *
 205  * This function will wait until a byte is available in the SCI input buffer if
 206  * it is empty.
 207  *
 208  * @note The byte is promoted to an int16_t in order to accommodate for
 209  * FAILURE/EOF/-1 if an error occurs. This is in order to conform with C getc,
 210  * but should never happen in current implementation because this is a blocking
 211  * call and will always wait for one byte to be available in the input buffer.
 212  * Nevertheless, if user compiles it's programs against POSIX FreeRTOS for
 213  * Simulation then the compatibility layers makes it possible to return EOF so
 214  * user expecting to run in Simulation should always check for FAILURE.
 215  *
 216  * @return [0-255] The byte read from the SCI input buffer.\n
 217  *         FAILURE If and error occurred.
 218  */
 219 int16_t rpp_sci_getc();
 220
 221
 222
 223 #endif /* __RPP_SCI_H */
 224