michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: edit the Galileo Platform documentation

Browse source 
Edited for grammar, style, markup, linkage, consistency.
This change was resubmitted to avoid having a nickname as author.

Change-Id: Ie3a1a16c33939062ce2e139024afd2162a0c802d
Signed-off-by: Steve Ballard <stephen.r.ballard@intel.com>
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero 2015-10-14 15:19:43 -05:00 • committed by Anas Nashif
commit 7306a61264
1 changed files with 73 additions and 82 deletions
Download patch file Download diff file Expand all files Collapse all files

155
doc/platform/galileo.rst
View file

@ -6,10 +6,11 @@ Platform Configuration: galileo
Overview Overview
******** ********
The galileo platform configuration is used by Zephyr applications Developers can use the galileo platform configuration
that run on Galileo (Gen 1 or Gen 2) Development Boards. to build a |codename| that runs on a Galileo Development Board (Gen 1 or Gen 2).
It provides support for a Quark CPU and the following devices: This platform configuration enables kernel support for the board's Quark CPU,
along with the following devices:
* High Precision Event Timer (HPET) * High Precision Event Timer (HPET)
@ -17,43 +18,38 @@ It provides support for a Quark CPU and the following devices:
* Serial Ports in Polling and Interrupt Driven Modes * Serial Ports in Polling and Interrupt Driven Modes
See `Procedures`_ for using third-party tools to load See `Procedures`_ for using third-party tools to load an image onto the target.
a Zephyr application image on the target.
.. note:: .. note::
This platform configuration may work with similar boards, This platform configuration may work with similar boards
but they are not officially supported. that are not officially supported.
Supported Boards Supported Boards
**************** ****************
This section either provides links to, or describes the physical This section provides information about the physical characteristics of boards
characteristics of the boards that are supported by the galileo that the galileo platform configuration supports.
platform configuration. Subsections provide information on pin names, Subsections contain detailed information on pin names, jumper settings, memory mappings,
jumper settings, memory mappings and board component layout. and board component layout.
Pin Names Pin Names
========= =========
Refer to page 46 of the Document Number: 329676-001US For a component layout diagram showing pin names, see page 46 of the
Intel® Quark SoC X1000 Datasheet for a component layout `Intel® Quark SoC X1000 Datasheet`_.
diagram. Click the link to open the `Intel® Galileo Datasheet`_.
.. _Intel® Galileo Datasheet: http://www.intel.com/newsroom/kits/quark/galileo/pdfs/Intel_Galileo_Datasheet.pdf See also the `Intel® Galileo Datasheet`_.
Also, refer to page 9 of the For the Galileo Board Connection Diagram see page 9 of the `Intel® Galileo Board User Guide`_.
`Intel® Galileo Board User Guide`_.
.. _Intel® Galileo Board User Guide: http://download.intel.com/support/galileo/sb/galileo_boarduserguide_330237_001.pdf
Jumpers & Switches Jumpers & Switches
================== ==================
The Zephyr kernel uses the Galileo default jumper settings except The kernel uses the Galileo default jumper settings except for the IOREF jumper,
for the IOREF jumper which must be set to match the external which must be set to match the external operating voltage of either 3.3 V or 5 V.
operating voltage of either 3.3 V or 5 V.
The default switch settings for the Galileo are: The Galileo default switch settings are:
+--------------+--------------+ +--------------+--------------+
| Jumper | Setting | | Jumper | Setting |
@ -63,10 +59,9 @@ The default switch settings for the Galileo are:
| VIN | 5V Jumpered | | VIN | 5V Jumpered |
+--------------+--------------+ +--------------+--------------+
For more information, refer to page 14 of the For more information, see page 14 of the
`Intel® Galileo Board User Guide`_. `Intel® Galileo Board User Guide`_.
.. _Intel® Galileo Board User Guide: http://download.intel.com/support/galileo/sb/galileo_boarduserguide_330237_001.pdf
Memory Mappings Memory Mappings
=============== ===============
@ -77,25 +72,21 @@ addresses and sizes.
For a list of memory mapped registers, see page 868 of the For a list of memory mapped registers, see page 868 of the
`Intel® Quark SoC X1000 Datasheet`_. `Intel® Quark SoC X1000 Datasheet`_.
.. _Intel® Quark SoC X1000 Datasheet: https://communities.intel.com/servlet/JiveServlet/previewBody/21828-102-2-25120/329676_QuarkDatasheet.pdf
Component Layout Component Layout
================ ================
Refer to page 3 of the Intel® Galileo Datasheet for a component layout See page 3 of the Intel® Galileo Datasheet for a component layout
diagram. Click the link to open the `Intel® Galileo Datasheet`_. diagram. Click the link to open the `Intel® Galileo Datasheet`_.
.. _Intel® Galileo Datasheet: http://www.intel.com/newsroom/kits/quark/galileo/pdfs/Intel_Galileo_Datasheet.pdf
For a block diagram refer to page 38 of the `Intel® Quark SoC X1000 Datasheet`_. For a block diagram, see page 38 of the `Intel® Quark SoC X1000 Datasheet`_.
.. _Intel® Quark SoC X1000 Datasheet: https://communities.intel.com/servlet/JiveServlet/previewBody/21828-102-2-25120/329676_QuarkDatasheet.pdf
Supported Features Supported Features
****************** ******************
The galileo platform configuration supports the following The galileo platform configuration supports the following hardware features:
hardware features:
* HPET * HPET
@ -118,50 +109,44 @@ hardware features:
| | | serial port-interrupt | | | | serial port-interrupt |
+------------------+------------+-----------------------+ +------------------+------------+-----------------------+
Other hardware features are not currently supported by the Zephyr kernel. The kernel currently does not support other hardware features.
See the `Intel® Quark Core Hardware Reference Manual`_ for a See the `Intel® Quark Core Hardware Reference Manual`_ for a
complete list of Galileo board hardware features, and the complete list of Galileo board hardware features, and the
`Intel® Quark Software Developer Manual for Linux`_ `Intel® Quark Software Developer Manual for Linux`_
.. _Intel® Quark Core Hardware Reference Manual: http://caxapa.ru/thumbs/497461/Intel_Quark_Core_HWRefMan_001.pdf
.. _Intel® Quark Software Developer Manual for Linux: http://www.intel.com/content/dam/www/public/us/en/documents/manuals/quark-x1000-linux-sw-developers-manual.pdf
PCI PCI
=== ===
The PCI driver initiates a PCI library scan of the PCI bus for any attached devices. The PCI driver initiates a PCI library scan of the PCI bus for any attached devices.
If devices are detected, they are initialized. When detected, the devices are initialized.
.. note:: .. note::
The PCI library does not support 64 bit devices. Memory The PCI library does not support 64-bit devices.
address and size storage only require 32 bit integers. Memory address and size storage only require 32-bit integers.
Serial Port Polling Mode Support Serial Port Polling Mode Support
================================ ================================
The polling mode serial port allows debug output to be printed. The polling mode serial port allows debug output to be printed.
For more information, see Intel® Quark SoC X1000 Datasheet, section `18.3.3 FIFO Polled-Mode Operation`_ For more information, see `Intel® Quark SoC X1000 Datasheet`_,
section 18.3.3 FIFO Polled-Mode Operation
.. _18.3.3 FIFO Polled-Mode Operation: https://communities.intel.com/servlet/JiveServlet/previewBody/21828-102-2-25120/329676_QuarkDatasheet.pdf
Serial Port Interrupt Mode Support Serial Port Interrupt Mode Support
================================== ==================================
The interrupt mode serial port is used to provide general serial communication The interrupt mode serial port provides general serial communication
and external communication. and external communication.
For more information, see Intel® Quark SoC X1000 Datasheet, section `21.12.1.4.5 Poll Mode`_ For more information, see `Intel® Quark SoC X1000 Datasheet`_, section 21.12.1.4.5 Poll Mode
.. _21.12.1.4.5 Poll Mode: https://communities.intel.com/servlet/JiveServlet/previewBody/21828-102-2-25120/329676_QuarkDatasheet.pdf
Interrupt Controller Interrupt Controller
==================== ====================
The galileo platform configuration uses the Zephyr kernel static The galileo platform configuration uses the kernel's static
Interrupt Descriptor Table (IDT) to program the Interrupt Descriptor Table (IDT) to program the
Advanced Programmable Interrupt Controller (APIC) Advanced Programmable Interrupt Controller (APIC)
interrupt redirection table. interrupt redirection table.
@ -172,15 +157,15 @@ Interrupts
+-------+-----------+------------------+-------------------------------+ +-------+-----------+------------------+-------------------------------+
| IRQ | Name | Remarks | Used by Zephyr Kernel | | IRQ | Name | Remarks | Used by Zephyr Kernel |
+=======+===========+==================+===============================+ +=======+===========+==================+===============================+
| 17 | INTB | UART | serial port, when used in | | 17 | INTB | UART | serial port when used in |
| | | | interrupt mode | | | | | interrupt mode |
+-------+-----------+------------------+-------------------------------+ +-------+-----------+------------------+-------------------------------+
| 20 | timer | HPET | timer driver | | 20 | timer | HPET | timer driver |
+-------+-----------+------------------+-------------------------------+ +-------+-----------+------------------+-------------------------------+
.. note:: .. note::
The galileo platform configuration does not support The galileo platform configuration does not support interrupt sharing.
interrupt sharing, for example, two PCI devices can not use same IRQ. For example, two PCI devices cannot use the same IRQ.
Configuration Options Configuration Options
===================== =====================
@ -199,8 +184,7 @@ configuration uses HPET as a system clock timer.
Procedures Procedures
********** **********
Use the following procedures for booting a project on Use the following procedures for booting an image on a Galileo board.
a Galileo board.
* `Creating a GRUB2 Boot Loader Image from a Linux Host`_ * `Creating a GRUB2 Boot Loader Image from a Linux Host`_
@ -213,31 +197,29 @@ Creating a GRUB2 Boot Loader Image from a Linux Host
==================================================== ====================================================
Create a GRUB2 boot loader image needed later to load Create a GRUB2 boot loader image needed later to load
a project image on to a Galileo board. the application's image onto a Galileo board.
Prerequisite The tested configuration uses:
------------
* The Linux host computer is running Ubuntu 12.04. * Linux host computer running Ubuntu 12.04.
* The GNU EFI development libraries (version 3.0u) is installed. * GNU EFI development libraries (version 3.0u).
* The GRUB 2.0 source code is available. * GRUB 2.0 source code.
.. note: .. note:
Only the specified release of the GRUB2 tarball works with the Only the specified release of the GRUB2 tarball works with the
galileo platform configuration. galileo platform configuration.
* The Zephyr application image is available in the project directory. * The appropriate image in the project directory.
Steps Steps
----- -----
1. Install the required development packages on the host computer. 1. Install the required development packages on the host computer.
a. Open a web browser and download the GNU EFI development a. Open a web browser and download the GNU EFI development libraries:
libraries from the following website:
https://launchpad.net/ubuntu/+source/gnu-efi/3.0u+debian-1ubuntu2~12.04.0/+build/5052631 https://launchpad.net/ubuntu/+source/gnu-efi/3.0u+debian-1ubuntu2~12.04.0/+build/5052631
The source code is unpacked to the ~/grub-2.00 directory. The source code is unpacked to the ~/grub-2.00 directory.
@ -310,19 +292,20 @@ following instructions apply to both devices.
Prerequisites Prerequisites
------------- -------------
* There is access to a Windows host. * Access to a Windows host.
* The stripped project image and the GRUB2 image have been copied * Access to the stripped project image and the GRUB2 image
which have been previously copied
from your Linux host to your Windows host. from your Linux host to your Windows host.
* There is a serial port for communication. * Access to a serial port for communication.
Steps Steps
----- -----
1. Insert the boot device into the Windows host computer, 1. Insert the boot device into the Windows host computer;
and make note of the Drive letter assigned to the device. make note of the Drive letter assigned to the device.
2. In the :guilabel:`Windows Computer` folder, right click the boot 2. In the :guilabel:`Windows Computer` folder, right click the boot
device and select :guilabel:`Format`. device and select :guilabel:`Format`.
@ -330,18 +313,20 @@ Steps
3. Format the boot device with the FAT file system. 3. Format the boot device with the FAT file system.
This is typically the default file system type on Windows. This is typically the default file system type on Windows.
4. Double click the formatted device to open it. 4. Double-click the formatted device to open it.
5. Create the following directory tree on the device:: 5. Create the following directory tree on the device:
`-- F: ::
-- F:
|-- efi |-- efi
| |-- boot | |-- boot
‘-- kernel ‘-- kernel
6. Copy the images to the directory tree. 6. Copy the images to the directory tree.
a. For a microkernel image, copy the file :file:`microkernel.strip` a. For a microkernel image: copy the file :file:`microkernel.strip`
to the kernel directory. to the kernel directory.
b. Alternatively, for a nanokernel image, copy the file b. Alternatively, for a nanokernel image, copy the file
@ -371,7 +356,7 @@ Steps
multiboot /kernel/nanokernel.strip multiboot /kernel/nanokernel.strip
} }
The device is ready to use to boot the board. The image on the SD-micro card or USB flash drive is now ready for use to boot the board.
Booting the Galileo Board Booting the Galileo Board
@ -391,7 +376,7 @@ Prerequisites
* The automatically created stripped Zephyr application image is * The automatically created stripped Zephyr application image is
in the project directory. in the project directory.
* There is a serial port for communication. * A serial port is available for communication.
.. note:: .. note::
For details on how to connect and configure the serial port, For details on how to connect and configure the serial port,
@ -423,18 +408,18 @@ Steps
grub.efi grub.efi
GRUB2 starts, and a menu shows entries for the items you added GRUB2 starts and a menu shows entries for the items you added
to the :file:`file grub.cfg`. to the :file:`file grub.cfg`.
5. Select the image you want to boot and press :guilabel:`Enter`. 5. Select the image you want to boot and press :guilabel:`Enter`.
When the boot process finishes, you have finished booting the When the boot process completes, you have finished booting the
Zephyr application image. Zephyr application image.
Known Problems and Limitations Known Problems and Limitations
****************************** ******************************
There is no support for the following: At this time, the kernel does not support the following:
* Isolated Memory Regions * Isolated Memory Regions
* Serial port in Direct Memory Access (DMA) mode * Serial port in Direct Memory Access (DMA) mode
@ -447,23 +432,29 @@ There is no support for the following:
Bibliography Bibliography
************ ************
1. `Intel® Galileo Datasheet`_. 1. `Intel® Galileo Datasheet`_, Order Number: 329681-001US
.. _Intel® Galileo Datasheet: http://www.intel.com/newsroom/kits/quark/galileo/pdfs/Intel_Galileo_Datasheet.pdf .. _Intel® Galileo Datasheet:
http://www.intel.com/newsroom/kits/quark/galileo/pdfs/Intel_Galileo_Datasheet.pdf
2. `Intel® Galileo Board User Guide`_. 2. `Intel® Galileo Board User Guide`_.
.. _Intel® Galileo Board User Guide: http://download.intel.com/support/galileo/sb/galileo_boarduserguide_330237_001.pdf .. _Intel® Galileo Board User Guide:
http://download.intel.com/support/galileo/sb/galileo_boarduserguide_330237_001.pdf
3. `Intel® Quark SoC X1000 Datasheet`_. 3. `Intel® Quark SoC X1000 Datasheet`_, Order Number: 329676-001US
.. _Intel® Quark SoC X1000 Datasheet: https://communities.intel.com/servlet/JiveServlet/previewBody/21828-102-2-25120/329676_QuarkDatasheet.pdf .. _Intel® Quark SoC X1000 Datasheet:
https://communities.intel.com/servlet/JiveServlet/previewBody/
21828-102-2-25120/329676_QuarkDatasheet.pdf
4. `Intel® Quark Core Hardware Reference Manual`_. 4. `Intel® Quark Core Hardware Reference Manual`_.
.. _Intel® Quark Core Hardware Reference Manual: http://caxapa.ru/thumbs/497461/Intel_Quark_Core_HWRefMan_001.pdf .. _Intel® Quark Core Hardware Reference Manual:
http://caxapa.ru/thumbs/497461/Intel_Quark_Core_HWRefMan_001.pdf
5. `Intel® Quark Software Developer Manual for Linux`_. 5. `Intel® Quark Software Developer Manual for Linux`_.
.. _Intel® Quark Software Developer Manual for Linux: http://www.intel.com/content/dam/www/public/us/en/documents/manuals/quark-x1000-linux-sw-developers-manual.pdf .. _Intel® Quark Software Developer Manual for Linux:
http://www.intel.com/content/dam/www/public/us/en/documents/manuals/
quark-x1000-linux-sw-developers-manual.pdf