You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ma...@apache.org on 2016/08/24 18:56:13 UTC
[12/14] incubator-mynewt-core git commit: uart driver;
try to make function comments doxygen friendly.
uart driver; try to make function comments doxygen friendly.
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/commit/11eb7f5e
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/tree/11eb7f5e
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/diff/11eb7f5e
Branch: refs/heads/sterly_refactor
Commit: 11eb7f5ee79e12d381912680736e03d38d1d6ef9
Parents: 6fe5810
Author: Marko Kiiskila <ma...@runtime.io>
Authored: Wed Aug 24 10:54:38 2016 -0700
Committer: Marko Kiiskila <ma...@runtime.io>
Committed: Wed Aug 24 10:54:38 2016 -0700
----------------------------------------------------------------------
drivers/uart/include/uart/uart.h | 40 +++++++++++++++++++++++++++++++++--
1 file changed, 38 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/11eb7f5e/drivers/uart/include/uart/uart.h
----------------------------------------------------------------------
diff --git a/drivers/uart/include/uart/uart.h b/drivers/uart/include/uart/uart.h
index 4be0d22..e889722 100644
--- a/drivers/uart/include/uart/uart.h
+++ b/drivers/uart/include/uart/uart.h
@@ -27,8 +27,12 @@ struct uart_dev;
/*
* Function prototype for UART driver to ask for more data to send.
- * Returns -1 if no more data is available for TX.
* Driver must call this with interrupts disabled.
+ *
+ * @param arg This is uc_cb_arg passed in uart_conf in
+ * os_dev_open().
+ *
+ * @return Byte value to send next, -1 if no more data to send.
*/
typedef int (*uart_tx_char)(void *arg);
@@ -37,13 +41,24 @@ typedef int (*uart_tx_char)(void *arg);
* complete. This should be called when transmission of last byte is
* finished.
* Driver must call this with interrupts disabled.
+ *
+ * @param arg This is uc_cb_arg passed in uart_conf in
+ * os_dev_open().
*/
typedef void (*uart_tx_done)(void *arg);
/*
* Function prototype for UART driver to report incoming byte of data.
- * Returns -1 if data was dropped.
* Driver must call this with interrupts disabled.
+ *
+ * @param arg This is uc_cb_arg passed in uart_conf in
+ * os_dev_open().
+ * @param byte Received byte
+ *
+ * @return 0 on success; -1 if data could not be received.
+ * Note that returning -1 triggers flow control (if
+ * configured), and user must call uart_start_rx() to
+ * start receiving more data again.
*/
typedef int (*uart_rx_char)(void *arg, uint8_t byte);
@@ -59,6 +74,9 @@ struct uart_dev {
void *ud_priv;
};
+/*
+ * ***Note that these enum values must match what hw/hal/hal_uart.h***
+ */
enum uart_parity {
UART_PARITY_NONE = 0, /* no parity */
UART_PARITY_ODD = 1, /* odd parity bit */
@@ -82,18 +100,36 @@ struct uart_conf {
void *uc_cb_arg;
};
+/*
+ * Tell driver that more data has been queued, and that the driver should
+ * start asking for it.
+ *
+ * @param dev Uart device in question
+ */
static inline void
uart_start_tx(struct uart_dev *dev)
{
dev->ud_funcs.uf_start_tx(dev);
}
+/*
+ * Tell driver that previous report on RX buffer shortage is now done,
+ * and that app is ready to receive more data.
+ *
+ * @param dev Uart device in question
+ */
static inline void
uart_start_rx(struct uart_dev *dev)
{
dev->ud_funcs.uf_start_rx(dev);
}
+/*
+ * Blocking transmit. ***Note that this should only be used with console.
+ * And only when MCU is about to restart, to write final log messages***
+ *
+ * @param dev Uart device in question
+ */
static inline void
uart_blocking_tx(struct uart_dev *dev, uint8_t byte)
{