2 * Serial Communication Interface RPP API header file.
6 * @copyright Copyright (C) 2013 Czech Technical University in Prague
8 * @author Carlos Jenkins <carlos@jenkins.co.cr>
16 * SCI module initialization.
18 * Call this method before using this module.
20 * @return SUCCESS if initialization successful.\n
21 * FAILURE if module already initialized.
23 int8_t rpp_sci_init();
29 * Configure the SCI module.
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.
34 * @return TRUE if baud rate is a known value.\n
37 boolean_t rpp_sci_setup(uint32_t baud);
42 * Number of bytes available on input buffer.
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.
47 * @return [0-MAX_BUFFER_LEN] The number of bytes available to read.
49 uint16_t rpp_sci_available();
53 * Read n number of bytes from input buffer.
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.
58 * This is a blocking call.
60 * Will block until requested amount of data is available.
62 * @param[in] amount Amount/number of bytes to read.
63 * @param[out] buffer Pointer to buffer where to store data.
65 * @return SUCCESS when all data was transfered.
67 int8_t rpp_sci_read(uint32_t amount, uint8_t* buffer);
71 * Read n number of bytes from input buffer if possible.
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.
76 * This is a non-blocking call.
78 * This function will only succeed if requested amount of data is present
79 * already in the input buffer.
81 * @param[in] amount Amount/number of bytes to read.
82 * @param[out] buffer Pointer to buffer where to store data.
84 * @return SUCCESS if the requested amount of data could be transfered.\n
85 * FAILURE if requested amount of data is unavailable.
87 int8_t rpp_sci_read_nb(uint32_t amount, uint8_t* buffer);
91 * Write n number of bytes to the output buffer.
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
97 * This is a blocking call.
99 * This will block if SCI output buffer is full waiting until some space is
102 * @param[in] amount Amount/number of bytes to send.
103 * @param[in] data Pointer to buffer from where to read data.
105 * @return SUCCESS when all data was transfered.
107 int8_t rpp_sci_write(uint32_t amount, uint8_t* data);
111 * Write n number of bytes to the output buffer if possible.
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
117 * This is a non-blocking call.
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.
124 * @param[in] amount Amount/number of bytes to send.
125 * @param[in] data Pointer to buffer from where to read data.
127 * @return SUCCESS if the requested amount of data could be transfered to the
129 * FAILURE if the SCI output buffer was locked by another process or
130 * not all the bytes requested to send could be transfered.
132 int8_t rpp_sci_write_nb(uint32_t amount, uint8_t* data);
136 * Flush incomming or outgoing buffers.
138 * This is a blocking call.
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.
143 * @param[in] buff TRUE to flush incomming buffer.
144 * FALSE to flush outgoing buffer.
146 * @return SUCCESS if flushed buffer had some data.\n
147 * FAILURE if flushed buffer had no data left.
149 int8_t rpp_sci_flush(boolean_t buff);
154 * C style printk using RPP SCI module.
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.
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.
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.
176 * @return SUCCESS when string was sent
177 * FAILURE when an error occurred
179 int32_t rpp_sci_printk(const char* format, ...);
183 * C style printk using RPP SCI module.
185 * This call is intended to be used from interrupt only.
186 * Function tries to append string to the output buffer.
188 * Implementation uses vsnprintf() from stdio.h using a fixed
189 * MAX_BUFFER_LEN bytes buffer.
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.
203 * @return The number of characters that have been written to the buffer.
204 * If an error occurs, a negative number is returned.
206 int32_t rpp_sci_printkb(const char* format, ...);
211 * C style printf using RPP SCI module.
213 * This is a blocking call.
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.
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.
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.
238 int32_t rpp_sci_printf(const char* format, ...);
242 * C style vprintf using RPP SCI module.
244 * This is a blocking call.
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.
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.
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.
269 int32_t rpp_sci_vprintf(const char* format, va_list args);
273 * C style putc (put character) using RPP SCI module.
275 * This is a blocking call.
277 * This function will wait until the given byte is put into SCI output buffer if
280 * @param[in] byte Byte to put into SCI output buffer.
282 * @return SUCCESS when the given byte could be transfered.
284 int8_t rpp_sci_putc(uint8_t byte);
288 * C style getc (get character) using RPP SCI module.
290 * This is a blocking call.
292 * This function will wait until a byte is available in the SCI input buffer if
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.
303 * @return [0-255] The byte read from the SCI input buffer.\n
304 * FAILURE If and error occurred.
306 int16_t rpp_sci_getc();
310 #endif /* __RPP_SCI_H */