From 257ee47245f4a83166c3475b24537c4fcde1365f Mon Sep 17 00:00:00 2001 From: Sethu Chandan Jangala Date: Thu, 16 Aug 2012 17:32:28 +0530 Subject: [PATCH 1/3] Seperated documents for each module --- module_uart_fast_rx/doc/Makefile | 10 ++ {doc => module_uart_fast_rx/doc}/fast.rst | 1 - module_uart_fast_rx/doc/index.rst | 10 ++ {doc => module_uart_fast_rx/doc}/summary.rst | 10 +- module_uart_fast_tx/doc/Makefile | 10 ++ module_uart_fast_tx/doc/fast.rst | 53 +++++++++ module_uart_fast_tx/doc/index.rst | 10 ++ module_uart_fast_tx/doc/summary.rst | 51 +++++++++ {doc => module_uart_rx/doc}/Makefile | 4 +- {doc => module_uart_rx/doc}/generic.rst | 28 +---- {doc => module_uart_rx/doc}/index.rst | 1 - module_uart_rx/doc/summary.rst | 45 ++++++++ module_uart_tx/doc/Makefile | 10 ++ module_uart_tx/doc/generic.rst | 114 +++++++++++++++++++ module_uart_tx/doc/index.rst | 10 ++ module_uart_tx/doc/summary.rst | 45 ++++++++ 16 files changed, 372 insertions(+), 40 deletions(-) create mode 100644 module_uart_fast_rx/doc/Makefile rename {doc => module_uart_fast_rx/doc}/fast.rst (98%) create mode 100644 module_uart_fast_rx/doc/index.rst rename {doc => module_uart_fast_rx/doc}/summary.rst (73%) create mode 100644 module_uart_fast_tx/doc/Makefile create mode 100644 module_uart_fast_tx/doc/fast.rst create mode 100644 module_uart_fast_tx/doc/index.rst create mode 100644 module_uart_fast_tx/doc/summary.rst rename {doc => module_uart_rx/doc}/Makefile (80%) rename {doc => module_uart_rx/doc}/generic.rst (77%) rename {doc => module_uart_rx/doc}/index.rst (90%) create mode 100644 module_uart_rx/doc/summary.rst create mode 100644 module_uart_tx/doc/Makefile create mode 100644 module_uart_tx/doc/generic.rst create mode 100644 module_uart_tx/doc/index.rst create mode 100644 module_uart_tx/doc/summary.rst diff --git a/module_uart_fast_rx/doc/Makefile b/module_uart_fast_rx/doc/Makefile new file mode 100644 index 0000000..ba9581f --- /dev/null +++ b/module_uart_fast_rx/doc/Makefile @@ -0,0 +1,10 @@ +REPO=../../sc_uart/module_fast_rx +SPHINX_PROJECT_NAME=UART +VERSION=0v1 +DOXYGEN_DIRS= $(REPO)/module_uart_fast_rx \ +SOURCE_INCLUDE_DIRS=$(REPO) +XDOC_DIR ?= ../../xdoc +include $(XDOC_DIR)/Makefile.inc + +all: html pdf + @if [ ! -d $(REPO)_gh_pages ] ; then echo '**** no gh_pages checked out ****'; exit 0; else cp -r _build/html/* $(REPO)_gh_pages/; cp -r _build/html/.doctrees $(REPO)_gh_pages/; echo 'HTML files copied to $(REPO)_gh_pages'; echo 'Now go to $(REPO)_gh_pages, add, commit, and push to publish the documentation'; fi diff --git a/doc/fast.rst b/module_uart_fast_rx/doc/fast.rst similarity index 98% rename from doc/fast.rst rename to module_uart_fast_rx/doc/fast.rst index 6b131e4..78de1d6 100644 --- a/doc/fast.rst +++ b/module_uart_fast_rx/doc/fast.rst @@ -22,7 +22,6 @@ API +++ .. doxygenfunction:: uart_rx_fast -.. doxygenfunction:: uart_tx_fast Example programs ++++++++++++++++ diff --git a/module_uart_fast_rx/doc/index.rst b/module_uart_fast_rx/doc/index.rst new file mode 100644 index 0000000..76d2934 --- /dev/null +++ b/module_uart_fast_rx/doc/index.rst @@ -0,0 +1,10 @@ +XCORE STAND ALONE UART COMPONENTS +================================= + +.. toctree:: + + summary.rst + fast.rst + + + diff --git a/doc/summary.rst b/module_uart_fast_rx/doc/summary.rst similarity index 73% rename from doc/summary.rst rename to module_uart_fast_rx/doc/summary.rst index d3b40a4..29153e8 100644 --- a/doc/summary.rst +++ b/module_uart_fast_rx/doc/summary.rst @@ -22,18 +22,12 @@ The most important characteristics are the following: UART Implementation Alternatives -------------------------------- -Two UART components are included in this repository, each consisting of two modules (one for each of RX and TX), summarised below: +UART components are included in this repository RX, summarised below: +--------------+---------------------+------------+--------+---------------+---------------+-------------+ | Component | modules | Data rate | Memory | Parity | Bits Per Byte | Stop Bits | +--------------+---------------------+------------+--------+---------------+---------------+-------------+ -| Generic UART | module_uart_tx | to 115.2K | ~1K | Even/Odd/None | 5/6/7/8 | 1 or 2 | -| |---------------------+------------+--------+---------------+---------------+-------------+ -| | module_uart_rx | to 115.2K | ~1K | Even/Odd/None | 5/6/7/8 | 1 or 2 | -+--------------+---------------------+------------+--------+---------------+---------------+-------------+ -| Simple UART | module_uart_fast_tx | 10 Mbaud | 0.25K | None | 8 | 1 | -| |---------------------+------------+--------+---------------+---------------+-------------+ -| | module_uart_fast_tx | 10 Mbaud | 0.25K | None | 8 | 1 | +| Simple UART | module_uart_fast_rx | 10 Mbaud | 0.25K | None | 8 | 1 | +--------------+---------------------+------------+--------+---------------+---------------+-------------+ diff --git a/module_uart_fast_tx/doc/Makefile b/module_uart_fast_tx/doc/Makefile new file mode 100644 index 0000000..2e641ea --- /dev/null +++ b/module_uart_fast_tx/doc/Makefile @@ -0,0 +1,10 @@ +REPO=../../sc_uart/module_uart_fast_tx +SPHINX_PROJECT_NAME=UART +VERSION=0v1 +DOXYGEN_DIRS=$(REPO)/module_uart_fast_tx +SOURCE_INCLUDE_DIRS=$(REPO) +XDOC_DIR ?= ../../xdoc +include $(XDOC_DIR)/Makefile.inc + +all: html pdf + @if [ ! -d $(REPO)_gh_pages ] ; then echo '**** no gh_pages checked out ****'; exit 0; else cp -r _build/html/* $(REPO)_gh_pages/; cp -r _build/html/.doctrees $(REPO)_gh_pages/; echo 'HTML files copied to $(REPO)_gh_pages'; echo 'Now go to $(REPO)_gh_pages, add, commit, and push to publish the documentation'; fi diff --git a/module_uart_fast_tx/doc/fast.rst b/module_uart_fast_tx/doc/fast.rst new file mode 100644 index 0000000..df389e0 --- /dev/null +++ b/module_uart_fast_tx/doc/fast.rst @@ -0,0 +1,53 @@ +Simple UART +=========== + +The intention of this module is to implement high speed uart, at the expense of threads and 1-bit ports. Other modules provide lower-speed uarts +that are thread-efficient, or that may use fewer 1-bit ports. This module will support a 10 Mbaud rate with 100 MIPS threads, and correspondingly less +with lower MIPS per thread. + +Note: the compiler inserts a spurious ZEXT and SETC in two places which makes 10 Mbit fail with 83 MIPS threads. + +Hardware Platforms +++++++++++++++++++ + +This UART is supported by all the hardware platforms from XMOS having suitable IO such as XC-1,XC-1A,XC-2,XK-1,etc and can be run on any XS1-L or XS1-G series devices. + +The example is prepared to run on teh XK-1 but can be easily modified for other boards. However note that a 500 MHz core clock is expected so when running on G4 devices +the baud rate should be reduced until it works, which can be done by altering the last "clocks" argument to the call to uart_tx_fast and uart_rx_fast in app_uart_fast/src/main.xc. + +Programming Guide ++++++++++++++++++ + +API ++++ + +.. doxygenfunction:: uart_tx_fast + +Example programs +++++++++++++++++ + +Declare ports (and clock blocks if you do not want to run the ports of the +reference clock): + +.. literalinclude:: app_uart_fast/src/main.xc + :start-after: //:: Port declarations + :end-before: //:: + +A function that produces data (just bytes 0..255 in this example) + +.. literalinclude:: app_uart_fast/src/main.xc + :start-after: //:: Producer function + :end-before: //:: + +A function that consumes data (and in this example throws it away) + +.. literalinclude:: app_uart_fast/src/main.xc + :start-after: //:: Consumer function + :end-before: //:: + +And a main par that starts the threads: + +.. literalinclude:: app_uart_fast/src/main.xc + :start-after: //:: Main program + :end-before: //:: + diff --git a/module_uart_fast_tx/doc/index.rst b/module_uart_fast_tx/doc/index.rst new file mode 100644 index 0000000..76d2934 --- /dev/null +++ b/module_uart_fast_tx/doc/index.rst @@ -0,0 +1,10 @@ +XCORE STAND ALONE UART COMPONENTS +================================= + +.. toctree:: + + summary.rst + fast.rst + + + diff --git a/module_uart_fast_tx/doc/summary.rst b/module_uart_fast_tx/doc/summary.rst new file mode 100644 index 0000000..18eb3e3 --- /dev/null +++ b/module_uart_fast_tx/doc/summary.rst @@ -0,0 +1,51 @@ +UART Overview +============= + +UART is one of the most basic asynchronous communication protocols. Also +known as RS-232, it transmits bits serially at a mutually agreed speed +without providing a clock. The speed is known as the *baud* rate, and is +typically something like 9600 baud, 115200 baud, or 10 Mbaud. + +The most important characteristics are the following: + +* The baud rate. + +* The number of start bits, typically 1, sometimes 1.5 + +* The number of data bits, typically 7 or 8 + +* Whether a parity bit is present, and if so whether it is even parity or + odd parity + +* The number of stop bits, typically 1, sometimes 2. + +UART Implementation Alternatives +-------------------------------- + +UART components are included in this repository TX, summarised below: + ++--------------+---------------------+------------+--------+---------------+---------------+-------------+ +| Component | modules | Data rate | Memory | Parity | Bits Per Byte | Stop Bits | ++--------------+---------------------+------------+--------+---------------+---------------+-------------+ +| Simple UART | module_uart_fast_tx | 10 Mbaud | 0.25K | None | 8 | 1 | ++--------------+---------------------+------------+--------+---------------+---------------+-------------+ + + +Simple UART ++++++++++++ + +This module is a much simpler implementation of a UART that will require a whole thread for TX and deliver up to 10 Mbaud. RX could be called as a function, and hence share a thread with other functionality although this will affect the TX baud rate achieved,and this usage is not shown. + +It is fixed to 8 bits, a single start bit, no parity, and a single stop bit. All of those parameters could be changed by altering the source code. + +*The baud rate is parameterisable, but has to be a whole division of 100 MHz.* This may make it unsuitable for some applications requiring a very particular baud rate. + +Note that the code is easy to understand; it comprises the example from the +XC programming manual. + +Other Uarts ++++++++++++ + +For an implementation of multi-uart suitable for applications where more than one uart is required, the sc_multi_uart component may be a better choice. + + diff --git a/doc/Makefile b/module_uart_rx/doc/Makefile similarity index 80% rename from doc/Makefile rename to module_uart_rx/doc/Makefile index 1c7f711..87eebca 100644 --- a/doc/Makefile +++ b/module_uart_rx/doc/Makefile @@ -2,9 +2,7 @@ REPO=../../sc_uart SPHINX_PROJECT_NAME=UART VERSION=0v1 DOXYGEN_DIRS=$(REPO)/module_uart_rx \ - $(REPO)/module_uart_tx \ - $(REPO)/module_uart_fast_rx \ - $(REPO)/module_uart_fast_tx + SOURCE_INCLUDE_DIRS=$(REPO) XDOC_DIR ?= ../../xdoc include $(XDOC_DIR)/Makefile.inc diff --git a/doc/generic.rst b/module_uart_rx/doc/generic.rst similarity index 77% rename from doc/generic.rst rename to module_uart_rx/doc/generic.rst index 2aee29d..5eac535 100644 --- a/doc/generic.rst +++ b/module_uart_rx/doc/generic.rst @@ -1,10 +1,8 @@ Generic UART ============ -This UART has two modules, one for RX and one for TX each of which uses one thread and is connected via channel to another thread using the UART Client API . +This UART has module for RX which uses one thread and is connected via channel to another thread using the UART Client API . -The thread for the UART TX component receives data from the client via a buffer (configurable between 1 and 64 bytes). A full buffer will block the client. - The thread for the UART RX component receives data from external into the RX buffer (configurable between 1 and 64 bytes) which is read by the client using channel. An empty RX buffer will block the client. @@ -23,14 +21,6 @@ Key Files +-------------------------------------+-----------------------------------------------+ | File | Description | +-------------------------------------+-----------------------------------------------+ -| module_uart_tx/src/uart_tx.h |Client API header file for Generic UART TX | -+-------------------------------------+-----------------------------------------------+ -| module_uart_tx/src/uart_tx.xc | Client API implementation for Generic UART TX | -+-------------------------------------+-----------------------------------------------+ -| module_uart_tx/src/uart_tx_impl.h | UART TX Server Header File | -+-------------------------------------+-----------------------------------------------+ -| module_uart_tx/src/uart_tx_impl.xc | UART TX Server implementation | -+-------------------------------------+-----------------------------------------------+ | module_uart_rx/src/uart_rx.h | Client API header file for Generic UART RX | +-------------------------------------+-----------------------------------------------+ | module_uart_rx/src/uart_rx.xc | Client API implementation for Generic UART RX | @@ -76,22 +66,6 @@ app_uart_back2back It will receive via the RX component and echo via TX component. -UART TX component Overview -++++++++++++++++++++++++++ - -The UART TX component is started using the uart_tx() function, which causes the TX server (called "_impl" in the code) to run in a while(1) loop until it receives and instruction to shut down via the channel from the client. Additionally a set of client functions are provided to transmit a byte and to alter the baud rate, parity, bits per byte and stop bit settings. Any such action except transmitting a byte causes the TX server to terminate and then be restarted with the new settings. Any data in the TX buffer is preserved and then sent with the new settings. - -UART TX API -+++++++++++ - -.. doxygenfunction:: uart_tx -.. doxygenfunction:: uart_tx_send_byte -.. doxygenfunction:: uart_tx_set_baud_rate -.. doxygenfunction:: uart_tx_set_parity -.. doxygenfunction:: uart_tx_set_stop_bits -.. doxygenfunction:: uart_tx_set_bits_per_byte - - UART RX component Overview ++++++++++++++++++++++++++ diff --git a/doc/index.rst b/module_uart_rx/doc/index.rst similarity index 90% rename from doc/index.rst rename to module_uart_rx/doc/index.rst index bcd5f19..772d18c 100644 --- a/doc/index.rst +++ b/module_uart_rx/doc/index.rst @@ -5,7 +5,6 @@ XCORE STAND ALONE UART COMPONENTS summary.rst generic.rst - fast.rst diff --git a/module_uart_rx/doc/summary.rst b/module_uart_rx/doc/summary.rst new file mode 100644 index 0000000..93924b1 --- /dev/null +++ b/module_uart_rx/doc/summary.rst @@ -0,0 +1,45 @@ +UART Overview +============= + +UART is one of the most basic asynchronous communication protocols. Also +known as RS-232, it transmits bits serially at a mutually agreed speed +without providing a clock. The speed is known as the *baud* rate, and is +typically something like 9600 baud, 115200 baud, or 10 Mbaud. + +The most important characteristics are the following: + +* The baud rate. + +* The number of start bits, typically 1, sometimes 1.5 + +* The number of data bits, typically 7 or 8 + +* Whether a parity bit is present, and if so whether it is even parity or + odd parity + +* The number of stop bits, typically 1, sometimes 2. + +UART Implementation Alternatives +-------------------------------- + +Two UART components are included in this repository, each consisting of two modules (one for each of RX and TX), summarised below: + ++--------------+---------------------+------------+--------+---------------+---------------+-------------+ +| Component | modules | Data rate | Memory | Parity | Bits Per Byte | Stop Bits | ++--------------+---------------------+------------+--------+---------------+---------------+-------------+ +| Generic UART | module_uart_tx | to 115.2K | ~1K | Even/Odd/None | 5/6/7/8 | 1 or 2 | ++--------------+---------------------+------------+--------+---------------+---------------+-------------+ + + +Generic UART +++++++++++++ + +This module is completely parameterisable at run time and will require a thread for each of RX and TX. + + +Other Uarts ++++++++++++ + +For an implementation of multi-uart suitable for applications where more than one uart is required, the sc_multi_uart component may be a better choice. + + diff --git a/module_uart_tx/doc/Makefile b/module_uart_tx/doc/Makefile new file mode 100644 index 0000000..291a74d --- /dev/null +++ b/module_uart_tx/doc/Makefile @@ -0,0 +1,10 @@ +REPO=../../sc_uart +SPHINX_PROJECT_NAME=UART +VERSION=0v1 +DOXYGEN_DIRS=$(REPO)/module_uart_tx \ +SOURCE_INCLUDE_DIRS=$(REPO) +XDOC_DIR ?= ../../xdoc +include $(XDOC_DIR)/Makefile.inc + +all: html pdf + @if [ ! -d $(REPO)_gh_pages ] ; then echo '**** no gh_pages checked out ****'; exit 0; else cp -r _build/html/* $(REPO)_gh_pages/; cp -r _build/html/.doctrees $(REPO)_gh_pages/; echo 'HTML files copied to $(REPO)_gh_pages'; echo 'Now go to $(REPO)_gh_pages, add, commit, and push to publish the documentation'; fi diff --git a/module_uart_tx/doc/generic.rst b/module_uart_tx/doc/generic.rst new file mode 100644 index 0000000..2fe2ad2 --- /dev/null +++ b/module_uart_tx/doc/generic.rst @@ -0,0 +1,114 @@ +Generic UART +============ + +This UART has module for TX which uses one thread and is connected via channel to another thread using the UART Client API . + +The thread for the UART TX component receives data from the client via a buffer (configurable between 1 and 64 bytes). A full buffer will block the client. + + +Hardware Platforms +------------------ + +This UART is supported by all the hardware platforms from XMOS having suitable IO such as XC-1,XC-1A,XC-2,XK-1,etc and can be run on any XS1-L or XS1-G series devices. + + +Programming Guide +----------------- + +Key Files ++++++++++ + ++-------------------------------------+-----------------------------------------------+ +| File | Description | ++-------------------------------------+-----------------------------------------------+ +| module_uart_tx/src/uart_tx.h |Client API header file for Generic UART TX | ++-------------------------------------+-----------------------------------------------+ +| module_uart_tx/src/uart_tx.xc | Client API implementation for Generic UART TX | ++-------------------------------------+-----------------------------------------------+ +| module_uart_tx/src/uart_tx_impl.h | UART TX Server Header File | ++-------------------------------------+-----------------------------------------------+ +| module_uart_tx/src/uart_tx_impl.xc | UART TX Server implementation | ++-------------------------------------+-----------------------------------------------+ + + +Required Repositories ++++++++++++++++++++++ + +* xcommon git\@github.com:xcore/xcommon.git + +Resource Usage +-------------- + +The following table details the resource usage of the component. + + +-----------------+---------+ + | Resource | Usage | + +=================+=========+ + | Code Memory | 2110 | + +-----------------+---------+ + | Ports | 2 x 1b | + +-----------------+---------+ + | ChannelEnds | 2 | + +-----------------+---------+ + + +Demo Application +----------------- + +The UART functionality is demonstrated using the app_uart_back2back. This has been rpepared to run on an XK-1 board, but can easily be ported to other development boards with small modificatiosn to the code. To prepare the XK-1 board to run this app, simply connect a jumper such that ports 1A and 1B are connected (e.g. connect X0D1 and X0D0 pins on the GPIO header). Refer to the XK-1 Hardware Manual for pni positions. + +The app can then be built and run. + +It will send the full set of characters from the UART TX, receive them on UART RX and then print them out in batches of 10 characters. + + +app_uart_back2back +++++++++++++++++++ + +It will receive via the RX component and echo via TX component. + +UART TX component Overview +++++++++++++++++++++++++++ + +The UART TX component is started using the uart_tx() function, which causes the TX server (called "_impl" in the code) to run in a while(1) loop until it receives and instruction to shut down via the channel from the client. Additionally a set of client functions are provided to transmit a byte and to alter the baud rate, parity, bits per byte and stop bit settings. Any such action except transmitting a byte causes the TX server to terminate and then be restarted with the new settings. Any data in the TX buffer is preserved and then sent with the new settings. + +UART TX API ++++++++++++ + +.. doxygenfunction:: uart_tx +.. doxygenfunction:: uart_tx_send_byte +.. doxygenfunction:: uart_tx_set_baud_rate +.. doxygenfunction:: uart_tx_set_parity +.. doxygenfunction:: uart_tx_set_stop_bits +.. doxygenfunction:: uart_tx_set_bits_per_byte + + +Verification +------------ + +An application app_uart_test is provided to run in XSIM using the Loopback Plugin DLL (see Tools User Guide for details) that validates the various combinations of parity, stop bit, bits-per-byte and baud rate settings. It will send data out via the UART TX component using single bit port and receive via UART RX component from another single bit port. It will check that the data matches. + +The testbench is run using a python script: regression_script_UART.py. The test suites are executed as follows (after having built the application with the makefile provided: + + +--------------------------+---------------------------------------------------+----------------------------------------------------------------+ + | Testbench | Command | Description | + +==========================+===================================================+===============================================================+ + | | |This test will confirm that buffer size is enough and data from | + | check buffering | -check_buffering |TX buffer to RX buffer passes correctly | + +--------------------------+---------------------------------------------------+----------------------------------------------------------------+ + | | -runtime_parameter_change |This test will confirm UART module supports change in parameter | + | runtime parameter change | |during runtime such as baud-rate,bits per byte, parity, stopbit | + +--------------------------+---------------------------------------------------+----------------------------------------------------------------+ + | | -test_parity |This test will confirm UART module discards data in case of | + | Parity test | |mismatch in change in parity | + +--------------------------+---------------------------------------------------+----------------------------------------------------------------+ + | single test |script.py -buad_rate -bitsperbyte |This test will confirm UART module discards data in case of | + | | -parity -stopbit |mismatch in change in parity | + +--------------------------+---------------------------------------------------+----------------------------------------------------------------+ + | | | This will take all possible combinations of baud-rate,bits | + | regression test | |per byte,parity and no. of stop bits.it will use testlist.txt | + +--------------------------+---------------------------------------------------+----------------------------------------------------------------+ + +The output is dumped to log.txt. This file should be manually removed, if it exists, before re-running. + + diff --git a/module_uart_tx/doc/index.rst b/module_uart_tx/doc/index.rst new file mode 100644 index 0000000..772d18c --- /dev/null +++ b/module_uart_tx/doc/index.rst @@ -0,0 +1,10 @@ +XCORE STAND ALONE UART COMPONENTS +================================= + +.. toctree:: + + summary.rst + generic.rst + + + diff --git a/module_uart_tx/doc/summary.rst b/module_uart_tx/doc/summary.rst new file mode 100644 index 0000000..fad2fb1 --- /dev/null +++ b/module_uart_tx/doc/summary.rst @@ -0,0 +1,45 @@ +UART Overview +============= + +UART is one of the most basic asynchronous communication protocols. Also +known as RS-232, it transmits bits serially at a mutually agreed speed +without providing a clock. The speed is known as the *baud* rate, and is +typically something like 9600 baud, 115200 baud, or 10 Mbaud. + +The most important characteristics are the following: + +* The baud rate. + +* The number of start bits, typically 1, sometimes 1.5 + +* The number of data bits, typically 7 or 8 + +* Whether a parity bit is present, and if so whether it is even parity or + odd parity + +* The number of stop bits, typically 1, sometimes 2. + +UART Implementation Alternatives +-------------------------------- + +UART component included in this repository consisting of module for TX, summarised below: + ++--------------+---------------------+------------+--------+---------------+---------------+-------------+ +| Component | modules | Data rate | Memory | Parity | Bits Per Byte | Stop Bits | ++--------------+---------------------+------------+--------+---------------+---------------+-------------+ +| Generic UART | module_uart_tx | to 115.2K | ~1K | Even/Odd/None | 5/6/7/8 | 1 or 2 | ++--------------+---------------------+------------+--------+---------------+---------------+-------------+ + + +Generic UART +++++++++++++ + +This module is completely parameterisable at run time and will require a thread for TX. + + +Other Uarts ++++++++++++ + +For an implementation of multi-uart suitable for applications where more than one uart is required, the sc_multi_uart component may be a better choice. + + From 31a4d74bae81d03d2a0d3588b396331dbe3f0d1d Mon Sep 17 00:00:00 2001 From: Sethu Chandan Jangala Date: Mon, 20 Aug 2012 11:17:09 +0530 Subject: [PATCH 2/3] Refined documents for module_uart_rx and module_uart_tx --- module_uart_rx/doc/Makefile | 2 +- module_uart_rx/doc/generic.rst | 6 +++++- module_uart_rx/doc/index.rst | 13 +++++++------ module_uart_tx/doc/generic.rst | 5 +++-- module_uart_tx/doc/index.rst | 13 +++++++------ 5 files changed, 23 insertions(+), 16 deletions(-) diff --git a/module_uart_rx/doc/Makefile b/module_uart_rx/doc/Makefile index 87eebca..90268f9 100644 --- a/module_uart_rx/doc/Makefile +++ b/module_uart_rx/doc/Makefile @@ -2,7 +2,7 @@ REPO=../../sc_uart SPHINX_PROJECT_NAME=UART VERSION=0v1 DOXYGEN_DIRS=$(REPO)/module_uart_rx \ - + SOURCE_INCLUDE_DIRS=$(REPO) XDOC_DIR ?= ../../xdoc include $(XDOC_DIR)/Makefile.inc diff --git a/module_uart_rx/doc/generic.rst b/module_uart_rx/doc/generic.rst index 5eac535..1121b6c 100644 --- a/module_uart_rx/doc/generic.rst +++ b/module_uart_rx/doc/generic.rst @@ -1,8 +1,10 @@ Generic UART ============ -This UART has module for RX which uses one thread and is connected via channel to another thread using the UART Client API . +This UART has two modules, one for RX and one for TX each of which uses one thread and is connected via channel to another thread using the UART Client API . +The thread for the UART TX component receives data from the client via a buffer (configurable between 1 and 64 bytes). A full buffer will block the client. + The thread for the UART RX component receives data from external into the RX buffer (configurable between 1 and 64 bytes) which is read by the client using channel. An empty RX buffer will block the client. @@ -66,6 +68,7 @@ app_uart_back2back It will receive via the RX component and echo via TX component. + UART RX component Overview ++++++++++++++++++++++++++ @@ -83,6 +86,7 @@ UART RX API .. doxygenfunction:: uart_rx_set_bits_per_byte + Verification ------------ diff --git a/module_uart_rx/doc/index.rst b/module_uart_rx/doc/index.rst index 772d18c..3476d04 100644 --- a/module_uart_rx/doc/index.rst +++ b/module_uart_rx/doc/index.rst @@ -1,10 +1,11 @@ -XCORE STAND ALONE UART COMPONENTS -================================= +I2C Software Component +---------------------- .. toctree:: - summary.rst + Overview.rst + Resource Requirements.rst + Hardware Requirements.rst generic.rst - - - + Programming Guide.rst + \ No newline at end of file diff --git a/module_uart_tx/doc/generic.rst b/module_uart_tx/doc/generic.rst index 2fe2ad2..0af1921 100644 --- a/module_uart_tx/doc/generic.rst +++ b/module_uart_tx/doc/generic.rst @@ -1,10 +1,12 @@ Generic UART ============ -This UART has module for TX which uses one thread and is connected via channel to another thread using the UART Client API . +This UART has two modules, one for RX and one for TX each of which uses one thread and is connected via channel to another thread using the UART Client API . The thread for the UART TX component receives data from the client via a buffer (configurable between 1 and 64 bytes). A full buffer will block the client. +The thread for the UART RX component receives data from external into the RX buffer (configurable between 1 and 64 bytes) which is read by the client using channel. An empty RX buffer will block the client. + Hardware Platforms ------------------ @@ -30,7 +32,6 @@ Key Files | module_uart_tx/src/uart_tx_impl.xc | UART TX Server implementation | +-------------------------------------+-----------------------------------------------+ - Required Repositories +++++++++++++++++++++ diff --git a/module_uart_tx/doc/index.rst b/module_uart_tx/doc/index.rst index 772d18c..3476d04 100644 --- a/module_uart_tx/doc/index.rst +++ b/module_uart_tx/doc/index.rst @@ -1,10 +1,11 @@ -XCORE STAND ALONE UART COMPONENTS -================================= +I2C Software Component +---------------------- .. toctree:: - summary.rst + Overview.rst + Resource Requirements.rst + Hardware Requirements.rst generic.rst - - - + Programming Guide.rst + \ No newline at end of file From 8e4d0e568a9364ae9308f41cbaa6842f6bdbe2a0 Mon Sep 17 00:00:00 2001 From: Sethu Chandan Jangala Date: Mon, 20 Aug 2012 11:25:01 +0530 Subject: [PATCH 3/3] Refined documents for module_uart_rx and module_uart_tx --- module_uart_fast_rx/doc/Makefile | 5 +++-- module_uart_fast_rx/doc/fast.rst | 1 + module_uart_fast_rx/doc/summary.rst | 8 ++------ module_uart_fast_tx/doc/Makefile | 2 +- module_uart_fast_tx/doc/summary.rst | 5 +++-- 5 files changed, 10 insertions(+), 11 deletions(-) diff --git a/module_uart_fast_rx/doc/Makefile b/module_uart_fast_rx/doc/Makefile index ba9581f..4d98e49 100644 --- a/module_uart_fast_rx/doc/Makefile +++ b/module_uart_fast_rx/doc/Makefile @@ -1,7 +1,8 @@ -REPO=../../sc_uart/module_fast_rx +REPO=../../sc_uart SPHINX_PROJECT_NAME=UART VERSION=0v1 -DOXYGEN_DIRS= $(REPO)/module_uart_fast_rx \ +DOXYGEN_DIRS=$(REPO)/module_uart_fast_rx \ + SOURCE_INCLUDE_DIRS=$(REPO) XDOC_DIR ?= ../../xdoc include $(XDOC_DIR)/Makefile.inc diff --git a/module_uart_fast_rx/doc/fast.rst b/module_uart_fast_rx/doc/fast.rst index 78de1d6..013ebfc 100644 --- a/module_uart_fast_rx/doc/fast.rst +++ b/module_uart_fast_rx/doc/fast.rst @@ -23,6 +23,7 @@ API .. doxygenfunction:: uart_rx_fast + Example programs ++++++++++++++++ diff --git a/module_uart_fast_rx/doc/summary.rst b/module_uart_fast_rx/doc/summary.rst index 29153e8..90bd260 100644 --- a/module_uart_fast_rx/doc/summary.rst +++ b/module_uart_fast_rx/doc/summary.rst @@ -22,7 +22,7 @@ The most important characteristics are the following: UART Implementation Alternatives -------------------------------- -UART components are included in this repository RX, summarised below: + UART component included in this repository consisting of module RX, summarised below: +--------------+---------------------+------------+--------+---------------+---------------+-------------+ | Component | modules | Data rate | Memory | Parity | Bits Per Byte | Stop Bits | @@ -31,11 +31,6 @@ UART components are included in this repository RX, summarised below: +--------------+---------------------+------------+--------+---------------+---------------+-------------+ -Generic UART -++++++++++++ - -This module is completely parameterisable at run time and will require a thread for each of RX and TX. Unlike the simple uart below, it can operate at the standard UART baud rates. - Simple UART +++++++++++ @@ -48,6 +43,7 @@ It is fixed to 8 bits, a single start bit, no parity, and a single stop bit. All Note that the code is easy to understand; it comprises the example from the XC programming manual. + Other Uarts +++++++++++ diff --git a/module_uart_fast_tx/doc/Makefile b/module_uart_fast_tx/doc/Makefile index 2e641ea..abfdaee 100644 --- a/module_uart_fast_tx/doc/Makefile +++ b/module_uart_fast_tx/doc/Makefile @@ -1,4 +1,4 @@ -REPO=../../sc_uart/module_uart_fast_tx +REPO=../../sc_uart SPHINX_PROJECT_NAME=UART VERSION=0v1 DOXYGEN_DIRS=$(REPO)/module_uart_fast_tx diff --git a/module_uart_fast_tx/doc/summary.rst b/module_uart_fast_tx/doc/summary.rst index 18eb3e3..815fb93 100644 --- a/module_uart_fast_tx/doc/summary.rst +++ b/module_uart_fast_tx/doc/summary.rst @@ -22,7 +22,7 @@ The most important characteristics are the following: UART Implementation Alternatives -------------------------------- -UART components are included in this repository TX, summarised below: +Two UART components are included in this repository, each consisting of two modules (one for each of RX and TX), summarised below: +--------------+---------------------+------------+--------+---------------+---------------+-------------+ | Component | modules | Data rate | Memory | Parity | Bits Per Byte | Stop Bits | @@ -31,10 +31,11 @@ UART components are included in this repository TX, summarised below: +--------------+---------------------+------------+--------+---------------+---------------+-------------+ + Simple UART +++++++++++ -This module is a much simpler implementation of a UART that will require a whole thread for TX and deliver up to 10 Mbaud. RX could be called as a function, and hence share a thread with other functionality although this will affect the TX baud rate achieved,and this usage is not shown. +This module is a much simpler implementation of a UART that will require a whole thread for RX and deliver up to 10 Mbaud. TX could be called as a function, and hence share a thread with other functionality although this will affect the TX baud rate achieved,and this usage is not shown. It is fixed to 8 bits, a single start bit, no parity, and a single stop bit. All of those parameters could be changed by altering the source code.