Mirrors/unleashed-firmware
2
0
Fork 0
mirror of https://github.com/DarkFlippers/unleashed-firmware synced 2024-11-22 20:43:07 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'fz-dev' into dev

Browse source
This commit is contained in:
MX 2022-09-15 18:28:57 +03:00
commit 668b7857b4
No known key found for this signature in database
GPG key ID: 6C4C311DFD4B4AB5
4 changed files with 24 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.vscode/example/settings.json vendored
View file

@ -14,7 +14,7 @@
"cortex-debug.openocdPath.osx": "${workspaceFolder}/toolchain/x86_64-darwin/openocd/bin/openocd",
"cortex-debug.gdbPath.windows": "${workspaceFolder}/toolchain/i686-windows/bin/arm-none-eabi-gdb-py.bat",
"cortex-debug.gdbPath.linux": "${workspaceFolder}/toolchain/x86_64-linux/bin/arm-none-eabi-gdb-py",
"cortex-debug.gdbPath.osx": "${workspaceFolder}/toolchain/x86_64-darwin/bin/arm-none-eabi-gdb",
"cortex-debug.gdbPath.osx": "${workspaceFolder}/toolchain/x86_64-darwin/bin/arm-none-eabi-gdb-py",
"editor.formatOnSave": true,
"files.associations": {
"*.scons": "python",

5
applications/ReadMe.md
View file

@ -1,8 +1,5 @@
# Structure
- `application.h` - Firmware application list header
## debug
Applications for factory testing the Flipper.
@ -53,6 +50,8 @@ Extra apps for Plugins & App Loader menus.
Background services providing system APIs to applications.
- `applications.h` - Firmware application list header
- `bt` - BLE service and application
- `cli` - Console service and API
- `crypto` - Crypto cli tools

20
documentation/AppsOnSDCard.md
View file

@ -1,20 +1,20 @@
### FAP (Flipper Application Package)
# FAP (Flipper Application Package)
[fbt](./fbt.md) has support for building applications as FAP files. FAP are essentially .elf executables with extra metadata and resources bundled in.
FAPs are built with `firmware_extapps` (or `plugin_dist`) **`fbt`** targets.
FAPs do not depend on being ran on a specific firmware version. Compatibility is determined by the FAP's metadata, which includes the required [API version](#api-versioning).
FAPs do not depend on being run on a specific firmware version. Compatibility is determined by the FAP's metadata, which includes the required [API version](#api-versioning).
## How to set up an application to be built as a FAP
FAPs are created and developed the same way as internal applications that are part of the firmware.
To build your application as a FAP, just create a folder with your app's source code in `applications_user` folder, then write its code the way you'd do when creating a regular built-in application. Then configure its `application.fam` manifest — and set its *apptype* to FlipperAppType.EXTERNAL. See [Application Manifests](./AppManifests.md#application-definition) for more details.
To build your application as a FAP, just create a folder with your app's source code in `applications_user`, then write its code the way you'd do when creating a regular built-in application. Then configure its `application.fam` manifest — and set its *apptype* to FlipperAppType.EXTERNAL. See [Application Manifests](./AppManifests.md#application-definition) for more details.
* To build your application, run `./fbt firmware_{APPID}`, where APPID is your application's ID in its manifest.
* To build your app, upload it over USB & run it on Flipper, run `./fbt launch_app APPSRC=applications/path/to/app`. This action is configured in default [VSCode profile](../.vscode/ReadMe.md) as "Launch App on Flipper" build action (Ctrl+Shift+B menu).
* To build your app, then upload it over USB & run it on Flipper, use `./fbt launch_app APPSRC=applications/path/to/app`. This command is configured in default [VSCode profile](../.vscode/ReadMe.md) as "Launch App on Flipper" build action (Ctrl+Shift+B menu).
* To build all FAPs, run `./fbt plugin_dist`.
@ -40,18 +40,18 @@ It is **important** that firmware and application build type (debug/release) mat
## How Flipper runs an application from SD card
Flipper's MCU cannot run code directly from external storage, so it needs to be copied to RAM first. This is done by the App Loader application, which is responsible for loading the FAP from SD card, verifying its integrity and compatibility and copying it to RAM.
Flipper's MCU cannot run code directly from external storage, so it needs to be copied to RAM first. That is done by the App Loader application, which is responsible for loading the FAP from SD card, verifying its integrity and compatibility, copying it to RAM and adjusting it for its new location.
Since FAP has to be loaded to RAM to be executed, the amount of RAM available for allocations from heap is reduced compared to running the same app from flash, as a part of firmware. Note that amount of occupied RAM is less than total FAP file size, since only code and data sections are allocated, and FAP file includes extra information only used at app load time.
Since FAP has to be loaded to RAM to be executed, the amount of RAM available for allocations from heap is reduced compared to running the same app from flash, as a part of firmware. Note that the amount of occupied RAM is less than total FAP file size, since only code and data sections are allocated, while FAP file includes extra information only used at app load time.
Applications are built for a specific API version. It is a part of hardware target's definition and contains a major and minor version number. Application loader checks if the application's major API version matches firmware's major API version.
Applications are built for a specific API version. It is a part of the hardware target's definition and contains a major and minor version number. Application loader checks if the application's major API version matches firmware's major API version.
App loader allocates memory for the application and copies it to RAM, processing relocations and providing concrete addresses for imported symbols using the [symbol table](#symbol-table). Then it starts the application.
## API Versioning
Not all parts of firmware are available for external applications. Subset of available functions and variables is defined in "api_symbols.csv" file, which is a part of firmware target definition in `firmware/targets/` directory.
Not all parts of firmware are available for external applications. A subset of available functions and variables is defined in "api_symbols.csv" file, which is a part of firmware target definition in `firmware/targets/` directory.
**`fbt`** uses semantic versioning for API versioning. Major version is incremented when there are breaking changes in the API, minor version is incremented when there are new features added.
@ -59,7 +59,7 @@ Breaking changes include:
- removal of a function or a global variable;
- changing the signature of a function.
API versioning is mostly automated by **`fbt`**. When rebuilding the firmware, **`fbt`** checks if there are any changes in the API exposed by headers gathered from `SDK_HEADERS`. If there are, it stops the build, adjusts API version and asks the user to go through the changes in .csv file. New entries are marked with "`?`" mark, and the user is supposed to change the mark to "`+`" for the entry to be exposed for FAPs, "`-`" for it to be unavailable.
API versioning is mostly automated by **`fbt`**. When rebuilding the firmware, **`fbt`** checks if there are any changes in the API exposed by headers gathered from `SDK_HEADERS`. If there are, it stops the build, adjusts the API version and asks the user to go through the changes in .csv file. New entries are marked with "`?`" mark, and the user is supposed to change the mark to "`+`" for the entry to be exposed for FAPs, "`-`" for it to be unavailable.
**`fbt`** will not allow building a firmware until all "`?`" entries are changed to "`+`" or "`-`".
@ -67,6 +67,6 @@ API versioning is mostly automated by **`fbt`**. When rebuilding the firmware, *
### Symbol Table
Symbol table is a list of symbols exported by firmware and available for external applications. It is generated by **`fbt`** from the API symbols file and is used by the App Loader to resolve addresses of imported symbols. It is build as a part of the `fap_loader` application.
The symbol table is a list of symbols exported by firmware and available for external applications. It is generated by **`fbt`** from the API symbols file and is used by the App Loader to resolve addresses of imported symbols. It is build as a part of the `fap_loader` application.
**`fbt`** also checks if all imported symbols are present in the symbol table. If there are any missing symbols, it will issue a warning listing them. Such application won't be able to run on the device until all requires symbols are provided in the symbol table.

22
documentation/OTA.md
View file

@ -1,8 +1,8 @@
# Executing code from RAM
In Flipper firmware, we have a special boot mode that loads a specially crafted system image into RAM and transfers control to it. System image executing in RAM has full write access to whole Flipper's flash memory — something that's not possible when running main code from same flash.
In Flipper firmware, we have a special boot mode that loads a specially crafted system image into RAM and transfers control to it. System image executing in RAM has full write access to whole Flipper's flash memory — something that's not possible when running main code from the same flash.
We leverage that boot mode to perform OTA firmware updates, including operations on radio stack running on second MCU core.
We leverage that boot mode to perform OTA firmware updates, including operations on a radio stack running on the second MCU core.
# How does Flipper OTA work?
@ -22,16 +22,16 @@ For that, main firmware loads an updater image - a customized build of main Flip
First, if there's a Radio stack image bundled with the update, updater compares its version with currently installed one. If they don't match, updater performs stack deinstallation followed by writing and installing a new one. The installation itself is performed by proprietary software, FUS, running on Core2, and leads to a series of system restarts.
Then updater validates and corrects Option Bytes — a special memory region containing low-level configuration for Flipper's MCU.
Then, updater validates and corrects Option Bytes — a special memory region containing low-level configuration for Flipper's MCU.
After that, updater loads a `.dfu` file with firmware to be flashed, checks its integrity using CRC32, writes it to system flash and validates written data.
## 3. Restoring internal storage and updating resources
After performing operations on flash memory, system restarts into newly flashed firmware. Then it performs restoration of previously backed up `/int` contents.
After performing operations on flash memory, the system restarts into newly flashed firmware. Then it performs restoration of previously backed up `/int` contents.
If update package contains an additional resources archive, it is extracted onto SD card.
If the update package contains an additional resources archive, it is extracted onto SD card.
# Update manifest
@ -40,13 +40,13 @@ Update packages come with a manifest that contains a description of its contents
## Mandatory fields
Update manifest must contain the following keys in given order:
An update manifest must contain the following keys in given order:
* __Filetype__: a constant string, "Flipper firmware upgrade configuration";
* __Version__: manifest version. Current value is 2;
* __Info__: arbitraty string, describing package contents;
* __Info__: arbitrary string, describing package contents;
* __Target__: hardware revision the package is built for;
@ -56,7 +56,7 @@ Update manifest must contain the following keys in given order:
## Optional fields
Other fields may have empty values, is such case updater skips all operations related to such values.
Other fields may have empty values, is such case, updater skips all operations related to such values.
* __Radio__: file name of radio stack image, provided by STM;
@ -66,16 +66,16 @@ Other fields may have empty values, is such case updater skips all operations re
* __Radio CRC__: CRC32 of radio image;
* __Resources__: file name of TAR acrhive with resources to be extracted on SD card;
* __Resources__: file name of TAR archive with resources to be extracted on SD card;
* __OB reference__, __OB mask__, __OB write mask__: reference values for validating and correcting option bytes.
# OTA update error codes
We designed the OTA update process to be as fail-safe as possible. We don't start any risky operation before validating all related pieces of data to ensure we don't leave the device in partially updated, or bricked, state.
We designed the OTA update process to be as fail-safe as possible. We don't start any risky operation before validating all related pieces of data to ensure we don't leave the device in a partially updated, or bricked, state.
Even if something goes wrong, Updater gives you an option to retry failed operations, and reports its state with an error code. These error codes have an `[XX-YY]` format, where `XX` encodes an operation that failed, and `YY` contains extra details on its progress where the error occured.
Even if something goes wrong, Updater gives you an option to retry failed operations, and reports its state with an error code. These error codes have an `[XX-YY]` format, where `XX` encodes an operation that failed, and `YY` contains extra details on its progress where the error occurred.
| Stage description | Code | Progress | Description |
|:-----------------------:|-------:|------------|--------------------------------------------|