From ebe30b034892fdd1ea6b95cb5ec817ef503110fe Mon Sep 17 00:00:00 2001
From: Peter Mitsis <peter.mitsis@windriver.com>
Date: Wed, 19 Aug 2015 15:35:42 -0400
Subject: [PATCH] doc: Provide basic_cortex_m3 platform documentation

Change-Id: If2f4f6352f0ac9f4c1fcc2246b8001965232822d
Signed-off-by: Peter Mitsis <peter.mitsis@windriver.com>
---
 doc/platform/basic_cortex_m3.rst | 103 +++++++++++++++++++++++++++++++
 doc/platform/platform.rst        |   3 +
 2 files changed, 106 insertions(+)
 create mode 100644 doc/platform/basic_cortex_m3.rst

diff --git a/doc/platform/basic_cortex_m3.rst b/doc/platform/basic_cortex_m3.rst
new file mode 100644
index 00000000000..cb92b8326e1
--- /dev/null
+++ b/doc/platform/basic_cortex_m3.rst
@@ -0,0 +1,103 @@
+.. _basic_cortex_m3:
+
+Platform Configuration: basic_cortex_m3
+#######################################
+
+Introduction
+************
+
+This section provides an overview of the basic_cortex_m3 platform configuration.
+
+Overview
+========
+
+The basic_cortex_m3 platform configuration is used by Zephyr applications
+to emulate the TI LM3S6965 platform running on QEMU. It provides support
+for an ARM Cortex-M3 CPU and the following devices:
+
+* Nested Vectored Interrupt Controller
+
+* System Tick System Clock
+
+* Stellaris UART
+
+.. note::
+   This platform configuration makes no claims about its suitability for use
+   with an actual ti_lm3s6965 hardware system, or any other hardware system.
+
+Supported Boards
+****************
+
+The basic_cortex_m3 platform configuration has been tested on
+QEMU 2.1 patched with Zephyr's
+:file:`0001-armv7m-support-basepri-primask-interrupt-locking.patch`.
+
+Supported Features
+******************
+
+The basic_cortex_m3 platform configuration supports the following
+hardware features:
+
++--------------+------------+----------------------+
+| Interface    | Controller | Driver/Component     |
++==============+============+======================+
+| NVIC         | on-chip    | nested vectored      |
+|              |            | interrupt controller |
++--------------+------------+----------------------+
+| Stellaris    | on-chip    | serial port          |
+| UART         |            |                      |
++--------------+------------+----------------------+
+| SYSTICK      | on-chip    | system clock         |
++--------------+------------+----------------------+
+
+Other hardware features are not currently supported by Zephyr applications.
+
+Interrupt Controller
+====================
+
+.. _fsl_frdm_k64f's platform documention: fsl_frdm_k64f.html
+
+Refer to the `fsl_frdm_k64f's platform documention`_.
+
+.. note::
+   Unlike the fsl_frdm_k64 platform configuration, the basic_cortex_m3
+   platform configuration sets option :option:`NUM_IRQ_PRIO_BITS` to '3'.
+
+System Clock
+============
+The basic_cortex_m3 platform configuration uses a system
+clock frequency of 12 MHz.
+
+Serial Port
+===========
+
+The basic_cortex_m3 platform configuration uses a single
+serial communication channel with the CPU's UART0.
+
+Known Problems or Limitations
+*****************************
+
+There is no support for the following:
+
+* Memory protection through optional MPU.
+  However, using a XIP kernel effectively provides
+  TEXT/RODATA write protection in ROM.
+
+* SRAM at addresses 0x1FFF0000-0x1FFFFFFF
+
+* Writing to the hardware's flash memory
+
+Bibliography
+************
+
+1. The Definitive Guide to the ARM Cortex-M3,
+   Second Edition by Joseph Yiu (ISBN?978-0-12-382090-7)
+2. ARMv7-M Architecture Technical Reference Manual
+   (ARM DDI 0403D ID021310)
+3. Procedure Call Standard for the ARM Architecture
+   (ARM IHI 0042E, current through ABI release 2.09,
+   2012/11/30)
+4. Cortex-M3 Revision r2p1 Technical Reference Manual
+   (ARM DDI 0337I ID072410)
+5. Cortex-M3 Devices Generic User Guide
+   (ARM DUI 0052A ID121610)
diff --git a/doc/platform/platform.rst b/doc/platform/platform.rst
index 68a42d85970..57c14f5c84d 100644
--- a/doc/platform/platform.rst
+++ b/doc/platform/platform.rst
@@ -8,6 +8,7 @@ Zephyr supports the following hardware platforms configurations:
 .. toctree::
    :maxdepth: 1
 
+   basic_cortex_m3.rst
    fsl_frdm_k64f.rst
    basic_atom.rst
    basic_minuteia.rst
@@ -19,6 +20,8 @@ hardware platform, and architecture.
 +--------------------------+----------------------------------------+--------------+
 | Platform Configuration   | Hardware Platform                      | Architecture |
 +==========================+========================================+==============+
+| basic_cortex_m3          | QEMU 2.1 + patch                       | ARM v7-M     |
++--------------------------+----------------------------------------+--------------+
 | fsl_frdm_k64f            | Freescale Freedom Development Platform | ARM v7E-M    |
 +--------------------------+----------------------------------------+--------------+
 | basic_atom               | QEMU 2.1                               | X86          |