From cb93bb8dc9568cb71bcd570ec33fd1df705df7b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Sim=C3=B5es?= Date: Tue, 6 Dec 2016 12:02:03 +0000 Subject: [PATCH 1/5] Add readme file to perform as documentation index --- docs/readme.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 docs/readme.md diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 0000000000..2125a69b00 --- /dev/null +++ b/docs/readme.md @@ -0,0 +1,5 @@ +# nanoFramework Documentation + +[Building nanoFramework] (build-instructions.md) +[Debug with VS Code] (vscode-debug-instructions.md) + \ No newline at end of file From d5e6423e40ade9e5dc15b453b02d2ade3fec3774 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Sim=C3=B5es?= Date: Tue, 6 Dec 2016 12:10:15 +0000 Subject: [PATCH 2/5] =?UTF-8?q?Rename=20toolchain=20file=20for=20clarity?= =?UTF-8?q?=E2=80=99s=20sake?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CMake/{STM32_GCC.cmake => toolchain.STM32.GCC.cmake} | 0 CMakeLists.txt | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename CMake/{STM32_GCC.cmake => toolchain.STM32.GCC.cmake} (100%) diff --git a/CMake/STM32_GCC.cmake b/CMake/toolchain.STM32.GCC.cmake similarity index 100% rename from CMake/STM32_GCC.cmake rename to CMake/toolchain.STM32.GCC.cmake diff --git a/CMakeLists.txt b/CMakeLists.txt index 8b74a58567..d57538f008 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -60,7 +60,7 @@ else() endif() # set toolchain file -set(CMAKE_TOOLCHAIN_FILE CMake/${CHIP_VENDOR_STM32}_${TOOLCHAIN}.cmake) +set(CMAKE_TOOLCHAIN_FILE CMake/toolchain.${CHIP_VENDOR_STM32}.${TOOLCHAIN}.cmake) ######################################### From 89230a6f1c2c72755a0647d0ec2c06e43f0f829f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Sim=C3=B5es?= Date: Tue, 6 Dec 2016 12:20:25 +0000 Subject: [PATCH 3/5] Rework styling --- docs/build-instructions.md | 14 +++++++------- docs/readme.md | 5 ++--- docs/vscode-debug-instructions.md | 4 ++-- 3 files changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/build-instructions.md b/docs/build-instructions.md index 40a2fc7631..2b650ae5ce 100644 --- a/docs/build-instructions.md +++ b/docs/build-instructions.md @@ -1,8 +1,8 @@ -# Instructions for building a nanoFramework image +# Instructions for building a **nano Framework** image **About this document** -This document describes how to build an image of nanoFramework to be flashed in a SoC or MCU. +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. @@ -28,8 +28,8 @@ In case you need to clean up or start a fresh build all you have to do is simply As a suggestion we recommend that you create a directory named *build* in the repository root and run CMake from there. - -# Build the nanoFramework image + +# Build the **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. @@ -62,10 +62,10 @@ Follows a brief explanation on the files you might want to tweak. 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). - -# nanoFramework image + +# **nano Framework** build deliverables -After a sucesfull build you can find the nanoFramework image files in the *build* directory. Those are: +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.lst (source code intermixed with disassembly) diff --git a/docs/readme.md b/docs/readme.md index 2125a69b00..4533268f2b 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -1,5 +1,4 @@ -# nanoFramework Documentation +# **nano Framework** Documentation -[Building nanoFramework] (build-instructions.md) +[Building **nano Framework**] (build-instructions.md) [Debug with VS Code] (vscode-debug-instructions.md) - \ No newline at end of file diff --git a/docs/vscode-debug-instructions.md b/docs/vscode-debug-instructions.md index 5771ec3544..870f216f0a 100644 --- a/docs/vscode-debug-instructions.md +++ b/docs/vscode-debug-instructions.md @@ -1,8 +1,8 @@ -# Instructions for debuging nanoFramework native code in VS Code +# Instructions for debuging **nano Framework** native code in VS Code **About this document** -This document describes how to debug nanoFramework native code using VS Code. +This document describes how to debug **nano Framework** native code using VS Code. # Prerequisites From 8325067ef381733fbee442d69302e30955eadfb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Sim=C3=B5es?= Date: Wed, 7 Dec 2016 11:53:50 +0000 Subject: [PATCH 4/5] Several corrections/changes - rework formating to correct erros in the markup - improve some styling with lists and names - rename readme files to upper case to follow GitHub common practices --- docs/build-instructions.md | 25 ++++++++++++++++--------- docs/readme.md | 4 ++-- docs/vscode-debug-instructions.md | 22 ++++++++++++++-------- 3 files changed, 32 insertions(+), 19 deletions(-) diff --git a/docs/build-instructions.md b/docs/build-instructions.md index 2b650ae5ce..3b11e02188 100644 --- a/docs/build-instructions.md +++ b/docs/build-instructions.md @@ -1,5 +1,12 @@ # Instructions for building a **nano Framework** image +## Table of contents ## + +- [Prerequisites](#Prerequisites) +- [Preparation](#Preparation) +- [Build a **nano Framework** image](#BuildNanoFrameworkImage) +- [**nano Framework** build deliverables](#NanoFrameworkBuildDeliverables) + **About this document** This document describes how to build an image of **nano Framework** to be flashed in a SoC or MCU. @@ -9,12 +16,12 @@ 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/) +- [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) +- [Visual Studio Code](http://code.visualstudio.com/) +- [CMake Tools](https://marketplace.visualstudio.com/items?itemName=vector-of-bool.cmake-tools) @@ -28,8 +35,8 @@ In case you need to clean up or start a fresh build all you have to do is simply As a suggestion we recommend that you create a directory named *build* in the repository root and run CMake from there. - -# Build the **nano Framework** image + +# 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. @@ -48,7 +55,7 @@ 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 -G "NMake Makefiles" ../``` -This will call CMake (on your *build* directory that is assumed to be on 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 and that the build files suitable for NMake are to be generated. +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 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) @@ -57,12 +64,12 @@ we've added the required files and configurations to help you launch your build 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). +- 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: diff --git a/docs/readme.md b/docs/readme.md index 4533268f2b..a96012b82e 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -1,4 +1,4 @@ # **nano Framework** Documentation -[Building **nano Framework**] (build-instructions.md) -[Debug with VS Code] (vscode-debug-instructions.md) +- [Building **nano Framework**](build-instructions.md) +- [Debug with VS Code](vscode-debug-instructions.md) diff --git a/docs/vscode-debug-instructions.md b/docs/vscode-debug-instructions.md index 870f216f0a..34e59c4b30 100644 --- a/docs/vscode-debug-instructions.md +++ b/docs/vscode-debug-instructions.md @@ -1,5 +1,11 @@ # Instructions for debuging **nano Framework** native code in VS Code +## Table of contents ## + +- [Prerequisites](#Prerequisites) +- [Preparation](#Preparation) +- [Launch the debug session](#LaunchTheDebugSession) + **About this document** This document describes how to debug **nano Framework** native code using VS Code. @@ -8,13 +14,13 @@ This document describes how to debug **nano Framework** native code using VS Cod # 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) +- [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) + - [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) @@ -22,7 +28,7 @@ You'll need: 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)) +(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. @@ -34,7 +40,7 @@ Here's what you probably need to change in order to adapt this file to your setu - 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). From a16e5eadfc3ebfd3f699a9f624e24d0511f1a9ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Sim=C3=B5es?= Date: Wed, 7 Dec 2016 11:54:24 +0000 Subject: [PATCH 5/5] Add documention for CMake modules and files --- docs/CMake/README.md | 4 ++++ docs/CMake/stcube-repository.md | 39 +++++++++++++++++++++++++++++++ docs/CMake/stm32-gcc-toolchain.md | 25 ++++++++++++++++++++ 3 files changed, 68 insertions(+) create mode 100644 docs/CMake/README.md create mode 100644 docs/CMake/stcube-repository.md create mode 100644 docs/CMake/stm32-gcc-toolchain.md diff --git a/docs/CMake/README.md b/docs/CMake/README.md new file mode 100644 index 0000000000..56291596d5 --- /dev/null +++ b/docs/CMake/README.md @@ -0,0 +1,4 @@ +# CMake configuration files documentation + +- [ST Cube repository](stcube-repository.md) +- [_Toolchain file_ for STM32 with GNU ARM Embedded](stm32-gcc-toolchain.md) diff --git a/docs/CMake/stcube-repository.md b/docs/CMake/stcube-repository.md new file mode 100644 index 0000000000..e0895df9a9 --- /dev/null +++ b/docs/CMake/stcube-repository.md @@ -0,0 +1,39 @@ +# CMake file for ST Cube repository folder + +**About this document** + +This document describes the purpose and workflow for the CMake configuration file on the *stcube-repository* folder. + + + +# Purpose + +The purpose of this configuration file is to download the appropriate ST Cube package from ST's web site and unzip it to the appropriate location. + + + +# Reasoning + +Each ST Cube package file has several hundred MB which can take a bit longer to download, therefore contributing to make the build process slower. +The *stcube-repository* folder is meant to hold the packages as a cache in order to speed up the build process. +The ZIP file with the packages are downloaded from ST's web site and stored in this folder. +After the download the file is unzipped to the respective series directory (with follows the series name). The documentation, utilities, example projects and other non code files are deleted in order to save disk space. +If the destination folder doesn't exist, CMake will try to find the ZIP file for the package. If the file exists it will be unzipped, if not it will be downloaded. + + + +# Workflow + +The configuration file relies on the STM32_SERIES variable to determine what is the SMT32 series along with the PACKAGE_VERSION variable that holds the package version that the build is expected to use. +The PACKAGE_VERSION is checked for the correct format which follows the standard format _MAJOR.MINOR.PATCH_. +The distribution of ST Cube packages has a particularity: when a package is a patch (meaning that the rightmost number is not zero) it only holds the patched files. This means that the original package is required too. +For example, if the target version is 1.13.2 (witch is a patch for v1.13.0) we need two files: the original one (v1.13.0) and the patch (v1.13.2). The destination directory has to be cleaned up before unzipping the first one and then the second one is unzip overwriting the patched files. + +The file naming of the ST Cube packages distribution files follows the following format: *stm32cube_fw_f0_v160.zip*. +Note the series name and the version. All in small case and the version number without dots. +After unzipping the destination directory name will be STM32Cube_FW_F0_V1.6.0. +Note that the version number now has the dots and that the name is all in upper case, except for the 'Cube' name. + +The base URL for downloading the package files from ST's web is "http://www.st.com/resource/en/firmware2". To have the complete URL for downloading a file just add the package file name to the base URL. + +To ease the management and search of the 'cache' and destination directories, the destination directory for the build (were the ST Cube package code is actually placed) is named just *stcube* (dropping the _repository). diff --git a/docs/CMake/stm32-gcc-toolchain.md b/docs/CMake/stm32-gcc-toolchain.md new file mode 100644 index 0000000000..ec0b4710c3 --- /dev/null +++ b/docs/CMake/stm32-gcc-toolchain.md @@ -0,0 +1,25 @@ +# CMake _toolchain file_ for STM32 with GNU ARM Embedded Toolchain + +**About this document** + +This document describes the CMake module that is loaded as a _toolchain file_ to support STM32 devices using the GNU ARM Embedded Toolchain. + + + +# Purpose + +The purpose of this CMake module is to configure CMake for cross-compiling an ARM Cortex image in the platform that is running (Windows, MAC or Linux) using the GNU ARM Embedded Toolchain. +In the process the parameters that were passed to CMake when invoking it are also validated. +The toolchain CMake module is located in the CMake directory, not in the Modules directory because CMake understands it as a _toolchain file_ not a module (despite being technically of the same kind). + + +# Workflow + +Follows a brief description on the validations that are performed: +- Toolchain location +- Target chip. The support for STM32 devices is added for each series (F0, F4, etc). The target chip is validated against a list of the series that are supported. + +The next part of the file takes care of configuring the GCC toolchain location, setup the working directories, C, C++ and assembly compilers, flags for the various build flavors (debug/release) and the targets that will eventually result from running the build. + +An important part is the inclusion of a CMake module that is specific to the STM32 series of the target chip. This helps on keeping things separated and more manageable. The general aspects, configurations and definitions are kept in this toolchain file and the particulars of the target series remain in the series CMake module. The naming of the series module follows the structure "STM32**NN**_GCC_options.cmake" on which the **NN** are replaced with the series designation in upper case. +The series CMake module has to be placed in the CMake\Modules directory otherwise CMake won't be able to find it.