*
* @file sci.h
*
- * @copyright Copyright (C) 2013 Czech Technical University in Prague
+ * @copyright Copyright (C) 2013-2015 Czech Technical University in Prague
*
* @author Carlos Jenkins <carlos@jenkins.co.cr>
*/
#ifndef __RPP_SCI_H
#define __RPP_SCI_H
+#include <stdarg.h>
+#include "types.h"
+
/**
* SCI module initialization.
- * Call this method before using this module.
*
- * @return SUCCESS if initialization successful.
- * FAILURE if module already initialized.
+ * Call this method before using this module. The default baudrate is
+ * initialized to 115200. It can be changed later by calling
+ * rpp_sci_setup().
+ *
+ * This function is not thread safe. Do not call it from multiple threads.
+ *
+ * @return SUCCESS if initialization successful.\n
+ * FAILURE if module already initialized.
*/
int8_t rpp_sci_init();
/**
* SCI module setup.
+ *
+ * The function is thread safe.
+ *
* Configure the SCI module.
*
- * @param[in] baud Baud rate for the SCI. Tested values are 9600 and FIXME
- * Default is 9600.
+ * @param[in] baud Baud rate for the SCI. Tested values are 9600 and 115200
+ * Default is 9600. If 0 is provided default is used.
*
- * @return TRUE if baud rate is a known value.
- * FALSE otherwise.
+ * @return TRUE if baud rate is a known value.\n
+ * FALSE otherwise.
*/
boolean_t rpp_sci_setup(uint32_t baud);
// Generic API
/**
+ * Number of bytes available on input buffer.
+ *
+ * The function is thread safe.
+ *
* Get the number of bytes (characters) available for reading from the serial
* port. This is data that's already arrived and stored in the SCI input buffer.
*
/**
+ * Read n number of bytes from input buffer.
+ *
+ * The function is thread safe.
+ *
* Transfer given amount of bytes from SCI input buffer into given buffer.
* Buffer should be at least as large as the amount of data requested.
*
*
* @return SUCCESS when all data was transfered.
*/
-int8_t rpp_sci_read(uint32_t amount, uint8_t* buffer);
+int8_t rpp_sci_read(uint32_t amount, uint8_t *buffer);
/**
+ * Read n number of bytes from input buffer if possible.
+ *
+ * The function is thread safe.
+ *
* Transfer given amount of bytes from SCI input buffer into given buffer.
* Buffer should be at least as large as the amount of data requested.
*
* @param[in] amount Amount/number of bytes to read.
* @param[out] buffer Pointer to buffer where to store data.
*
- * @return SUCCESS if the requested amount of data could be transfered.
- * FAILURE if requested amount of data is unavailable.
+ * @return SUCCESS if the requested amount of data could be transfered.\n
+ * FAILURE if requested amount of data is unavailable.
*/
-int8_t rpp_sci_read_nb(uint32_t amount, uint8_t* buffer);
+int8_t rpp_sci_read_nb(uint32_t amount, uint8_t *buffer);
/**
+ * Write n number of bytes to the output buffer.
+ *
+ * The function is thread safe.
+ *
* Transfer given amount of bytes from given buffer to the SCI output buffer.
* Data buffer should be at least as large as the amount of data requested to be
* sent.
*
* @return SUCCESS when all data was transfered.
*/
-int8_t rpp_sci_write(uint32_t amount, uint8_t* data);
+int8_t rpp_sci_write(uint32_t amount, uint8_t *data);
/**
+ * Write n number of bytes to the output buffer if possible.
+ *
+ * The function is thread safe.
+ *
* Transfer given amount of bytes from given buffer to the SCI output buffer.
* Data buffer should be at least as large as the amount of data requested to be
* sent.
* @param[in] data Pointer to buffer from where to read data.
*
* @return SUCCESS if the requested amount of data could be transfered to the
- * output buffer.
- * FAILURE if the SCI output buffer was locked by another process or
- * not all the bytes requested to send could be transfered.
+ * output buffer.\n
+ * FAILURE if the SCI output buffer was locked by another process or
+ * not all the bytes requested to send could be transfered.
*/
-int8_t rpp_sci_write_nb(uint32_t amount, uint8_t* data);
+int8_t rpp_sci_write_nb(uint32_t amount, uint8_t *data);
+/**
+ * Flush incomming or outgoing buffers.
+ *
+ * The function is thread safe.
+ *
+ * This is a blocking call.
+ *
+ * This will block if another process is writing to or reading data from the
+ * selected buffer to flush until this process releases the lock on the buffer.
+ *
+ * @param[in] buff TRUE to flush incomming buffer.
+ * FALSE to flush outgoing buffer.
+ *
+ * @return SUCCESS if flushed buffer had some data.\n
+ * FAILURE if flushed buffer had no data left.
+ */
+int8_t rpp_sci_flush(boolean_t buff);
+
+
+
+/**
+ * C style printk using RPP SCI module.
+ *
+ * The function is not thread safe.
+ *
+ * This call is intended to be used from interrupt only.
+ * Function blocks until whole string was sent to the SCI output, therefore
+ * it should be used with care. Frequent usage is for debugging.
+ *
+ * This function will wait until all the bytes are sent to the SCI output.
+ * Implementation uses vsnprintf() from stdio.h using a fixed
+ * MAX_BUFFER_LEN bytes buffer.
+ *
+ * @param[in] format C string that contains a format string that follows the
+ * same specifications as format in printf (see stdio.h's
+ * printf for details).
+ * @param[in] ... (additional arguments) Depending on the format string,
+ * the function may expect a sequence of additional
+ * arguments, each containing a value to be used to replace
+ * a format specifier in the format string (or a pointer to
+ * a storage location).
+ * There should be at least as many of these arguments as
+ * the number of values specified in the format specifiers.
+ * Additional arguments are ignored by the function.
+ *
+ * @return SUCCESS when string was sent
+ * FAILURE when an error occurred
+ */
+int32_t rpp_sci_printk(const char *format, ...);
+
+
+/**
+ * C style printk using RPP SCI module.
+ *
+ * The function is not thread safe.
+ *
+ * This call is intended to be used from interrupt only.
+ * Function tries to append string to the output buffer.
+ *
+ * Implementation uses vsnprintf() from stdio.h using a fixed
+ * MAX_BUFFER_LEN bytes buffer.
+ *
+ * @param[in] format C string that contains a format string that follows the
+ * same specifications as format in printf (see stdio.h's
+ * printf for details).
+ * @param[in] ... (additional arguments) Depending on the format string,
+ * the function may expect a sequence of additional
+ * arguments, each containing a value to be used to replace
+ * a format specifier in the format string (or a pointer to
+ * a storage location).
+ * There should be at least as many of these arguments as
+ * the number of values specified in the format specifiers.
+ * Additional arguments are ignored by the function.
+ *
+ * @return The number of characters that have been written to the buffer.
+ * If an error occurs, a negative number is returned.
+ */
+int32_t rpp_sci_printkb(const char *format, ...);
// C style API
/**
* C style printf using RPP SCI module.
- * Implementation uses vsnprintf() from stdio.h using a fixed 128 bytes buffer.
+ *
+ * The function is thread safe.
+ *
+ * This is a blocking call.
+ *
+ * This function will wait until all the bytes are sent to the SCI output
+ * buffer. Implementation uses vsnprintf() from stdio.h using a fixed
+ * MAX_BUFFER_LEN bytes buffer.
*
* @param[in] format C string that contains a format string that follows the
* same specifications as format in printf (see stdio.h's
* completely written.
*/
int32_t rpp_sci_printf(const char *format, ...);
-//int8_t rpp_sci_putc(uint8_t ch);
-//int16_t rpp_sci_getc();
-#endif /* __RPP_SCI_H */
+/**
+ * C style vprintf using RPP SCI module.
+ *
+ * The function is thread safe.
+ *
+ * This is a blocking call.
+ *
+ * This function will wait until all the bytes are sent to the SCI output
+ * buffer. Implementation uses vsnprintf() from stdio.h using a fixed
+ * MAX_BUFFER_LEN bytes buffer.
+ *
+ * @param[in] format C string that contains a format string that follows the
+ * same specifications as format in printf (see stdio.h's
+ * printf for details).
+ * @param[in] args (additional arguments) Depending on the format string,
+ * the function may expect a sequence of additional
+ * arguments, each containing a value to be used to replace
+ * a format specifier in the format string (or a pointer to
+ * a storage location).
+ * There should be at least as many of these arguments as
+ * the number of values specified in the format specifiers.
+ * Additional arguments are ignored by the function.
+ *
+ * @return The number of characters that would have been written if the buffer
+ * had been sufficiently large, not counting the terminating null
+ * character. If an encoding error occurs, a negative number is
+ * returned. Please note that only when this returned value is
+ * non-negative and less than the buffer size, the string has been
+ * completely written.
+ */
+int32_t rpp_sci_vprintf(const char *format, va_list args);
+
+
+/**
+ * C style putc (put character) using RPP SCI module.
+ *
+ * The function is not thread safe.
+ *
+ * This is a blocking call.
+ *
+ * This function will wait until the given byte is put into SCI output buffer if
+ * it is full.
+ *
+ * @param[in] byte Byte to put into SCI output buffer.
+ *
+ * @return SUCCESS when the given byte could be transfered.
+ */
+int8_t rpp_sci_putc(uint8_t byte);
+
+
+/**
+ * C style getc (get character) using RPP SCI module.
+ *
+ * The function is not thread safe.
+ *
+ * This is a blocking call.
+ *
+ * This function will wait until a byte is available in the SCI input buffer if
+ * it is empty.
+ *
+ * @note The byte is promoted to an int16_t in order to accommodate for
+ * FAILURE/EOF/-1 if an error occurs. This is in order to conform with C getc,
+ * but should never happen in current implementation because this is a blocking
+ * call and will always wait for one byte to be available in the input buffer.
+ * Nevertheless, if user compiles it's programs against POSIX FreeRTOS for
+ * Simulation then the compatibility layers makes it possible to return EOF so
+ * user expecting to run in Simulation should always check for FAILURE.
+ *
+ * @return [0-255] The byte read from the SCI input buffer.\n
+ * FAILURE If and error occurred.
+ */
+int16_t rpp_sci_getc();
+
+
+
+#endif /* __RPP_SCI_H */
projects / pes-rpp / rpp-lib.git / blobdiff