Remove documentation
- These are now in the nf-nanoframework.github.io repo. Signed-off-by: José Simões <jose.simoes@eclo.solutions>
This commit is contained in:
José Simões
Родитель
03f7343b74
Коммит
253db007f5
|
|
@ -1,5 +0,0 @@
|
|||
# HAL architecture
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes the **nanoFramework** [HAL](https://en.wikipedia.org/wiki/Hardware_abstraction) design, some explanation on the choices that were made and the options that are available to customize it.
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
# **nanoFramework** Architecture
|
||||
|
||||
- [Class Libraries](class-libraries.md)
|
||||
- [Date and Time](date-and-time.md)
|
||||
- [Application deployment](deployment.md)
|
||||
- [Thread execution](thread-execution.md)
|
||||
- [Native interrupt handlers](native-interrupt-handlers.md)
|
||||
- [Wire Protocol](wire-protocol.md)
|
||||
|
|
@ -1,65 +0,0 @@
|
|||
# Class Libraries
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes the design and organization of **nanoFramework** Class Libraries, offers some explanation on the choices that were made and how to add a new Class Library. The examples bellow are related with ChibiOS (which is the currently reference implementation for **nanoFramework**).
|
||||
|
||||
|
||||
## Libraries
|
||||
|
||||
|
||||
Follow the list of the existing libraries, respective Nuget package and CMake enable option:
|
||||
|
||||
| Class Library | Nuget package name | CMake option |
|
||||
| --- | --- | --- |
|
||||
| Base Class Library (also know as mscorlib) | nanoFramework.CoreLibrary | (always included) |
|
||||
| Windows.Device.Gpio | nanoFramework.Windows.Devices.Gpio | -DAPI_Windows.Devices.Gpio=ON |
|
||||
| Windows.Device.Spi | nanoFramework.Windows.Devices.Spi | -DAPI_Windows.Devices.Spi=ON |
|
||||
|
||||
|
||||
## Distribution strategy
|
||||
|
||||
To ease the burden of distributing and updating the class libraries we've choose to use Nuget to handle all this. It has the added benefit of dealing with the dependency management, version and such.
|
||||
|
||||
So, for each class library, there is a Nuget package that includes the assembly and documentation files. The Nuget package takes care of making sure that the required dependency(ies) and correct version(s) are added to a managed (C#) project, making a developer's life much easier.
|
||||
|
||||
|
||||
## How to add a new class library
|
||||
|
||||
Follows the procedure to add a new class library to a **nanoFramework** target image.
|
||||
|
||||
The example is for adding Windows.Devices.Gpio library.
|
||||
|
||||
|
||||
1. In VS2017 start a new project for a **nanoFramework** C# Class library. Source code [here](https://github.com/nanoframework/lib-Windows.Devices.Gpio)
|
||||
|
||||
2. Implement all the required methods, enums, properties in that project. It's recommended that you add XML comments there (and enable the automated documentation generation in the project properties).
|
||||
|
||||
3. Add the Nuget packaging project to distribute the managed assembly and documentation. We have a second Nuget package that includes all the build artifacts, generated stubs, dump files and such. This is to be used in automated testing and distribution of followup projects or build steps.
|
||||
|
||||
4. Upon a successfully build of the managed project the skeleton with the stubs should be available in the respective folder. Because **nanoFramework** aims to be target independent the native implementation of a class library will live 'inside' each target RTOS folder.
|
||||
The next step would be to copy the stubs to a folder with the assembly name inside the nanoCLR folder. For our example: [Windows.Devices.Gpio](https://github.com/nanoframework/nf-interpreter/tree/develop/targets/CMSIS-OS/ChibiOS/nanoCLR/Windows.Devices.Gpio).
|
||||
|
||||
5. Add the CMake as a module to the modules folder [here](https://github.com/nanoframework/nf-interpreter/tree/develop/CMake/Modules). The name of the module should follow the assembly name (Find**Windows.Devices.Gpio**.cmake). Mind the CMake rules for the naming: start with _Find_ followed by the module name and _cmake_ extension. The CMake for the Windows.Devices.Gpio module is [here](https://github.com/nanoframework/nf-interpreter/blob/develop/CMake/Modules/FindWindows.Devices.Gpio.cmake).
|
||||
|
||||
6. In the CMake [NF_API_Namespaces.cmake](https://github.com/nanoframework/nf-interpreter/blob/develop/CMake/Modules/NF_API_Namespaces.cmake) add an option for the API. The option name must follow the pattern API_**namespace**. The option for Windows.Devices.Gpio is API_Windows.Devices.Gpio.
|
||||
|
||||
7. In the CMake [NF_API_Namespaces.cmake](https://github.com/nanoframework/nf-interpreter/blob/develop/CMake/Modules/NF_API_Namespaces.cmake) find the macro `ParseApiOptions` and add a block for the API. Just copy/paste an existing one and replace the namespace with the one that you are adding.
|
||||
|
||||
8. Update the template file for the CMake variants [here](https://github.com/nanoframework/nf-interpreter/blob/develop/cmake-variants.TEMPLATE.json) to include the respective option. For the Windows.Devices.Gpio example you would add to the _OPTION1..._ and _OPTION2..._ (under _linkage_) the following line: "API_Windows.Devices.Gpio" : "OFF"
|
||||
|
||||
9. If the API requires enabling hardware or SoC peripherals in the target HAL/PAL make the required changes to the appropriate files.
|
||||
For Windows.Devices.Gpio in ChibiOS there is nothing to enable because the GPIO subsystem is always enabled.
|
||||
In contrast, for the Windows.Devices.Spi, the SPI subsystem has to be enabled at the _halconf.h_ file and also (at driver level) in _mcuconf.h_ the SPI peripherals have to be individually enabled (e.g. `#define STM32_SPI_USE_SPI1 TRUE`).
|
||||
|
||||
To ease the overall configuration of an API and related hardware (and when it makes sense) the API option (API_Windows.Devices.Gpio) can be _extended_ to automatically enable the HAL subsystem. This happens with the Windows.Devices.Spi API. The CMake option is mirrored in the general [CMakeLists.txt](https://github.com/nanoframework/nf-interpreter/blob/develop/CMakeLists.txt) in order to be used in CMakes and headers. This mirror property is `HAL_USE_SPI_OPTION`. It's being defined here and not in the individual _halconf.h_ files as usual. To make this work the CMake property has to be added to the CMake template file of the platform [target_platform.h.in](https://github.com/nanoframework/nf-interpreter/blob/develop/targets/CMSIS-OS/ChibiOS/nanoCLR/target_platform.h.in).
|
||||
|
||||
10. When adding/enabling new APIs and depending on how the drivers and the library are coded, some static variables will be added to the BSS RAM area. Because of that extra space that is taken by those variables the Managed Heap size may have to be adjusted to make room for those. To do this find the `__clr_managed_heap_size__` in the general CMakeLists.txt of that target and decrease the value there as required.
|
||||
|
||||
11. Some APIs depend of others. This happens for example with Windows.Devices.Gpio that requires nanoFramework.Runtime.Events in order to generate the interrupts for the changed pin values. To make this happen the option to include the required API(s) has to be enabled in the main [CMakeLists.txt](https://github.com/nanoframework/nf-interpreter/blob/develop/CMakeLists.txt) inside the if clause of the dependent API. Just like if the option was enabled at the CMake command line. Check this by searching for `API_nanoFramework.Runtime.Events` inside the `if(API_Windows.Devices.Gpio)`.
|
||||
|
||||
## How to include a class library in the build
|
||||
|
||||
To include a class library in the build for a target image you have to add to the CMake an option for the API. For the Windows.Devices.Gpio example the option would be `-DAPI_Windows.Devices.Gpio=ON`.
|
||||
You can also add this to your own cmake-variants.json file.
|
||||
To exclude a class library just set the option to OFF or simply don't include it in the command.
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
# Date and Time
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes how **nanoFramework** handles Date & Time and the available option regarding this matter.
|
||||
|
||||
|
||||
## UTC and local time
|
||||
|
||||
Time (and date) is fundamental for the inner works of **nanoFramework**. But an application running on top of it can make use of it, or not, thus making relevant the discussion and evaluation of the related features and associated code.
|
||||
Because **nanoFramework** runs on constrained resources platforms inclusion of features that increase both RAM and FLASH usage has to be considered and evaluated.
|
||||
|
||||
[`DateTime`](https://msdn.microsoft.com/en-us/library/system.datetime(v=vs.110).aspx) supports the use of Local and UTC times by its [`DateTime.Kind`](https://msdn.microsoft.com/en-us/library/system.datetime.kind(v=vs.110).aspx) property. Supporting this requires adding several _blocks_ such as: an API for setting the platform timezone, handling the huge number of available timezones, managing the daylight savings changes, manage conversion to/from the different kinds, etc.
|
||||
|
||||
Considering all the above, **nanoFramework** addresses this matter providing the _absolute minimal viable_ options.
|
||||
There is support for `DateTime` (obviously) but all DateTime are considered UTC. There is no support for `DateTime.Kind.Local`, setting timezone or converting to/from the different kinds.
|
||||
If an application requires this, it has to implement it at its own level.
|
||||
|
||||
|
||||
## Time source
|
||||
|
||||
The _time base_ source is, by default, the `SysTick` available in the CMSIS RTOS API.
|
||||
This is the _source_ of the time when a `DateTime` object is instantiated.
|
||||
|
||||
Because almost all hardware platforms capable of running **nanoFramework** include an hardware [RTC](https://en.wikipedia.org/wiki/Real-time_clock) this peripheral can be used as the _source_ for time objects.
|
||||
Note that for all other internals of **nanoFramework** the CMSIS RTOS API `SysTick` keeps being used as the time base.
|
||||
|
||||
This option is exposed to the board designer by the `NF_FEATURE_RTC` configuration option. Setting it to `ON` when calling CMake brings in the RTC subsystem and all the calls to `DateTime` make use of the time base provided by this peripheral.
|
||||
|
||||
|
||||
## RTC and hardware
|
||||
|
||||
Leveraging the RTC hardware peripheral allows several interesting/valuable features:
|
||||
- more accurate timekeeping (when compared with a regular timer);
|
||||
- possibility for timekeeping in sleep/deep sleep modes;
|
||||
- setting alarms to wake-up the system at a future time;
|
||||
|
|
@ -1,18 +0,0 @@
|
|||
# Application deployment
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes how a managed **nanoFramework** application is deployed to a target device.
|
||||
|
||||
|
||||
## Deployment preparation
|
||||
|
||||
The pre-requisites for deploying a managed **nanoFramework** application to a target device are very simple: a collection with the PE files for the target application and the referenced assemblies needs to be compiled. This collection of PE files is a blob with the binary contents of those files.
|
||||
|
||||
|
||||
## Deployment
|
||||
|
||||
The deployment stage consists on erasing the required deployment blocks on the device (FLASH sectors) and programming them with the blob containing the binary versions of the PE files.
|
||||
|
||||
**nanoFramework** follows a simplified and high level approach to this. It's up to the programming application to manage the device memory, meaning that it will tell the device exactly where and what is going into the memory.
|
||||
Also there is no "reuse" of what might be already deployed on the device. All the PE files are always deployed. This has the advantage of not requiring the extra steps of reading back what's in the device, checking the exact versions and deciding if a certain PE file will fit on a flash block. The downside is that sometimes this causes unnecessary flash erase and write cycles. Considering that a typical modern SoC flash endurance limit is in the range of 100k to 1M cycles this is neglectable and acceptable for a device used for development purposes.
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
|
||||
```
|
||||
{
|
||||
"base":"0x08000000",
|
||||
"blocks":[16,16,16,16,64,128,128,128,128,128,128,128]
|
||||
}
|
||||
```
|
||||
|
||||
[JSON validator](https://jsonformatter.curiousconcept.com/)
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
# Thread execution
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes how thread execution works with the **nanoFramework** CLR.
|
||||
|
||||
|
||||
## Native interrupt handlers
|
||||
|
||||
The functions implementing interrupt handlers for native code need to be _wrapped_ by the macros `NATIVE_INTERRUPT_START` and `NATIVE_INTERRUPT_END` that take care of setting/resetting the appropriate `System_State` flags.
|
||||
|
|
@ -1,24 +0,0 @@
|
|||
# Thread execution
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes how thread execution works with the **nanoFramework** CLR.
|
||||
|
||||
|
||||
## Introduction to Threads
|
||||
|
||||
Oversimplifying it a **nanoFramework** thread is (in terms of execution) basically a stream of IL instructions that are translated by the interpreter making things happen.
|
||||
This execution occurs in a cooperative fashion, meaning that a thread is allowed to run for a certain amount of time, after that it stops and the execution is passed to the next thread that meets the required conditions to run.
|
||||
|
||||
|
||||
## Thread execution
|
||||
|
||||
The **nanoFramework** CLR and interpreter run on a RTOS thread. When the RTOS works in a [cooperative](https://en.wikipedia.org/wiki/Computer_multitasking#Cooperative_multitasking) fashion (opposed to a [preemptive](https://en.wikipedia.org/wiki/Computer_multitasking#Preemptive_multitasking) fashion) the thread is expected to relinquish control to the RTOS so that context switching can occur and the next RTOS thread is given the opportunity to run.
|
||||
This context switching in **nanoFramework** is expected to occur after each time slot that a **nanoFramework** thread is allowed to run.
|
||||
It's up to the target board developer to provide the correct way to relinquish the control of the threads execution according to the RTOS running beneath.
|
||||
This may not be required by all RTOS's. For example when by default the RTOS works in a preemptive fashion, the thread execution occurs in a round robin fashion among the various RTOS threads.
|
||||
|
||||
The execution relinquish to the underlying RTOS, so that the 'next' RTOS thread and other RTOS services can run is performed inside the `Events_WaitForEvents` function that is implemented for each target platform.
|
||||
For the current version of **nanoFramework** this is accomplished in the following ways:
|
||||
- For targets running with ChibiOS (a CMSIS compliant RTOS) a call to `osDelay(10)` is sufficient and allows the kernel to run all the other threads with the same (or higher) priority.
|
||||
- For the ESP32 target - which is running with FreeRTOS - a call to `vTaskDelay(0)` is sufficient and allows the kernel to run all the other threads with the same (or higher) priority.
|
||||
|
|
@ -1,148 +0,0 @@
|
|||
# Wire Protocol
|
||||
|
||||
## Table of contents ##
|
||||
|
||||
- [Wire Protocol Message](#wire-protocol-message)
|
||||
- [Data channels](#data-channels)
|
||||
- [Receiving and transmitting data](#receiving-and-transmitting-data)
|
||||
- [Receiver workflow](#receiver-workflow)
|
||||
- [Wire Protocol Commands](#wire-protocol-commands)
|
||||
- [How to add support for a new command](#how-to-add-support-for-a-new-command)
|
||||
- [How to add support for new channels](#how-to-add-support-for-new-channels)
|
||||
- [HAL interface](#hal-interface)
|
||||
- [Application interface](#application-interface)
|
||||
- [Debugging Wire Protocol communications](#debugging-wire-protocol-communications)
|
||||
- [CRC32 validations](#crc32-validatons)
|
||||
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes the Wire Protocol used by **nanoFramework** for debug and the booter stage.
|
||||
The protocol follows the implementation of the .NET Micro Framework Wire Protocol. The intention is to review it later in order to improve and simplify it.
|
||||
|
||||
|
||||
# Wire Protocol Message
|
||||
|
||||
The message basic structure is comprised by:
|
||||
- Signature which is basically a marker to detect the start of a new message packet. Has a fixed length.
|
||||
- Header with several fields to cary packet sequence, flags, commands, CRC, etc. Has a fixed length.
|
||||
- CRC32 of header (for verification calculation this CRC32 field has to be zeroed).
|
||||
- CRC32 of payload, when it exists (for verification calculation this CRC32 field has to be zeroed).
|
||||
- Command code.
|
||||
- Sequence number of the message.
|
||||
- Sequence reply. Carries the sequence number of the message that the message is a reply to.
|
||||
- Flags.
|
||||
- Size of the payload.
|
||||
- Payload for carrying data. Optional and its size is variable.
|
||||
|
||||
You can check the details on [WireProtocol.h](..\src\CLR\WireProtocol\WireProtocol.h)
|
||||
|
||||
|
||||
# Data channels
|
||||
|
||||
Currently **nanoFramework** Wire Protocol supports only serial channels. The plan is to add support for USB (using CDC class device) and TCP.
|
||||
To ease the port to new HAL/platforms the code is architecture so that only minimal changes are required to add support for new implementations.
|
||||
|
||||
|
||||
# Receiving and transmitting data
|
||||
|
||||
The code is architecture to receive and transmit data over a serial stream.
|
||||
Preferably (and to use the reference implementation provided without much changes) the interface/API of the serial stream should:
|
||||
- Allow checking if there is data available for reading.
|
||||
- Allow reading sequentially (FIFO fashion) the input stream for a definite number of bytes. Having a timeout for the read operation is ideal to prevent bad/incomplete read operations.
|
||||
- Allow writing to the transmit stream a definite number of bytes. Ideally in a non-blocking fashion to prevent bad/incomplete write operations.
|
||||
|
||||
|
||||
# Receiver workflow
|
||||
|
||||
Follows a high-level description on how the Wire Protocol component works.
|
||||
|
||||
- RTOS thread - ```ReceiverThread(...)``` in [WireProtocol_ReceiverThread.c](..\src\CLR\WireProtocol\WireProtocol_ReceiverThread.c) - that loops continuously checking for available data in the receiving channel.
|
||||
- On available data the reception of the message is initialized (WP_Message_Initialize) and prepared (WP_Message_PrepareReception) so the reception can actually occur and be processed by calling WP_Message_Process.
|
||||
- During the reception states the input stream is read (```WP_ReceiveBytes(...)``` in [WireProtocol_HAL_Interface.c](..\src\CLR\WireProtocol\WireProtocol_HAL_Interface.c)) so the message header is received and it's integrity checked. Follows the reception and the integrity check of the payload, if there is any.
|
||||
- After a successful reception of the header (and payload, if any) the _Process_ state machine in [WireProtocol_Message.c](..\src\CLR\WireProtocol\WireProtocol_Message.c)) reaches the ```ReceiveState_CompletePayload``` state and calls the ```ProcessPayload(...)``` function.
|
||||
- Inside ```ProcessPayload(...)``` the lookup table for the commands that are implemented is searched and, if the command is found, the respective handler is called. According to the command its processing can require extra processing or gathering data. Invariably the handler execution end with a call to ```ReplyToCommand(...)``` where the reply is sent back to the host device.
|
||||
- When executing ```ReplyToCommand(...)``` the output stream is written (```WP_TransmitMessage(...)``` in [WireProtocol_HAL_Interface.c](..\src\CLR\WireProtocol\WireProtocol_HAL_Interface.c)) with the reply message.
|
||||
|
||||
|
||||
# Wire Protocol Commands
|
||||
|
||||
Processing a command is carried in a handler function.
|
||||
The collection of the commands that are implemented is listed in ```c_Lookup_Request```. This lookup structure is basically an array with the command code along with a pointer to the respective handler. It resides in *WireProtocol_App_Interface.c*.
|
||||
The actual command implementation resides in *WireProtocol_Commands.c*.
|
||||
|
||||
# How to add support for a new command
|
||||
|
||||
There are two groups of commands: monitor commands and debug commands.
|
||||
|
||||
In order to add a new monitor command you have to:
|
||||
- Add the function declaration and any required structure and/or type definition in [WireProtocol_MonitorCommands.h](..\src\CLR\WireProtocol\WireProtocol_MonitorCommands.h)
|
||||
- Add a weak prototype in [WireProtocol_MonitorCommands.c](..\src\CLR\WireProtocol\WireProtocol_MonitorCommands.c)
|
||||
- The actual code for the command handler function (and any required helper functions or extra processing) is added at target level. For the reference implementation for nanoBooter in ChibiOS check [WireProtocol_MonitorCommands.c](..\targets\CMSIS-OS\ChibiOS\nanoBooter\WireProtocol_MonitorCommands.c)
|
||||
|
||||
To add the command to the collection of the supported monitor commands un-comment or add the respective line in the ```c_Lookup_Request``` variable in _WireProtocol_App_Interface.c_ for both [nanoBooter](..\targets\CMSIS-OS\ChibiOS\nanoBooter\WireProtocol_MonitorCommands.c) and/or [nanoCLR](..\targets\CMSIS-OS\ChibiOS\nanoCLR\WireProtocol_MonitorCommands.c).
|
||||
Because this declaration uses a macro to add the declaration of a command, make sure the existing naming pattern is _**strictly**_ followed.
|
||||
|
||||
This architecture tries to bring flexibility by making it easy to have different monitor commands for nanoBooter and nanoCLR and also having them implemented in different ways, if necessary.
|
||||
|
||||
To ease code portability from .NET Micro Framework code base and maintain an understandable implementation the naming has been maintained or minimally adapted from the original C++ code.
|
||||
Try to follow this as much as possible when implementing new commands or porting the original C++ code to C.
|
||||
|
||||
|
||||
# How to add support for new channels
|
||||
|
||||
Current Wire Protocol implementation has support for transmission over serial port (UART/USART) and serial over USB (USB CDC device class).
|
||||
Support for TCP channel is planned at a later stage.
|
||||
|
||||
When adding support for new channels the functions ```WP_ReceiveBytes(...)``` and ```WP_TransmitMessage(...)``` in _WireProtocol_HAL_Interface.c_ are the ones that need to be reworked. This implementation is target and board specific so it resides in the board folder. Check the reference implementation for the ST_STM32F4_DISCOVERY board [here](..\targets\CMSIS-OS\ChibiOS\ST_STM32F4_DISCOVERY\common\WireProtocol_HAL_Interface.c).
|
||||
|
||||
On both, the relevant part is that they read/write to a serial stream a specified number of bytes. Preferably non blocking calls with a timeout. Please read the comments inside of each of those functions for the details.
|
||||
The last piece that needs to be adjusted is the code inside the ```ReceiverThread(...)``` which is the RTOS thread that is running the Wire Protocol component. That thread is basically a loop with a wait state were the checks for existing data to be read on the input stream. On data available the ```WP_Message_Process(...)``` function is called.
|
||||
|
||||
|
||||
# HAL interface
|
||||
|
||||
The Wire Protocol requires the following functions in order to interface with the HAL.
|
||||
Weak implementations of each function are part of the core code.
|
||||
|
||||
- ```WP_TransmitMessage(...)``` in [WireProtocol_HAL_Interface.c](..\src\CLR\WireProtocol\WireProtocol_HAL_Interface.c)
|
||||
- ```WP_ReceiveBytes(...)``` in [WireProtocol_HAL_Interface.c](..\src\CLR\WireProtocol\WireProtocol_HAL_Interface.c)
|
||||
- ```WP_CheckAvailableIncomingData(...)``` in [WireProtocol_HAL_Interface.c](..\src\CLR\WireProtocol\WireProtocol_HAL_Interface.c)
|
||||
|
||||
An implementation for an STM32F4_DISCOVERY board with ChibiOS (including its HAL) is provided as a reference. Please check it at [WireProtocol_HAL_Interface.c](..\targets\CMSIS-OS\ChibiOS\ST_STM32F4_DISCOVERY\common\WireProtocol_HAL_Interface.c).
|
||||
|
||||
When porting **nanoFramework** to another RTOS or HAL follow the reference implementation to ease the port work.
|
||||
|
||||
|
||||
# Application interface
|
||||
|
||||
The Wire Protocol requires the following functions in order to interface with it's client app.
|
||||
Weak implementations of each function are part of the core code.
|
||||
|
||||
- ```WP_App_ProcessHeader(...)``` in [WireProtocol_App_Interface.c]()
|
||||
- ```WP_App_ProcessPayload(...)``` in [WireProtocol_App_Interface.c]()
|
||||
|
||||
Actual implementations of these are to be provided by nanoBooter and nanoCLR. Please check the reference implementation for ChibiOS at [WireProtocol_App_Interface.c](..\targets\CMSIS-OS\ChibiOS\nanoBooter\WireProtocol_App_Interface.c).
|
||||
|
||||
|
||||
# Debugging Wire Protocol communications
|
||||
|
||||
To ease debugging of Wire Protocol sessions there are available a set of CMake options to adjust the output of the Wire Protocol state machine and TX/Rx operations. The available options are:
|
||||
- NF_WP_TRACE_ERRORS: Enable error tracing.
|
||||
- NF_WP_TRACE_HEADERS: Enable packet headers tracing.
|
||||
- NF_WP_TRACE_STATE: Enable tracing of the current state of the Wire Protocol sate machine.
|
||||
- NF_WP_TRACE_NODATA: Enable tracing of empty or incomplete packets.
|
||||
- NF_WP_TRACE_ALL: Enable all the options above. In case this setting is chosen it takes precedence over all the other and replaces when on.
|
||||
|
||||
|
||||
# CRC32 validations
|
||||
|
||||
In order to ensure Wire Protocol communications integrity the message header and payload have each a CRC32 field that can be filled in with the CRC32 hash of the respective section. This allows the receiver to validate the integrity of both the header and the payload.
|
||||
|
||||
Considering that the most frequent transport layers are USB and Ethernet (under development) which already have their own validation and integrity mechanisms, it might seems a bit paranoid to have this extra validation on top of those. Moreover, in the unlikely event of a garbled packet reaching the end of the parser engine, the wrong data would (most likely) prevent the correct execution of such command.
|
||||
|
||||
In face of the above the CRC32 calculation and validation of the Wire Protocol header and payload has been made optional, meaning that a target can choose *not* to implement that. The Wire Protocol layer in the debugger is able to automatically handle both situations.
|
||||
|
||||
To have a target image built **without** implementing CRC32 validation the option `NF_WP_IMPLEMENTS_CRC32=OFF` has to be passed to CMake.
|
||||
|
||||
In case a less reliable transport layer is used (COM port for example) or if the developer deems this necessary it can be enabled with the option above set to `ON`.
|
||||
|
|
@ -1,14 +0,0 @@
|
|||
# Building **nanoFramework**
|
||||
|
||||
* [Building **nanoFramework**](build-instructions.md)
|
||||
* [Build using local source for RTOS](rtos-source-for-build.md)
|
||||
* [CMake variants for CMake tools](cmake-tools-cmake-variants.md)
|
||||
|
||||
* ### [ChibiOS HAL](chibios-hal)
|
||||
* [GCC linker script for ChibiOS boards](chibios-hal/gcc-linker-script.md)
|
||||
|
||||
* ### [CMake](cmake)
|
||||
* [Building with ChibiOS](cmake/chibios-build.md)
|
||||
* [_Toolchain file_ for STM32 with GNU ARM Embedded](cmake/stm32-gcc-toolchain.md)
|
||||
* [_Toolchain file_ for ChibiOS GNU ARM Embedded](cmake/chibios-toolchain.md)
|
||||
* [Building using Ninja](cmake/ninja-build.md)
|
||||
|
|
@ -1,121 +0,0 @@
|
|||
# Instructions for building **nanoFramework** images
|
||||
|
||||
## Table of contents ##
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Preparation](#preparation)
|
||||
- [Build a **nanoFramework** image](#build-a-nanoframework-image)
|
||||
- [**nanoFramework** build deliverables](#nanoframework-build-deliverables)
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes how to build the required images for **nanoFramework** 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/) (Minimum required version is 3.7)
|
||||
- A build system for CMake to generate the build files to.
|
||||
+ If you have Visual Studio (full version) you can use the included NMake.
|
||||
+ A nice alternative is [Ninja](https://github.com/ninja-build/ninja). This is lightweight build system, designed for speed and it works on Windows and Linux machines. See [here](cmake/ninja-build.md) how to setup Ninja to build **nanoFramework**.
|
||||
|
||||
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 Extension](https://marketplace.visualstudio.com/items?itemName=twxs.cmake)
|
||||
- [CMake Tools Extension](https://marketplace.visualstudio.com/items?itemName=vector-of-bool.cmake-tools)
|
||||
|
||||
In case you specify an RTOS and you want its source to be downloaded 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 ChibiOS 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 etc.
|
||||
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 **nanoFramework** image
|
||||
|
||||
The build script accepts the a number of parameters (some of them are mandatory). Please check the details about each parameter [here](cmake-tools-cmake-variants.md#content-explained).
|
||||
|
||||
_Note 1: The RTOS currently supported (except for ESP32 target) is ChibiOS. If no source path is specified the source files will be downloaded from nanoFramework GitHub fork._
|
||||
_Note 2: 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" \
|
||||
-DCHIBIOS_BOARD=ST_NUCLEO_F091RC \
|
||||
-DTARGET_SERIES=STM32F0xx \
|
||||
-DNF_FEATURE_DEBUGGER=TRUE \
|
||||
-DAPI_Windows.Devices.Gpio=ON \
|
||||
-DNF_FEATURE_RTC=ON \
|
||||
-G "NMake Makefiles" ../
|
||||
```
|
||||
|
||||
This will call CMake (on your *build* directory that is assumed to be under the repository root) specifying the location of the toolchain install, that the target board is named ST_NUCLEO_F091RC, that STM32F0xx is the series name that it belongs to, debugger feature is to be included, Windows.Devices.Gpio API is to be included 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" \
|
||||
-DCHIBIOS_SOURCE=E:/GitHub/ChibiOS \
|
||||
-DCHIBIOS_BOARD=ST_NUCLEO144_F746ZG \
|
||||
-DTARGET_SERIES=STM32F7xx \
|
||||
-DNF_FEATURE_DEBUGGER=TRUE \
|
||||
-DAPI_Windows.Devices.Gpio=ON \
|
||||
-DNF_FEATURE_RTC=ON \
|
||||
-G "NMake Makefiles" ../
|
||||
```
|
||||
|
||||
This will call CMake (on your *build* directory that is assumed to be under the repository root) specifying the location of the toolchain install, specifying that ChibiOS sources to be used are located in the designated path (mind the forward slash and no ending slash), that the target board is named ST_NUCLEO144_F746ZG, that STM32F7xx is the series name that it belongs to, debugger feature is to be included, Windows.Devices.Gpio API is to be included, RTC is used and that the build files suitable for NMake are to be generated.
|
||||
|
||||
After successful 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 CMake uses to generate the build. The default is ```"cmake.generator": "NMake Makefiles"```. The recommendation is to use Ninja as the build tool because it's way faster than NMake.
|
||||
You'll also need to set the use of CMake Server to true, like this: ```"cmake.useCMakeServer" : true```.
|
||||
- launch.json (inside .vscode folder) here you can set up your launch configurations, such as gdb path or OpenOCD configuration. We've made available Gists with launch.json for several of the reference targets. Grab yours from [here](https://gist.github.com/nfbot). :warning: Remember to update paths and other preferences according to your setup and machine configuration. :wink:
|
||||
- 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://vector-of-bool.github.io/docs/vscode-cmake-tools/variants.html#). We've made available Gists with cmake-variants.json for each of the reference targets. Grab yours from [here](https://gist.github.com/nfbot). :warning: Remember to update paths and other preferences according to your setup and machine configuration. :wink:
|
||||
|
||||
To launch the build in VS Code check the status bar at the bottom. Select the build flavor and then click the build button (or hit F7).
|
||||
|
||||
|
||||
# **nanoFramework** build deliverables
|
||||
|
||||
After a successful build you can find the **nanoFramework** image files in the *build* directory. Those are:
|
||||
|
||||
- nanoBooter image (not available for ESP32 builds):
|
||||
- nanoBooter.bin (raw binary format)
|
||||
- nanoBooter.hex (Intel hex format)
|
||||
- nanoBooter.s19 (Motorola S-record format, equivalent to srec)
|
||||
- nanoBooter.lst (source code listing intermixed with disassembly)
|
||||
- nanoBooter.map (image map)
|
||||
|
||||
- nanoCLR image:
|
||||
- nanoCLR.bin (raw binary format)
|
||||
- nanoCLR.hex (Intel hex format)
|
||||
- nanoCLR.s19 (Motorola S-record format, equivalent to srec)
|
||||
- nanoCLR.lst (source code listing intermixed with disassembly)
|
||||
- nanoCLR.map (image map)
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
# GCC linker script for ChibiOS boards
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes the GCC linker script for **nanoFramework** boards using ChibiOS HAL/PAL and some explanations on how to customize and adapt it to a new target board.
|
||||
|
||||
|
||||
## Linker script file naming
|
||||
|
||||
To make it very clear on what file belongs to what image, the linker script files names carry a suffix of '_booter' for the nanoBooter and '_CLR' for the nanoCLR.
|
||||
|
||||
These linker scripts are used by the linker at the link stage and are added to the build on the CMakeLists.txt global to a target board.
|
||||
|
||||
When adding a new target board make sure that you set each linker script file to the appropriate target (in CMake, that is).
|
||||
|
||||
It's also recommended that each linker script file is located in the respective nanoBooter or nanoCLR folder (these being inside a target board folder, that is).
|
||||
|
||||
|
||||
## Configurations for nanoBooter link script
|
||||
|
||||
The nanoBooter image is located at the default boot address of the target Soc/MCU.
|
||||
|
||||
It's recommended that that the region length is set to match the FLASH space reserved for the nanoBooter. This adds an extra check because when the build and link occurs, if the image is too large to fit that space an error is generated and corrective actions can be taken.
|
||||
|
||||
To illustrate this we are going to look into the linker script for the ST_NUCLEO_F091RC board. This is file [STM32F091xC_booter.ld](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/nanoBooter/STM32F091xC_booter.ld).
|
||||
|
||||
|
||||
The only configuration here is the length of the `flash` region that should be set to the FLASH space reserved for the nanoBooter. In the example it can be seen that the nanoBooter image will start at address 0x08000000, with a maximum size of 16K.
|
||||
|
||||
|
||||
## Configurations for nanoCLR link script
|
||||
|
||||
The nanoCLR image is located at the designated address of the available FLASH space, typically right after the space reserved for the nanoBooter.
|
||||
|
||||
It's recommended that that the region length is set to match the FLASH space reserved for the nanoCLR. This adds an extra check because when the build and link occurs, if the image is too large to fit that space an error is generated and corrective actions can be taken.
|
||||
|
||||
To illustrate this we are going to look into the linker script for the ST_NUCLEO_F091RC board. This is file [STM32F091xC_CLR.ld](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/nanoCLR/STM32F091xC_CLR.ld).
|
||||
|
||||
|
||||
The `flash` region configuration depends on two factors: the space reserved for nanoBooter image and the space reserved for application deployment.
|
||||
In the example it can be seen that nanoCLR image will start at address 0x08004000 and has a maximum size of 256k - 16k - 100k. That's the size reserved for nanoBooter and the size reserved for the application deployment.
|
||||
|
||||
On this particular example (because this SoC requires that the vector table is copied to RAM) the `ram0` region needs to be tweaked so it starts after the space reserved for the vector table. The end result is `ram0` starting at 0x200000C0 with a length of 32k - 0xC0.
|
||||
|
||||
|
||||
### Tips
|
||||
|
||||
- When designing the address map make sure that the address region boundaries **match the FLASH memory blocks**. This is very important in order to be able to perform image updates. This is valid for nanoBooter, nanoCLR and application deployment.
|
||||
|
||||
- The link script accepts several number format. Use the one that is convenient for what you are specifying.
|
||||
Follow some examples. For an absolute address (such as the start of a FLASH block) use the hexadecimal notation like in 0x08000000. When specifying the size of a region use the _k_ and _M_ suffixes, like 16k for a block with 16k Bytes (4096 bytes), or 1M. This makes it much easier to copy/paste from the device data sheet.
|
||||
|
||||
- It's OK to use mathematical expressions. For example, when setting the available space for the nanoCLR image don't bother with doing the math, just put there 1M - 16k.
|
||||
|
|
@ -1,188 +0,0 @@
|
|||
# Tweaking cmake-variants.TEMPLATE.json
|
||||
|
||||
### Table of contents ##
|
||||
|
||||
- [What is it](#what-is-it)
|
||||
- [How to use it](#how-to-use-it)
|
||||
- [Brief description](#brief-description)
|
||||
- [Content explained](#content-explained)
|
||||
- [Working example](#working-example)
|
||||
- [Templates](#templates)
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes how to use and modify the **cmake-variants.TEMPLATE.json** file to suit your needs.
|
||||
|
||||
_Note : the current revision of the document only focuses on using ChibiOS RTOS. Other RTOSes will follow in a future revision._
|
||||
|
||||
## What is it
|
||||
|
||||
cmake-variants.TEMPLATE.json is a template containing a minimal set of configuration examples needed to build nanoFramework for you board.
|
||||
|
||||
Its content describes what kind of build you will get, which toolchain(s) you will use, which type of MCU is on the board, and some other options that will be described later in this document.
|
||||
|
||||
## How to use it
|
||||
|
||||
First, you have to either rename the file or copy the contents to **cmake-variants.json**. Then, you will have to modify the content to match your environment.
|
||||
|
||||
|
||||
## Brief description
|
||||
|
||||
There are two sets of parameters that need to be present in this file :
|
||||
- the build type : 'debug' or 'release', for example
|
||||
- the board's environment : MCU, toolchain, RTOS
|
||||
|
||||
You should not have to modify the *BuildType* section unless you have good reasons to do so. However, the *Linkage* section is the one you will have to take care of.
|
||||
|
||||
For each *board* you want to build, you will have to create a dedicated section in the *Linkage* area, precisely describing the MCU, the toolchain, the build type and the RTOS you will use.
|
||||
|
||||
## Content explained
|
||||
The following explains each line of the *linkage* section. Text highlighted in **bold** is an information that you will have to provide.
|
||||
|
||||
**_Note : Mind the forward slash ('/') in paths strings !_**
|
||||
|
||||
- "**OPTION1_NAME_HERE**"
|
||||
- Replace this text with a distinctive option name. e.g. *"STM32F429_Disco"*
|
||||
- "short": "**<summary-here>**"
|
||||
- Replace the *<summary-here>* text with one word describing shortly your board. e.g. "F429Disco"
|
||||
- "long": "**<description-here>**"
|
||||
- This is a more complete description of the configuration
|
||||
- "BUILD_VERSION" : "**version-number-for-the-build-format-is-N.N.N.N**"
|
||||
- "TOOLCHAIN_PREFIX" : "**absolute-to-gcc-toolchain-mind-the-forward-slash**"
|
||||
- This is the path to your gcc toolchain compiler. Use forward slashes and do not provide executable name here
|
||||
- "TOOL_HEX2DFU_PREFIX" : "**absolute-path-to-hex2dfu-utility-mind-the-forward-slash**"
|
||||
- This is the path to the HEX2DFU utility. Use forward slashes and do not provide executable name here.
|
||||
- "ESP32_IDF_PATH" : "**absolute-path-to-esp-idf-mind-the-forward-slash**"
|
||||
- This the path to the ESP32 IDF utility. Use forward slashes and do not provide executable name here.
|
||||
- "ESP32_LIBS_PATH" : "**absolute-path-to-the-ESP32-libs-folder-mind-the-forward-slashes**"
|
||||
- This is the path to the folder where the ESP32 libraries can be found. Use forward slashes.
|
||||
- "EXECUTABLE_OUTPUT_PATH" : "**${workspaceRoot}/build**"
|
||||
- This is the default and recommended path which will expand to the build folder when building from VS Code. When building from the command line or from Visual Studio this is not required.
|
||||
- "TARGET_SERIES" : "**STM32F7xx**"
|
||||
- For STM32 MCUs represents the target series (STM32F4XX, STM32L4XX, and so on)
|
||||
- For ESP32 matches the target name: "ESP32_WROOM_32"
|
||||
- "USE_RNG" : "**ON**"
|
||||
- Option to enable the use of the hardware true random generator unit, if present. Default is ON as the majority of the targets have this feature.
|
||||
- "DP_FLOATINGPOINT" : "**OFF**"
|
||||
- Enables support for double-precision floating point. The default is single-precision. Set to ON to enable double precision floating point.
|
||||
- "SUPPORT_ANY_BASE_CONVERSION" : "**OFF**"
|
||||
- Defines which bases are supported when performing string to value conversions. When ON support for any base is enabled. When OFF (the default) the image will be compiled with support for base 10 and base 16 only.
|
||||
- "RTOS" : "**one-of-valid-rtos-options**"
|
||||
- Defines the RTOS that will be used to build nanoFramework. It can be CHIBIOS or FREERTOS_ESP32. Currently ChibiOS is supported for all STM32 targets and FreeRTOS is supported for ESP32 targets.
|
||||
- "CHIBIOS_SOURCE" : "**absolute-path-to-chibios-source-mind-the-forward-slash**"
|
||||
- Path to an optional local installation of ChibiOS source files. If no path is given, then CMake will download the sources from the projects ChibiOS repository when needed
|
||||
- "CHIBIOS_BOARD" : "**valid-chibios-board-name-from-boards-collection**"
|
||||
- Name of your board, chosen from the available boards collection that can be found in the \os\hal\boards folder of the ChibiOS installation (or distant repository)
|
||||
- "SWO_OUTPUT" : "**OFF**"
|
||||
- Allows specifying whether to include, or not, support for Cortex-M Single Wire Output (SWO). Default is OFF. Check the documentation [here](arm-swo.md) for more details on how to use SWO.
|
||||
- "NF_BUILD_RTM" : "**OFF**"
|
||||
- Sets if the build is of **R**eady **T**o **M**arket type. Meaning that all debug helpers and code blocks will be removed from compilation and the build will be compiled and linked with all possible code reducing options enabled.
|
||||
- "NF_WP_TRACE_ERRORS" : "**OFF**"
|
||||
- Enable error tracing in Wire Protocol.
|
||||
- "NF_WP_TRACE_HEADERS" : "**OFF**"
|
||||
- Enable packet headers tracing in Wire Protocol.
|
||||
- "NF_WP_TRACE_STATE" : "**OFF**"
|
||||
- Enable state tracing in Wire Protocol.
|
||||
- "NF_WP_TRACE_NODATA" : "**OFF**"
|
||||
- Enable tracing of empty or incomplete packets in Wire Protocol.
|
||||
- "NF_WP_TRACE_ALL" : "**OFF**"
|
||||
- Enable all tracing options for Wire Protocol.
|
||||
- "NF_WP_IMPLEMENTS_CRC32" : "**OFF**"
|
||||
- Enable CRC32 calculations for Wire Protocol. See details [here](../architecture/wire-protocol.md#crc32-validatons).
|
||||
- "NF_FEATURE_DEBUGGER" : "**OFF**"
|
||||
- Defines is support for debuggin managed applications is enabled. Default is OFF.
|
||||
- "NF_FEATURE_RTC" : "**OFF**"
|
||||
- Allows you to specify whether to use the real time clock unit of the hardware for date & time functions. Depends on target availability. Default is OFF.
|
||||
- "NF_FEATURE_USE_APPDOMAINS" : "**OFF**"
|
||||
- Allows you to specify whether to include, or not, support for Application Domains. Default is OFF. More information about this is available in the documentation [here](https://msdn.microsoft.com/en-us/library/cxk374d9(v=vs.90).aspx). ***Note that the complete removal of support for this feature is being considered (see issue [here](https://github.com/nanoframework/nf-interpreter/issues/303)).***
|
||||
- "NF_FEATURE_WATCHDOG" : "**ON**"
|
||||
- Allows you to define it the hardware watchdog should be disabled.
|
||||
This setting can only be set to OFF for STM32 targets. ESP32 build enables this by default so there is no way to disable it.
|
||||
Default is ON, so the hardware watchdog will be enabled by default.
|
||||
- "NF_FEATURE_HAS_CONFIG_BLOCK" : "**OFF**"
|
||||
- Allows the developer to set if the targets platform has configuration block.
|
||||
This requires the the block storage definition and the linker files add support for that.
|
||||
Default is OFF meaning that that the target DOES NOT have configuration block.
|
||||
- "NF_PLATFORM_NO_CLR_TRACE" : "**OFF**"
|
||||
- Allows you to define if trace messages and checks are added to CLR or not.
|
||||
These checks are usually valuable when debugging issues within the CLR.
|
||||
Can and should be removed for RTM build flavours.
|
||||
Default is OFF meaning that all the standard trace and checks are added to the CLR.
|
||||
- "NF_CLR_NO_IL_INLINE" : "**OFF**"
|
||||
- Allows you to define if CLR will use IL inlining.
|
||||
Default is OFF meaning that CLR will inline IL.
|
||||
- "NF_INTEROP_ASSEMBLIES" : [ "Assembly1-Namespace", "Assembly2-Namespace" ]
|
||||
- Lists the name of the Interop assembly(ies) to be added to the build. Leave empty or don't add it if no Interop assembly is to be added.
|
||||
- "API_nanoFramework.Devices.OneWire" : "**OFF**"
|
||||
- Allows you to specify whether support for Devices.OneWire is available to your application. Default is OFF.
|
||||
- "API_System.Net" : "**OFF**"
|
||||
- Allows you to specify whether System.Net support is available to your application. Default is OFF.
|
||||
- "API_Windows.Devices.Adc" : "**OFF**"
|
||||
- Allows you to specify whether ADC functions are available to your application. Default is OFF.
|
||||
- "API_Windows.Devices.Gpio" : "**OFF**"
|
||||
- Allows you to specify whether GPIO functions are available to your application. Default is OFF.
|
||||
- "API_Windows.Devices.I2c" : "**OFF**"
|
||||
- Allows you to specify whether I2C functions are available to your application. Default is OFF.
|
||||
- "API_Windows.Devices.Pwm" : "**OFF**"
|
||||
- Allows you to specify whether PWM functions are available to your application. Default is OFF.
|
||||
- "API_Windows.Devices.SerialCommunication" : "**OFF**"
|
||||
- Allows you to specify whether Serial Communication functions are available to your application. Default is OFF.
|
||||
- "API_Windows.Devices.Spi" : "**OFF**"
|
||||
- Allows you to specify whether SPI functions are available to your application. Default is OFF.
|
||||
- "API_Windows.Networking.Sockets" : "**OFF**"
|
||||
- Allows you to specify whether Networking Sockets functions are available to your application. Default is OFF.
|
||||
- "API_Windows.Storage" : "**OFF**"
|
||||
- Allows you to specify whether Windows.Storage functions are available to your application. Default is OFF.
|
||||
- "API_Hardware.Esp32" : "**OFF**"
|
||||
- Allows you to specify whether Hardware.Esp32 functions are available to your application. Default is OFF.
|
||||
Note that this API is exclusive of ESP32 targets and can't be used with any other.
|
||||
- "API_Hardware.Stm32" : "**OFF**"
|
||||
- Allows you to specify whether Hardware.Stm32 functions are available to your application. Default is OFF.
|
||||
Note that this API is exclusive of STM32 targets and can't be used with any other.
|
||||
|
||||
|
||||
## Working example
|
||||
The following linkage section is a real example used to build nanoFramework for the MBN Quail board. It is using the minimal mandatory information :
|
||||
|
||||
```
|
||||
"MBNQUAIL":
|
||||
{
|
||||
"oneWordSummary$": "QUAIL",
|
||||
"description$": "MBN Quail",
|
||||
"settings":
|
||||
{
|
||||
"TOOLCHAIN_PREFIX" : "C:/Program Files (x86)/GNU Tools ARM Embedded/5.4 2016q3",
|
||||
"TARGET_CHIP" : "STM32F427VIT",
|
||||
"TARGET_SERIES" : "STM32F4xx",
|
||||
"RTOS" : "CHIBIOS",
|
||||
"CHIBIOS_SOURCE" : "C:/dev/ChibiOS_16.1.7",
|
||||
"CHIBIOS_BOARD" : "MBN_QUAIL"
|
||||
"NF_FEATURE_DEBUGGER" : "TRUE",
|
||||
"NF_FEATURE_RTC" : "ON",
|
||||
"NF_FEATURE_USE_APPDOMAINS" : "OFF",
|
||||
"NF_FEATURE_USE_NETWORKING" : "OFF",
|
||||
"API_Windows.Devices.Gpio" : "ON"
|
||||
},
|
||||
"buildType": "Debug"
|
||||
},
|
||||
```
|
||||
|
||||
## Templates
|
||||
|
||||
To make your life easier, we provide templates with pre-configured cmake-variants.json for the various reference targets. Just grab them from our Gist.
|
||||
|
||||
- [ST_STM32F4_DISCOVERY](https://gist.github.com/nfbot/d4dbea239069146fe30d0869463507a8)
|
||||
|
||||
- [ST_STM32F429I_DISCOVERY](https://gist.github.com/nfbot/a5e04d750ff67d7b377f6aea74514208)
|
||||
|
||||
- [ST_NUCLEO_F091RC](https://gist.github.com/nfbot/cf7f6cfeb6f776ba068985bc44c005f0)
|
||||
|
||||
- [ST_NUCLEO144_F746ZG](https://gist.github.com/nfbot/6de229c9e6e64d5c48b729e077af7153)
|
||||
|
||||
- [ST_STM32F769I_DISCOVERY](https://gist.github.com/nfbot/efd47b5cfffdc7e54e388c37f1cb7a9c)
|
||||
|
||||
- [MBN_QUAIL](https://gist.github.com/nfbot/06723075c41d4e8f66ba511a4ce46e3f)
|
||||
|
||||
- [NETDUINO3_WIFI](https://gist.github.com/nfbot/dae2411ba9d2251c45d302ea1cac135a)
|
||||
|
||||
- [ESP32_WROOM_32](https://gist.github.com/nfbot/627051a2f9f459d3c8f17752ca4985be)
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
# CMake configuration files documentation
|
||||
|
||||
- [Building ChibiOS](chibios-build.md)
|
||||
- [_Toolchain file_ for STM32 with GNU ARM Embedded](stm32-gcc-toolchain.md)
|
||||
- [_Toolchain file_ for ChibiOS GNU ARM Embedded](chibios-toolchain.md)
|
||||
- [Building using Ninja](ninja-build.md)
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
# CMake file for building ChibiOS from sources
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes the purpose and workflow for the CMake configuration files to build ChibiOS from the repository sources.
|
||||
Building ChibiOS from sources might be needed when debugging a **nanoFramework** feature that interacts with it.
|
||||
|
||||
|
||||
# Purpose
|
||||
|
||||
The purpose of the configuration files collections is to create a CMake package for ChibiOS and build it.
|
||||
|
||||
|
||||
# Reasoning
|
||||
|
||||
The sources from ChibiOS can be downloaded from their GitHub mirror repository or, if already available in the build machine, can be copied to the build folder.
|
||||
When invoking CMake these options are passed specifying ```RTOS=CHIBIRTOS``` and ```CHIBI_SOURCE=path-to-the-local-repository-folder```.
|
||||
|
||||
_Note: when specifying the location of a local clone make sure that the correct branch is checked out._
|
||||
|
||||
# Workflow
|
||||
|
||||
ChibiOS HAL is based on _boards_. The collection of supported boards and the respective configurations live in hal/boards directory.
|
||||
**nanoFramework** includes an 'overlay' for ChibiOS were supported boards can be added. This collection is also checked for the target board. The collection of supported boards and the respective configurations implemented in the 'overlay' live in /targets/CMSIS-OS/ChibiOS/nf-overlay/os/hal/boards directory.
|
||||
|
||||
A **nanoFramework** target can also include the ChibiOS board definitions. This is the advisable approach for OEM boards.
|
||||
In this case the board.c and board.h files have to be included right in the target directory.
|
||||
|
||||
Support for each board in **nanoFramework** is required. This is were the configuration details and components/features are specified and/or configured. CMakes checks if the target board is available in the targets collection. The collection of board support is at /targets/CMSIS-OS/ChibiOS.
|
||||
|
||||
After successfully finding the board support in both ChibiOS and **nanoFramework** targets, CMake checks the TARGET_SERIES in the list of supported series in order to figure out the series for later use. Please check the code at [FindCHIBIOS.cmake](../../CMake/Modules/FindCHIBIOS.cmake) for details.
|
||||
(NOTE: the current code has been validated for STM boards only)
|
||||
|
||||
The _FindCHIBIOS.cmake_ includes the specifics for the target series and the respective GCC options.
|
||||
The file naming logic is:
|
||||
- CHIBIOS_**STM32F0xx**_sources.cmake: common source files for the series (with the series name in bold)
|
||||
- CHIBIOS_**STM32F0xx**_GCC_options.cmake: GCC options for the series (with the series name in bold)
|
||||
|
||||
When adding a new vendor/series/board follow these general guidelines:
|
||||
1. When in doubt try to follow the make files of the repo. They'll give you all the details that you need in order to replicate that in the CMake files.
|
||||
2. Check if the series file exists. If not, create it and add the source files and include directories.
|
||||
3. Check if the target series name is contained in the `CHIBIOS_SUPPORTED_SERIES` list. If not add the series name there.
|
||||
4. Check if the linker file name is listed in the series file. If not, add it.
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
# CMake _toolchain file_ for ChibiOS with GNU ARM Embedded Toolchain
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes the CMake module that is loaded as a _toolchain file_ to support ChibiOS target 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
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
# Using Ninja to build **nanoFramework**
|
||||
|
||||
|
||||
## Inside VS Code using CMake Tools
|
||||
|
||||
To setup the CMake tools to build using Ninja you have to follow the following steps:
|
||||
|
||||
1. Download and place the Ninja executable in a folder.
|
||||
|
||||
2. Edit the `settings.json` file that VS Code places inside the .vscode folder
|
||||
|
||||
3. Find a line for `"cmake.generator"`. If you don't have one just add it like this: `"cmake.generator": "Ninja",`
|
||||
|
||||
4. Find a line for `"cmake.configureSettings"`. This is were the full path to the Nina executable should be set. Mind the forward slashes.
|
||||
If you don't have one just add a block like this: `"cmake.configureSettings": { "CMAKE_MAKE_PROGRAM": "E:/ninja/ninja.exe" },`
|
||||
|
||||
And that is it! Hit F7 or click the build configuration options for CMake Tools at the bottom toolbar.
|
||||
|
||||
|
||||
## Performance comparison
|
||||
|
||||
A simple test to compare the performance of NMake and Ninja was carried. It's a complete build (nanoBooter and nanoCLR) for a STM32F429I_DISCOVERY target with debugger and GPIO enabled.
|
||||
|
||||
| Build tool | Time to complete build |
|
||||
| --- | --- |
|
||||
| NMake | 3m 17sec |
|
||||
| Ninja | 1m 19sec |
|
||||
|
|
@ -1,24 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
## Building **nanoFramework** with local RTOS source vs RTOS source from repository
|
||||
|
||||
|
||||
When building **nanoFramework** for a CMSIS target (currently only ChibiOS is supported) the developer has two options: either using a local path for the RTOS source code or downloading it from the official repository.
|
||||
This document aims to give you an brief overview of the differences between these two so you can choose the option that best fits your use scenario.
|
||||
|
||||
|
||||
### Source from official repository
|
||||
|
||||
When running CMake, if the parameter `-DCHIBIOS_SOURCE` is not not specified CMake will connect to **nanoFrameworks** [ChibiOS mirror](https://github.com/nanoframework/ChibiOS) on GitHub and will clone the source from there. The time for this operation to complete will mostly depend on the speed of your internet connection.
|
||||
|
||||
ChibiOS will be cached within the build directory so the full download won't happen again unless the build directory is cleared. A check for any changes in the repo is made whenever a build is run. If there are any, the changes will be downloaded and merged.
|
||||
|
||||
This option is good for automated builds or when you don't have (or don't want) the repo cloned to your local storage device.
|
||||
|
||||
Another advantage is that you don't have to manage the updates to the local clone yourself.
|
||||
|
||||
An obvious disadvantage is that if the build folder is cleaned (required when switching between target boards) the 'cached' repo will be gone and a full download will occur when the project is next built.
|
||||
|
||||
|
||||
### Source from local clone
|
||||
|
||||
When running CMake, if the parameter `-DCHIBIOS_SOURCE="....."` is specified a local clone located at the designated path will be used when the build occurs.
|
||||
The only _timing penalty_ is the one necessary for CMake to copy the contents of the local ChibiOS repo to the build cache folder. This is a one time operation and it won't happen again unless the build folder is cleaned up.
|
||||
|
||||
This option is good when you have a local clone of the repo and you don't want to increase the build time with checks on the repo and downloading it or wish to target a different branch (such as `master`).
|
||||
|
||||
The downside is that you have to manage the update process for the ChibiOS repo yourself.
|
||||
|
||||
Another important aspect to consider is the branch **to _manually_ checkout**. Not doing this is synonym of using the 'master' branch that contains the development files and is not a stable version, which is probably not what you want to use.
|
||||
|
||||
Also here, if the build folder is cleaned the 'cached' repo will be gone.
|
||||
|
|
@ -1,14 +0,0 @@
|
|||
# Contributing to **nanoFramework**
|
||||
|
||||
- [API review process](api-review-process.md)
|
||||
- [Contribution workflow](contributing-workflow.md)
|
||||
- [C# Coding Style](cs-coding-style.md)
|
||||
- [C/C++ Coding Style](cxx-coding-style.md)
|
||||
- [GitHub Labels](labels.md)
|
||||
- [Project priorities](project-priorities.md)
|
||||
- [Contribution License Agreement](cla.md)
|
||||
|
||||
* ### [Developing native code](developing-native/)
|
||||
* [Debug with VS Code](developing-native/vscode-debug-instructions.md)
|
||||
* [Debug class libraries and startup](developing-native/debugging-class-libraries.md)
|
||||
* [Use a viewer to watch output from Cortex-M SWO](developing-native/arm-swo.md)
|
||||
|
|
@ -1,100 +0,0 @@
|
|||
# nanoFramework Individual Contributor License Agreement #
|
||||
|
||||
|
||||
Thank you for your interest in contributing to nanoFramework ("We" or "Us").
|
||||
|
||||
|
||||
This contributor agreement ("Agreement") documents the rights granted by contributors to Us. To make this document effective, please sign it and send it to Us by electronic submission, following the instructions at . This is a legally binding document, so please read it carefully before agreeing to it. The Agreement may cover more than one software project managed by Us.
|
||||
|
||||
|
||||
## 1. Definitions ##
|
||||
|
||||
|
||||
"You" means the individual who Submits a Contribution to Us.
|
||||
|
||||
|
||||
"Contribution" means any work of authorship that is Submitted by You to Us in which You own or assert ownership of the Copyright. If You do not own the Copyright in the entire work of authorship, please follow the instructions in .
|
||||
|
||||
|
||||
"Copyright" means all rights protecting works of authorship owned or controlled by You, including copyright, moral and neighboring rights, as appropriate, for the full term of their existence including any extensions by You.
|
||||
|
||||
|
||||
"Material" means the work of authorship which is made available by Us to third parties. When this Agreement covers more than one software project, the Material means the work of authorship to which the Contribution was Submitted. After You Submit the Contribution, it may be included in the Material.
|
||||
|
||||
|
||||
"Submit" means any form of electronic, verbal, or written communication sent to Us or our representatives, including but not limited to electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, Us for the purpose of discussing and improving the Material, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
|
||||
|
||||
|
||||
"Submission Date" means the date on which You Submit a Contribution to Us.
|
||||
"Effective Date" means the date You execute this Agreement or the date You first Submit a Contribution to Us, whichever is earlier.
|
||||
|
||||
|
||||
## 2. Grant of Rights ##
|
||||
|
||||
### 2.1 Copyright License ###
|
||||
|
||||
(a) You retain ownership of the Copyright in Your Contribution and have the same rights to use or license the Contribution which You would have had without entering into the Agreement.
|
||||
|
||||
(b) To the maximum extent permitted by the relevant law, You grant to Us a perpetual, worldwide, non-exclusive, transferable, royalty-free, irrevocable license under the Copyright covering the Contribution, with the right to sublicense such rights through multiple tiers of sublicensees, to reproduce, modify, display, perform and distribute the Contribution as part of the Material; provided that this license is conditioned upon compliance with Section 2.3.
|
||||
|
||||
|
||||
### 2.2 Patent License ##
|
||||
|
||||
For patent claims including, without limitation, method, process, and apparatus claims which You own, control or have the right to grant, now or in the future, You grant to Us a perpetual, worldwide, non-exclusive, transferable, royalty-free, irrevocable patent license, with the right to sublicense these rights to multiple tiers of sublicensees, to make, have made, use, sell, offer for sale, import and otherwise transfer the Contribution and the Contribution in combination with the Material (and portions of such combination). This license is granted only to the extent that the exercise of the licensed rights infringes such patent claims; and provided that this license is conditioned upon compliance with Section 2.3.
|
||||
|
||||
|
||||
### 2.3 Outbound License ###
|
||||
|
||||
As a condition on the grant of rights in Sections 2.1 and 2.2, We agree to license the Contribution only under the terms of the license or licenses which We are using on the Submission Date for the Material (including any rights to adopt any future version of a license if permitted).
|
||||
|
||||
|
||||
### 2.4 Moral Rights. ###
|
||||
|
||||
If moral rights apply to the Contribution, to the maximum extent permitted by law, You waive and agree not to assert such moral rights against Us or our successors in interest, or any of our licensees, either direct or indirect.
|
||||
|
||||
|
||||
### 2.5 Our Rights. ###
|
||||
|
||||
You acknowledge that We are not obligated to use Your Contribution as part of the Material and may decide to include any Contribution We consider appropriate.
|
||||
|
||||
|
||||
### 2.6 Reservation of Rights. ###
|
||||
|
||||
Any rights not expressly licensed under this section are expressly reserved by You.
|
||||
|
||||
|
||||
## 3. Agreement ##
|
||||
|
||||
You confirm that:
|
||||
|
||||
(a) You have the legal authority to enter into this Agreement.
|
||||
|
||||
(b) You own the Copyright and patent claims covering the Contribution which are required to grant the rights under Section 2.
|
||||
|
||||
(c) The grant of rights under Section 2 does not violate any grant of rights which You have made to third parties, including Your employer. If You are an employee, You have had Your employer approve this Agreement or sign the Entity version of this document. If You are less than eighteen years old, please have Your parents or guardian sign the Agreement.
|
||||
|
||||
(d) You have followed the instructions in , if You do not own the Copyright in the entire work of authorship Submitted.
|
||||
|
||||
|
||||
## 4. Disclaimer ##
|
||||
|
||||
EXCEPT FOR THE EXPRESS WARRANTIES IN SECTION 3, THE CONTRIBUTION IS PROVIDED "AS IS". MORE PARTICULARLY, ALL EXPRESS OR IMPLIED WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY DISCLAIMED BY YOU TO US. TO THE EXTENT THAT ANY SUCH WARRANTIES CANNOT BE DISCLAIMED, SUCH WARRANTY IS LIMITED IN DURATION TO THE MINIMUM PERIOD PERMITTED BY LAW.
|
||||
|
||||
|
||||
## 5. Consequential Damage Waiver ##
|
||||
|
||||
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL YOU BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF ANTICIPATED SAVINGS, LOSS OF DATA, INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL AND EXEMPLARY DAMAGES ARISING OUT OF THIS AGREEMENT REGARDLESS OF THE LEGAL OR EQUITABLE THEORY (CONTRACT, TORT OR OTHERWISE) UPON WHICH THE CLAIM IS BASED.
|
||||
|
||||
|
||||
## 6. Miscellaneous ##
|
||||
|
||||
6.1 This Agreement will be governed by and construed in accordance with the laws of excluding its conflicts of law provisions. Under certain circumstances, the governing law in this section might be superseded by the United Nations Convention on Contracts for the International Sale of Goods ("UN Convention") and the parties intend to avoid the application of the UN Convention to this Agreement and, thus, exclude the application of the UN Convention in its entirety to this Agreement.
|
||||
|
||||
|
||||
6.2 This Agreement sets out the entire agreement between You and Us for Your Contributions to Us and overrides all other agreements or understandings.
|
||||
|
||||
6.3 If You or We assign the rights or obligations received through this Agreement to a third party, as a condition of the assignment, that third party must agree in writing to abide by all the rights and obligations in the Agreement.
|
||||
|
||||
6.4 The failure of either party to require performance by the other party of any provision of this Agreement in one situation shall not affect the right of a party to require such performance at any time in the future. A waiver of performance under a provision in one situation shall not be considered a waiver of the performance of the provision in the future or a waiver of the provision in its entirety.
|
||||
|
||||
6.5 If any provision of this Agreement is found void and unenforceable, such provision will be replaced to the extent possible with a provision that comes closest to the meaning of the original provision and which is enforceable. The terms and conditions set forth in this Agreement shall apply notwithstanding any failure of essential purpose of this Agreement or any limited remedy to the maximum extent possible under law.
|
||||
|
|
@ -1,217 +0,0 @@
|
|||
# Contribution Workflow
|
||||
|
||||
You can contribute to **nanoFramework** with issues and PRs. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated.
|
||||
|
||||
|
||||
### Table of contents
|
||||
|
||||
- [Getting Started](#getting-started)
|
||||
- [Making a change](#making-a-change)
|
||||
- [Typos](#typos)
|
||||
- [Coding Style Changes](#coding-style-changes)
|
||||
- [Commit Messages](#commit-messages)
|
||||
- [Contributor License Agreement](#contributor-license-agreement)
|
||||
- [PR Feedback](#pr-feedback)
|
||||
- [Working on an open issue](#working-on-an-open-issue)
|
||||
- [Suggested Workflow](#suggested-workflow)
|
||||
- [General git resources](#general-git-resources)
|
||||
|
||||
|
||||
## Getting Started
|
||||
|
||||
If you are looking at getting your feet wet with some simple (but still beneficial) changes, check out [_up-for-grabs_](https://github.com/nanoframework/Home/issues?q=is%3Aissue+is%3Aopen+label%3Aup-for-grabs) issues on the [**nanoFramework** Home](https://github.com/nanoframework/Home) repo.
|
||||
|
||||
For new ideas, please always start with an issue before starting development of an implementation. See [project priorities](project-priorities.md) to understand the team's approach to engagement on general improvements to the product.
|
||||
|
||||
You do not need to file an issue for trivial changes (e.g. typo fixes). Just create a PR for those changes.
|
||||
|
||||
|
||||
## Making a change
|
||||
|
||||
Make a quality change. Consider and document (preferably with tests) as many usage scenarios as you can to ensure that your change will work correctly in the miriad of ways it might get used.
|
||||
|
||||
There are several issues to keep in mind when making a change.
|
||||
|
||||
|
||||
## Typos
|
||||
|
||||
Typos are embarrassing! We will accept most PRs that fix typos. In order to make it easier to review your PR, please focus on a given component with your fixes or on one type of typo across the entire repository. If it's going to take >30 mins to review your PR, then we will probably ask you to chunk it up.
|
||||
|
||||
|
||||
## Coding Style Changes
|
||||
|
||||
We would like to have **nanoFramework** in full conformance with the style guidelines described here [C/C++ Coding Style](cxx-coding-style.md) and here [C# Coding Style](cs-coding-style.md). We plan to do that with tooling, in a holistic way. In the meantime, please:
|
||||
|
||||
* **DO NOT** send PRs for style changes.
|
||||
* **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
|
||||
|
||||
|
||||
## Commit Messages
|
||||
|
||||
Please format commit messages as follows (based on this [excellent post](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)):
|
||||
|
||||
```
|
||||
Summarize change in 50 characters or less
|
||||
|
||||
Provide more detail after the first line. Leave one blank line below the
|
||||
summary and wrap all lines at 72 characters or less.
|
||||
|
||||
If the change fixes an issue, leave another blank line after the final
|
||||
paragraph and indicate which issue is fixed in the specific format
|
||||
below.
|
||||
|
||||
Fix #42
|
||||
```
|
||||
|
||||
Also do your best to factor commits appropriately, i.e. not too large with unrelated
|
||||
things in the same commit, and not too small with the same small change applied N
|
||||
times in N different commits. If there was some accidental reformatting or whitespace
|
||||
changes during the course of your commits, please rebase them away before submitting
|
||||
the PR.
|
||||
|
||||
|
||||
### Signing off your commit messages
|
||||
|
||||
We recommend (although is not mandatory) that you include a `Signed-off-by` line in the commit message:
|
||||
|
||||
```
|
||||
Signed-off-by: Joe Smith <joe.smith@email.com>
|
||||
```
|
||||
|
||||
The project requires that the name used is your real name. Neither anonymous contributions nor those utilizing pseudonyms will be accepted.
|
||||
|
||||
|
||||
## Contributor License Agreement
|
||||
|
||||
### Why a CLA?
|
||||
|
||||
The Contributor License Agreement helps ensure everyone that **nanoFramework** is here to stay.
|
||||
Specifically, our Contributor License Agreements (CLAs) grant the contributor and **nanoFramework** joint copyright interest in contributed code. Further, it provides assurance from the contributor that contributions are original work that does not violate any third-party license agreement. The agreement between contributors and project is explicit, so developers and users can be confident in the legal status of the source code and their right to use it.
|
||||
|
||||
### Our CLA's
|
||||
|
||||
All contributions to **nanoFramework** (no matter if that's code, bug fixes, configuration changes, documentation, or anything elase) requires that the contributor(s) complete and sign a Contributor License Agreement. You can read it [here](cla.md).
|
||||
|
||||
|
||||
**nanoFramework** team and community members will provide feedback on your change. Community feedback is highly valued. You will often see the absence of team feedback if the community has already provided good review feedback.
|
||||
|
||||
|
||||
## PR Feedback
|
||||
|
||||
**nanoFramework** team and community members will provide feedback on your change. Community feedback is highly valued. You will often see the absence of team feedback if the community has already provided good review feedback.
|
||||
|
||||
One or more **nanoFramework** team members will review every PR prior to merge. They will often reply with "LGTM, modulo comments". That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me".
|
||||
|
||||
There are lots of thoughts and [approaches](https://github.com/antlr/antlr4-cpp/blob/master/CONTRIBUTING.md#emoji) for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback.
|
||||
Also don't think that comments and requests for changes means that your contribution is not appreciated and people can be stalling or discouraging you. You may have done a wonderfull job on the task at hand but, as it's still part of a very large sofware project, there could be implications on aspects that you might not be aware of, or that it's impacting or causing side effects on other parts. Keep an open mind and positive attitude! :wink:
|
||||
|
||||
**nanoFramework** project uses many labels for categorizing issues and pull requests. Check [here](labels.md) the full list.
|
||||
|
||||
|
||||
## Working on an open issue
|
||||
|
||||
When you want to work on an open issue (including _up-for-grabs_) we recommend the following.
|
||||
|
||||
- Issues labeled with [_investigating_](labels.md#investigating): if the current status doesn't seem updated or clear, add a comment asking for clarification before start any work on it.
|
||||
- Issues labeled with [_under-review_](labels.md#under-review): if the current status doesn't seem updated or clear, add a comment asking for a clarification before start any work on it.
|
||||
- Issues labeled with [_up-for-grabs_](labels.md#up-for-grabs): add a comment stating your interest and the issue will be assigned to you and the label switched to _in progress_.
|
||||
|
||||
|
||||
## Suggested Workflow
|
||||
|
||||
We use and recommend the following workflow:
|
||||
|
||||
1. Create an issue for your work.
|
||||
- You can skip this step for trivial changes.
|
||||
- Reuse an existing issue on the topic, if there is one.
|
||||
- Get agreement from the team and the community that your proposed change is a good one.
|
||||
- If your change adds a new API, follow the [API Review Process](api-review-process.md).
|
||||
- Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.
|
||||
|
||||
2. Create a personal fork of the repository on GitHub (if you already have one you can jump straight to step 5 bellow).
|
||||
|
||||
Forking the repository is a simple click on the "Fork" button (at the top right corner) on the repositories page in GitHub.
|
||||
|
||||
3. Clone that new fork to your local system.
|
||||
|
||||
This operation depends heavily on what local client you are going to use in order to manage your local clone. There are a number of clients, from Git command line to more sophisticated and GUI clients.
|
||||
|
||||
- GitHub has it's own [desktop client](https://desktop.github.com/).
|
||||
- There is an extension for [Visual Studio](https://marketplace.visualstudio.com/items?itemName=GitHub.GitHubExtensionforVisualStudio).
|
||||
- Visual Studio Code has it's owned Git client baked in.
|
||||
- There is also the popular [Tower](https://www.git-tower.com/) and many others.
|
||||
|
||||
If you are using a GUI client don't bother with the the git command lines shown bellow.
|
||||
|
||||
Cloning locally is a simple click on the green "Clone or Download" button (at the top right corner) that shows on your personal fork in GitHub.
|
||||
|
||||
You can also perform this operation localy. Directly from your Git client or from the git command line:
|
||||
|
||||
`git clone https://github.com/<your-github-id-here>/<nf-repo-name-here>.git`
|
||||
|
||||
4. Configure a remote upstream to the master repository.
|
||||
|
||||
`git remote add upstream https://github.com/nanoframework/<nf-repo-name-here>.git`
|
||||
|
||||
5. Make sure that your develop branch is in sync with the master **develop** branch.
|
||||
|
||||
`git checkout develop`
|
||||
|
||||
`git pull upstream develop`
|
||||
|
||||
6. Create a branch off of **develop** branch.
|
||||
|
||||
`git checkout -b <branch-name-here> develop`
|
||||
|
||||
We suggest that you name the branch so that it clearly communicates your intentions, such as *issue-123* or *githubhandle-issue*.
|
||||
Don't use a branch name starting with _develop_ because that may be mistaken with the _develop_ branches on the master repository.
|
||||
|
||||
Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork.
|
||||
|
||||
7. Work your way through the changes and commit them using your Git client or the command line as you prefer.
|
||||
- Please follow our [Commit Messages](contributing-workflow.md#commit-messages) guidance.
|
||||
- Include `Signed-off-by` line, e.g. `git commit -s`
|
||||
|
||||
8. Add new tests corresponding to your change, if applicable.
|
||||
|
||||
9. Build the repository with your changes.
|
||||
- Make sure that the builds are clean.
|
||||
- Make sure that the tests are all passing, including any new tests that you've added.
|
||||
|
||||
10. Push your changes to your fork on GitHub (if you haven't already).
|
||||
|
||||
`git push origin <branch-name-here>`
|
||||
|
||||
11. Create a pull request (PR) against the upstream repository's **develop** branch.
|
||||
|
||||
Creating a PR is a simple click on the "Pull Request" button that shows on your personal fork in GitHub.
|
||||
|
||||
There is a template for the PR message. We ask you to follow it. It has the required topics and placeholders for what is required to make it clear. Also acts as a check list for you as the submitter.
|
||||
|
||||
When starting a PR GitHub will show you if you repo is up to date with the master one and if a merge is OK. If there are differences showing you have to go back to you local clone and merge those into your local clone. After doing that it's advisable to re-run the build and tests because there could have been changed brought in that affected your code.
|
||||
After the above succeeds you have to push the changes up to origin repeating step 10 above.
|
||||
|
||||
Note 1: It is OK for your PR to include a large number of commits. If that's the case, once your change is accepted, you can be asked to squash your commits into one or some appropriately small number of commits before your PR is merged.
|
||||
|
||||
Note 2: It is OK to create your PR as "[WIP]" on the upstream repo before the implementation is done. This can be useful if you'd like to start the feedback process concurrent with your implementation. State that this is the case in the initial PR comment.
|
||||
|
||||
Note 3: If you are working on a feature that has high impact or it's something experimental, your original PR can have it's target branch moved into a new develop branch in the master repo, something like *develop-shiny-awesome-feature*.
|
||||
|
||||
|
||||
## General git resources
|
||||
|
||||
If you are coming from another version control system *git* can feel daunting, awkward, confusing and may cause you frustration. :warning: Be warned about that! :warning: :stuck_out_tongue_winking_eye:
|
||||
|
||||
We suggest that you go through some basic tutorial and give it a try on a test repo that you setup for yourself.
|
||||
|
||||
Here are a few resources that we've compiled to get you up to speed. No claims that these are, by any stretch, the only or the better ones! You can find a bunch of these out there!
|
||||
|
||||
- [GitHub trial site](http://try.github.io/). Gives you a nice tour of git. Get your feet wet without even installing software!
|
||||
|
||||
- [GitHub help page](http://help.github.com/) Deals with basic usage, concepts and terms of git and github. Good to get a first idea.
|
||||
|
||||
- [Git Reference](http://git.github.io/git-reference/). Nice and concise reference of the essential functions of git. Takes about 30min to read through, you'll come out smarter at the end.
|
||||
|
||||
- The git [community book](https://git-scm.com/book/en/v2). This book is meant to help you learn how to use Git as quickly and easily as possible.
|
||||
|
||||
- [Escape a git mess step-by-step](http://justinhileman.info/article/git-pretty/git-pretty.png). Humorous and handy workflow to help you when you get stuck with git and your blood pressure starts to rise.
|
||||
|
|
@ -1,126 +0,0 @@
|
|||
# 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 `nnnnn.vssettings` at the root of each 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; }
|
||||
}
|
||||
}
|
||||
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -1,26 +0,0 @@
|
|||
# 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/).
|
||||
|
|
@ -1,34 +0,0 @@
|
|||
# Using ARM Cortex-M Single Wire Output (SWO)
|
||||
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes how to use Cortex-M SWO to output data from **nanoFramework**.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You'll need:
|
||||
* Target board with SWO pin free _and_ configured in it's reset state (meaning not used by GPIO or any other peripheral and not configured in any alternate mode).
|
||||
* If using a stock board it's also convenient to check the schematics if any hardware changes are required.
|
||||
* [STM F429I_DISCOVERY](../../images/STM32F429I-DISCOVERY-solder-bridge-for-swo.jpg) board requires solder bridge SB9 to be soldered
|
||||
* [STM F769I-DISCO](../../images/STM32F769I-DISCO-solder-bridge-for-swo.jpg) board requires a 0 Ohm resistor on R92 (or just soldering the pads toghether)
|
||||
* Software capable of driving and outputting data from an SWO source. (ST-Link)[http://www.st.com/content/st_com/en/products/embedded-software/development-tool-software/stsw-link004.html] is an excellent tool for this purpose.
|
||||
* Set **nanoFramework** build options to include support for SWO (either setting `"SWO_OUTPUT" : "ON"` in cmake-variants.json or launching CMake with -DSWO_OUPUT=ON).
|
||||
|
||||
|
||||
## Outputting SWO
|
||||
|
||||
1. Load the target flash with a **nanoFramework** image build with SWO option
|
||||
|
||||
2. On ST-Link menu choose ST-Link -> Printf via SWO viewer
|
||||
|
||||
|
||||
|
||||
3. After SWO viewer windows loads, set the Sytem clock to match the target and the Stimulus port to `0`.
|
||||
|
||||
|
||||
|
||||
4. Click the Start button and watch the output in the main window area.
|
||||
|
||||
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
# Guidelines for debugging **nanoFramework** class libraries native code
|
||||
|
||||
**About this document**
|
||||
|
||||
This document provides guidelines useful when debugging class libraries native code.
|
||||
It doesn't care if the developer is using VS Code or other IDE.
|
||||
|
||||
|
||||
## How does an assembly load successfully?
|
||||
|
||||
The assemblies with the class libraries and the managed application are loaded at startup from the deployment area in the FLASH memory.
|
||||
When the `LoadDeploymentAssemblies()` is called the deployment area is sweep and all 'candidate' assemblies are validated. The validation steps are basically checking the start token, a valid header and the CRC32 of the full assembly. Only the ones that pass the complete set of validation make it to the assembly collection.
|
||||
|
||||
After this step a call to `g_CLR_RT_TypeSystem.ResolveAll()` happens in which the type system tries to resolve all the assemblies. This means that all the required types and methods (from all the assemblies) are available and in the correct versions.
|
||||
|
||||
Next comes the `g_CLR_RT_TypeSystem.PrepareForExecution()` which is only called if all the assemblies could be resolved along with the required types.
|
||||
|
||||
|
||||
## Starting the execution engine
|
||||
|
||||
The managed application actually starts to be executed with a call to `g_CLR_RT_ExecutionEngine.Execute()`.
|
||||
As long the managed code is being executed this will never exit.
|
||||
When the execution ends, because of a serious exception or because there is no managed application to execute the code flow hits the `CLR_EE_DBG_IS( RebootPending )` line (bellow the the call to the execution engine call).
|
||||
|
||||
|
||||
## Summarizing
|
||||
|
||||
So, by setting break points at, or after, the above calls one can understand and perform a check if the assemblies are being loaded and/or the managed application being executed.
|
||||
If something goes wrong (for instance) with an assembly failing to load the developer has to go deeper in order to find out the root cause. But that's a matter for another piece of documentation.
|
||||
|
|
@ -1,60 +0,0 @@
|
|||
# Instructions for debugging **nanoFramework** 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 **nanoFramework** 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/openocd)
|
||||
|
||||
|
||||
# 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 setup the *launch.json* file, located in the .vscode folder.
|
||||
We've provided a template file [launch.TEMPLATE.json](..\.vscode\launch.TEMPLATE.json) to get you started with this. Just copy it and rename to *launch.json*.
|
||||
|
||||
Here's what you need to change in order to adapt the template file to your setup and make it more suitable to your working style and preferences.
|
||||
- name: here you can name each of the launch configurations to help choosing the appropriate one when launching the debug session. These could be for example: "nanoBooter in Discovery 4", "nanoCLR in Nucleo F091RC", "test featureXYZ in Discovery 4".
|
||||
- miDebuggerPath: full path to the gdb executable (this one is inside the GCC tool-chain folder)
|
||||
- program: full path to the .elf output file that results from a successful build
|
||||
- setupCommands (fourth 'text' entry): full path to the final image (the .hex file)
|
||||
- setupCommands (fifth 'text' entry): the same as the program entry above (the .elf file)
|
||||
- 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.
|
||||
|
||||
_Note 1: VS Code parser seems to have trouble parsing and replacing the ${workspaceRoot} for some OpenOCD commands. That's the reason why you see there the ${workspaceRoot} variable and in other places the full path were that variable would make sense to be at. Just use what's there to keep OpenOCD happy._
|
||||
|
||||
_Note 2: Always mind the forward slash in the paths above, otherwise you'll get into troubles with strange and unclear errors from OpenOCD._
|
||||
|
||||
|
||||
# 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
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
# Labels
|
||||
|
||||
**nanoFramework** project uses many labels for categorizing issues and pull requests.
|
||||
|
||||
| Label | Meaning on Issue | Meaning on Pull Request |
|
||||
| --- | --- | --- |
|
||||
| bug | The issue concerns a bug in the code | The issue concerns a bug in the code |
|
||||
| enhancement | The issue is an improvement to the code | The pull request is an improvement to the code |
|
||||
| up-for-grabs <a id="up-for-grabs"></a> | The issue has been discussed and it's ready for someone to start working on it. It's not assigned to a particular person. If you want to work on it, just add a comment saying so and it's yours! | Normally not applicable (see comments if observed on a pull request) |
|
||||
| investigating <a id="investigating"></a> | The issue is being investigated by the team or by a community member. If the status is not clear, better ask for an update about it. | n/a |
|
||||
| question | The issue is a question | Normally not applicable (see comments if observed on a pull request) |
|
||||
| code review | n/a | The pull request is under review |
|
||||
| needs discussion | The issue needs further discussion before an actionable decision can be made | The pull request needs further discussion before an actionable decision can be made |
|
||||
| pull request | A pull request intended to address the issue has been created, but not yet merged | n/a |
|
||||
| blocked | The issue cannot be fixed until another issue, which may be external, is addressed | The pull request cannot be merged until another issue, which may be external, is addressed |
|
||||
| do not merge | n/a | The pull request should not be merged at this time. This could indicate a work-in-progress, a problem in the implementation code, or cases where the pull request depends on (is blocked by) another issue or pull request which has not been addressed. |
|
||||
| merge OK | n/a | The pull request has been reviewed and meets all the contribution requirements so it's ready to be merged |
|
||||
| in progress | A developer is currently working on the issue | A developer is currently making updates to the code in the pull request |
|
||||
| fixed | The issue has been resolved | The pull request describes a new issue (i.e. no separate issue exists), and the content of the pull request was merged to fix the issue |
|
||||
| duplicate | Another issue or pull request contains the original report for this topic | Another pull request was submitted to correct the issue. This is generally only applied to pull requests after another pull request to correct the issue is merged. |
|
||||
| wontfix | The issue will not be corrected. The current behaviour could be by design, out of scope, or cannot be changed due to the breaking changes policy for the project (see comments for details). | The pull request will not be merged due to a fundamental issue (see description for this label on issues) |
|
||||
| documentation | The issue is related with documentation | The pull request is related with documentation |
|
||||
| feature-request | The issue contains a new feature request | Normally not applicable (see comments if observed on a pull request) |
|
||||
| FEEDBACK REQUESTED | Feedback from the community is requested. Please step in and add your comment, that is if you have anything relevant to say about it. | Normally not applicable (see comments if observed on a pull request) |
|
||||
| help wanted | If this issue has any work assigned or has already started to be addressed in a pull request help is welcomed. If you are willing to help add a comment to coordinate with the people already working on it. | Help is welcomed for this pull request. If you are willing to help add a comment to coordinate with the people already working on it. |
|
||||
| DONE | The work on the issue is completed | n/a |
|
||||
| under review <a id="under review"></a> | The issue (probably a feature request) is under review and a decision hasn't been made | n/a |
|
||||
| trivial | The work required to complete this issue is considered to be very simple and it shouldn't pose any significant challenge. It can be completed in a very short time. It doesn't require any particular skills or deep knowledge on the matter or the project. | n/a |
|
||||
| non trivial | The work required to complete this issue is considered to be somewhat complex. It requires a particular skill set or deep knowledge on the matter or about the matter or the project architecture. | n/a |
|
||||
| area-Config-and-Build | The issue is related with the configuration and build of **nanoFramework** | The pull request is related with the configuration and build of **nanoFramework** |
|
||||
| area-Infrastructure-and-Organization | The issue is related with the infrastructure or the overall organization of the **nanoFramework** project | The pull request with the infrastructure or the overall organization of the **nanoFramework** project |
|
||||
| area-Interpreter | The issue is related with the Interpreter component of **nanoFramework** | The pull request is related with the Interpreter component of **nanoFramework** |
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
# Developing C# (managed) applications
|
||||
|
||||
- [Getting started guid](getting-started-guide.md)
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
# Getting Started Guide
|
||||
|
||||
|
||||
**nanoFramework** enables the writing of managed code applications for embedded devices. Doesn't matter if you are a seasoned .NET developer or if you've just arrived here and want to give it a try.
|
||||
|
||||
This getting started guide will walk you through the setup of your development machine to get you coding a nice "Hello World" in no time!
|
||||
|
||||
|
||||
You can find the video for this guide on our YouTube channel [here](https://youtu.be/iZdN2GmefXI).
|
||||
|
||||
|
||||
## The hardware
|
||||
|
||||
In this guide we'll be using a ST Microelectronics [STM32F746 NUCLEO](http://www.st.com/content/st_com/en/products/evaluation-tools/product-evaluation-tools/mcu-eval-tools/stm32-mcu-eval-tools/stm32-mcu-nucleo/nucleo-f746zg.html) board. This is a rather common and inexpensive board that packs a Cortex M7 with 1MB flash, 320 kB of RAM and includes an ethernet connector.
|
||||
|
||||
|
||||
## Installing Visual Studio 2017
|
||||
|
||||
The first part is to get Visual Studio 2017 and the **nanoFramework** extension installed.
|
||||
|
||||
1. Download Visual Studio 2017. If you already have it installed, you can skip this step. If you don't, please download the free [Visual Studio Community 2017](https://www.visualstudio.com/downloads) edition. Either way, make sure you've selected the .NET desktop workload.
|
||||
|
||||
2. Launch Visual Studio 2017 (we'll just refer to it as VS from now on) and install the **nanoFramework** extension. You can do this by going into Tools > Extensions and Updates. Make sure you've switched the left-hand tree view to the Online branch and enter _nanoFramework_ in the search box.
|
||||
|
||||
3. Now open the Device Explorer window. You can do this by going into View > Other Windows > Device Explorer.
|
||||
|
||||
|
||||
## Uploading the firmware to the board
|
||||
|
||||
The second part is to load the **nanoFramework** image in the board flash. Actually there are two images, one for nanoBooter and another one for nanoCLR.
|
||||
|
||||
1. Download the [STM32 ST-LINK Utility](http://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/stsw-link004.html) from ST web site and install it in your development machine.
|
||||
|
||||
2. Download a ZIP file with the firmware for the board from our web site [here](https://github.com/nanoframework/nf-interpreter#firmware-for-reference-boards) by clicking on the appropriate badge. This will take you to our JFrog Bintray repository that holds the packages with pre-build images for several target boards. After downloading it, unzip the package contents.
|
||||
|
||||
3. Connect the STM32F746 NUCLEO board to your PC using an USB cable. In fact, you'll be needing two USB cables with a micro USB connector. One to connect to the ST-Link debugger, that doubles as power supply to the board. And a second one to connect the USB client of the board.
|
||||
|
||||
4. Launch the ST-LINK Utility that you've just installed and connect to the STM32F746 NUCLEO board.
|
||||
|
||||
5. Perform a "full chip erase" to clear the flash.
|
||||
|
||||
6. Load the `nanoBooter.hex` file from the package and hit the "Program and verify" button. Make sure you tick the "Reset after programming" check box and hit "Start". After the upload completes, the MCU is reset and the nanoBooter image runs. You can check the success of the operation watching for a slow blink pattern on the LED. Congratulations, you now have a board running nanoFramework's booter!
|
||||
|
||||
7. Next, load the `nanoCLR.hex` file from the extracted package folder and hit again the "Program and verify" button. Make sure you tick the "Reset after programming" check box and hit "Start". After the upload completes, the MCU is reset and the nanoCLR image will run. This time and if all goes as expected, there will be no LED blinking. You can check if the board is properly running **nanoFramework** by looking into the Device Explorer window in VS.
|
||||
|
||||
|
||||
## Coding a 'Hello World' application
|
||||
|
||||
Now you have everything that you need to start coding your first application. Let's go for a good old 'Hello World' in micro-controller mode, which is blinking a LED, shall we?
|
||||
|
||||
1. Go back to VS and click File > New > Project. Make sure you have selected 'Framework 4.6 or above' and choose nanoFramework, on the left hand side tree view. Choose the 'Blank Application' template and a location of your choosing were the project files will be saved. Name your project and hit OK. The program file will be automatically opened for you.
|
||||
|
||||
2. We'll code a very simple application that enters an infinite loop and turns on and off an LED. We'll skip the details because that's not the aim of this guide. Let's just grab the code from the **nanoFramework** samples repo [here](https://github.com/nanoframework/Samples/tree/master/Blinky). Make sure that the correct GPIO pin is being used. That's the line below the comment mentioning the STM32F746 NUCLEO board.
|
||||
|
||||
3. Because GPIO is being used we need to pull that class library and a reference to it in our project. The class libraries are distributed through NuGet. To add this class, right click on 'References' in the Solution Explorer and click 'Manage NuGet Packages'. On the search box type 'nanoFramework'. Make sure you have the preview checkbox ticked. Find the Windows.Devices.Gpio package and click "Install". After the license confirmation box, the package will be downloaded and a reference to it will be added. You'll notice that you no longer have the unknown references hints in VS.
|
||||
|
||||
4. Click "Build Solution" from the Build menu. A success message shows in the Build window.
|
||||
|
||||
5. We are almost there. Go into the Device Explorer window and click on the **nanoFramework** device showing there. Make sure the connection is OK by hitting the "Ping" button. On success, a message shows on the output window.
|
||||
|
||||
6. Let's deploy the application to the board. In order to do that, right click on the Project name and choose "Deploy". You'll see the feedback of the several operations that are running on the background in the Output Window. After a successful deployment, your 'Hello World' blinky application will start running and, _voilá_, the LED starts blinking!
|
||||
|
||||
|
||||
## Wrapping up
|
||||
|
||||
Congratulations! That's your first **nanoFramework** C# application executing right there on the target board. How awesome is that?!
|
||||
|
||||
And this is it for the getting started guide.
|
||||
|
||||
You've went through the steps required to install Visual Studio, the **nanoFramework** extension and the ST-LINK Utility.
|
||||
|
||||
You've also learned how to upload **nanoFramework** firmware images into a target board.
|
||||
And last, but not the least: how to code a simple 'Hello World' C# application and deploy it to a target board.
|
||||
|
||||
Check out other guides and tutorials. You may also want to join our [Discord community](https://discord.gg/gCyBu8T) where you'll find a supportive community to discuss your ideas and help you in case you get stuck on something.
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
# **nanoFramework** HAL/PAL
|
||||
|
||||
* ### [ChibiOS HAL](chibios)
|
||||
* [ADC configuration](chibios/adc-configuration.md)
|
||||
* [CLR Managed heap definition](chibios/clr-managed-heap.md)
|
||||
* [USB configuration of Virtual COM port (CDC)](chibios/config-usb-virtual-com-port.md)
|
||||
|
|
@ -1,66 +0,0 @@
|
|||
# ADC configuration
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes how to configure the ADC and respective GPIO pins for a STM32 target board based in ChibiOS HAL/PAL.
|
||||
|
||||
|
||||
## Assumptions and design
|
||||
|
||||
The STM32 parts can have up to 19 multiplexed channels (being 16 from external sources). Those can be grouped for special conversion scenarios that we are not going to use.
|
||||
Each ADC channel can be exposed in one or more GPIO pins. Despite this providing more flexibility to a system designer it poses an additional complication at the time of configuring the ADC.
|
||||
Considering that the heavy-lifting on the ADC configuration and initial setup is performed by ChibiOS, we've tried to make the remaining configuration as simple as possible, which is pretty much mapping the GPIO pins.
|
||||
|
||||
For the remaining of this document we'll be using ST STM32F769I_DISCOVERY reference target and will configure the ADC to use the ADC channels exposed through the CN14 connector. From the schematics of the board (mb1225 F769I-DISCO schematic.pdf downloadable from ST web site) one can see that the following channels exposed:
|
||||
|
||||
| pad | GPIO pin | ADC channel |
|
||||
|:-:|:-:|:-:|
|
||||
| A0 | PA6 | ADC1_IN6 |
|
||||
| A1 | PA4 | ADC1_IN4 |
|
||||
| A2 | PC2 | ADC1_IN12 |
|
||||
| A3 | PF10 | ADC1_IN8 |
|
||||
| A4 | PF8 | ADC3_IN6 |
|
||||
| A5 | PB8 | ADC3_IN7 |
|
||||
|
||||
To fully take advantage of the ADC hardware we are going to enable the internal ADC sources. These ones have to be mapped to ADC1.
|
||||
|
||||
| pad | GPIO pin | ADC channel |
|
||||
|:-:|:-:|:-:|
|
||||
| N.A. | N.A. | ADC1_TEMP_SENSOR |
|
||||
| N.A. | N.A. | ADC1_VREFINT |
|
||||
| N.A. | N.A. | ADC1_VBAT |
|
||||
|
||||
|
||||
## Configurations
|
||||
|
||||
The configurations are all concentrated in the `target_windows_devices_adc_config.cpp` file in the reference target folder.
|
||||
This source file is added to the CMake target only if the `API_Windows.Devices.Adc` option is set to ON. See the target CMakeList.txt.
|
||||
|
||||
There is a global `NF_PAL_ADC_PORT_PIN_CHANNEL` array for the ADC controller. On each entry there are the configurations for the ADC block, the GPIO port and pin along with the ADC internal channel reference.
|
||||
Note that for the internal sources channels the GPIO port and pin are to be set to `NULL` and those are only available on ADC1.
|
||||
All the naming come from existing ChibiOS defines.
|
||||
|
||||
The configuration array will look like:
|
||||
```
|
||||
const NF_PAL_ADC_PORT_PIN_CHANNEL AdcPortPinConfig[] = {
|
||||
|
||||
// ADC1
|
||||
{1, GPIOA, 6, ADC_CHANNEL_IN6},
|
||||
{1, GPIOA, 4, ADC_CHANNEL_IN4},
|
||||
{1, GPIOC, 2, ADC_CHANNEL_IN12},
|
||||
{1, GPIOF, 10, ADC_CHANNEL_IN8},
|
||||
|
||||
// ADC3
|
||||
{3, GPIOF, 8, ADC_CHANNEL_IN6},
|
||||
{3, GPIOB, 8, ADC_CHANNEL_IN7},
|
||||
|
||||
// these are the internal sources, available only at ADC1
|
||||
{1, NULL, NULL, ADC_CHANNEL_SENSOR},
|
||||
{1, NULL, NULL, ADC_CHANNEL_VREFINT},
|
||||
{1, NULL, NULL, ADC_CHANNEL_VBAT},
|
||||
};
|
||||
```
|
||||
There is also a variable with the channel count, like this:
|
||||
`const int AdcChannelCount = ARRAYSIZE(AdcPortPinConfig);`
|
||||
|
||||
To complete the configuration one has to enable ADC1 and ADC3 for ChibiOS HAL. Remember those were the ADC blocks used in the configuration above. This is done by editing the `mcuconf.h` file inside the target nanoCLR folder. Search for `STM32_ADC_USE_ADC1` and `STM32_ADC_USE_ADC3` and set those to `TRUE`.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# CLR Managed heap definition
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes how the CLR manged heap is defined as a ChibiOS target.
|
||||
|
||||
For STM32 based devices:
|
||||
The configurations are chained by linker files:
|
||||
- the target linker file provided for the nanoCLR in the target board folder, e.g. [STM32F091xC.ld](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/nanoCLR/STM32F091xC.ld) and from within calls rules.ld **except** the F7 series which calls rules_clr.ld, rules_code.ld, rules_data.ld and rules_stacks.ld directly.
|
||||
- [rules.ld](../../targets/CMSIS-OS/ChibiOS/common/rules.ld) (which is common to all STM32 based ChibiOS targets and calls the next set of linker files)
|
||||
- [rules_clr.ld](../../targets/CMSIS-OS/ChibiOS/common/rules_clr.ld), [rules_code.ld](../../targets/CMSIS-OS/ChibiOS/common/rules_code.ld), [rules_data.ld](../../targets/CMSIS-OS/ChibiOS/common/rules_data.ld) and [rules_stacks.ld](../../targets/CMSIS-OS/ChibiOS/common/rules_stacks.ld)
|
||||
|
||||
|
||||
|
||||
## Managed heap location and size
|
||||
|
||||
The CLR managed heap can be located on the target board at any RAM address where space available. Either internal or external.
|
||||
|
||||
It will be placed (considering the RAM region defined) after the region containing the CRT heap (if it's assigned to that same RAM region) and right before the Vector table copy in RAM (if it is assigned to the same RAM region).
|
||||
|
||||
This empowers developers to create new target boards with maximum flexibility of where to locate the CLR managed heap and its respective size.
|
||||
|
||||
|
||||
### Definition the CLR managed heap location
|
||||
|
||||
The location of the CLR managed heap is set in in target linker file provided for nanoCLR in the target boards folder, e.g. [STM32F091xC.ld](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/nanoCLR/STM32F091xC.ld)
|
||||
|
||||
For example the line (usually toward the end of the file) will contain something similar to `REGION_ALIAS("CLR_MANAGED_HEAP_RAM", ram0);`. The example stated here defines CLR manged heap location as being set in the _ram0_ region. The RAM regions and respective sizes are defined in the same file. For further information, please check the ChibiOS documentation for details on how to define further RAM regions.
|
||||
|
||||
|
||||
### Size of the CLR managed heap
|
||||
|
||||
The size of the CLR managed heap is automatically adjusted to take all the available RAM space after the CRT heap (if it's assigned to that same RAM region).
|
||||
|
||||
It maybe be required to adjust the size of the CRT heap. This is set in the CMake file of the target board, e.g. [CMakeLists.txt](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/CMakeLists.txt).
|
||||
Look for the `__crt_heap_size__` definition in a line that contain something similar to `--defsym=__crt_heap_size__=0x800`. In the example stated here the size of CRT heap is being set to 0x800.
|
||||
|
||||
When defining the size you need to take into account several factors:
|
||||
- the total available size of the region where it's being placed
|
||||
- if there are initialized variables assigned to this region how much space they are taking
|
||||
- if the CRT heap is located in this region and the size left for it is enough
|
||||
|
||||
The linker is only able to determine whether there is enough room for all of these factors and it will only complain if there isn't. However it can not determine if the CRT heap (just like the CRT heap) is large enough for the running requirements. That is up to the target board developer.
|
||||
For a detailed overview on the final memory map you may want to check the _nanoCLR.map_ that will be located in the build folder after a successful build. Look for the regions called `.heap` and `.clr_managed_heap` to see the final addresses where those were placed.
|
||||
|
|
@ -1,51 +0,0 @@
|
|||
# USB configuration of Virtual COM port (CDC)
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes the available settings/options to configure the USB Virtual COM port provided by ChibiOS HAL.
|
||||
All these settings/options are exposed in the _usbcfg.c_ file, located in the _common_ folder of the reference boards that expose an USB device connector.
|
||||
|
||||
|
||||
## USB Vendor
|
||||
|
||||
```#define USB_STRING_VENDOR L"STMicroelectronics"```
|
||||
|
||||
In this setting it's defined the string that will show as the Vendor name for the USB device (showing in Windows Device manager, for example).
|
||||
Adjust the string to whatever is to show there. Mind the L prefix, **DO NOT** remove it.
|
||||
|
||||
|
||||
## USB Device description
|
||||
|
||||
```#define USB_STRING_DEVICE_DESCRIPTION L"nanoFramework Virtual COM Port"```
|
||||
|
||||
In this setting it's defined the string that will show as the device description for the USB device (showing in Windows Device manager, for example).
|
||||
Adjust the string to whatever is to show there. Mind the L prefix, **DO NOT** remove it.
|
||||
|
||||
|
||||
## USB serial number
|
||||
|
||||
```#define USB_STRING_SERIAL_NUMBER L"NANO_xxxxxxxxxxxx"```
|
||||
|
||||
In this setting it's defined the string that will show as the serial number of the USB device (showing in Windows Device manager, for example).
|
||||
This serial number will be part of the instance path of the device that helps the OS to identify and address the USB device like in \\USB\\VID_0483&PID_5740\\NANO_3267335D3333.
|
||||
Adjust the string to whatever is to show there. Mind the L prefix, **DO NOT** remove it.
|
||||
|
||||
_Note 1: nanoFramework ANT tool uses this serial number as a helper to identify nanoFramework devices relying that this string starts with_ **NANO_**_ (that is upper case NANO followed by an underscore)._
|
||||
|
||||
_Note 2: For STMicroelectronics reference boards the serial number is completed with the silicon unique ID available on their STM32 parts. Check the series manual for details._
|
||||
|
||||
|
||||
## USB Vendor ID
|
||||
|
||||
```idVendor``` in the ```vcom_device_descriptor_data``` structure.
|
||||
In this setting it's defined the [USB Vendor ID](http://www.usb.org/developers/vendor/) of the USB device. Hexadecimal 0x0483 in the reference boards (that's STMicroelectronics USB Vendor ID).
|
||||
|
||||
_Note: You are not allowed to use the USB Vendor from a third party without their express consent. If you want to use your own Vendor ID you have to apply for one with the USB organization._
|
||||
|
||||
|
||||
## USB Product ID
|
||||
|
||||
```idProduct``` in the ```vcom_device_descriptor_data``` structure.
|
||||
In this setting it's defined the [USB Product ID](http://www.usb.org/developers/usbfaq#12) of the USB device. Hexadecimal 0x5740 in the reference boards (that's STM USB product ID used in the Discovery and Nucleo boards).
|
||||
|
||||
_Note: You are not allowed to use the USB Vendor ID + Product from a third party without their express consent. If you want to use your own Vendor ID + Product ID you have to apply for one with the USB organization._
|
||||
|
|
@ -1,33 +0,0 @@
|
|||
# External memory
|
||||
|
||||
**About this document**
|
||||
|
||||
This document describes how to use external memory for the managed heap using the ChibiOS FSMC driver from the **nanoFramework** overlay.
|
||||
Please refer to the CLR managed heap [documentation](clr-managed-heap.md).
|
||||
|
||||
|
||||
## Memory controller
|
||||
|
||||
Most STM32 devices include a FSMC (Flexible Static Memory Controller) that provides seamless interface with the most common memory types either synchronous or asynchronous.
|
||||
|
||||
|
||||
## Assumptions and design
|
||||
|
||||
The initialization of the memory controller along with the memory configuration have to occur as early as possible after the boot. In the current **nanoFramework** design this is expected to occur right after the call to CMSIS `osKernelInitialize()` when all other initialization and configurations have already happen and interrupts are enabled. Because the memory space is to be used as the managed heap the timing is no more critical than that, so pretty much anywhere before the call to the CLR startup should be quite alright.
|
||||
|
||||
|
||||
The function were the external memory configuration and initialization is to occur is `Target_ExternalMemoryInit()`. The `nanoHAL_v2.h` provides a _weak_ and empty implementation of this function. If a target is to use external memory it has to provide the _strong_ implementation of this function and call it before `ClrStartup()` is called.
|
||||
|
||||
Considering that the default placement of the CLR managed is in the SoC internal RAM, the linker file includes a rule to place this region (called `clr_managed_heap`) in one of its RAM regions.
|
||||
|
||||
|
||||
# Example for STM32F429I-Discovery reference target
|
||||
|
||||
To provide a working example of this configuration we are taking the STM32F429I-Discovery reference target that is in the nf-interpreter repository [here](https://github.com/nanoframework/nf-interpreter/tree/develop/targets/CMSIS-OS/ChibiOS/ST_STM32F429I_DISCOVERY).
|
||||
This targets board has a 64Mbit SDRAM (the chip is the IS42S16400J).
|
||||
|
||||
|
||||
1. The _target_ implementation is provided in the `target_external_memory.c` file that is located in the target base folder. This location allows the function to be reused by nanoCLR and nanoBooter, if desired. Plus, it's included in the compile sequence at a time that the target CPU and other required definitions are already set.
|
||||
In order to include this code file in the build it has to be included as source file the target definition. For our example this is in the arguments of `add_executable` for nanoCLR.
|
||||
|
||||
2. Next we have to set the `__crt_heap_size__` symbol to 0 so the managed heap is not placed in the SoC RAM. This is done by setting it to 0 in the target CMakelist.txt like this `--defsym=__crt_heap_size__=0x0`.
|
||||
Двоичные данные
docs/images/STM32F429I-DISCOVERY-solder-bridge-for-swo.jpg
Двоичные данные
docs/images/STM32F429I-DISCOVERY-solder-bridge-for-swo.jpg
Двоичный файл не отображается.
|
До Ширина: | Высота: | Размер: 214 KiB |
Двоичные данные
docs/images/STM32F769I-DISCO-solder-bridge-for-swo.jpg
Двоичные данные
docs/images/STM32F769I-DISCO-solder-bridge-for-swo.jpg
Двоичный файл не отображается.
|
До Ширина: | Высота: | Размер: 210 KiB |
Двоичные данные
docs/images/docs-trigger-build-all-community-targets.png
Двоичные данные
docs/images/docs-trigger-build-all-community-targets.png
Двоичный файл не отображается.
|
До Ширина: | Высота: | Размер: 18 KiB |
Двоичные данные
docs/images/st-link-menu-print-swo.png
Двоичные данные
docs/images/st-link-menu-print-swo.png
Двоичный файл не отображается.
|
До Ширина: | Высота: | Размер: 49 KiB |
Двоичные данные
docs/images/st-link-swo-window-after-boot-01.png
Двоичные данные
docs/images/st-link-swo-window-after-boot-01.png
Двоичный файл не отображается.
|
До Ширина: | Высота: | Размер: 18 KiB |
Двоичные данные
docs/images/st-link-swo-window-settings-01.png
Двоичные данные
docs/images/st-link-swo-window-settings-01.png
Двоичный файл не отображается.
|
До Ширина: | Высота: | Размер: 3.2 KiB |
|
|
@ -1,51 +0,0 @@
|
|||
# Licensing options when using ChibiOS as the RTOS
|
||||
|
||||
|
||||
**About this document**
|
||||
|
||||
This document provides a general overview of the licensing options available when using [ChibiOS](http://chibios.org) as the **nanoFramework** RTOS component.
|
||||
The nanoFramework team have been in contact with the ChibiOS sales team to ensure accuracy of the following information at time of print (October 2017).
|
||||
|
||||
For details or to discuss your particular situation, we strongly recommend getting in touch with the ChibiOS [sales team](http://chibios.org/dokuwiki/doku.php?id=chibios:licensing:quote).
|
||||
|
||||
|
||||
## What exactly is being used from ChibiOS in **nanoFramework** firmware?
|
||||
|
||||
**nanoFramework** is built against _unmodified_ ChibiOS sources via a mirror (for stability). It's using:
|
||||
* The [HAL](http://chibios.org/dokuwiki/doku.php?id=chibios:product:hal:start), which is released under Apache License 2.0 meaning that it's 100% free to use or distribute without royalties for any purpose.
|
||||
* The [RT](http://chibios.org/dokuwiki/doku.php?id=chibios:product:rt:start), is released under GPL3. See below for the licensing options which maybe different depending on your particular use.
|
||||
|
||||
|
||||
## Can I use ChibiOS freely for my hobby or personal development at home?
|
||||
|
||||
Yes, using ChibiOS in a Free and Open Source Software project or for personal use is perfectly fine.
|
||||
|
||||
|
||||
## Can I use ChibiOS freely if I'm developing a commercial product?
|
||||
|
||||
Yes but if you modify the ChibiOS source code in any way please be aware of the following options:
|
||||
* you must comply with the [GPL3](https://www.gnu.org/licenses/gpl.html) licensing terms. Basically you **MUST** keep the ChibiOS part open source.
|
||||
|
||||
OR
|
||||
|
||||
* are okay with ChibiOS publicizing your use of it _and_ you clearly mention that your product is using ChibiOS you may keep your additions closed source.
|
||||
|
||||
|
||||
## Can I use ChibiOS 'components licensing'?
|
||||
|
||||
'Components Licensing' is when you buy only parts of ChibiOS, for example the RT kernel with the CM4 port. This option **MUST** be discussed it with the ChibiOS sales team.
|
||||
|
||||
|
||||
## What is a 'runtime license'?
|
||||
|
||||
The 'runtime license' is an option for the use of parts of ChibiOS in software products that are sold to 3rd parties. This option **MUST** be discussed with the ChibiOS sales team.
|
||||
|
||||
|
||||
## What about the **nanoframework** firmware
|
||||
The [nanoframwork firmware](nanoframework/nf-interpreter) is released under Apache 2 license and has no implications of using ChibiOS as the RTOS.
|
||||
|
||||
|
||||
## What about managed apps (C#) running on **nanoFramework**?
|
||||
|
||||
Applications (the C# code) that are _loaded_ into and _executed by_ the [nanoframwork firmware](nanoframework/nf-interpreter) firmware image are not compiled or built by it due to the fact that it is interpreted on the fly from memory. As such, it can be deemed as a seperate component and _your_ C# managed code from a licensing perspective can be deemed seperate from the firmware. For discussion sake imagine that you won't ever load a managed app on the firmqare image. **nanoFramework** would still be perfectly working software, just not doing much.
|
||||
As such this means that ChibiOS licensing doesn't apply to C# managed apps and it's use is not affected by the ChibiOS licensing terms.
|
||||
Загрузка…
Ссылка в новой задаче