doc: update the docs of arc feature examples

Signed-off-by: Wayne Ren <wei.ren@synopsys.com>
foss-for-synopsys-dwc-arc-processors · Nov 1, 2018 · 8fb1a4c · 8fb1a4c
1 parent 7faf347
commit 8fb1a4c
Show file tree

Hide file tree

Showing 6 changed files with 27 additions and 162 deletions.
diff --git a/example/baremetal/arc_feature/cache/README.rst b/example/baremetal/arc_feature/cache/README.rst
@@ -6,7 +6,7 @@ ARC Cache Example
 Overview
 ********
 
- This example is designed to test the cache module of ARC. Besides, it shows how to use ARC Cache API defined in embARC.
+ This example is designed to test the cache module of |arc|. Besides, it shows how to use ARC cache API defined in |embarc|.
 
 Detailed Description
 ====================
@@ -18,26 +18,22 @@ Detailed Description
     NO
 
  * Design Concept
-    This example is designed to test the cache module of ARC. Besides, it shows how to use ARC Cache API defined in embARC.
+    This example is designed to test the cache module of |arc|. Besides, it shows how to use ARC Cache API defined in ``arc_cache.h``.
 
- * Usage Manual
-    Test cases for ARC cache-related functions defined in arc_cache.h.
-
-
- * Extra Comments
-    Only for ARC EM cores that contain cache, so EM4, EM4CR16 on EMSK 1.x, and EM5D, EM9D on EMSK 2.x should NOT run this example
+.. note::
+    Hardware support: Only works for |arc| that contain cache, please check your |arc| configuration before running this example
 
 Buidling and Running
 ********************
 
-The commands to run this example are as follows:
+Taking |emsk| as exmaple, the commands to run this example are as follows:
 
 .. code-block:: console
 
     $ cd <embarc_root>/example/baremetal/arc_feature/cache
     $ make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu run
 
-.. note:: Make sure you have selected the correct configuration of EMSK via dipswitches and that you have reset the board (button above “R”) to confirme its configuration
+.. note:: Make sure you have selected the correct configuration of |emsk| via dip switches and that you have reset the board (button above “R”).
 
 Sample Output
 =============

diff --git a/example/baremetal/arc_feature/cache/main.c b/example/baremetal/arc_feature/cache/main.c
@@ -27,43 +27,6 @@
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *
 --------------------------------------------- */
-
-/**
- * \defgroup	EMBARC_APP_BAREMETAL_ARC_FEATURE_CACHE	embARC Cache Example
- * \ingroup	EMBARC_APPS_TOTAL
- * \ingroup	EMBARC_APPS_BAREMETAL
- * \brief	embARC example for testing ARC cache module
- *
- * \details
- * ### Extra Required Tools
- *
- * ### Extra Required Peripherals
- *
- * ### Design Concept
- *     This example is designed to test the cache module of ARC,
- *     by the way to show how to use ARC Cache API defined in embARC.
- *
- * ### Usage Manual
- *     Test cases for ARC cache-related functions defined in arc_cache.h.
- *     ![ScreenShot of cache under baremetal](pic/images/example/emsk/emsk_cache.jpg)
- *
- * ### Extra Comments
- *     Only for ARC EM cores that contain cache, so EM4, EM4CR16 on EMSK 1.x, and EM5D.
- *     ARC EM SEP on EMSK 2.x shouldn't run this application
- */
-
-/**
- * \file
- * \ingroup	EMBARC_APP_BAREMETAL_ARC_FEATURE_CACHE
- * \brief	main source of example of cache
- * show the basic operations of cache
- */
-
-/**
- * \addtogroup	EMBARC_APP_BAREMETAL_ARC_FEATURE_CACHE
- * @{
- */
-/* embARC HAL */
 #include "embARC.h"
 #include "embARC_debug.h"
 
@@ -161,6 +124,4 @@ int main(void)
 	while(1);
 
 	return E_SYS;
-}
-
-/** @} */
+}
diff --git a/example/baremetal/arc_feature/timer_interrupt/README.rst b/example/baremetal/arc_feature/timer_interrupt/README.rst
@@ -6,11 +6,10 @@ ARC Timer Interrupt Example
 Overview
 ********
 
- This example is designed to show how to use ARC timer and interrupt.
+ This example is designed to show how to use |arc| internal timers and timer interrupt.
 
 Detailed Description
 ====================
- embARC example for testing ARC timer and interrupt
 
  * Extra Required Tools
       NO
@@ -20,33 +19,22 @@ Detailed Description
 
  * Design Concept
     This example is designed to show how to use ARC timer and interrupt.
-
- * Usage Manual
     During initialization, the timer 0 and timer 1 are enabled and interrupt is configured. The timer 0 Interrupt Service Routine (ISR) is set as Fast Interrupt Request Queue (FIQ) using ``int_pri_set()``. The timer 0 interrupt is responsed with the highest priority.
 
- * Extra Comments
-    Please take care of the selected ARC core configuration to make sure FIQ is enabled.
+.. note::
+    Hardware support: all |arc| based platform with internal timers configured
 
 Buidling and Running
 ********************
 
-This example outputs to the console. It is supported by all platform. The commands
-to run this example are as follows:
-
-.. code-block:: console
-
-    $ cd <embarc_root>/example/baremetal/arc_feature/timer_interrupt
-    $ make BOARD=emsk BD_VER=11 CUR_CORE=arcem6 TOOLCHAIN=gnu run
-
-If you do not have an EMSK development board, you can use the nSIM simulator
-which have been installed in MetaWare IDE.
+Taking |emsk| as exmaple, the commands to run this example are as follows:
 
 .. code-block:: console
 
     $ cd <embarc_root>/example/baremetal/arc_feature/timer_interrupt
-    $ gmake BOARD=nism BD_VER=1506 CUR_CORE=arcemfull TOOLCHAIN=mw run
+    $ make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu run
 
-.. note:: Make sure you have selected the correct configuration of EMSK via dipswitches and that you have reset the board (button above “R”) to confirme its configuration
+.. note:: Make sure you have selected the correct configuration of |emsk| via dip switches and that you have reset the board (button above “R”).
 
 Sample Output
 =============
@@ -86,6 +74,6 @@ If you are using the ``nSIM``, you will see the following outputs in the CMD win
     enable timer 0 watchdog
     ---end----
 
-If you are using the ``ARC EMSK`` development board, you will see the same msg in the ``COM DEBUG TOOL`` (eg.Tera Term VT).
+If you are using the |emsk|, you will see the same msg through UART
 
-.. note:: Make sure you have chosen correct COM port and set the Baud rate to 115200 before you start.
+.. note:: Make sure you have chosen correct COM port and set the baud rate to 115200 before you start.
diff --git a/example/baremetal/arc_feature/timer_interrupt/main.c b/example/baremetal/arc_feature/timer_interrupt/main.c
@@ -27,42 +27,6 @@
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *
 --------------------------------------------- */
-
-/**
- * \defgroup	EMBARC_APP_BAREMETAL_ARC_FEATURE_TIMER_INTERRUPT	embARC ARC Timer and Interrupt Example
- * \ingroup	EMBARC_APPS_TOTAL
- * \ingroup	EMBARC_APPS_BAREMETAL
- * \brief	embARC example for testing ARC timer and interrupt
- *
- * \details
- * ### Extra Required Tools
- *
- * ### Extra Required Peripherals
- *
- * ### Design Concept
- *     This example is designed to show how to use ARC timer and interrupt.
- *
- * ### Usage Manual
- *     In the initialization, the timer 0 and timer 1 are enabled and interrupt is configured.
- *     The timer 0 Interrupt Service Routine (ISR) is set as Fast Interrupt Request Queue (FIQ) using int_pri_set().
- *     The timer 0 interrupt is responsed with the highest priority.
- *     ![ScreenShot of timer 0 and timer 1 ISR under baremetal](pic/images/example/emsk/emsk_timer_interrupt.jpg)
- *
- * ### Extra Comments
- *     Please take care of the selected ARC core configuration to make sure FIQ is enabled.
- */
-
-/**
- * \file
- * \ingroup	EMBARC_APP_BAREMETAL_ARC_FEATURE_TIMER_INTERRUPT
- * \brief	example of ARC timer and interrupt
- */
-
-/**
- * \addtogroup	EMBARC_APP_BAREMETAL_ARC_FEATURE_TIMER_INTERRUPT
- * @{
- */
-
 /* embARC HAL */
 #include "embARC.h"
 #include "embARC_debug.h"
@@ -87,7 +51,6 @@ static void timer1_isr(void *ptr)
 	EMBARC_PRINTF("timer1 interrupt:%d\r\n", t1);
 }
 
-/** main entry for testing arc fiq interrupt */
 int main(void)
 {
 	uint32_t val;
@@ -154,5 +117,3 @@ int main(void)
 	while(1);
 	return E_SYS;
 }
-
-/** @} */
diff --git a/example/baremetal/arc_feature/udma/README.rst b/example/baremetal/arc_feature/udma/README.rst
@@ -20,28 +20,27 @@ Detailed Description
  * Design Concept
     This example is designed to show how to use uDMA API and to compare uDMA copy with memory copy.
 
- * Usage Manual
-    | You can uncomment the *APPL_DEFINES* line in this application makefile to overwrite the linker script settings.
-    | If you uncomment the *APPL_DEFINES* line, then you can modify the *REGION_ROM* and *REGION_RAM* in *appl_mem_config.h* to proper values.
-    | If you want to run in DDR, you can set this two values to *EXT_RAM*.
-    | When you change this values defined in *appl_mem_config.h* in this example, you need to clean the project first then rebuilt it.
-
-
- * Extra Comments
- 	- This example only supports EMSK 2.2 and EMSK 2.3.
- 	- the uDMA option is required in core configuration to run this example.
+.. note::
+    Hardware support: all |arc| based platform with uDMA configured
 
 Buidling and Running
 ********************
 
-The commands to run this example are as follows:
+Taking |emsk| as exmaple, the commands to run this example are as follows:
 
 .. code-block:: console
 
     $ cd <embarc_root>/example/baremetal/arc_feature/udma
     $ gmake BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=mw run
 
-.. note:: Make sure you have selected the correct configuration of EMSK via dipswitches and that you have reset the board (button above “R”) to confirme its configuration
+.. note:: Make sure you have selected the correct configuration of |emsk| via dip switches and that you have reset the board (button above “R”).
+
+You can uncomment the *APPL_DEFINES* line in this application makefile to overwrite the linker script settings.
+If you uncomment the *APPL_DEFINES* line, then you can modify the *REGION_ROM* and *REGION_RAM* in ``appl_mem_config.h`` to proper values.
+
+If you want to run in DDR, you can set this two values to *EXT_RAM*. When you
+change this values defined in ``appl_mem_config.h`` in this example, you need to
+clean the project first then rebuilt it.
 
 Sample Output
 =============

diff --git a/example/baremetal/arc_feature/udma/main.c b/example/baremetal/arc_feature/udma/main.c
@@ -27,44 +27,6 @@
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *
 --------------------------------------------- */
-
-/**
- * \defgroup	EMBARC_APP_BAREMETAL_ARC_FEATURE_UDMA	embARC ARC uDMA Example
- * \ingroup	EMBARC_APPS_TOTAL
- * \ingroup	EMBARC_APPS_BAREMETAL
- * \brief	embARC example for testing ARC uDMA feature in baremetal mode
- *
- * \details
- * ### Extra Required Tools
- *
- * ### Extra Required Peripherals
- *
- * ### Design Concept
- *     This example is designed to show how to use uDMA API and compare uDMA copy with memory copy.
- *
- * ### Usage Manual
- *     ![ScreenShot of uDMA features under baremetal](pic/images/example/emsk/baremetal_arc_feature_udma.jpg)
- *     You can uncomment the *APPL_DEFINES* line in this application makefile to overwrite the linker script settings.
- *     If you uncomment the *APPL_DEFINES* line, then you can modify the *REGION_ROM* and *REGION_RAM* in *appl_mem_config.h* to proper values.
- *     If you want to run in DDR, you can set this two values to *EXT_RAM*.
- *     When you change this values defined in *appl_mem_config.h* in this example, you need to clean the project first then rebuilt it.
- *
- * ### Extra Comments
- *     - This example only supported EMSK 2.2 and EMSK 2.3.
- *     - This example require the core configuration to have uDMA option.
- */
-
-/**
- * \file
- * \ingroup	EMBARC_APP_BAREMETAL_ARC_FEATURE_UDMA
- * \brief	example of ARC uDMA in baremetal mode
- */
-
-/**
- * \addtogroup	EMBARC_APP_BAREMETAL_ARC_FEATURE_UDMA
- * @{
- */
-
 /* embARC HAL */
 #include "embARC.h"
 #include "embARC_debug.h"
@@ -321,6 +283,4 @@ int main( void )
 	dma_finish();
 	dmac_close();
 	return 0;
-}
-
-/** @} */
+}