doc: update the board related docs

* merge the page getting started of board into the page
of board introduction.
* fix and enhancement

Signed-off-by: Wayne Ren <wei.ren@synopsys.com>

doc/documents/board/emsk.rst

@@ -35,7 +35,7 @@ Usage
 -----
 
 EM core configurations
-^^^^^^^^^^^^^^^^^^^^^^
+**********************
 
 The FPGA board includes a SPI flash storage device pre-programmed with FPGA
 images containing different configurations of DesignWare® ARC EM cores.
@@ -57,7 +57,7 @@ for different suported versions of EMSK board.
 
 
 Peripherals
-^^^^^^^^^^^
+***********
 
 There are many peripheral devices available, such as SPI master, SPI slave,
 IIC, UART, GPIO. External hardware interface devices can be connected to the
@@ -77,10 +77,138 @@ memory mappings for different supported versions of EMSK board are shown below:
     :alt: EMSK 2.3 - Peripheral Connections and Memory Mapping
 
 Peripherals interrupts
-^^^^^^^^^^^^^^^^^^^^^^
+**********************
 
 Peripherals can generate interrupts to the CPU. The interrupt irq assignments
 are as follows.
 
 .. image:: /pic/emsk_interrupt_connection.jpg
     :alt: Interrupt Assignments
+
+.. _getting_started_with_em_starter_kit:
+
+Programming and Debugging
+-------------------------
+
+Required Hardware and Software
+******************************
+
+To use embARC OSP applications on the IoTDK board, the following items are required
+
+* USB Cable
+* The USB cable provides power to the board (maximum 500 mA); however, if the board is to run
+  standalone, the universal switching power adaptor (110-240V AC to 5V DC),
+  can be used to power the board
+* :ref:`software_requirement`.
+* (optional) A collection of PMOD modules.
+
+Set up the EMSK
+***************
+
+#. The EMSK has a bank of DIP switches labeled SW1 that are used to select a configuration. For example, to select ARC EM11D for EMSK 2.3, set bit 2 to the ON position (down), and the others to OFF (up) as shown.
+
+.. figure:: /pic/images/getting_started/emsk23_dipswitch.jpg
+   :scale: 40 %
+
+   DIP switch settings for ARC EM11D on EMSK 2.3
+
+For exact DIP switch settings for various ARC EM Starter Kit versions, refer to EM Starter Kit section in provided embARC documentation. For complete ARC EM Starter Kit information, see the **EM Starter Kit User's Guide** provided with the ARC EM Starter Kit.
+
+#. Connect the USB cable to connector J7 on the EMSK to USB port on your development host. If using the Ashling Opella-XD for ARC Debug Probe, connect it to the J15 connector on EMSK.
+
+.. note:: Despite the fact that EMSK 2.3 can be powered by connector J7, it is recommended to always use an AC adapter to supply power of the board.
+
+#. You can use any terminal emulation program to view UART output from the EMSK. The USB connection provides both the debug channel and RS232 transport. Use PuTTY application on Windows as an example.
+
+   * Determine which COM port the EMSK is using.
+
+      * Open the **Windows Control Panel** and select **Device Manager** in a Windows environment.
+      * Expand **Ports (COM and LPT)** in the list. Select **USB Serial Port (COM x)** and note the COM port number for the ARC board.
+
+   * Configure serial terminal connection.
+
+      * Launch PuTTY. Select **Serial** under **Connection type** and enter the appropriate COM port string under **Serial line**.
+      * Choose 115200 baud, 8 bits, 1 stop bit, no parity (115200-8-N-1) in settings.
+      * You can optionally save your settings so they can be easily retrieved every time PuTTY is launched.
+      * Click Open to open the console.
+
+#. Test serial output with EMSK.
+
+      * Press the middle ("R"eset) button above the **ARC** label on the EMSK board to reset the board and run the self-test.
+      * Use EMSK 2.3 as an example. Confirm that you can see the header and self-test message printed to the console.
+
+      .. code-block:: console
+
+         ***********************************
+         **       Synopsys, Inc.          **
+         **     ARC EM Starter kit        **
+         **                               **
+         ** Comprehensive software stacks **
+         **   available from embARC.org   **
+         **                               **
+         ***********************************
+         Firmware   Feb 22 2017, v2.3
+         Bootloader Feb 22 2017, v1.1
+         ARC EM11D, core configuration #3
+
+         ARC IDENTITY = 0x43
+         RF_BUILD = 0xc902
+         TIMER_BUILD = 0x10304
+         ICCM_BUILD = 0x804
+         DCCM_BUILD = 0x10804
+         I_CACHE_BUILD = 0x135104
+         D_CACHE_BUILD = 0x215104
+
+         SelfTest PASSED
+
+         Info: No boot image found
+
+#. (Optional) Connect the PmodWiFi, PmodRF2, and PmodTMP2 modules to the EMSK as shown.
+
+.. figure:: /pic/images/getting_started/emsk_board_settings.jpg
+   :scale: 15 %
+   :alt: emsk board setting
+
+   EMSK board connection
+
+Building
+********
+
+Take :ref:`example_blinky` as an example and use the em7d configuration of EMSK 2.2
+
+.. code-block:: console
+
+   cd embarc_osp\example\baremetal\blinky
+   # for ARC GNU toolchain
+   make TOOLCHAIN=gnu BOARD=emsk BD_VER=22 CUR_CORE=arcem7d
+   # for MWDT toolchain
+   make TOOLCHAIN=mw  BOARD=emsk BD_VER=22 CUR_CORE=arcem7d
+
+Running
+*******
+
+.. code-block:: console
+
+   cd embarc_osp\example\baremetal\blinky
+   # for ARC GNU toolchain
+   make TOOLCHAIN=gnu  BOARD=emsk BD_VER=22 CUR_CORE=arcem7d
+   # for MWDT toolchain
+   make TOOLCHAIN=mw  BOARD=emsk BD_VER=22 CUR_CORE=arcem7d
+
+Debugging
+*********
+
+.. code-block:: console
+
+   cd embarc_osp\example\baremetal\blinky
+   # for ARC GNU toolchain
+   make TOOLCHAIN=gnu  BOARD=emsk BD_VER=22 CUR_CORE=arcem7d
+   # for MWDT toolchain
+   make TOOLCHAIN=mw  BOARD=emsk BD_VER=22 CUR_CORE=arcem7d
+
+Flashing
+********
+
+EMSK has an on board SPI flash, but you cannot directly flash your
+application into EMSK through debugger. You need other tools/applications
+(e.g., embarc bootloader) to do this. Please refer :ref:`example_bootloader`

doc/documents/board/hsdk.rst

@@ -12,36 +12,44 @@ source code includes bare metal and FreeRTOS device drivers and example
 applications. Code development is made easy using the MetaWare Development
 Toolkit, MetaWare Lite tools or the ARC GNU Tool Chain.
 
+
+See also this URL for details about the board: `DesignWare ARC HS Development Kit
+(HSDK) <https://www.synopsys.com/dw/ipdir.php?ds=arc-hs-development-kit>`_
+
 .. image:: /pic/hsdk_board.jpg
     :alt: ARC HS Development Kit
 
 
 The ARC HS Development Kit features the following components:
 
 - ARC HS SoC:
-  - Quad Core HS38x4 Processor
-  - DDR3 memory controller
-  - GPU
-  - USB, Ethernet, SDIO
-  - DesignWare APB Peripherals (consult HSDK documentation for complete details)
+
+    - Quad Core HS38x4 Processor
+    - DDR3 memory controller
+    - GPU
+    - USB, Ethernet, SDIO
+    - DesignWare APB Peripherals (consult HSDK documentation for complete details)
+
 - Memory / Storage:
-  - DDR3-1333 (4 GB)
-  - 2x SPI Flash (2 MB)
-  - I2C EEPROM (3 KB)
+    - DDR3-1333 (4 GB)
+    - 2x SPI Flash (2 MB)
+    - I2C EEPROM (3 KB)
+
 - Interfaces:
-  - USB2 (2x)
-  - Ethernet (10/100/1000)
-  - Audio  - line in/out
-  - USB Data port (JTAG/UART)
-  - Micro-SD Card
-  - WIFI/BT module
-  - ADC (6 channels)
-  - RTT Nexus and JTAG connectors
+    - USB2 (2x)
+    - Ethernet (10/100/1000)
+    - Audio  - line in/out
+    - USB Data port (JTAG/UART)
+    - Micro-SD Card
+    - WIFI/BT module
+    - ADC (6 channels)
+    - RTT Nexus and JTAG connectors
+
 - Extensions:
-  - AXI Tunnel (32-bit, 150 MHz)
-  - Arduino  - Interface headers (UNO R3 compatible)
-  - mikroBUS headers
-  - Pmod Interfaces (3x), PMOD A and PMOD B (12 pins), PMOD C (6 pins)
+    - AXI Tunnel (32-bit, 150 MHz)
+    - Arduino  - Interface headers (UNO R3 compatible)
+    - mikroBUS headers
+    - PMOD Interfaces (3x), PMOD A and PMOD B (12 pins), PMOD C (6 pins)
 
 .. image:: /pic/hsdk_block_diagram.jpg
     :alt: ARC HSDK Block Diagram
@@ -88,9 +96,9 @@ The ARC HS SoC provides the following main features:
 - DDR3 interface
 
   - max speed grade DDR-1600 (800MHz)
-  - data width 32bit
-  - max row address width 16bit
-  - max bank address width 3bit
+  - data width 32 bits
+  - max row address width 16 bits
+  - max bank address width 3 bits
   - max 2 memory ranks
   - max supported DDR memory size is 4GByte
 
@@ -109,3 +117,128 @@ The ARC HS SoC provides the following main features:
 - SPI interfaces
 - PWM interfaces
 - JTAG interface
+
+Extension Interfaces
+--------------------
+
+To bring your application context around the ARC HSDK, the following
+peripheral module standards are supported:
+
+* Digilent PMOD™ (3x)
+* MikroBUS (1x)
+* Arduino (1x)
+
+For the details of extension interfaces, please go for the user manual/datasheet of HSDK. Users can change the interface configuration through the pinmux API in ``dev_pinmux.h``.
+
+.. note:: In the examples of embARC OSP, PMOD_B is used to connected SPI devices with PMOD interface, e.g. PMOD WiFI, PMOD_A is used to connected I2C devices with PMOD interface, e.g. PMOD ADC.
+
+Programming and Debugging
+-------------------------
+
+.. _getting_started_with_hs_development_kit:
+
+
+Required Hardware and Software
+******************************
+
+To use embARC OSP applications on the IoTDK board, the following items are required
+
+* USB Cable
+* The universal switching power adaptor (110-240V AC to 12V DC), can be used to power the board
+* :ref:`software_requirement`.
+* (optional) A collection of PMODs and Arduino modules.
+
+
+Set up the HSDK
+***************
+
+#. The HSDK boot switches are shown below. There are multiple configurations, such as boot mirror, boot image location, boot start mode, core selection and multi-core mode. For example, the configurations in the following picture are boot image location: 0x1 (internal ROM), boot start mode: generate cpu_start autonomously after reset, core selection: 0x0 (HS38X4_0), and multi-core mode: 0x0 (signal-core). For complete HSDK information, see the **HS Development Kit User's Guide** provided with the HSDK.
+
+.. figure:: /pic/images/getting_started/hsdk_dip_settings.png
+   :scale: 80 %
+
+   ARC HSDK DIP switch settings
+
+#. Connect the USB cable to the HSDK mini-USB connector and to the USB port on your development host. If using the Ashling Opella-XD for ARC Debug Probe or Digilent JTAG-HS2 Probe, connect it to the right connector. Connect the power supply to the board and to the power outlet.
+
+.. figure:: /pic/images/getting_started/hsdk_debug_interface.png
+   :scale: 50 %
+
+   ARC HSDK debug interface
+
+#. You can use any terminal emulation program to view UART output from the HSDK. The USB connection provides both the debug channel and RS232 transport. Use Tera Term in Windows as an example.
+
+   * Determine which COM port the HSDK is using.
+
+      * Open the **Windows Control Panel** and select **Device Manager** in a Windows environment.
+      * Expand **Ports (COM and LPT)** in the list. Select **USB Serial Port (COM x)** and Note the COM port number for the ARC board.
+
+   * Configure serial terminal connection.
+
+      * Launch Tera Term. Select **Serial** in **Setup**. Choose the appropriate COM port string in **Port** and 115200 in **Baud rate**, 8 bits data, 1 stop bit, no parity (115200-8-N-1). Click **OK** to set the port configuration.
+      * You can optionally save your settings so they can be easily retrieved.
+      * Select **New connection** in **File** and choose the appropriate COM in **Serial**.
+
+#. Test serial output with HSDK.
+
+      * Press the "RESET" button on the HSDK board to reset the board.
+      * Confirm that you can see the header and self-test message printed to the console.
+
+      .. code-block:: console
+
+         ********************************
+         **       Synopsys, Inc.       **
+         **   ARC HS Development Kit   **
+         ********************************
+         ** IC revision: Rev 1.0
+         Bootloader revision: Jun 12 2016, 08:54:06
+         Bootloader location: 0x1 (internal ROM)
+         Bootloader aux: 0x9 (sg15E,4Gb,x8,2r)
+         Bootloader speedmode: Slow
+         Bootloader multicore: 0x0 (Single-core)
+
+
+#. (Optional) Connect the PmodWiFi and PmodRF2 to the HSDK as shown.
+
+.. figure:: /pic/images/getting_started/hsdk_pmod_connection.png
+   :scale: 80 %
+
+Building
+********
+
+Take :ref:`example_blinky` as an example
+
+.. code-block:: console
+
+   cd embarc_osp\example\baremetal\blinky
+   # for ARC GNU toolchain
+   make TOOLCHAIN=gnu BOARD=hsdk
+   # for MWDT toolchain
+   make TOOLCHAIN=mw BOARD=hsdk
+
+Running
+*******
+
+.. code-block:: console
+
+   cd embarc_osp\example\baremetal\blinky
+   # for ARC GNU toolchain
+   make TOOLCHAIN=gnu BOARD=hsdk run
+   # for MWDT toolchain
+   make TOOLCHAIN=mw BOARD=hsdk run
+
+Debugging
+*********
+
+.. code-block:: console
+
+   cd embarc_osp\example\baremetal\blinky
+   # for ARC GNU toolchain
+   make TOOLCHAIN=gnu BOARD=hsdk gui
+   # for MWDT toolchain
+   make TOOLCHAIN=mw BOARD=hsdk gui
+
+Flashing
+********
+
+The related introduction is working in progress.