Merge pull request #660 from fadushin/doc-updates

Documentation updates

doc/release-notes.md.in

@@ -8,16 +8,14 @@
 
 Welcome to AtomVM `@ATOMVM_VERSION@`
 
-These release notes provide information about the current release of AtoVM.
+These release notes provide version information about the current release of AtomVM.
 
 ## Required Software
 
 The following software is required to develop Erlang or Elixir applications on AtomVM:
 
-* The [`esptool`](https://github.com/espressif/esptool) program, for flashing the AtomVM image and AtomVM programs to ESP32 MCUs.
 * An [Erlang/OTP](https://erlang.org) compiler (`erlc`)
 * The [Elixir](https://elixir-lang.org) runtime, if developing Elixir applications.
-* A serial console program, such as `minicom` or `screen`, so that you can view console output from your AtomVM application.
 * (recommended) For Erlang programs, [`rebar3`](https://rebar3.org)
 * (recommended) For Elixir programs, [`mix`](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html), which ships with the Elixir runtime.
 
@@ -30,20 +28,20 @@ AtomVM will run BEAM files that have been compiled using the following Erlang an
 | ✅ OTP 23 | ✅ 1.11 |
 | ✅ OTP 24 | ✅ 1.14 |
 | ✅ OTP 25 | ✅ 1.14 |
-| ✅ OTP 26* | ✅ 1.15* |
+| ✅ OTP 26 | ✅ 1.15 |
+
+> Note. Versions of Elixir that are compatible with a particular OTP version may work.  This table reflects the versions that are tested.
+
+Not all BEAM instructions are supported for every Erlang and Elixir compiler.  For details about which instructions are supported, see the `src/libAtomVM/opcodes.h` header file in the  [AtomVM](https://github.com/atomvm/AtomVM/) github repository corresponding to the current release.
 
-`*` OTP 26 is still a release candidate and should be considered experimental.
-Other versions of Elixir that are compatible with a particular OTP version may work, this chart reflects the versions that are tested.
+For detailed information about features and bug fixes in the current release, see the AtomVM [Change Log](CHANGELOG.md).
 
-> Note.  Not all BEAM instructions are supported for every Erlang and Elixir compiler.  For details about which instructions are supported, see the `src/libAtomVM/opcodes.h` header file in the  [AtomVM](https://github.com/atomvm/AtomVM/) github repository corresponding to the current release.
+### ESP32 Support
 
-### ESP32 Build requirements
+To run applications built for AtomVM on the ESP32 platform you will need:
 
-This is entirely optional, you may simply use the downloadable images and flash them to your esp32 using `esptool`, but if you wish to work on development of the VM or use one on the additional drivers that are available in the ([AtomVM repositories](https://github.com/atomvm)) you will need a compatible version of ([Espressif's](https:/espressif.com)) ESP-IDF.
-Espressif provides excellent installation documentation on their website at:
-```
-     https://docs.espressif.com/projects/esp-idf/en/release-v4.4/esp32/get-started/index.html
-```
+* The [`esptool`](https://github.com/espressif/esptool) program, for flashing the AtomVM image and AtomVM programs to ESP32 MCUs.
+* A serial console program, such as `minicom` or `screen`, so that you can view console output from your AtomVM application.
 
 AtomVM currently supports the following versions of ESP-IDF:
 
@@ -52,8 +50,29 @@ AtomVM currently supports the following versions of ESP-IDF:
 | ESP-IDF v4.2 | ✅ |
 | ESP-IDF v4.3 | ✅ |
 | ESP-IDF v4.4 | ✅ |
-| ESP-IDF v5.0 | ❌ |
+| ESP-IDF v5.0 | ✅ |
 
-> Support is planned for version 5.0...
+Building the AtomVM virtual machine for ESP32 is optional.  In most cases, you can simply download a release image from the AtomVM [release](https://github.com/atomvm/AtomVM/releases) repository.  If you wish to work on development of the VM or use one on the additional drivers that are available in the ([AtomVM repositories](https://github.com/atomvm)) you will need a compatible version of ([Espressif's](https:/espressif.com)) ESP-IDF.  Espressif provides excellent [installation documentation](https://docs.espressif.com/projects/esp-idf/en/release-v4.4/esp32/get-started/index.html).
 
-For detailed information about features and bug fixes in the current release, see the AtomVM [Change Log](CHANGELOG.md).
+### STM32 Support
+
+The following software is required to build AtomVM for the STM32 platform:
+
+| Package |
+|---------|
+| [11.3 ARM toolchain](https://developer.arm.com/-/media/Files/downloads/gnu/11.3.rel1/binrel/arm-gnu-toolchain-11.3.rel1-x86_64-arm-none-eabi.tar.xz) |
+| [libopencm3](https://github.com/libopencm3/libopencm3.git) version 0.8.0 |
+
+> Note.  AtomVM tests this build on the latest Ubuntu github runner.
+
+### Raspberry Pi Pico Support
+
+The following software is required to build AtomVM for the Raspberry Pi Pico platform:
+
+| Package |
+|---------|
+| `gcc-arm-none-eabi` |
+| `libnewlib-arm-none-eabi` |
+| `libstdc++-arm-none-eabi-newlib` |
+
+> Note.  AtomVM tests this build on the latest Ubuntu github runner.

doc/src/getting-started-guide.md

@@ -10,6 +10,7 @@ The getting started is broken up into the following sections:
 
 * Getting Started on the ESP32 platform
 * Getting Started on the STM32 platform
+* Getting Started on the Raspberry Pi Pico platform
 * Getting Started on the Generic UNIX platform
 
 ## Getting Started on the ESP32 platform
@@ -210,6 +211,10 @@ Once the application has been flashed, you may connect to the ESP32 over the ser
 
 > TODO will se distribute a binary image for STM32?
 
+## Getting Started on the Raspberry Pi Pico platform
+
+> TODO
+
 ## Getting Started on the Generic UNIX platform
 
 AtomVM may be run on UNIX-like platforms using the `atomvm` command.

doc/src/programmers-guide.md

@@ -33,6 +33,8 @@ A high level overview of the supported language features include:
 * send (`!`) and `receive` messages
 * bit syntax (with some restrictions)
 * reference counted binaries
+* stacktraces
+* symmetric multi-processing (SMP)
 
 In addition, several features are supported specifically for integration with micro-controllers, including:
 
@@ -45,6 +47,7 @@ In addition, several features are supported specifically for integration with mi
     * UART interface
     * LEDC (PWM)
     * non-volatile storage (NVS)
+    * RTC storage
     * deep sleep
 
 ### Limitations
@@ -53,7 +56,6 @@ While the list of supported features is long and growing, the currently unsuppor
 
 * Bignums.  Integer values are restricted to 64-bit values.
 * Bit Syntax.  While packing and unpacking of arbitrary (but less than 64-) bit values is support, packing and unpacking of integer values at the start or end of a binary, or bordering binary packing or extraction must align on 8-bit boundaries.  Arbitrary bit length binaries are not currently supported.
-* SMP support.  The AtomVM VM is currently a single-threaded process.
 * The `epmd` and the `disterl` protocols are not supported.
 * There is no support for code hot swapping.
 * There is no support for a Read-Eval-Print-Loop. (REPL)
@@ -498,6 +500,82 @@ Stack frames will contain file and line information in the AuxData list if the B
 
 The PackBEAM tool does not include file and line information in the AVM files it creates, but file and line information can be included via a command line option.  For information about the PackBEAM too, see the [`PackBEAM` tool](#Packbeam_tool).
 
+### Reading data from AVM files
+
+AVM files are generally packed BEAM files, but they can also contain non-BEAM files, such as plain text files, binary data, or even encoded Erlang terms.
+
+Typically, these files are included from the `priv` directory in a build tree, for example, when using the [`atomvm_rebar3_plugin`](https://github.com/atomvm/atomvm_rebar3_plugin), though the [`PackBEAM`](./packbeam-format.md) tool and the [`atomvm_packbeam`](https://github.com/atomvm/atomvm_packbeam) tool allow you to specify any location for files to include in AVM files.
+
+By convention, these files obey the following path in an AVM file:
+
+    <application-name>/priv/<file-path>
+
+For example, if you wanted to embed `my_file.txt` into your application AVM file (where your application name is, for example, `my_application`), you would use:
+
+    my_application/priv/my_file.txt
+
+The `atomvm:read_priv/2` function can then be used to extract the contents of this file into a binary, e.g.,
+
+    %% erlang
+    MyFileBin = atomvm:read_priv(my_application, <<"my_file.txt">>)
+
+> Note. Embedded files may contain path separators, so for example `<<"my_files/my_file.txt">>` would be used if the AVM file embeds `my_file.txt` using the path `my_application/priv/my_files/my_file.txt`
+
+For more information about how to embed files into AVM files, see the [`atomvm_rebar3_plugin`](https://github.com/atomvm/atomvm_rebar3_plugin).
+
+### Code Loading
+
+AtomVM provides a limited set of APIs for loading code and data embedded dynamically at runtime.
+
+To load an AVM file from binary data, use the `atomvm:add_avm_pack_binary/2` function.  Supply a reference to the AVM data, together with a (possibly empty) list of options.  Specify a `name` option, whose value is an atom, if you wish to close the AVM data at a later point in the program.
+
+For example:
+
+    %% erlang
+    AVMData = ... %% load AVM data into memory as a binary
+    ok = atomvm:add_avm_pack_binary(AVMData, [{name, my_avm}])
+
+You can also load AVM data from a file (on the `generic_unix` platform) or from a flash partition (on ESP32 platforms) using the `atomvm:add_avm_pack_file/2` function.  Specify a string (or binary) as the path to the AVM file, together with a list of options.
+
+For example:
+
+    %% erlang
+    ok = atomvm:add_avm_pack_file("/path/to/file.avm", [])
+
+> Note.  Currently, the options parameter is ignored, so use the empty list (`[]`) for foward compatibility.
+
+On `esp32` platforms, the partition name should be prefixed with the string `/dev/partition/by-name/`.  Thus, for example, if you specify `/dev/partition/by-name/main2.avm` as the partition, the ESP32 flash should contain a data partition with the name `main2.avm`
+
+For example:
+
+    %% erlang
+    ok = atomvm:add_avm_pack_file("/dev/partition/by-name/main2.avm", [])
+
+To close a previous opened AVM by name, use the `atomvm:close_avm_pack/2` function.  Specify the name of the AVM pack used to add
+
+    %% erlang
+    ok = atomvm:close_avm_pack(my_avm, [])
+
+> Note.  Currently, the options parameter is ignored, so use the empty list (`[]`) for foward compatibility.
+
+You can load an individual BEAM file using the `code:load_binary/3` function.  Specify the Module name (as an atom), as well as the BEAM data you have loaded into memory.
+
+For Example:
+
+    %% erlang
+    BEAMData = ... %% load BEAM data into memory as a binary
+    {module, Module} = code:load_binary(Module, Filename, BEAMData)
+
+> Note.  The `Filename` parameter is currently ignored.
+
+You can load an individual BEAM file from the file system using the `code:load_abs/1` function.  Specify the path to the BEAM file.  This path should not include the `.beam` extension, as this extension will be added automatically.
+
+For example:
+
+    {module, Module} = code:load_abs("/path/to/beam/file/without/beam/extension")
+
+> Note.  This function is currently only supported on the `generic_unix` platform.
+
 ### Math
 
 AtomVM supports the following standard functions from the OTP `math` module:
@@ -657,6 +735,25 @@ Use the `esp:sleep_enable_ext0_wakeup/2` and `esp:sleep_enable_ext1_wakeup` func
         % Deep sleep for 1 hour
         esp:deep_sleep(60*60*1000).
 
+#### RTC Memory
+
+On ESP32 systems, you can use (slow) "real-time clock" memory to store data between deep sleeps.  This storage can be useful, for example, to store interim state data in your application.
+
+> Note.  RTC memory is initialized if the device is reset.
+
+To store data in RTC slow memory, use the `esp:rtc_slow_set_binary/1` function:
+
+    %% erlang
+    esp:rtc_slow_set_binary(<<"some binary data">>)
+
+To retrieve data in RTC slow memory, use the `esp:rtc_slow_get_binary/0` function:
+
+    %% erlang
+    Data = esp:rtc_slow_get_binary()
+
+By default, RTC slow memory in AtomVM is limited to 4098 (4k) bytes.  This value can be modified at build time using an IDF SDK `KConfig` setting.  For  instructions about how to build AtomVM, see the AtomVM [Build Instructions](./build-instructions.html).
+
+
 ### Miscellaneous
 
 The `freq_hz` function can be used to retrieve the clock frequency of the chip.

doc/src/welcome-to-atomvm.md

@@ -19,6 +19,7 @@ AtomVM features include:
 * A memory-managed environment, with efficient garbage collection and shared data, where permissible;
 * Support for truly functional programming languages, making your programs easier to understand and debug;
 * A concurrency-oriented platform, allowing users to spawn, monitor, and communicate with lightweight processes, making it easy for your IoT devices to perform tasks simultaneously;
+* Support for symmetric multi-processing (SMP); leverage all available cores on platforms that support it (e.g., ESP32) without any code changes;
 * A rich set of networking APIs, for writing robust IoT applications that communicate over IP networks;
 * A rich set of APIs for interfacing with standard device protocols, such as GPIO, I2C, SPI, and UART;
 * And more!

libs/eavmlib/src/atomvm.erl

@@ -30,14 +30,19 @@
     platform/0,
     random/0,
     rand_bytes/1,
-    read_priv/2
+    read_priv/2,
+    add_avm_pack_binary/2,
+    add_avm_pack_file/2,
+    close_avm_pack/2
 ]).
 
 -type platform_name() ::
     generic_unix
     | esp32
     | stm32.
 
+-type avm_path() :: string() | binary().
+
 %%-----------------------------------------------------------------------------
 %% @returns The platform name.
 %% @doc     Return the platform moniker.
@@ -83,3 +88,64 @@ rand_bytes(_Len) ->
 -spec read_priv(App :: atom(), Path :: list()) -> binary().
 read_priv(_App, _Path) ->
     throw(nif_error).
+
+%%-----------------------------------------------------------------------------
+%% @param   AVMData AVM data.
+%% @param   Options Options, as a property list.
+%% @returns `ok'
+%% @doc     Add code from an AVM binary to your application.
+%%
+%%          This function will add the data in the `AVMData' parameter to
+%%          your application.  The data is assumed to be valid AVM data (e.g, as
+%%          generated by packbeam tooling).
+%%
+%%          Failure to properly load AVM data is result in a runtime `error'
+%% @end
+%%-----------------------------------------------------------------------------
+-spec add_avm_pack_binary(AVMData :: binary(), Options :: [{name, Name :: atom()}]) -> ok.
+add_avm_pack_binary(_AVMData, _Options) ->
+    throw(nif_error).
+
+%%-----------------------------------------------------------------------------
+%% @param   AVMPath Path to AVM data.
+%% @param   Options Options, as a property list.
+%% @returns `ok'
+%% @doc     Add code from an AVM binary to your application.
+%%
+%%          This function will add the data located in the `AVMPath' parameter to
+%%          your application.  The data is assumed to be valid AVM data (e.g, as
+%%          generated by packbeam tooling).
+%%
+%%          On `generic_unix' platforms, the `AVMPath' may be a valid file system
+%%          path to an AVM file.
+%%
+%%          On `esp32' platforms, the `AVMPath' should be the name of an ESP32
+%%          flash partition, prefixed with the string
+%%          `/dev/partition/by-name/'.  Thus, for example, if you specify
+%%          `/dev/partition/by-name/main2.app' as the `AVMPath', the ESP32
+%%          flash should contain a data partition with the
+%%          name `main2.app'
+%%
+%%          Failure to properly load AVM path is result in a runtime `error'
+%% @end
+%%-----------------------------------------------------------------------------
+-spec add_avm_pack_file(AVMPath :: avm_path(), Options :: []) -> ok.
+add_avm_pack_file(_AVMPath, _Options) ->
+    throw(nif_error).
+
+%%-----------------------------------------------------------------------------
+%% @param   name the AVM name.
+%% @param   Options Options, as a property list.
+%% @returns `ok | error'
+%% @doc     Close previously opened AVM binary from your application.
+%%
+%%          This function will close the data referenced by the `Name' parameter from
+%%          your application.  The `Name' parameter must reference previously
+%%          opened AVM data.
+%%
+%%          Failure to close AVM data is result in a runtime `error'
+%% @end
+%%-----------------------------------------------------------------------------
+-spec close_avm_pack(Name :: atom(), Options :: []) -> ok | error.
+close_avm_pack(_Name, _Options) ->
+    throw(nif_error).