doc/board/arduino_101.rst

.. _arduino_101:

Board Configuration: arduino 101
################################

Overview
********

The Arduino 101 board is an Arduino product that uses the Intel Quark SE
processor.  As an unsupported configuration, the Zephyr Project is able to be
flashed to an Arduino 101 for experimentation and testing purposes.

As the Quark SE contains both an ARC and an X86 core, a developer will need to
flash an ARC and an X86 image to use both.  Developers can use the
**arduino_101** and **arduino_101_sss** board configurations to build a Zephyr
Kernel that can be flashed and run on the Arduino 101 platform.  The default
configuration for Arduino 101 boards can be found in
:file:`boards/arduino_101/arduino_101_defconfig` for the X86 and
:file:`boards/arduino_101/arduino_101_sss_defconfig` for the ARC.

Board Layout
************

General information for the board can be found at the `Arduino website`_,
which includes both `schematics`_ and BRD files.

Supported Features
******************

The Zephyr kernel supports multiple hardware features on the Arduino 101
through the use of drivers.  Some drivers are functional on the x86 side, some
only on the ARC side, and a few functional on both sides.  The below table
breaks down which drivers and functionality can be found on which architectures:

+-----------+------------+-----+-----+-----------------------+
| Interface | Controller | ARC | x86 | Driver/Component      |
+===========+============+=====+=====+=======================+
| APIC      | on-chip    |  N  |  Y  | interrupt_controller  |
+-----------+------------+-----+-----+-----------------------+
| UART      | on-chip    |  N  |  Y  | serial port-polling;  |
|           |            |     |     | serial port-interrupt |
+-----------+------------+-----+-----+-----------------------+
| SPI       | on-chip    |  Y  |  Y  | spi                   |
+-----------+------------+-----+-----+-----------------------+
| ADC       | on-chip    |  Y  |  N  | adc                   |
+-----------+------------+-----+-----+-----------------------+
| I2C       | on-chip    |  Y  |  Y  | i2c                   |
+-----------+------------+-----+-----+-----------------------+
| GPIO      | on-chip    |  Y  |  Y  | gpio                  |
+-----------+------------+-----+-----+-----------------------+
| PWM       | on-chip    |  Y  |  Y  | pwm                   |
+-----------+------------+-----+-----+-----------------------+
| mailbox   | on-chip    |  Y  |  Y  | ipm                   |
+-----------+------------+-----+-----+-----------------------+

Flashing Arduino 101 for Zephyr
*******************************

For the use of this tutorial, the sample application hello_world will be
used found in :file:`$ZEPHYR_BASE/samples/nanokernel/apps/hello_world`.

Use the following procedures for booting an image on a Arduino 101 board.

.. contents:: Procedures
   :depth: 1
   :local:
   :backlinks: entry

Required Hardware and Software
==============================

Before flashing the Zephyr kernel onto an Arduino 101, a few additional
pieces of hardware are required.

* `FlySwatter2 JTAG debugger`_

* ARM Micro JTAG Connector, Model: `ARM-JTAG-20-10`_

* While using the USB port for power does work, it is recommended that
  the 7V-12V barrel connector be used when working with the JTAG connector.

* :ref:`The Zephyr SDK <zephyr_sdk>`

* If you wish to grab any data off the serial port, you will need a TTY to USB
  adaptor.  There are two the Zephyr team has tested and found to work.  Both
  will require male to male jumper cables to connect to the Arduino 101 board.

  1. USB to TTL Serial Cable - https://adafru.it/954

  2. FTDI USB to TTL Serial Part #TTL-232R-3V3
     http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm

Connecting JTAG to Arduino 101
==============================

#. Connect the ARM Micro JTAG Connector to the FlySwatter2.

#. Locate the micro JTAG connector on the Arduino 101 board.  It can be found
   adjacent to the SCL and SDA pins in the Arduino headers. It is highlighted
   as the red square in the figure below.

   .. figure:: figures/arduino_101_01.png
      :scale: 50 %
      :alt: Highlight of the JTAG connector.

#. Locate next to the micro JTAG header a small white dot indicating the
   location of pin 0 on the header. The orange arrow on the figure points to
   the dot.

   .. figure:: figures/arduino_101_02.png
      :scale: 50 %
      :alt: Pointer to the pin 0 of the JTAG connector.

#. Connect the FlySwatter2 to the Arduino 101 micro JTAG connector.

#. Ensure that both the cable and header pin 0 locations line up. The cable
   from the ARM Micro JTAG connector uses a red wire on the cable to denote
   which end on the cable has the pin 0.  The orange arrow in the figure below
   points towards JTAG silkscreen indicator.

#. Plug the USB Type B cable into the FlySwatter2 and your computer. On
   Linux, you should see something similar to the following in your dmesg:

    .. code-block:: console

      usb 1-2.1.1: new high-speed USB device number 13 using xhci_hcd
      usb 1-2.1.1: New USB device found, idVendor=0403, idProduct=6010
      usb 1-2.1.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
      usb 1-2.1.1: Product: Flyswatter2
      usb 1-2.1.1: Manufacturer: TinCanTools
      usb 1-2.1.1: SerialNumber: FS20000
      ftdi_sio 1-2.1.1:1.0: FTDI USB Serial Device converter detected
      usb 1-2.1.1: Detected FT2232H
      usb 1-2.1.1: FTDI USB Serial Device converter now attached to ttyUSB0
      ftdi_sio 1-2.1.1:1.1: FTDI USB Serial Device converter detected
      usb 1-2.1.1: Detected FT2232H
      usb 1-2.1.1: FTDI USB Serial Device converter now attached to ttyUSB1




Making a Backup
===============

Before continuing, it is worth considering the creation of a backup
image of the ROM device as it stands today.  This would be necessary if you
ever decide to run Arduino sketches on the hardware again as the Arduino IDE
requires updating via a USB flashing method that is not currently supported
by Zephyr.

Typically Arduino hardware can re-program the Bootloader through connecting
the ICSP header and issuing the "Burn Bootloader" option from the Arduino
IDE.  On the Arduino 101, this option is not currently functional.

#. Make sure the Zephyr SDK has been installed on your platform.

#. Open a terminal window

#. Source the :file:`zephyr-env.sh` file.

#. Change directories to :file:`$ZEPHYR_BASE`.

#. In the termminal window , enter:

  .. code-block:: console

     $ sudo -E ./boards/arduino_101/support/arduino_101_backup.sh

  .. note::

  This will cause the system to dump two files in your ZEPHYR_BASE:
  A101_BOOT.bin and A101_OS.bin.  These contain copies of the original
  flash that can be used to restore the state to factory conditions.

At this point you have now created a backup for the Arduino 101.

Restoring a Backup
==================

#. Make sure the Zephyr SDK has been installed on your development
   environment.

#. Open a terminal window

#. Source the :file:`zephyr-env.sh` file.

#. Change directories to $ZEPHYR_BASE.

#. In the termminal window , enter:

  .. code-block:: console

     $ sudo -E ./boards/arduino_101/support/arduino_101_load.sh

  .. note::

  This script expects two files in your :file:`$ZEPHYR_BASE` with titles of
  :file:`A101_OS.bin` and :file:`A101_BOOT.bin`.

Flashing an Application to Arduino 101
======================================

By default, the Arduino 101 comes with an X86 and ARC image ready to run.  Both
images can be replaced by Zephyr OS images following the steps below.  In cases
where only an X86 image is needed or wanted it is important to disable the
ARC processor, as the X86 OS will appear to hang waiting for the ARC processor.

Details on how to disable the ARC can be found in the Debugging on Arduino 101
section.

Flashing the ROM
================

The default boot ROM used by the Arduino 101 requires that any binary to run
be authorized.  Currently the Zephyr project is not supported by this ROM.  To
work around this requirement, an alternative boot ROM has been created that
needs to be flashed just one time.  To flash a Zephyr compatible boot ROM, use
zflash to flash the :file:`quark_se_rom.bin` to the board.

.. note::
    This will cause the Arduino 101 board to no longer run an Arduino sketch
    or work with the Arduino IDE.

#. Source the :file:`zephyr-env.sh` file.

#. Change directories to $ZEPHYR_BASE.

#. The Zephyr Project has included a pre-compiled version of a bootloader for
   general use on the Arduino 101.  Details about how to build your own
   bootloader can be found in the
   :file:`$ZEPHYR_BASE/boards/arduino_101/support/README`

   .. code-block:: console

      $ sudo -E ./boards/arduino_101/support/arduino_101_load.sh rom

   This script will flash the boot rom located in
   :file:`$ZEPHYR_BASE/boards/arduino_101/support/quark_se_rom.bin` to the
   Arduino 101 device, overwriting the original shipping ROM.

Flashing an ARC Kernel
======================

# Make sure the binary image has been built.  Change directories to your local
checkout copy of Zephyr, and run:

   .. code-block:: console

      $ source ./zephyr-env.sh
      $ cd $ZEPHYR_BASE/samples/nanokernel/apps/hello_world

      $ make pristine && BOARD=arduino_101_sss ARCH=arc
      $ make BOARD=arduino_101_sss flash

.. note::

   When building for the ARC processor, the board type is listed as
   arduino_101_sss and the ARCH type is set to arc.


Congratulations you have now flashed the hello_world image to the ARC
processor.

Flashing an x86 Kernel
======================

# Make sure the binary image has been built.

   .. code-block:: console

      $ source ./zephyr-env.sh
      $ cd $ZEPHYR_BASE/samples/nanokernel/apps/hello_world
      $ make pristine && BOARD=arduino_101 ARCH=x86
      $ make BOARD=arduino_101 flash

.. note::

   When building for the x86 processor, the board type is listed as
   arduino_101 and the ARCH type is set to x86.

Congratulations you have now flashed the hello_world image to the x86
processor.

Debugging on Arduino 101
========================

The image file used for debugging must be built to the corresponding
architecture that you wish to debug. For example, the binary must be built
for ARCH=x86 if you wish to debug on the x86 core.

1. Build the binary for your application on the architecture you wish to
   debug.  Alternatively, use the instructions above as template for testing.

   When debugging on ARC, you will need to enable the ARC_INIT_DEBUG
   configuration option in your X86 PRJ file.  Details of this flag can be
   found in :file:`arch/x86/soc/quark_se/Kconfig`.  Setting this variable will
   force the ARC processor to halt on bootstrap, giving the debugger a chance
   at connecting and controlling the hardware.

    This can be done by editing the
    :file:`samples/nanokernel/apps/hello_world/prj.conf` to include:

   .. code-block:: console

      CONFIG_ARC_INIT=y
      CONFIG_ARC_INIT_DEBUG=y

   .. note::

       By enabling CONFIG_ARC_INIT, you ::MUST:: flash both an ARC and an X86
       image to the hardware.  If you do not, the X86 image will appear to hang
       at boot while it is waiting for the ARC to finish initialization.

2. Open two terminal windows

3. In terminal window 1, type:

  .. code-block:: console

    $ cd $ZEPHYR_BASE/samples/nanokernel/apps/hello_world
    $ make BOARD=arduino_101 debug

  These commands will start an openocd session that creates a local telnet
  server (on port 4444 for direct openocd commands to be issued), and a
  gdbserver (for gdb access).  The command should not return to a command line
  interface until you are done debugging, at which point you can press Cntl-C
  to shutdown everything.

4. Start GDB in terminal window 2


   * To debug on x86:

       .. code-block:: console

         $ cd $ZEPHYR_BASE/samples/nanokernel/apps/hello_world
         $ gdb outdir/zephyr.elf
         gdb$  target remote :3333

   * To debug on ARC:

     ARC debugging will require some extra steps and a third terminal.  It is
     necessary to use a version of gdb that understands ARC binaries.
     Thankfully one is provided with the Zephyr SDK at
     :envvar:`$ZEPHYR_SDK_INSTALL_DIR`
     :file:`/sysroots/i686-pokysdk-linux/usr/bin/arc-poky-elf/arc-poky-elf-gdb`.

     It is suggested to create an alias in your shell to run this command,
     such as:

     .. code-block:: console

        alias arc_gdb= "$ZEPHYR_SDK_INSTALL_DIR/sysroots/i686-pokysdk-
        linux/usr/bin/arc-poky-elf/arc-poky-elf-gdb"

     a) On Terminal 2:

       .. code-block:: console

          $ cd $ZEPHYR_BASE/samples/nanokernel/apps/hello_world
          $ arc_gdb outdir/zephyr.elf
          gdb$  target remote :3334

     At this point you may set the breakpoint needed in the code/function.

     b) On Terminal 3 connect to the X86 side:

      .. code-block:: console

         $ gdb
         gdb$  target remote :3333
         gdb$  continue

   .. note::
     In previous versions of the SDK, the gdbserver remote ports were reversed.
     The gdb ARC server port was 3333 and the X86 port was 3334.  As of SDK
     v0.7.2, the gdb ARC server port is 3334, and the X86 port is 3333.

   The :code:`continue` on the X86 side is needed as the ARC_INIT_DEBUG flag has
   been set and halts the X86 until the ARC core is ready.  Ready in this case
   is defined as openocd has had a chance to connect, setup registers, and any
   breakpoints.  Unfortunately, there exists no automated method for notifying
   the X86 side that openocd has connected to the ARC at this time.

   Once you've started the X86 side again, and have configured any debug
   stubs on the ARC side, you will need to have gdb issue the continue
   command for the ARC processor to start.

Connecting Serial Output
************************

In the default configuration, Zephyr's Arduino 101 images support serial output
via the UART0 on the board. To read the output, you will need a USB to TTL
serial cable.  To enable serial output:

* Connect the Serial Cable RX pin, to the Arduino 101's TX->1 pin.

   .. figure:: figures/arduino_101_03.png
      :scale: 50 %
      :alt: Image for pin positions and serial output

* Connect the Serial Cable TX pin, to the Arduino 101's RX<-0 pin.

   .. figure:: figures/arduino_101_04.png
      :scale: 50 %
      :alt: Image for pin positions and serial output

* Connect the Serial Cable GND pin, to the Arduino 101's GND pin.

   .. figure:: figures/arduino_101_05.png
      :scale: 50 %
      :alt: Image for pin positions and serial output

Once connected, on your development environment you will need to:

* Open a serial port emulator (i.e. on Linux minicom, screen, etc)

* Attach to the USB to TTL Serial cable, for example, on Linux this may be
  :file:`/dev/ttyUSB0`

* Set the communication details to:
  ** Speed: 115200
  ** Data: 8 bits
  ** Parity: None
  ** Stopbits: 1


Arduino 101 Pinout
******************

When using the Zephyr kernel, the pinout mapping for the Arduino 101 becomes a
little more complicated.  The table below details which pins in Zephyr map to
those on the Arduino 101 board for control.  Full details of the pinmux
implementation, what valid options can be configured, and where things map can
be found in the :file:`boards/arduino_101/pinmux.c`.


+-------------+----------+------------+
| Arduino Pin | Function | Zephyr Pin |
+=============+==========+============+
| IO-0        | UART1-RX |     17     |
+-------------+----------+------------+
| IO-1        | UART1-TX |     16     |
+-------------+----------+------------+
| IO-2        | GPIO     |     52     |
+-------------+----------+------------+
| IO-3        | GPIO     |     51     |
|             |          |     63     |
+-------------+----------+------------+
| IO-4        | GPIO     |     53     |
+-------------+----------+------------+
| IO-5        | GPIO     |     49     |
|             |          |     64     |
+-------------+----------+------------+
| IO-6        | PWM2     |     65     |
+-------------+----------+------------+
| IO-7        | GPIO     |     54     |
+-------------+----------+------------+
| IO-8        | GPIO     |     50     |
+-------------+----------+------------+
| IO-9        | PWM3     |     66     |
+-------------+----------+------------+
| IO-10       | AIN0     |     0      |
+-------------+----------+------------+
| IO-11       | AIN3     |     3      |
+-------------+----------+------------+
| IO-12       | AIN1     |     1      |
+-------------+----------+------------+
| IO-13       | AIN2     |     2      |
+-------------+----------+------------+
| ADC0        | GPIO SS  |     10     |
+-------------+----------+------------+
| ADC1        | GPIO SS  |     11     |
+-------------+----------+------------+
| ADC2        | GPIO SS  |     12     |
+-------------+----------+------------+
| ADC3        | GPIO SS  |     13     |
+-------------+----------+------------+
| ADC4        | AIN14    |     14     |
+-------------+----------+------------+
| ADC5        | AIN9     |     9      |
+-------------+----------+------------+

.. note::
  IO3 and IO5 require both pins to be set for functionality changes.

Release Notes
*************

When debugging on ARC, it is important that the x86 core be started and
running BEFORE attempting to debug on ARC.  This is because the IPM console
calls will hang waiting for the x86 core to clear the communication.

Bibliography
************

.. _Arduino Website: https://www.arduino.cc/en/Main/ArduinoBoard101

.. _schematics: https://www.arduino.cc/en/uploads/Main/Arduino101Schematic.pdf

.. _FlySwatter2 JTAG debugger:
   http://www.tincantools.com/JTAG/Flyswatter2.html

.. _Intel Datasheet:
   http://www.intel.com/content/www/us/en/embedded/products/quark/mcu/se-soc/overview.html

.. _ARM-JTAG-20-10:
   http://www.amazon.com/gp/product/
   B009UEO9ZY/ref=oh_aui_detailpage_o04_s00?ie=UTF8&psc=1