michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Edit arduino_101.rst for spelling, grammar, consistency

Browse source 
Minor ReST syntax and consistency errors fixed.

Change-Id: Ia53ffc3303d1fb75dc513ae1d7f53301d8c874e3
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
L.S. Cook 2016-02-16 11:03:08 -08:00 • committed by Gerrit Code Review
commit 7c2a12f6a5
1 changed files with 92 additions and 88 deletions
Download patch file Download diff file Expand all files Collapse all files

180
doc/board/arduino_101.rst
View file

@ -6,15 +6,16 @@ Arduino 101
Overview Overview
******** ********
The Arduino 101 board is an Arduino product that uses the Intel Quark SE The Arduino 101 board is an Arduino product with an Intel Quark SE
processor. As an unsupported configuration, the Zephyr Project is able to be processor. Zephyr can be flashed to an Arduino 101 for experimentation
flashed to an Arduino 101 for experimentation and testing purposes. and testing purposes; keep in mind this is configuration is unsupported
by Arduino.
As the Quark SE contains both an ARC and an X86 core, a developer will need to The Quark SE contains both an ARC and an X86 core, so be sure to
flash an ARC and an X86 image to use both. Developers can use the flash an ARC and an X86 image if you wish to use both. Either **arduino_101**
**arduino_101** and **arduino_101_sss** board configurations to build a Zephyr (for x86) or **arduino_101_sss** (for ARC) board configurations work to build
Kernel that can be flashed and run on the Arduino 101 platform. The default a Zephyr Kernel that can be flashed to and run on the Arduino 101 platform.
configuration for Arduino 101 boards can be found in 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_defconfig` for the X86 and
:file:`boards/arduino_101_sss/arduino_101_sss_defconfig` for the ARC. :file:`boards/arduino_101_sss/arduino_101_sss_defconfig` for the ARC.
@ -22,15 +23,15 @@ Board Layout
************ ************
General information for the board can be found at the `Arduino website`_, General information for the board can be found at the `Arduino website`_,
which includes both `schematics`_ and BRD files. which also includes `schematics`_ and BRD files.
Supported Features Supported Features
****************** ******************
The Zephyr kernel supports multiple hardware features on the Arduino 101 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 through the use of drivers. Some drivers are functional on the x86 side only,
only on the ARC side, and a few functional on both sides. The below table some on the ARC side only, and a few are functional on both sides. The table
breaks down which drivers and functionality can be found on which architectures: below shows which drivers and functionality can be found on which architectures:
+-----------+------------+-----+-----+-----------------------+ +-----------+------------+-----+-----+-----------------------+
| Interface | Controller | ARC | x86 | Driver/Component | | Interface | Controller | ARC | x86 | Driver/Component |
@ -56,10 +57,11 @@ breaks down which drivers and functionality can be found on which architectures:
Flashing Arduino 101 for Zephyr Flashing Arduino 101 for Zephyr
******************************* *******************************
For the use of this tutorial, the sample application hello_world will be The sample hello_world application used in this tutorial can be
used found in :file:`$ZEPHYR_BASE/samples/hello_world/nanokernel`. found in :file:`$ZEPHYR_BASE/samples/hello_world/nanokernel`.
Use the following procedures for booting an image on a Arduino 101 board. To boot an image on a Arduino 101 board, follow the steps in this
section:
.. contents:: Procedures .. contents:: Procedures
:depth: 1 :depth: 1
@ -76,18 +78,19 @@ pieces of hardware are required.
* ARM Micro JTAG Connector, Model: `ARM-JTAG-20-10`_ * ARM Micro JTAG Connector, Model: `ARM-JTAG-20-10`_
* While using the USB port for power does work, it is recommended that * The USB port for power will work; however, we recommend the 7V-12V barrel
the 7V-12V barrel connector be used when working with the JTAG connector. connector be used when working with the JTAG connector.
* :ref:`The Zephyr SDK <zephyr_sdk>` * :ref:`The Zephyr SDK <zephyr_sdk>`
* If you wish to grab any data off the serial port, you will need a TTY to USB * 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 adaptor. Two kinds the Zephyr team has tested and found to work are listed
will require male to male jumper cables to connect to the Arduino 101 board. here. Both require male-to-male jumper cables in order to connect to the
Arduino 101 board.
1. `USB to TTL Serial Cable`_ #. `USB to TTL Serial Cable`_
2. FTDI USB to TTL Serial Part #TTL-232R-3V3 #. FTDI USB to TTL Serial Part #TTL-232R-3V3
http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm
Connecting JTAG to Arduino 101 Connecting JTAG to Arduino 101
@ -95,15 +98,15 @@ Connecting JTAG to Arduino 101
#. Connect the ARM Micro JTAG Connector to the FlySwatter2. #. Connect the ARM Micro JTAG Connector to the FlySwatter2.
#. Locate the micro JTAG connector on the Arduino 101 board. It can be found #. Locate the micro JTAG connector on the Arduino 101 board. It is
adjacent to the SCL and SDA pins in the Arduino headers. It is highlighted adjacent to the SCL and SDA pins in the Arduino headers, highlighted
as the red square in the figure below. as the red square in the figure below.
.. figure:: figures/arduino_101_01.png .. figure:: figures/arduino_101_01.png
:scale: 50 % :scale: 50 %
:alt: Highlight of the JTAG connector. :alt: Highlight of the JTAG connector.
#. Locate next to the micro JTAG header a small white dot indicating the #. Beside the micro JTAG header is a small white dot indicating the
location of pin 0 on the header. The orange arrow on the figure points to location of pin 0 on the header. The orange arrow on the figure points to
the dot. the dot.
@ -141,25 +144,24 @@ Connecting JTAG to Arduino 101
Making a Backup Making a Backup
=============== ===============
Before continuing, it is worth considering the creation of a backup Before continuing, consider creating a backup image of the ROM device as
image of the ROM device as it stands today. This would be necessary if you it stands today. This would be necessary if you wanted to run Arduino sketches
ever decide to run Arduino sketches on the hardware again as the Arduino IDE on the hardware again, as the Arduino IDE requires updating via a USB flashing
requires updating via a USB flashing method that is not currently supported method that is not currently supported by Zephyr.
by Zephyr.
Typically Arduino hardware can re-program the Bootloader through connecting Typically Arduino hardware can re-program the Bootloader by connecting
the ICSP header and issuing the "Burn Bootloader" option from the Arduino the ICSP header and issuing the "Burn Bootloader" option from the Arduino
IDE. On the Arduino 101, this option is not currently functional. IDE. On the Arduino 101, this option is not currently functional.
#. Make sure the Zephyr SDK has been installed on your platform. #. Confirm the Zephyr SDK has been installed on your platform.
#. Open a terminal window #. Open a terminal window.
#. Source the :file:`zephyr-env.sh` file. #. Source the :file:`zephyr-env.sh` file.
#. Change directories to :file:`$ZEPHYR_BASE`. #. Change directories to :file:`$ZEPHYR_BASE`.
#. In the termminal window , enter: #. In the terminal window, enter:
.. code-block:: console .. code-block:: console
@ -167,25 +169,26 @@ IDE. On the Arduino 101, this option is not currently functional.
.. note:: .. note::
This will cause the system to dump two files in your ZEPHYR_BASE: This command tells the JTAG to dump two files in your :file:`$ZEPHYR_BASE`:
A101_BOOT.bin and A101_OS.bin. These contain copies of the original directory: :file:`A101_BOOT.bin` and :file:`A101_OS.bin`. These contain copies
flash that can be used to restore the state to factory conditions. of the original flash, which can be used to restore the state of the board to
factory conditions.
At this point you have now created a backup for the Arduino 101. Done! You have finished creating a backup for the Arduino 101.
Restoring a Backup Restoring a Backup
================== ==================
#. Make sure the Zephyr SDK has been installed on your development #. Confirm the Zephyr SDK has been installed on your development
environment. environment.
#. Open a terminal window #. Open a terminal window.
#. Source the :file:`zephyr-env.sh` file. #. Source the :file:`zephyr-env.sh` file.
#. Change directories to $ZEPHYR_BASE. #. Change directories to :file:`$ZEPHYR_BASE`.
#. In the termminal window , enter: #. In the terminal window, enter:
.. code-block:: console .. code-block:: console
@ -193,39 +196,40 @@ Restoring a Backup
.. note:: .. note::
This script expects two files in your :file:`$ZEPHYR_BASE` with titles of This script expects two files in your :file:`$ZEPHYR_BASE` directory
:file:`A101_OS.bin` and :file:`A101_BOOT.bin`. named :file:`A101_OS.bin` and :file:`A101_BOOT.bin`.
Flashing an Application to Arduino 101 Flashing an Application to Arduino 101
====================================== ======================================
By default, the Arduino 101 comes with an X86 and ARC image ready to run. Both 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 images can be replaced by Zephyr OS image by following the steps below. When
where only an X86 image is needed or wanted it is important to disable the only the X86 image is needed or wanted, it is important to disable the ARC
ARC processor, as the X86 OS will appear to hang waiting for the ARC processor. processor; 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 Details on how to disable the ARC can be found in the `Debugging on Arduino 101`_
section. section.
Flashing the ROM Flashing the ROM
================ ================
The default boot ROM used by the Arduino 101 requires that any binary to run The default boot ROM used by the Arduino 101 requires that any binary
be authorized. Currently the Zephyr project is not supported by this ROM. To 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 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 needs to be flashed just once. To flash a Zephyr-compatible boot ROM, use
zflash to flash the :file:`quark_se_rom.bin` to the board. :command:`zflash` to flash the :file:`quark_se_rom.bin` to the board.
.. note:: .. note::
This will cause the Arduino 101 board to no longer run an Arduino sketch
or work with the Arduino IDE. This will cause the Arduino 101 board to lose Arduino sketch functionality
and it will no longer work with the Arduino IDE.
#. Source the :file:`zephyr-env.sh` file. #. Source the :file:`zephyr-env.sh` file.
#. Change directories to $ZEPHYR_BASE. #. Change directories to :file:`$ZEPHYR_BASE`.
#. The Zephyr Project has included a pre-compiled version of a bootloader for #. The Zephyr Project includes a pre-compiled version of a bootloader for
general use on the Arduino 101. Details about how to build your own general use on the Arduino 101. Details for how to build your own
bootloader can be found in the bootloader can be found in the
:file:`$ZEPHYR_BASE/boards/arduino_101/support/README` :file:`$ZEPHYR_BASE/boards/arduino_101/support/README`
@ -234,14 +238,14 @@ zflash to flash the :file:`quark_se_rom.bin` to the board.
$ cd $ZEPHYR_BASE/boards/arduino_101/support $ cd $ZEPHYR_BASE/boards/arduino_101/support
$ sudo -E ./arduino_101_load.sh rom $ sudo -E ./arduino_101_load.sh rom
This script will flash the boot rom located in This script will flash the boot ROM located in
:file:`$ZEPHYR_BASE/boards/arduino_101/support/quark_se_rom.bin` to the :file:`$ZEPHYR_BASE/boards/arduino_101/support/quark_se_rom.bin` to the
Arduino 101 device, overwriting the original shipping ROM. Arduino 101 device, overwriting the original shipping ROM.
Flashing an ARC Kernel Flashing an ARC Kernel
====================== ======================
#. Make sure the binary image has been built. Change directories to your local #. Make sure the binary image has been built. Change directories to your local
checkout copy of Zephyr, and run: checkout copy of Zephyr, and run:
.. code-block:: console .. code-block:: console
@ -262,13 +266,13 @@ Flashing an ARC Kernel
arduino_101_sss and the ARCH type is set to arc. arduino_101_sss and the ARCH type is set to arc.
Congratulations you have now flashed the hello_world image to the ARC Congratulations, you have now flashed the hello_world image to the ARC
processor. processor.
Flashing an x86 Kernel Flashing an x86 Kernel
====================== ======================
#. Make sure the binary image has been built. Change directories to your local #. Make sure the binary image has been built. Change directories to your local
checkout copy of Zephyr, and run: checkout copy of Zephyr, and run:
.. code-block:: console .. code-block:: console
@ -298,12 +302,12 @@ 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 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. 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 #. Build the binary for your application on the architecture you wish to
debug. Alternatively, use the instructions above as template for testing. debug. Alternatively, use the instructions above as template for testing.
When debugging on ARC, you will need to enable the ARC_INIT_DEBUG When debugging on ARC, you will need to enable the :option:`ARC_INIT_DEBUG`
configuration option in your X86 PRJ file. Details of this flag can be 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 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 force the ARC processor to halt on bootstrap, giving the debugger a chance
at connecting and controlling the hardware. at connecting and controlling the hardware.
@ -317,27 +321,26 @@ for ARCH=x86 if you wish to debug on the x86 core.
.. note:: .. note::
By enabling CONFIG_ARC_INIT, you ::MUST:: flash both an ARC and an X86 By enabling :option:`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 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. at boot while it is waiting for the ARC to finish initialization.
2. Open two terminal windows #. Open two terminal windows.
3. In terminal window 1, type: #. In terminal window 1, type:
.. code-block:: console .. code-block:: console
$ cd $ZEPHYR_BASE/samples/hello_world/nanokernel $ cd $ZEPHYR_BASE/samples/hello_world/nanokernel
$ make BOARD=arduino_101 debug $ make BOARD=arduino_101 debugserver
These commands will start an openocd session that creates a local telnet These commands will start an ``openocd`` session with a local telnet
server (on port 4444 for direct openocd commands to be issued), and a 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 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 interface until you are done debugging, at which point you can press :kbd:`Ctrl+C`
to shutdown everything. to shutdown everything.
4. Start GDB in terminal window 2
#. Start GDB in terminal window 2:
* To debug on x86: * To debug on x86:
@ -349,7 +352,7 @@ for ARCH=x86 if you wish to debug on the x86 core.
* To debug on ARC: * To debug on ARC:
ARC debugging will require some extra steps and a third terminal. It is ARC debugging will require some extra steps and a third terminal. It is
necessary to use a version of gdb that understands ARC binaries. necessary to use a version of gdb that understands ARC binaries.
Thankfully one is provided with the Zephyr SDK at Thankfully one is provided with the Zephyr SDK at
:envvar:`$ZEPHYR_SDK_INSTALL_DIR` :envvar:`$ZEPHYR_SDK_INSTALL_DIR`
@ -382,6 +385,7 @@ for ARCH=x86 if you wish to debug on the x86 core.
gdb$ continue gdb$ continue
.. note:: .. note::
In previous versions of the SDK, the gdbserver remote ports were reversed. 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 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. v0.7.2, the gdb ARC server port is 3334, and the X86 port is 3333.
@ -403,25 +407,25 @@ 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 via the UART0 on the board. To read the output, you will need a USB to TTL
serial cable. To enable serial output: serial cable. To enable serial output:
* Connect the Serial Cable RX pin, to the Arduino 101's TX->1 pin. * Connect the Serial Cable RX pin to the Arduino 101's TX->1 pin.
.. figure:: figures/arduino_101_03.png .. figure:: figures/arduino_101_03.png
:scale: 50 % :scale: 50 %
:alt: Image for pin positions and serial output :alt: Image for pin positions and serial output
* Connect the Serial Cable TX pin, to the Arduino 101's RX<-0 pin. * Connect the Serial Cable TX pin to the Arduino 101's RX<-0 pin.
.. figure:: figures/arduino_101_04.png .. figure:: figures/arduino_101_04.png
:scale: 50 % :scale: 50 %
:alt: Image for pin positions and serial output :alt: Image for pin positions and serial output
* Connect the Serial Cable GND pin, to the Arduino 101's GND pin. * Connect the Serial Cable GND pin to the Arduino 101's GND pin.
.. figure:: figures/arduino_101_05.png .. figure:: figures/arduino_101_05.png
:scale: 50 % :scale: 50 %
:alt: Image for pin positions and serial output :alt: Image for pin positions and serial output
Once connected, on your development environment you will need to: Once connected, on your development environment, you will need to:
* Open a serial port emulator (i.e. on Linux minicom, screen, etc) * Open a serial port emulator (i.e. on Linux minicom, screen, etc)
@ -439,8 +443,8 @@ Arduino 101 Pinout
****************** ******************
When using the Zephyr kernel, the pinout mapping for the Arduino 101 becomes a 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 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 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 implementation, what valid options can be configured, and where things map can
be found in the :file:`boards/arduino_101/pinmux.c`. be found in the :file:`boards/arduino_101/pinmux.c`.
@ -498,7 +502,7 @@ Release Notes
************* *************
When debugging on ARC, it is important that the x86 core be started and 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 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. calls will hang waiting for the x86 core to clear the communication.
Bibliography Bibliography