Add preliminary versions of documentation (#25)

(squashed)

.gitignore

@@ -0,0 +1,19 @@
+# ignore all ZIP files
+
+*.zip
+
+
+
+# ignore stcube_repository folder
+
+stcube_repository/*
+
+# except CMakeLists file
+
+!stcube_repository/CMakeLists.txt
+
+
+
+# ignore build folder
+
+build/*

CODE_KEEPERS.md

@@ -0,0 +1,19 @@
+The following is a list of keepers for different areas of the **nano Framework** code. 
+Each of the keepers is responsible for ensuring that changes in their areas 
+are reviewed, either by themselves or by someone they designate, in 
+addition to being the final word for the architecture and content of an area.
+
+List sorted by name and the fields are Name (N), GitHub user account (G), 
+Area (A).
+
+Note: If you don't find the area in the below list, or you have a general 
+question, send a message to Stanislav Šimíček (@cw2) or José Simões
+(@josesimoes). They can ensure that the question gets forwarded to the
+right person or answer it themselves.  
+
+| Name | GitHub user | Area |
+| --- | --- | --- |
+| José Simões | @josesimoes | Native code build, VS Code Debug and CMake |
+| Stanislav Šimíček | @cw2 | Debug protocol, nano Framework Interpreter |
+
+This list is incomplete, if you need to find other keepers please ping the team to get them filled in.

docs/README.md

@@ -1,6 +1,30 @@
-# Introduction to nano Framework Interpreter
+# Documents Index
 
-## Architecture
+This repo includes several documents that explain both high-level and low-level concepts about the **nano Framework**. These are very useful for contributors, to get context that can be very difficult to acquire from just reading code.
 
-## Developer Guide
+## Intro to **nano Framework**
 
+**nano Framework** is ?????????????????. It targets ARM Cortex M architectures and can be ported to multiple platforms.
+
+## Getting Started
+
+<!--- [??????](https://?????)-->
+
+## Project Documentation
+
+- [Developer Guide](project-documentation/developer-guide.md)
+- [Project priorities](project-documentation/project-priorities.md)
+- [Contributing to **nano Framework**](project-documentation/contributing.md)
+- [Contributing Workflow](project-documentation/contributing-workflow.md)
+
+## Build **nano Framework**
+
+- [Building **nano Framework**](building/build-instructions.md)
+
+## Testing and Debugging **nano Framework**
+
+- [Debugging **nano Framework** with VS Code](building/vscode-debug-instructions.md)
+
+## CMake Documentation
+
+- [CMake configuration files](cmake-documentation/README.md)

docs/building/build-instructions.md

@@ -0,0 +1,109 @@
+# Instructions for building a **nano Framework** image
+
+## Table of contents ##
+
+- [Prerequisites](#Prerequisites)
+- [Preparation](#Preparation)
+- [Build a **nano Framework** image](#Build-a-nano-Framework-Image)
+- [**nano Framework** build deliverables](#nano-Framework-Build-Deliverables)
+
+**About this document**
+
+This document describes how to build an image of **nano Framework** to be flashed in a SoC or MCU.
+The build is based on CMake tool to ease the development in all major platforms.
+
+# Prerequisites
+
+You'll need:
+- [GNU ARM Embedded Toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads)
+- [CMake](https://cmake.org/)
+
+If you are using VS Code as your development platform we suggest that you use the CMake Tools extension. This will allow you to run the builds without leaving VS Code.
+- [Visual Studio Code](http://code.visualstudio.com/)
+- [CMake Tools](https://marketplace.visualstudio.com/items?itemName=vector-of-bool.cmake-tools)
+
+In case you specify an RTOS and you want its source to be dowloaded from the official repository, you'll need:
+- For FreeRTOS a SVN client. [Tortoise SVN](https://tortoisesvn.net/downloads) seems to be a popular choice for Windows machines.
+- For mBed RTOS a Git client. [GitHub Desktop](https://desktop.github.com/) seems to be a popular choice for Windows machines.
+
+# Preparation
+
+It's ***highly*** recommended that run the build outside the source tree. This prevents you from cluttering the source tree with CMake artifacts, temporary files and like. 
+In fact this is enforced and checked by the CMake script.
+
+In case you need to clean up or start a fresh build all you have to do is simply delete the contents of the build directory.
+
+As a suggestion we recommend that you create a directory named *build* in the repository root and run CMake from there.
+
+
+
+# Build a **nano Framework** image
+
+The build script accepts the following parameters (some of them are mandatory).
+- TARGET_CHIP: this is the vendor reference to the chip that you are building the image for. At this time only STM32F4 series are supported. A valid reference here would be STM32F407VG.
+- PACKAGE_VERSION: In case you are building for an STM32 chip this is the package version of the ST Cube package (with the CMSIS and HAL drivers) that you want to use. This will be downloaded from ST web site except if the package already exists in the ST Cube repository folder. A valid package number is required. E.g.: 1.3.0 or 1.41.2.  
+- TOOLCHAIN: the toolchain to use in the build. The default (and only option at this time) is GCC.
+- TOOLCHAIN_PREFIX: path to the install directory of the toolchain. E.g.: "E:/GNU_Tools_ARM_Embedded/5_4_2016q3". Mind the forward slash on the path for all platforms.
+- CMAKE_BUILD_TYPE: build type (Debug, Release, etc). The default is Release.
+- RTOS: specifies the RTOS to add to the image. If no source path is specified the source files will be downloaded from the respective repository. Current valid RTOSes are FreeRTOS (FREERTOS), mBed RTOS (MBEDRTOS) and ARM RTX (RTXRTOS).
+- FREERTOS_VERSION: specifies the FreeRTOS version to grab the source files. It has to match one of the official versions from the FreeRTOS repository. If none is specified it will download the 'trunk' version. This parameter is ignored if FREERTOS_SOURCE is specified. 
+- FREERTOS_SOURCE: specifies the path for the location of the FreeRTOS source code. If this parameter is specified the code on that path will be used and no download is performed. For this parameter to be valid RTOS must be specified with FREERTOS option. 
+- MBED_SOURCE: specifies the path for the location of the mBed source code. If this parameter is specified the code on that path will be used and no download is performed. For this parameter to be valid RTOS parameter must be specified with MBEDRTOS option. 
+
+_Note: the very first build will take more or less time depending on the download speed of the Internet connection of the machine were the build is running. This is because the source code of the RTOS of your choice will be downloaded from its repository. On the subsequent builds this won't happen._
+
+You can specify any generator that is supported in the platform where you are building.
+For more information on this check CMake documentation [here](https://cmake.org/cmake/help/v3.7/manual/cmake-generators.7.html?highlight=generator).
+
+## Building from the command prompt
+
+If you are building from the command prompt, just go to your *build* directory and run CMake from there with the appropriate parameters. 
+The following is a working example:
+
+```
+cmake \
+-DTOOLCHAIN_PREFIX="E:/GNU_Tools_ARM_Embedded/5_4_2016q3" \
+-DTARGET_CHIP=STM32F407VG \
+-DPACKAGE_VERSION=1.13.1 \
+-RTOS=FREERTOS \
+-FREERTOS_VERSION=9.0.0 \
+-G "NMake Makefiles" ../ 
+```
+
+This will call CMake (on your *build* directory that is assumed to be under the repository root) specifing the location of the toolchain install, targeting STM32F407VG, asking for the ST Cube package version 1.13.1 to be used, specifying FreeRTOS v9.0.0 as the RTOS and that the build files suitable for NMake are to be generated.
+
+Another example:
+
+```
+cmake \
+-DTOOLCHAIN_PREFIX="E:/GNU_Tools_ARM_Embedded/5_4_2016q3" \
+-DTARGET_CHIP=STM32F091RC \
+-DPACKAGE_VERSION=1.6.0 \
+-RTOS=MBEDRTOS \
+-MBEDRTOS_SOURCE=E:/GitHub/mbed-os \
+-G "NMake Makefiles" ../ 
+```
+
+This will call CMake (on your *build* directory that is assumed to be under the repository root) specifing the location of the toolchain install, targeting STM32F091RC, asking for the ST Cube package version 1.6.0 to be used, specifying MBEDRTOS as the RTOS, that mBed RTOS sources are located in the designated path (mind the forward slash and no ending slash) and that the build files suitable for NMake are to be generated.
+
+After succesfull completion you'll have the build files ready to be used in the target build tool.
+
+## Building from VS Code (using CMake Tools extension)
+
+We've added the required files and configurations to help you launch your build from VS Code.
+Follows a brief explanation on the files you might want to tweak.
+
+- settings.json (inside .vscode folder) here you can change the generator that CMage uses to generate the build. The default is ```"cmake.generator": "NMake Makefiles"```.
+- cmake-variants.json (at the repository root) here you can add several build flavors. You can even add variants to each one. Check the documentation extension [here](https://github.com/vector-of-bool/vscode-cmake-tools/blob/develop/docs/build_variants.md).
+
+To launch the build in VS Code check the status bar at the bottom. Select the build flavor and then click the build buttom (or hit F7).
+
+
+# **nano Framework** build deliverables
+
+After a sucesfull build you can find the **nano Framework** image files in the *build* directory. Those are:
+- nanoFramework.bin (raw binary format)
+- nanoFramework.hex (Intel hex format)
+- nanoFramework.s19 (Motorola S-record format, equivalent to srec)
+- nanoFramework.lst (source code intermixed with disassembly)
+- nanoFramework.map (image map) 

docs/building/vscode-debug-instructions.md

@@ -0,0 +1,53 @@
+# Instructions for debuging **nano Framework** native code in VS Code
+
+## Table of contents ##
+
+- [Prerequisites](#Prerequisites)
+- [Preparation](#Preparation)
+- [Launch the debug session](#Launch-the-debug-Session)
+
+**About this document**
+
+This document describes how to debug **nano Framework** native code using VS Code.
+
+# Prerequisites
+
+You'll need:
+- [GNU ARM Embedded Toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads)
+- [Visual Studio Code](http://code.visualstudio.com/)
+- [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
+- OpenOCD (any working distribution will work, follow some suggestions)
+    - [Freddie Chopin OpenOCD (development)](http://www.freddiechopin.info/en/download/category/10-openocd-dev)
+    - [OpenOCD – Open On-Chip Debugger](https://sourceforge.net/projects/openocd/)
+    - [GNU ARM Eclipse OpenOCD](https://github.com/gnuarmeclipse/openocds)
+
+
+# Preparation
+
+You'll need a binary image with debug information to be loaded in the SoC or MCU.
+Assuming you are using VS Code to launch your builds, you'll have this image ready to be loaded in the MCU.
+(see [Build instructions documentation](build-instructions.md))
+
+In order to launch the debug session you'll need to tweak the *launch.json* file, located in the .vscode folder.
+Here's what you probably need to change in order to adapt this file to your setup.
+- miDebuggerPath: full path to the gdb executable (this one is inside the GCC toolchain folder)
+- program: full path to the .hex or .bin output file that results from a successful build
+- setupCommands (third 'text' entry): full path to the final image (same as above)
+- setupCommands (fourth 'text' entry): the same as the program entry above
+- debugServerPath: full path to the OpenOCD executable
+- debugServerArgs: full path to the scripts directory on the OpenOCD installation AND the appropriate .cfg files for the interface and the board.
+
+
+# Launch the debug session
+
+Using VS Code menu View > Debug, clicking on the debug icon on the left hand toolbar or hitting the CTRL+SHIT+D shortcut you'll reach the debug view. There you'll find the launch configurations for debug that we've setup above (see the drop down at the top) and the familiar green play button (or F5 if you prefer).
+
+When a debug session is active you can find a lot of familiar stuff:
+- debug toolbar with the usual operations (pause, step over, into, out, restart and stop)
+- variables list
+- call stack that you can use to navigate up and down
+- breakpoint list to manage those
+- watch expressions
+- support for 'mouse over' a variable which will display a context with the variable content
+- ability to set/remove breakpoints by clicking near the line number
+- other handy tools and options using the right click on the various objects

docs/coding-guidelines/cs-coding-style.md

@@ -0,0 +1,126 @@
+# C# Coding Style
+
+For non code files (xml etc) our current best guidance is consistency. When editing files, keep new code and changes consistent with the style in the files. For new files, it should conform to the style for that component. Last, if there's a completely new component, anything that is reasonably broadly accepted is fine.
+
+The general rule we follow is "use Visual Studio defaults".
+
+1. We use [Allman style](http://en.wikipedia.org/wiki/Indent_style#Allman_style) braces, where each brace begins on a new line. A single line statement block can go without braces but the block must be properly indented on its own line and it must not be nested in other statement blocks that use braces. 
+2. We use four spaces of indentation (no tabs).
+3. We use `_camelCase` for internal and private fields and use `readonly` where possible. Prefix static fields with `s_` and thread static fields with `t_`. When used on static fields, `readonly` should come after `static` (i.e. `static readonly` not `readonly static`).
+4. We avoid `this.` unless absolutely necessary. 
+5. We always specify the visibility, even if it's the default (i.e.
+   `private string _foo` not `string _foo`). Visibility should be the first modifier (i.e. 
+   `public abstract` not `abstract public`).
+6. Namespace imports should be specified at the top of the file, *outside* of
+   `namespace` declarations and should be sorted alphabetically.
+7. Avoid more than one empty line at any time. For example, do not have two
+   blank lines between members of a type.
+8. Avoid spurious free spaces.
+   For example avoid `if (someVar == 0)...`, where the dots mark the spurious free spaces.
+   Consider enabling "View White Space (Ctrl+E, S)" if using Visual Studio, to aid detection.
+9. If a file happens to differ in style from these guidelines (e.g. private members are named `m_member`
+   rather than `_member`), the existing style in that file takes precedence.
+10. We only use `var` when it's obvious what the variable type is (i.e. `var stream = new FileStream(...)` not `var stream = OpenStandardInput()`).
+11. We use language keywords instead of BCL types (i.e. `int, string, float` instead of `Int32, String, Single`, etc) for both type references as well as method calls (i.e. `int.Parse` instead of `Int32.Parse`).
+12. We use PascalCasing to name all our constant local variables and fields. The only exception is for interop code where the constant value should exactly match the name and value of the code you are calling via interop.
+13. We use ```nameof(...)``` instead of ```"..."``` whenever possible and relevant.
+14. Fields should be specified at the top within type declarations.
+
+We have provided a Visual Studio 2013 vssettings file (`nfcore.vssettings`) at the root of the repository, enabling C# auto-formatting conforming to the above guidelines. Note that rules 7 and 8 are not covered by the vssettings, since these are not rules currently supported by VS formatting.
+
+### Example File:
+
+``ObservableLinkedList`1.cs:``
+
+```C#
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Collections.Specialized;
+using System.ComponentModel;
+using System.Diagnostics;
+using Microsoft.Win32;
+
+namespace System.Collections.Generic
+{
+    public partial class ObservableLinkedList<T> : INotifyCollectionChanged, INotifyPropertyChanged
+    {
+        private ObservableLinkedListNode<T> _head;
+        private int _count;
+
+        public ObservableLinkedList(IEnumerable<T> items)
+        {
+            if (items == null)
+                throw new ArgumentNullException(nameof(items));
+
+            foreach (T item in items)
+            {
+                AddLast(item);
+            }
+        }
+
+        public event NotifyCollectionChangedEventHandler CollectionChanged;
+
+        public int Count
+        {
+            get { return _count; }
+        }
+
+        public ObservableLinkedListNode AddLast(T value) 
+        {
+            var newNode = new LinkedListNode<T>(this, value);
+
+            InsertNodeBefore(_head, node);
+        }
+
+        protected virtual void OnCollectionChanged(NotifyCollectionChangedEventArgs e)
+        {
+            NotifyCollectionChangedEventHandler handler = CollectionChanged;
+            if (handler != null)
+            {
+                handler(this, e);
+            }
+        }
+
+        private void InsertNodeBefore(LinkedListNode<T> node, LinkedListNode<T> newNode)
+        {
+           ...
+        }
+
+        ...
+    }
+}
+```
+
+``ObservableLinkedList`1.ObservableLinkedListNode.cs:``
+
+```C#
+using System;
+
+namespace System.Collections.Generics
+{
+    partial class ObservableLinkedList<T>
+    {
+        public class ObservableLinkedListNode
+        {
+            private readonly ObservableLinkedList<T> _parent;
+            private readonly T _value;
+
+            internal ObservableLinkedListNode(ObservableLinkedList<T> parent, T value)
+            {
+                Debug.Assert(parent != null);
+
+                _parent = parent;
+                _value = value;
+            }
+
+            public T Value
+            {
+               get { return _value; }
+            }
+        }
+
+        ...
+    }
+}
+```

docs/coding-guidelines/cxx-coding-style.md

@@ -0,0 +1,26 @@
+# C/C++ Coding Style
+
+For C/C++ files (*.c, *.cpp and *.h), we use clang-format (version 3.6+) to ensure code styling. 
+
+## Using Visual Studio Code
+
+If you are using Visual Studio Code we suggest that you install the [Clang-Format extension](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format).
+To have this extension working you need to have the clang-format.exe installed in your system.
+
+LLVM.org doesn't provide a separate installer for this tool so follows a quick and dirty way of getting it.
+1. Install the Clang-Format extension.
+2. Install the Visual Studio plugin (as described bellow) and **DON'T** close the install window before opening the install log.
+3. After a succesfull install of the plugin, scroll down the install log until you find the path where it was installed.
+4. Copy that path and edit your VS Code user settings.
+5. Add to the end of the setting collection the following:
+```
+"clang-format.executable" : "C:/Users/nnnnnnnnn/AppData/Local/Microsoft/VisualStudio/14.0/Extensions/yyyyyy.zzzz/clang-format.exe"
+```
+You might have something different in your setup. 
+Just remeber the following: add that setting, the path that you've copied before, change it to have forward slashes and add the **clang-format.exe** at the end.
+
+After following the above steps suceesfully you can now right click on any C, C++ or H file and hit 'Format Document'. The VS Code extension will take care that the document is properly formated according to the coding style guidelines.
+
+## Using Visual Studio
+
+If you are using Visual Studio we suggest that you install the [clang-format plugin for Visual Studio](http://llvm.org/builds/).