doc: fix .rst files canonical heading order
The headings on some .rst files were not following the expected
heading order of using # for h1, * for h2, = for h3, and - for h4
This patch fixes that, and the doc/templates/*.tmpl files created
for folks to use as templates for creating board and sample docs.
Change-Id: I0263b005648558d5ea41a681ceaa4798c9594dd9
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
diff --git a/boards/arm/qemu_cortex_m3/doc/board.rst b/boards/arm/qemu_cortex_m3/doc/board.rst
index 30dcc82..8d53dcf 100644
--- a/boards/arm/qemu_cortex_m3/doc/board.rst
+++ b/boards/arm/qemu_cortex_m3/doc/board.rst
@@ -4,7 +4,7 @@
##############################
Overview
-========
+********
The Zephyr kernel uses the qemu_cortex_m3 board configuration to emulate the TI
LM3S6965 platform running on QEMU. It provides support for an ARM Cortex-M3 CPU
@@ -19,9 +19,9 @@
with an actual ti_lm3s6965 hardware system, or any other hardware system.
Hardware
-========
+********
Supported Features
-------------------
+==================
The qemu_cortex_m3 board configuration supports the following hardware features:
@@ -40,20 +40,20 @@
The kernel currently does not support other hardware features on this platform.
Devices
---------
+========
System Clock
-~~~~~~~~~~~~
+------------
The qemu_cortex_m3 board configuration uses a system clock frequency of 12 MHz.
Serial Port
-~~~~~~~~~~~
+-----------
The qemu_cortex_m3 board configuration uses a single serial communication
channel with the CPU's UART0.
Known Problems or Limitations
-------------------------------
+==============================
The following platform features are unsupported:
@@ -63,7 +63,7 @@
* Writing to the hardware's flash memory
References
-==========
+**********
1. The Definitive Guide to the ARM Cortex-M3, Second Edition by Joseph Yiu (ISBN
978-0-12-382090-7)
diff --git a/boards/arm/v2m_beetle/doc/v2m_beetle.rst b/boards/arm/v2m_beetle/doc/v2m_beetle.rst
index 54f90da..6f9d539 100644
--- a/boards/arm/v2m_beetle/doc/v2m_beetle.rst
+++ b/boards/arm/v2m_beetle/doc/v2m_beetle.rst
@@ -4,7 +4,7 @@
##############
Overview
-========
+********
The v2m_beetle board configuration is used by Zephyr applications that run on
the V2M Beetle board. It provides support for the Beetle ARM Cortex-M3 CPU and
@@ -24,7 +24,7 @@
More information about the board can be found at the `V2M Beetle Website`_.
Hardware
-========
+********
ARM V2M BEETLE provides the following hardware components:
@@ -49,7 +49,7 @@
Supported Features
--------------------
+===================
The v2m_beetle board configuration supports the following hardware features:
@@ -83,7 +83,7 @@
boards/arm/v2m_beetle/v2m_beetle_defconfig
Interrupt Controller
---------------------
+====================
Beetle is a Cortex-M3 based SoC and has 15 fixed exceptions and 45 IRQs.
@@ -124,7 +124,7 @@
+------+------------+----------------+--------------------------+
Pin Mapping
------------
+===========
The ARM V2M Beetle Board has 4 GPIO controllers. These controllers are responsible for pin muxing, input/output, pull-up, etc.
@@ -190,27 +190,27 @@
For mode details please refer to `Beetle Technical Reference Manual (TRM)`_.
System Clock
-------------
+============
V2M Beetle has one external and two on-chip oscillators. The slow clock is
32.768 kHz, and the main clock is 24 MHz. The processor can set up PLL to drive
the master clock.
Serial Port
------------
+===========
The ARM Beetle processor has two UARTs. Both the UARTs have only two wires for
RX/TX and no flow control (CTS/RTS) or FIFO. The Zephyr console output, by
default, is utilizing UART1.
Programming and Debugging
-=========================
+*************************
Flashing
---------
+========
CMSIS DAP
-^^^^^^^^^
+---------
V2M Beetle provides:
@@ -223,7 +223,7 @@
to `CMSIS-DAP Website`_.
Flashing an application to V2M Beetle
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------------------
The sample application hello_world is being used in this tutorial:
diff --git a/boards/boards.rst b/boards/boards.rst
index 626bb26..08d683f 100644
--- a/boards/boards.rst
+++ b/boards/boards.rst
@@ -5,7 +5,7 @@
X86 Boards
-==========
+**********
.. toctree::
:maxdepth: 1
@@ -14,7 +14,7 @@
x86/**/*
ARM Boards
-==========
+**********
.. toctree::
:maxdepth: 1
@@ -23,7 +23,7 @@
arm/**/*
ARC Boards
-==========
+**********
.. toctree::
:maxdepth: 1
diff --git a/boards/x86/qemu_x86/doc/board.rst b/boards/x86/qemu_x86/doc/board.rst
index 5cafffc..a49727e 100644
--- a/boards/x86/qemu_x86/doc/board.rst
+++ b/boards/x86/qemu_x86/doc/board.rst
@@ -4,7 +4,7 @@
####################
Overview
-========
+********
The Zephyr Kernel uses the qemu_x86 board configuration to emulate pentium-class
systems running on QEMU.
@@ -17,10 +17,10 @@
Hardware
-========
+********
Supported Features
-------------------
+==================
The qemu_x86 board configuration supports the following hardware features:
@@ -36,15 +36,15 @@
+--------------+------------+-----------------------+
Devices
--------
+=======
HPET System Clock Support
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
The qemu_x86 board configuration uses an HPET clock frequency of 25 MHz.
Serial Port
-~~~~~~~~~~~
+-----------
The qemu_x86 board configuration uses a single serial communication channel that
uses the NS16550 serial driver operating in polling mode. To override, enable
@@ -52,7 +52,7 @@
interrupt-driven.
Known Problems or Limitations
------------------------------
+=============================
The following platform features are unsupported:
diff --git a/boards/x86/quark_d2000_crb/doc/quark_d2000_crb.rst b/boards/x86/quark_d2000_crb/doc/quark_d2000_crb.rst
index cacf735..9eaefae 100644
--- a/boards/x86/quark_d2000_crb/doc/quark_d2000_crb.rst
+++ b/boards/x86/quark_d2000_crb/doc/quark_d2000_crb.rst
@@ -4,7 +4,7 @@
#############################
Overview
-========
+********
The Intel® Quark ™ microcontroller D2000 package is shipped as a 40-pin QFN
component.
@@ -33,7 +33,7 @@
- EEMBC power input header
Hardware
-========
+********
General information for the board can be found at the `Intel Website`_,
which includes both `schematics`_ and BRD files.
@@ -45,7 +45,7 @@
Supported Features
--------------------
+===================
+-----------+------------+-----------------------+
| Interface | Controller | Driver/Component |
@@ -66,7 +66,7 @@
Programming and Debugging
-=========================
+*************************
The D2000 board configuration details are found in the project's tree at
:file:`boards/x86/quark_d2000_crb`.
@@ -78,7 +78,7 @@
$ make BOARD=quark_d2000_crb <make target>
Flashing
---------
+========
#. Since the board has a built-in JTAG; it is possible to flash the device
through the USB only. Set the following jumpers to enable the built-in JTAG:
@@ -106,7 +106,7 @@
$ make BOARD=quark_d2000_crb flash
Debugging
----------
+=========
To debug an application on the Quark D2000 board, follow these steps. As an
example, we are using the hello_world application.
diff --git a/doc/application/application.rst b/doc/application/application.rst
index 28013fc..abc8a31 100644
--- a/doc/application/application.rst
+++ b/doc/application/application.rst
@@ -5,7 +5,7 @@
Overview
-========
+********
The Zephyr Kernel's build system is based on the Kbuild system used in the
Linux kernel.
@@ -54,7 +54,7 @@
Application Structure
-=====================
+*********************
Create one directory for your application and a sub-directory for the
@@ -94,7 +94,7 @@
Application Definition
-======================
+**********************
An application is integrated into the build system by including the Makefile.inc
file provided.
@@ -133,10 +133,10 @@
Makefiles
-=========
+*********
Overview
---------
+========
The build system defines a set of conventions for the correct use of Makefiles
in the kernel source directories. The correct use of Makefiles is driven by the
@@ -151,7 +151,7 @@
.. _makefile_conventions:
Makefile Conventions
---------------------
+====================
The following conventions restrict how to add modules and Makefiles to the
build system. These conventions ensure the correct implementation of the
@@ -174,7 +174,7 @@
recursion model.
Adding Source Files
--------------------
+===================
The Makefile must refer the source build indirectly, specifying the object file
that results from the source file using the :literal:`obj-y` variable. For
@@ -199,7 +199,7 @@
obj-$(CONFIG_VAR) += <file>.o
Adding Directories
-------------------
+==================
Add a subdirectory to the build system by editing the Makefile in its
directory. The subdirectory is added using the :literal:`obj-y` variable. The
@@ -228,7 +228,7 @@
Application Makefile
-====================
+********************
Create an application Makefile to define basic information, such as the board
configuration used by the application. The build system uses the Makefile to
@@ -277,7 +277,7 @@
include ${ZEPHYR_BASE}/Makefile.inc
Application Configuration
-=========================
+*************************
The application's kernel is configured using a set of configuration options
that can be customized for application-specific purposes.
@@ -300,7 +300,7 @@
inter-dependencies between options, see the :ref:`configuration`.
Default Board Configuration
----------------------------
+===========================
An application's :file:`.conf` file defines its default kernel configuration.
The settings in this file override or augment the board configuration settings.
@@ -348,7 +348,7 @@
.. _override_kernel_conf:
Overriding Default Configuration
---------------------------------
+================================
Override the default board and kernel configuration to temporarily alter the
application's configuration, perhaps to test the effect of a change.
@@ -486,7 +486,7 @@
command line.
Application-Specific Code
-=========================
+*************************
Application-specific source code files are normally added to the application's
:file:`src` directory. If the application adds a large number of files the
@@ -558,7 +558,7 @@
Build an Application
-====================
+********************
The Zephyr build system compiles and links all components of an application
into a single application image that can be run on simulated hardware or real
@@ -596,7 +596,7 @@
when building the application.
Rebuilding an Application
-=========================
+*************************
Application development is usually fastest when changes are continually tested.
Frequently rebuilding your application makes debugging less painful
@@ -640,7 +640,7 @@
Run an Application
-==================
+******************
An application image can be run on real or emulated hardware. The kernel has
built-in emulator support for QEMU. It allows you to run and test an application
@@ -668,7 +668,7 @@
redisplays.
Application Debugging
-=====================
+*********************
This section is a quick hands-on reference to start debugging your
application with QEMU. Most content in this section is already covered on
diff --git a/doc/porting/application.rst b/doc/porting/application.rst
index f61ba37..5eb53f1 100644
--- a/doc/porting/application.rst
+++ b/doc/porting/application.rst
@@ -17,7 +17,7 @@
API Changes
-===========
+***********
As described in the section :ref:`kernel_api_changes` the kernel now has one
unified and consistent API with new naming.
@@ -28,7 +28,7 @@
application to the new kernel.
Same Arguments
---------------
+==============
In many cases, a simple search and replace is enough to move from the legacy to
the new APIs, for example:
@@ -37,7 +37,7 @@
* :cpp:func:`task_sem_count_get()` -> :cpp:func:`k_sem_count_get()`
Additional Arguments
---------------------
+====================
The number of arguments to some APIs have changed,
* :cpp:func:`nano_sem_init()` -> :cpp:func:`k_sem_init()`
@@ -61,7 +61,7 @@
k_sem_init(sem, 0, UINT_MAX);
Return Codes
-------------
+============
Many kernel APIs now return 0 to indicate success and a non-zero error code
to indicate the reason for failure. You should pay special attention to this
@@ -72,7 +72,7 @@
Application Porting
-===================
+*******************
The existing :ref:`synchronization_sample` from the Zephyr tree will be used to
guide you with porting a legacy application to the new kernel.
@@ -85,7 +85,7 @@
:lines: 9-
Porting a Nanokernel Application
----------------------------------
+=================================
Below is the code for the application using the legacy kernel:
@@ -95,7 +95,7 @@
:lines: 9-
Porting a Microkernel Application
----------------------------------
+=================================
The MDEF feature of the legacy kernel has been eliminated. Consequently, all
kernel objects are now defined directly in code.
diff --git a/doc/subsystems/bluetooth/bluetooth.rst b/doc/subsystems/bluetooth/bluetooth.rst
index 2429310..55770e7 100644
--- a/doc/subsystems/bluetooth/bluetooth.rst
+++ b/doc/subsystems/bluetooth/bluetooth.rst
@@ -46,7 +46,7 @@
* Features, buffer sizes/counts, stack sizes, etc.
Source tree layout
-==================
+******************
The stack is split up as follows in the source tree:
@@ -81,7 +81,7 @@
Extra documentation, such as PICS documents.
Further reading
-===============
+***************
More information on the stack and its usage can be found in the
`wiki <http://wiki.zephyrproject.org/view/Arduino_101#Bluetooth_firmware_for_the_Arduino_101>`_ and the following subsections:
diff --git a/doc/subsystems/bluetooth/gap-pics.rst b/doc/subsystems/bluetooth/gap-pics.rst
index 7b0e66b..bb2f7ed 100644
--- a/doc/subsystems/bluetooth/gap-pics.rst
+++ b/doc/subsystems/bluetooth/gap-pics.rst
@@ -13,7 +13,7 @@
Device Configuration
-====================
+********************
============== ============== =======================================
Parameter Name Selected Description
@@ -25,7 +25,7 @@
Version Configuration
-=====================
+*********************
============== ============== =======================================
Parameter Name Selected Description
@@ -38,7 +38,7 @@
Modes
-=====
+*****
============== ============== =======================================
Parameter Name Selected Description
@@ -56,7 +56,7 @@
Security Aspects
-================
+****************
============== ============== =======================================
Parameter Name Selected Description
@@ -76,7 +76,7 @@
Idle Mode Procedures
-====================
+********************
============== ============== =======================================
Parameter Name Selected Description
@@ -91,7 +91,7 @@
Establishment Procedures
-========================
+************************
============== ============== =======================================
Parameter Name Selected Description
@@ -110,7 +110,7 @@
LE Roles
-========
+********
============== ============== =======================================
Parameter Name Selected Description
@@ -123,7 +123,7 @@
Broadcaster Physical Layer
-==========================
+**************************
============== ============== =======================================
Parameter Name Selected Description
@@ -134,7 +134,7 @@
Broadcaster Link Layer States
-=============================
+*****************************
============== ============== =======================================
Parameter Name Selected Description
@@ -145,7 +145,7 @@
Broadcaster Link Layer Advertising Event Types
-==============================================
+**********************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -156,7 +156,7 @@
Broadcaster Link Layer Advertising Data Types
-=============================================
+*********************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -183,7 +183,7 @@
Broadcaster Connection Modes and Procedures
-===========================================
+*******************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -193,7 +193,7 @@
Broadcaster Broadcasting and Observing Features
-===============================================
+***********************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -203,7 +203,7 @@
Broadcaster Privacy Feature
-===========================
+***************************
============== ============== =======================================
Parameter Name Selected Description
@@ -219,7 +219,7 @@
Observer Physical Layer
-=======================
+***********************
============== ============== =======================================
Parameter Name Selected Description
@@ -230,7 +230,7 @@
Observer Link Layer States
-==========================
+**************************
============== ============== =======================================
Parameter Name Selected Description
@@ -241,7 +241,7 @@
Observer Link Layer Scanning Types
-==================================
+**********************************
============== ============== =======================================
Parameter Name Selected Description
@@ -252,7 +252,7 @@
Observer Connection Modes and Procedures
-========================================
+****************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -262,7 +262,7 @@
Observer Broadcasting and Observing Features
-============================================
+********************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -272,7 +272,7 @@
Observer Privacy Feature
-========================
+************************
============== ============== =======================================
Parameter Name Selected Description
@@ -290,7 +290,7 @@
Peripheral Physical Layer
-=========================
+*************************
============== ============== =======================================
Parameter Name Selected Description
@@ -301,7 +301,7 @@
Peripheral Link Layer States
-============================
+****************************
============== ============== =======================================
Parameter Name Selected Description
@@ -313,7 +313,7 @@
Peripheral Link Layer Advertising Event Types
-=============================================
+*********************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -326,7 +326,7 @@
Peripheral Link Layer Advertising Data Types
-============================================
+********************************************
=============== ============= =======================================
Parameter Name Selected Description
@@ -353,7 +353,7 @@
Peripheral Link Layer Control Procedures
-========================================
+****************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -372,7 +372,7 @@
Peripheral Discovery Modes and Procedures
-=========================================
+*****************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -385,7 +385,7 @@
Peripheral Connection Modes and Procedures
-==========================================
+******************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -399,7 +399,7 @@
Peripheral Bonding Modes and Procedures
-=======================================
+***************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -412,7 +412,7 @@
Peripheral Security Aspects Features
-====================================
+************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -433,7 +433,7 @@
Peripheral Privacy Feature
-==========================
+**************************
============== ============== =======================================
Parameter Name Selected Description
@@ -451,7 +451,7 @@
Peripheral GAP Characteristics
-==============================
+******************************
============== ============== =======================================
Parameter Name Selected Description
@@ -469,7 +469,7 @@
Central Physical Layer
-======================
+**********************
============== ============== =======================================
Parameter Name Selected Description
@@ -480,7 +480,7 @@
Central Link Layer States
-=========================
+*************************
============== ============== =======================================
Parameter Name Selected Description
@@ -493,7 +493,7 @@
Central Link Layer Scanning Types
-=================================
+*********************************
============== ============== =======================================
Parameter Name Selected Description
@@ -504,7 +504,7 @@
Central Link Layer Control Procedures
-=====================================
+*************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -523,7 +523,7 @@
Central Discovery Modes and Procedures
-======================================
+**************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -535,7 +535,7 @@
Central Connection Modes and Procedures
-=======================================
+***************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -551,7 +551,7 @@
Central Bonding Modes and Procedures
-====================================
+************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -563,7 +563,7 @@
Central Security Features
-=========================
+*************************
============== ============== =======================================
Parameter Name Selected Description
@@ -584,7 +584,7 @@
Central Privacy Feature
-=======================
+***********************
============== ============== =======================================
Parameter Name Selected Description
@@ -604,7 +604,7 @@
Central GAP Characteristics
-===========================
+***************************
============== ============== =======================================
Parameter Name Selected Description
@@ -616,7 +616,7 @@
BR/EDR/LE Roles
-===============
+***************
============== ============== =======================================
Parameter Name Selected Description
@@ -629,7 +629,7 @@
Central BR/EDR/LE Modes
-=======================
+***********************
============== ============== =======================================
Parameter Name Selected Description
@@ -644,7 +644,7 @@
Central BR/EDR/LE Idle Mode Procedures
-======================================
+**************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -658,7 +658,7 @@
Central BR/EDR/LE Security Aspects
-==================================
+**********************************
============== ============== =======================================
Parameter Name Selected Description
@@ -669,7 +669,7 @@
Peripheral BR/EDR/LE Modes
-==========================
+**************************
============== ============== =======================================
Parameter Name Selected Description
@@ -684,7 +684,7 @@
Peripheral BR/EDR/LE Security Aspects
-=====================================
+*************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -695,7 +695,7 @@
Central Simultaneous BR/EDR and LE Transports
-=============================================
+*********************************************
============== ============== =======================================
Parameter Name Selected Description
@@ -708,7 +708,7 @@
Peripheral Simultaneous BR/EDR and LE Transports
-================================================
+************************************************
============== ============== =======================================
Parameter Name Selected Description
diff --git a/doc/subsystems/bluetooth/gatt-pics.rst b/doc/subsystems/bluetooth/gatt-pics.rst
index 2e1bb75..292fdb3 100644
--- a/doc/subsystems/bluetooth/gatt-pics.rst
+++ b/doc/subsystems/bluetooth/gatt-pics.rst
@@ -13,7 +13,7 @@
Generic Attribute Profile Role
-==============================
+******************************
============== =========== ============================================
Parameter Name Selected Description
@@ -26,7 +26,7 @@
ATT Bearer Transport
-====================
+********************
============== =========== ============================================
Parameter Name Selected Description
@@ -38,7 +38,7 @@
Generic Attribute Profile Support
-=================================
+*********************************
============== =========== ============================================
Parameter Name Selected Description
@@ -77,7 +77,7 @@
Profile Attribute Types and Formats, by client
-==============================================
+**********************************************
=============== =========== ============================================
Parameter Name Selected Description
@@ -128,7 +128,7 @@
Attribute Profile Support, by Server
-====================================
+************************************
============== =========== ============================================
Parameter Name Selected Description
@@ -167,7 +167,7 @@
Profile Attribute Types and Characteristic Formats
-==================================================
+**************************************************
=============== =========== ============================================
Parameter Name Selected Description
@@ -218,7 +218,7 @@
Generic Attribute Profile Service - SDP Inteoperability
-=======================================================
+*******************************************************
============== =========== ============================================
Parameter Name Selected Description
@@ -231,7 +231,7 @@
Attribute Protocol Transport Security
-=====================================
+*************************************
============== =========== ============================================
Parameter Name Selected Description
@@ -247,7 +247,7 @@
Attribute Protocol Client Messages
-==================================
+**********************************
============== =========== ============================================
Parameter Name Selected Description
@@ -273,7 +273,7 @@
Attribute Protocol Server Messages
-==================================
+**********************************
============== =========== ============================================
Parameter Name Selected Description
@@ -300,7 +300,7 @@
Attribute Protocol Transport
-============================
+****************************
============== =========== ============================================
Parameter Name Selected Description
@@ -312,7 +312,7 @@
Device Configuration
-====================
+********************
============== =========== ============================================
Parameter Name Selected Description
diff --git a/doc/subsystems/bluetooth/l2cap-pics.rst b/doc/subsystems/bluetooth/l2cap-pics.rst
index adea418..2c859f6 100644
--- a/doc/subsystems/bluetooth/l2cap-pics.rst
+++ b/doc/subsystems/bluetooth/l2cap-pics.rst
@@ -6,7 +6,7 @@
* - different than PTS defaults
Device Configuration
-====================
+********************
=============== =========== =======================================
Parameter Name Selected Description
@@ -18,7 +18,7 @@
Roles
-=====
+*****
=============== =========== =======================================
Parameter Name Selected Description
@@ -33,7 +33,7 @@
General Operation
-=================
+*****************
=============== =========== =======================================
Parameter Name Selected Description
@@ -96,7 +96,7 @@
Configurable Parameters
-=======================
+***********************
=============== =========== =======================================
Parameter Name Selected Description
diff --git a/doc/subsystems/bluetooth/sm-pics.rst b/doc/subsystems/bluetooth/sm-pics.rst
index 13a948d..03820a1 100644
--- a/doc/subsystems/bluetooth/sm-pics.rst
+++ b/doc/subsystems/bluetooth/sm-pics.rst
@@ -13,7 +13,7 @@
Connection Roles
-================
+****************
=============== =========== =======================================
Parameter Name Selected Description
@@ -24,7 +24,7 @@
Security Properties
-===================
+*******************
=============== =========== =======================================
Parameter Name Selected Description
@@ -38,7 +38,7 @@
Encryption Key Size
-===================
+*******************
=============== =========== =======================================
Parameter Name Selected Description
@@ -48,7 +48,7 @@
Pairing Method
-==============
+**************
=============== =========== =======================================
Parameter Name Selected Description
@@ -60,7 +60,7 @@
Security Initiation
-===================
+*******************
=============== =========== =======================================
Parameter Name Selected Description
@@ -73,7 +73,7 @@
Signing Algorithm
-=================
+*****************
=============== =========== =======================================
Parameter Name Selected Description
@@ -84,7 +84,7 @@
Key Distribution
-================
+****************
=============== =========== =======================================
Parameter Name Selected Description
diff --git a/doc/subsystems/networking/buffers.rst b/doc/subsystems/networking/buffers.rst
index 1ad8901..e88dd0b 100644
--- a/doc/subsystems/networking/buffers.rst
+++ b/doc/subsystems/networking/buffers.rst
@@ -6,7 +6,7 @@
defined in ``include/net/buf.h``.
Creating buffers
-================
+****************
Network buffers are created by first defining a pool of them:
@@ -48,7 +48,7 @@
FIFOs. These APIs ensure that the buffer chains stay intact.
Common Operations
-=================
+*****************
The network buffer API provides some useful helpers for encoding and
decoding data in the buffers. To fully understand these helpers it's
@@ -92,7 +92,7 @@
whereas Pull is used when decoding data from a buffer.
Reference Counting
-==================
+******************
Each network buffer is reference counted. The buffer is initially
acquired from a free buffers pool by calling :c:func:`net_buf_alloc()`,
diff --git a/doc/subsystems/networking/networking.rst b/doc/subsystems/networking/networking.rst
index 86aa4e2..9763e21 100644
--- a/doc/subsystems/networking/networking.rst
+++ b/doc/subsystems/networking/networking.rst
@@ -39,7 +39,7 @@
* SLIP (for testing with Qemu)
Source tree layout
-==================
+******************
The IP stack source code tree is organized as follows:
diff --git a/doc/subsystems/test/ztest.rst b/doc/subsystems/test/ztest.rst
index 2f21751..196392d 100644
--- a/doc/subsystems/test/ztest.rst
+++ b/doc/subsystems/test/ztest.rst
@@ -99,14 +99,14 @@
*************
Running tests
--------------
+=============
.. doxygengroup:: ztest_test
:project: Zephyr
:content-only:
Assertions
-----------
+==========
These macros will instantly fail the test if the related assertion fails.
When an assertion fails, it will print the current file, line and function,
@@ -127,7 +127,7 @@
:content-only:
Mocking
--------
+=======
These functions allow abstracting callbacks and related functions and
controlling them from specific tests. You can enable the mocking framework by
diff --git a/doc/templates/board.tmpl b/doc/templates/board.tmpl
index 12adad5..1faf29a 100644
--- a/doc/templates/board.tmpl
+++ b/doc/templates/board.tmpl
@@ -1,39 +1,41 @@
+.. _boardname_linkname:
+
[Board Name]
#############
Overview
-========
+********
[A short description about the board, its main features and availability]
Hardware
-=========
+********
[General Hardware information]
Supported Features
-------------------
+==================
[List of supported features and level of support in Zephyr]
Connections and IOs
---------------------
+===================
[Tables describing the board PINs and how they are configured and can be used
to connect external components]
Programming and Debugging
-=========================
+*************************
Flashing
---------
+========
[How to use this board with Zephyr and how to flash a Zephyr binary on this
device]
Debugging
----------
+=========
[ How to debug this board]
References
-==========
+**********
[ Links to external references such as datasheets or additional documentation]
diff --git a/doc/templates/sample.tmpl b/doc/templates/sample.tmpl
index d63a4c6..f27fb78 100644
--- a/doc/templates/sample.tmpl
+++ b/doc/templates/sample.tmpl
@@ -1,29 +1,31 @@
+.. _descriptive_title_link_name:
+
[A Descriptive Title]
#####################
Overview
-========
+********
[A short description about the sample and what it does]
Requirements
-============
+************
[List of required software and hardware components. Provide pointers to
hardware components such as sensors and shields]
Wiring
-======
+******
[For simple projects, a description of how to wire the board for the demo. For
complex projects, provide a graphic with more details, preferably using
Fritzing or some other visualisation tools]
Building and Running
-====================
+********************
[ How to build the sample and how to run it. Pointers to where to find the
sample in the source tree and how to configure it and run it for a specific
target platform]
References
-==========
+**********
[ Links to external references such as datasheets or additional documentation]
diff --git a/samples/basic/blink_led/README.rst b/samples/basic/blink_led/README.rst
index fdf8b79..46344fd 100644
--- a/samples/basic/blink_led/README.rst
+++ b/samples/basic/blink_led/README.rst
@@ -2,7 +2,7 @@
##############
Overview
-========
+********
This is a sample app which blinks a LED using PWM.
@@ -14,23 +14,23 @@
for ever.
Wiring
-======
+******
Arduino 101 and Quark D2000 CRB
--------------------------------
+===============================
You will need to connect the LED to ground and PWM0 via the shield.
You may need a current limiting resistor. See your LED datasheet.
Nucleo_F401RE and Nucleo_L476RG
--------------------------------
+===============================
Connect PWM2(PA0) to LED
Nucleo_F103RB
--------------
+=============
Connect PWM1(PA8) to LED
Building and Running
-====================
+********************
This sample can be built for multiple boards, in this example we will build it
for the arduino_101 board:
diff --git a/samples/basic/blinky/README.rst b/samples/basic/blinky/README.rst
index 9e25b66..49acde0 100644
--- a/samples/basic/blinky/README.rst
+++ b/samples/basic/blinky/README.rst
@@ -2,14 +2,14 @@
##################
Overview
-========
+********
The Blinky example shows how to configure GPIO pins as outputs which can also be
used to drive LEDs on the hardware usually delivered as "User LEDs" on many of
the supported boards in Zephyr.
Requirements
-============
+************
The demo assumes that an LED is connected to one of GPIO lines. The
sample code is configured to work on boards with user defined buttons and that
@@ -22,7 +22,7 @@
Building and Running
-====================
+********************
This samples does not output anything to the console. It can be built and
flashed to a board as follows:
diff --git a/samples/basic/button/README.rst b/samples/basic/button/README.rst
index 0c75e63..bcf9790 100644
--- a/samples/basic/button/README.rst
+++ b/samples/basic/button/README.rst
@@ -2,12 +2,12 @@
###########
Overview
-========
+********
A simple button demo showcasing the use of GPIO input with interrupts.
Requirements
-============
+************
The demo assumes that a push button is connected to one of GPIO lines. The
sample code is configured to work on boards with user defined buttons and that
@@ -34,7 +34,7 @@
Building and Running
-====================
+********************
This sample can be built for multiple boards, in this example we will build it
for the nucleo_f103rb board:
diff --git a/samples/basic/disco/README.rst b/samples/basic/disco/README.rst
index c74087e..228f483 100644
--- a/samples/basic/disco/README.rst
+++ b/samples/basic/disco/README.rst
@@ -2,20 +2,20 @@
##########
Overview
-========
+********
A simple 'disco' demo. The demo assumes that 2 LEDs are connected to
GPIO outputs of the MCU/board.
Wiring
-======
+******
The code may need some work before running on another board: set PORT,
LED1 and LED2 according to the board's GPIO configuration.
Nucleo-64 F103RB/F401RE boards
-------------------------------
+==============================
Connect two LEDs to PB5 and PB8 pins. PB5 is mapped to the
Arduino's D4 pin and PB8 to Arduino's D15. For more details about
@@ -25,7 +25,7 @@
- https://developer.mbed.org/platforms/ST-Nucleo-F401RE/
Arduino 101 (x86)
------------------
+=================
Connect two LEDs to D4 (IO4) and D7 (IO7) pins. The schematics for the Arduino
101 board is available at:
@@ -45,7 +45,7 @@
#define LED2 20
Building and Running
-=====================
+*********************
After startup, the program looks up a predefined GPIO device defined by 'PORT',
and configures pins 'LED1' and 'LED2' in output mode. During each iteration of
@@ -59,21 +59,21 @@
The sample can be found here: :file:`samples/basic/disco`.
Nucleo F103RB
--------------
+=============
.. code-block:: console
$ make BOARD=nucleo_f103rb
Nucleo F401RE
--------------
+=============
.. code-block:: console
$ make BOARD=nucleo_f401re
Arduino 101
-------------
+============
.. code-block:: console
diff --git a/samples/basic/fade_led/README.rst b/samples/basic/fade_led/README.rst
index 2d7b64c..23aa8bf 100644
--- a/samples/basic/fade_led/README.rst
+++ b/samples/basic/fade_led/README.rst
@@ -2,7 +2,7 @@
#############
Overview
-========
+********
This is a sample app which fades a LED using PWM.
@@ -13,24 +13,24 @@
repeat this cycle for ever.
Wiring
-======
+******
Arduino 101 and Quark D2000 CRB
--------------------------------
+===============================
You will need to connect the LED to ground and PWM0 via
the shield. You may need a current limiting resistor. See
your LED datasheet.
Nucleo_F401RE and Nucleo_L476RG
--------------------------------
+===============================
Connect PWM2(PA0) to LED
Nucleo_F103RB
--------------
+=============
Connect PWM1(PA8) to LED
Building and Running
-====================
+********************
This sample can be built for multiple boards, in this example we will build it
for the arduino_101 board:
diff --git a/samples/basic/rgb_led/README.rst b/samples/basic/rgb_led/README.rst
index 6c5d5b5..052e3ff 100644
--- a/samples/basic/rgb_led/README.rst
+++ b/samples/basic/rgb_led/README.rst
@@ -2,7 +2,7 @@
############
Overview
-========
+********
This is a sample app which drives a RGB LED using PWM.
@@ -16,10 +16,10 @@
ever.
Wiring
-======
+******
Arduino 101
------------
+===========
You will need to connect the LED pins to PWM0, PWM1 and PWM2
on arduino 101 via the shield. Depending on what kind of RGB
@@ -31,7 +31,7 @@
on Quark D2000 platform.
Building and Running
-====================
+********************
This samples does not output anything to the console. It can be built and
flashed to a board as follows:
diff --git a/samples/basic/servo_motor/README.rst b/samples/basic/servo_motor/README.rst
index e943a03..a6d9a8d 100644
--- a/samples/basic/servo_motor/README.rst
+++ b/samples/basic/servo_motor/README.rst
@@ -2,7 +2,7 @@
################
Overview
-========
+********
This is a sample app which drives a servo motor using
PWM.
@@ -19,17 +19,17 @@
the app if you are using a different servo motor.
Wiring
-======
+******
Arduino 101 and Quark D2000 CRB
--------------------------------
+===============================
You will need to connect the motor's red wire to 5v,
the black wire to ground and the white wire to PWM 0 via
the shield.
Building and Running
-====================
+********************
This sample can be built for multiple boards, in this example we will build it
for the arduino_101 board:
diff --git a/samples/environmental_sensing/README.rst b/samples/environmental_sensing/README.rst
index 60521f3..88e012f 100644
--- a/samples/environmental_sensing/README.rst
+++ b/samples/environmental_sensing/README.rst
@@ -2,7 +2,7 @@
############################
Overview
-========
+********
This sample implementes a simple environmental sensing service using the Arduino
101 board.
@@ -16,7 +16,7 @@
Environmental Sensing Service.
Requirements
-============
+************
To use this sample, the following hardware is required:
@@ -28,10 +28,10 @@
Wiring
-======
+******
External Wiring
----------------
+===============
The sample uses the HDC1008 sensor for temperature and humidity measurement, and
the BMP280 sensor for pressure measurement. This section describes how to wire
@@ -60,7 +60,7 @@
:alt: Wiring with Arduino 101
Using board sensors
--------------------
+===================
If you do not want to use any external sensors, you can use the Arduino 101's
internal BMI160 sensor to do just temperature readings. To do this, you need to
@@ -74,7 +74,7 @@
on the LCD, as humidity and pressure values will not be available.
Grove LCD
----------
+=========
Using the Grove LCD is optional and it can be disabled by removing the Grove
configuration options from the arc/proj.conf file.
@@ -91,10 +91,10 @@
backlight).
Building and Running
-====================
+********************
Building
---------
+========
This sample builds two applications for both the sensor subsystem (arc) and the
application processor (x86). The resulting images need to be flashed to the
@@ -119,7 +119,7 @@
$ make flash # for flashing with JTAG
Running
---------
+========
The ARC (Sensor Subsystem) program collects temperature, humidity and pressure
data using the sensors API and sends it to the x86 core through an outbound
IPM. The collected data is also displayed on a Grove LCD.
diff --git a/samples/grove/lcd/README.rst b/samples/grove/lcd/README.rst
index c31356c..139d737 100644
--- a/samples/grove/lcd/README.rst
+++ b/samples/grove/lcd/README.rst
@@ -2,13 +2,13 @@
#########
Overview
-========
+********
This sample displays an incrementing counter through the Grove LCD, with
changing backlight.
Requirements
-============
+************
To use this sample, the following hardware is required:
@@ -17,7 +17,7 @@
* `Grove Base Shield`_ [Optional]
Wiring
-======
+******
You will need to connect the Grove LCD via the Grove shield onto a board that
supports Arduino shields.
@@ -37,7 +37,7 @@
Building and Running
-====================
+********************
This sample should work on any board that has I2C enabled and has an Arduino
shield interface. For example, it can be run on the Quark D2000 DevBoard as
diff --git a/samples/hello_world/README.rst b/samples/hello_world/README.rst
index 96311eb..52a25d7 100644
--- a/samples/hello_world/README.rst
+++ b/samples/hello_world/README.rst
@@ -4,7 +4,7 @@
###########
Overview
-========
+********
A simple Hello World example that can be used with any supported board and
prints 'Hello World' to the console. This application can be built into modes:
@@ -12,7 +12,7 @@
* multi threading
Building and Running
-====================
+********************
This project outputs 'Hello World' to the console. It can be built and executed
on QEMU as follows:
@@ -31,7 +31,7 @@
$ make CONF_FILE=prj_single.conf run
Sample Output
--------------
+=============
.. code-block:: console
diff --git a/samples/net/dns_client/README.rst b/samples/net/dns_client/README.rst
index 8bf0182..369cbe7 100644
--- a/samples/net/dns_client/README.rst
+++ b/samples/net/dns_client/README.rst
@@ -2,7 +2,7 @@
######################
Overview
-========
+********
The DNS resolver or DNS client sample application implements a basic
DNS resolver according to RFC 1035. Supported DNS answers are:
@@ -30,7 +30,7 @@
A return code of 0 must be interpreted as success.
Requirements
-============
+************
- net_tools:
@@ -48,7 +48,7 @@
Dnsmasq version 2.76 Copyright (c) 2000-2016 Simon Kelley
Wiring
-======
+******
The ENC28J60 module is an Ethernet device with SPI interface.
The following pins must be connected from the ENC28J60 device to the
@@ -68,14 +68,14 @@
Building and Running
-====================
+********************
Read the :file:`samples/net/dns_client/src/config.h` file.
Change the IP addresses and DNS server port according to the
LAN environment.
Network Configuration
----------------------
+=====================
For example, if your LAN is 192.168.0.0/16, the IPv4 addresses must be
similar to:
@@ -96,7 +96,7 @@
assumes that the DNS server is listening at UDP port 5353.
DNS server
-----------
+==========
The dnsmasq tool may be used for testing purposes. Open a terminal
window and type:
@@ -123,7 +123,7 @@
QEMU x86
---------
+========
Open a terminal window and type:
@@ -149,7 +149,7 @@
$ make run
FRDM K64F
----------
+=========
Open a terminal window and type:
@@ -181,7 +181,7 @@
Once the binary is loaded into the FRDM board, press the RESET button.
Arduino 101
------------
+===========
Open a terminal window and type:
@@ -206,7 +206,7 @@
Once the binary is loaded into the Arduino 101 board, press the RESET button.
Sample Output
--------------
+=============
IPv4 (CONFIG_NET_IPV6=n, CONFIG_NET_IPV4=y)
@@ -221,7 +221,7 @@
Note: IPv6 addresses obtained via dnsmasq and :file:`/etc/hosts`.
Known Issues
-------------
+============
- The above sample contains a rc: -22 (-EINVAL). This is the expected behavior
for that domain name.
diff --git a/samples/net/mbedtls_dtlsclient/README.rst b/samples/net/mbedtls_dtlsclient/README.rst
index 880a593..779900b 100644
--- a/samples/net/mbedtls_dtlsclient/README.rst
+++ b/samples/net/mbedtls_dtlsclient/README.rst
@@ -2,14 +2,14 @@
####################
Overview
-========
+********
This sample code shows a simple DTLS client using mbed TLS on top of Zephyr
Requirements
-============
+************
Building and running
-====================
+********************
Follow the steps for testing :ref:`networking with Qemu <networking_with_qemu>`.
@@ -102,7 +102,7 @@
Reset the board.
References
-==========
+**********
- https://wiki.zephyrproject.org/view/Networking-with-Qemu
- https://tls.mbed.org/
diff --git a/samples/net/mbedtls_dtlsserver/README.rst b/samples/net/mbedtls_dtlsserver/README.rst
index d47c3b6..a52d028 100644
--- a/samples/net/mbedtls_dtlsserver/README.rst
+++ b/samples/net/mbedtls_dtlsserver/README.rst
@@ -2,11 +2,11 @@
############################
Overview
-========
+********
This sample code shows a simple DTLS server using mbedTLS on top of Zephyr.
Building and Running
-====================
+********************
Follow the steps for testing :ref:`networking with Qemu <networking_with_qemu>`.
@@ -103,7 +103,7 @@
the client again.
References
-==========
+**********
* https://wiki.zephyrproject.org/view/Networking-with-Qemu
* https://tls.mbed.org/
diff --git a/samples/net/zperf/README.rst b/samples/net/zperf/README.rst
index d966157..4ec060b 100644
--- a/samples/net/zperf/README.rst
+++ b/samples/net/zperf/README.rst
@@ -2,20 +2,20 @@
################################
Description
-===========
+***********
zperf is a network traffic generator for Zephyr that may be used to
evaluate network bandwidth.
Features
-=========
+*********
- Compatible with iPerf_2.0.5.
- Client or server mode allowed without need to modify the source code.
- Working with task profiler (PROFILER=1 to be set when building zperf)
Supported Boards
-================
+****************
zperf is board-agnostic. However, to run the zperf sample application,
the target platform must provide a network interface supported by Zephyr.
@@ -27,7 +27,7 @@
- QEMU x86
Requirements
-============
+************
- iPerf 2.0.5 installed on the host machine
- Supported board
@@ -36,7 +36,7 @@
to setup the network environment.
Usage
-=====
+*****
If Zephyr acts as a client, iPerf must be executed in server mode.
For example, the following command line must be used for UDP testing:
diff --git a/samples/philosophers/README.rst b/samples/philosophers/README.rst
index 7536472..c398bb6 100644
--- a/samples/philosophers/README.rst
+++ b/samples/philosophers/README.rst
@@ -2,7 +2,7 @@
###################
Overview
-========
+********
An implementation of a solution to the Dining Philosophers problem (a classic
multi-thread synchronization problem). This particular implementation
@@ -36,7 +36,7 @@
(preempt-only) and -7 to -2 (coop-only).
Building and Running
-====================
+********************
This project outputs to the console. It can be built and executed
on QEMU as follows:
@@ -47,7 +47,7 @@
$ make run
Sample Output
--------------
+=============
.. code-block:: console
diff --git a/samples/sensor/apds9960/README.rst b/samples/sensor/apds9960/README.rst
index 597e4c7..089fa02 100644
--- a/samples/sensor/apds9960/README.rst
+++ b/samples/sensor/apds9960/README.rst
@@ -2,7 +2,7 @@
######################
Overview
-========
+********
This sample utilizes APDS-9960 Sensor and reads RGB values from the sensor
then displays the color through the APA102C LED.
@@ -12,7 +12,7 @@
This sample does not use the Zephyr sensor APIs
Wiring
-======
+******
The SparkFun RGB and Gesture Sensor was being used:
@@ -36,7 +36,7 @@
and do not look directly into those LEDs.
Building and Running
-====================
+********************
This sample can be built for multiple boards, in this example we will build it
for the Arduino 101 board:
diff --git a/samples/sensor/magn_polling/README.rst b/samples/sensor/magn_polling/README.rst
index 4fbbd00..8f8bc90 100644
--- a/samples/sensor/magn_polling/README.rst
+++ b/samples/sensor/magn_polling/README.rst
@@ -2,7 +2,7 @@
##########################
Overview
---------
+********
Sample application that periodically reads magnetometer (X, Y, Z) data from
the first available device that implements SENSOR_CHAN_MAGN_* (predefined array
diff --git a/samples/sensor/mcp9808/README.rst b/samples/sensor/mcp9808/README.rst
index aac1cc8..41df2a1 100644
--- a/samples/sensor/mcp9808/README.rst
+++ b/samples/sensor/mcp9808/README.rst
@@ -2,13 +2,13 @@
##########################
Overview
-========
+********
Sample application that periodically reads temperature from the MCP9808 sensor.
Requirements
-============
+************
The MCP9808 digital temperature sensor converts temperatures between -20°C and
+100°C to a digital word with ±0.5°C (max.) accuracy. It is I2C compatible and
@@ -23,7 +23,7 @@
This sample uses the sensor APIs and the provided driver for the MCP9808 sensor.
Wiring
-=======
+*******
The MCP9808 requires 2 wires for the I2C bus plus power and ground. The power
can be either 5V or 3.3V.
@@ -36,7 +36,7 @@
References
-===========
+***********
- http://www.microchip.com/wwwproducts/en/en556182
diff --git a/samples/sensor/th02/README.rst b/samples/sensor/th02/README.rst
index d4230ee..f162b4e 100644
--- a/samples/sensor/th02/README.rst
+++ b/samples/sensor/th02/README.rst
@@ -2,14 +2,14 @@
######################################
Overview
-========
+********
This sample periodically reads temperature and humidity from the Grove
Temperature & Humidity Sensor (TH02) and display the results on the Grove LCD
display.
Requirements
-============
+************
This sample uses the TH02 sensor and the grove LCD display. Both devices are
controlled using the I2C interface.
@@ -20,7 +20,7 @@
- `Grove LCD Module`_
Wiring
-======
+******
The easiest way to get this wired is to use the Grove shield and connect both
devices to I2C. No additional wiring is required. Depending on the board you are
@@ -30,7 +30,7 @@
References
-==========
+**********
- TH02: http://www.datasheetspdf.com/mobile/748107/TH02.html
diff --git a/samples/synchronization/README.rst b/samples/synchronization/README.rst
index 6eae787..14052a1 100644
--- a/samples/synchronization/README.rst
+++ b/samples/synchronization/README.rst
@@ -4,7 +4,7 @@
######################
Overview
-========
+********
A simple application that demonstates basic sanity of the kernel.
Two threads (A and B) take turns printing a greeting message to the console,
@@ -13,7 +13,7 @@
and timing are operating correctly.
Building and Running
-====================
+********************
This project outputs to the console. It can be built and executed
on QEMU as follows:
@@ -24,7 +24,7 @@
$ make run
Sample Output
--------------
+=============
.. code-block:: console
