Seperated documents for each module.

module_uart_fast_rx/doc/Makefile

@@ -0,0 +1,11 @@
+REPO=../../sc_uart
+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

doc/fast.rst → module_uart_fast_rx/doc/fast.rst

@@ -22,7 +22,7 @@ API
 +++
 
 .. doxygenfunction:: uart_rx_fast
-.. doxygenfunction:: uart_tx_fast
+
 
 Example programs
 ++++++++++++++++

doc/index.rst → module_uart_fast_rx/doc/index.rst

@@ -4,7 +4,6 @@ XCORE STAND ALONE UART COMPONENTS
 .. toctree::
 
    summary.rst
-   generic.rst
    fast.rst
 
 

module_uart_fast_rx/doc/summary.rst

@@ -0,0 +1,52 @@
+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 RX, summarised below:
+
++--------------+---------------------+------------+--------+---------------+---------------+-------------+
+| Component    | modules             | Data rate  | Memory | Parity        | Bits Per Byte | Stop Bits   | 
++--------------+---------------------+------------+--------+---------------+---------------+-------------+
+| Simple UART  | module_uart_fast_rx | 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 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. 
+
+*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.
+
+

module_uart_fast_tx/doc/Makefile

@@ -0,0 +1,10 @@
+REPO=../../sc_uart
+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

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: //::
+

module_uart_fast_tx/doc/index.rst

@@ -0,0 +1,10 @@
+XCORE STAND ALONE UART COMPONENTS
+=================================
+
+.. toctree::
+
+   summary.rst
+   fast.rst
+
+
+

doc/summary.rst → module_uart_fast_tx/doc/summary.rst

@@ -27,20 +27,10 @@ Two UART components are included in this repository, each consisting of two modu
 +--------------+---------------------+------------+--------+---------------+---------------+-------------+
 | 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           |
 +--------------+---------------------+------------+--------+---------------+---------------+-------------+
 
 
-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
 +++++++++++

doc/Makefile → 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

doc/generic.rst → module_uart_rx/doc/generic.rst

@@ -23,14 +23,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,21 +68,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
 ++++++++++++++++++++++++++
@@ -109,6 +86,7 @@ UART RX API
 .. doxygenfunction:: uart_rx_set_bits_per_byte
 
 
+
 Verification
 ------------
 

module_uart_rx/doc/index.rst

@@ -0,0 +1,11 @@
+I2C Software Component
+----------------------
+
+.. toctree::
+
+   Overview.rst
+   Resource Requirements.rst
+   Hardware Requirements.rst
+   generic.rst
+   Programming Guide.rst
+

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.
+
+

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