Review Arch README pages

Sming/Arch/Esp32/README.rst

@@ -51,11 +51,15 @@ Building
 Make sure that the :envvar:`IDF_PATH` is set.
 Also make sure that the other ESP-IDF environmental variables are set.
 
-In Linux this can be done using the following command::
+In Linux/MacOS this can be done using the following command::
 
   source $SMING_HOME/Tools/export.sh
 
-Build the framework and application as usual, specifying :envvar:`SMING_ARCH` =Esp32. For example::
+For Windows::
+
+  $SMING_HOME\Tools\export
+
+Build the framework and application as usual, specifying :envvar:`SMING_ARCH=Esp32 <SMING_ARCH>`. For example::
 
    cd $SMING_HOME/../samples/Basic_Serial
    make SMING_ARCH=Esp32
@@ -71,40 +75,38 @@ SDK
 
 Sming comes with pre-compiled libraries and configuration files. If needed you can re-configure ESP-IDF using the command below::
 
-  make SMING_ARCH=Esp32 sdk-menuconfig
+  make sdk-menuconfig
 
-A re-compilation is required after the change of the configuration. This can be done with the following command::
+A re-compilation is required after the change of the configuration thus::
 
-  make SMING_ARCH=Esp32 Sming-build all
+  make Sming-build all
 
-If you want to revert to using the default SDK settings then issue the following command::
+If you want to revert to using the default SDK settings::
 
-  make SMING_ARCH=Esp32 sdk-config-clean
+  make sdk-config-clean
 
 You can also configure per-project custom settings via :envvar:`SDK_CUSTOM_CONFIG`.
 
 
 SoC variants
 ------------
 
-Sming leverages the `ESP IDF HAL <https://docs.espressif.com/projects/esp-idf/en/v4.3/esp32/api-guides/hardware-abstraction.html>`__
+Sming leverages the `ESP IDF HAL <https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/hardware-abstraction.html>`__
 to support multiple processor variants.
 
-This is still at an early stage of development however basic applications should build for the following variants:
+A family of SoCs is supported, currently::
 
-- esp32 (default)
+- esp32
 - esp32s2
 - esp32c3
 - esp32s3
 - esp32c2
 
-You can change variants like this:
+You can change variants like this::
 
-```
-make SMING_SOC=esp32c3
-```
+  make SMING_SOC=esp32c3
 
-Each variant uses a different build directory, e.g. ``out/Esp32/esp32c3/...`` to avoid conflicts.
+Each variant uses a different build directory, e.g. ``out/Esp32/esp32c3/...``.
 
 See :component-esp32:`esp32` for further details.
 
@@ -115,23 +117,23 @@ IDF versions
 ------------
 
 Sming currently supports IDF versions 4.3, 4.4, 5.0 and 5.2.
+The recommended version is 5.2.
+This is installed by default.
 
-The default installed IDF version is 5.2. This can be changed as follows::
+A different version can be installed if necessary::
 
     INSTALL_IDF_VER=4.4 $SMING_HOME/../Tools/install.sh esp32
 
 The installation script creates a soft-link in ``/opt/esp-idf`` pointing to the last version installed.
 Use the `IDF_PATH` environment variable or change the soft-link to select which one to use.
 
-After switching versions, run `make clean components-clean` before re-compiling.
-
-.. note::
+After switching versions, run a full clean before re-compiling.
+This must include SDK configuration::
 
-  Currently, switching from version 4.x to 5.0 or vice-versa requires an additional step
-  as they use different versions of the 'pyparsing' Python library.
+  make sdk-config-clean clean components-clean
 
-  If moving from IDF 4.x to 5.0:	``python -m pip install --upgrade pyparsing``
-  Moving from IDF 5.0 to 4.x: ``python -m pip install 'pyparsing<2.4'``
+See `ESP-IDF Versions <https://docs.espressif.com/projects/esp-idf/en/stable/esp32/versions.html>`__
+for the IDF release schedule.
 
 
 Components

Sming/Arch/Esp8266/README.rst

@@ -3,6 +3,47 @@ Sming Esp8266 Architecture
 
 Support building Sming for the Esp8266 architecture.
 
+This is the SOC for which Sming was originally developed,
+so many of the low-level API calls reflect those in the
+`SDK </_inc/Sming/Arch/Esp8266/Components/esp8266/README>`.
+These include functions such as
+:c:func:`system_get_free_heap_size`,
+:c:func:`system_update_cpu_freq`,
+:c:func:`system_get_cpu_freq`,
+:c:func:`esp_get_ccount`
+and others.
+
+The Esp8266 is the device which popularised 32-bit microcontrollers
+with integrated WiFi capability, the so-called
+`System on a chip <https://en.wikipedia.org/wiki/System_on_a_chip>`__ (SoC).
+
+Compared with more recent offerings such as the
+:doc:`ESP32 </_inc/Sming/Arch/Esp32/README>` and
+:doc:`RP2040 </_inc/Sming/Arch/Rp2040/README>`,
+it has characteristics which require special consideration:
+
+Limited RAM
+   Typically around 50 KiB of RAM is available for user applications,
+   compared with over 200 KiB for the Rp2040 and 300 KiB for the Esp32.
+   Although applications not requiring WiFi can recover another 30 KiB
+   via :component:`esp_no_wifi`, careful use of RAM is a primary consideration.
+   See :doc:`/information/memory`.
+Word-aligned SPI flash accesses
+   Flash memory is relatively plentiful, provided via high-speed serial SPI.
+   Because it is not internal to the SoC, the Esp8266 (and others) have hardware which
+   supports mapping areas of external memory into the address space so that
+   code and data can be accessed using standard machine instructions.
+   The Esp8266 has a particular quirk in that all such accesses must be
+   properly aligned to 32-bit word boundaries; failure to do this crashes the
+   system.
+   Other microcontrollers have better caching which handles misaligned accesses
+   without issue. See :doc:`/information/flash'.
+Weak hardware peripheral support
+   Even compared to older Atmel or Microchip 8-bit microcontrollers,
+   hardware support for interfaces such as I2C and PWM is lacking and these must
+   be implemented in software.
+
+
 Configuration Variables
 -----------------------
 

Sming/Arch/Rp2040/README.rst

@@ -7,17 +7,16 @@ Support building Sming for the `Raspberry Pi RP2040 SOC
 <https://www.raspberrypi.org/documentation/microcontrollers/raspberry-pi-pico.html>`__.
 
 Testing so far has been limited to the Rasperry Pi Pico, but there are lots of other boards available.
-Configure this using the :envvar:`PICO_BOARD` setting. The default is ``pico``.
+Configure this using the :envvar:`PICO_BOARD` setting. The default is ``pico`` (or ``pico_w`` if networking is enabled).
 You can find the `full list here <https://github.com/raspberrypi/pico-sdk/tree/master/src/boards/include/boards>`__.
 
 Special mention to the arduino-pico project https://github.com/earlephilhower/arduino-pico.
 Lots of helpful stuff in there!
 
-.. note::
-
-   This architecture should be considered experimental at present.
+Features
+--------
 
-Tested and working:
+The following features are tested and working:
 
 - CPU frequency adjustment :cpp:func:`system_get_cpu_freq`, :cpp:func:`system_update_cpu_freq`
 - Timers working: hardware, software and CPU cycle counter
@@ -36,13 +35,13 @@ Tested and working:
 - System functions :cpp:func:`system_get_chip_id`, :cpp:func:`system_get_sdk_version`.
 - Partitions and file systems (except SD cards and FAT)
 - SPIClass tested with Radio_nRF24L01 sample only
-- WiFi networking support for the Pico-W
+- `WiFi networking <Networking>`_ support for the Pico-W
 - Standard analogue I/O via analogRead. More advanced hardware capabilities require use of the SDK directly.
-- Dual-core support. See below for details.
+- `Dual-core support`_
 - USB supported using the :library:`USB` library, both host and device modes.
 - HardwareSPI via :library:`HardwareSPI` for fully asynchronous SPI communications (host mode only).
 
-Yet to be implemented:
+Not yet implemented:
 
 PWM
    Hardware can drive up to 16 outputs and measure input frequency/duty cycle.
@@ -67,57 +66,40 @@ Multi-boot / OTA updates.
    Adding RP2040 support to rBoot may work, however the Pico typically has only 2MByte flash which is quite restrictive.
    It is also necessary to compile images at different addresses as there is no windowed XIP (eXecute In Place) capability.
    See :library:`FlashIP` library for a basic method of OTA.
+Bluetooth
+   The SDK supports this but has not yet been integrated into Sming.
 
 
-Requirements
+Installation
 ------------
 
-These requirements are in addition to the standard Sming setup.
-
 The easiest way to get started is with the Sming installer - see :doc:`/getting-started/index`.
-For Linux and MacOS just run ``Tools/install.sh rp2040``.
-
-Note: Windows is not currently included in the chocolatey repository.
-The following instructions should help.
-
-Compiler/linker
-   The RP2040 contains two ARM Cortex-M0+ cores. Tools for all platforms can be downloaded from the
-   `ARM developer website <https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads>`__.
-
-   Unzip the archive to a suitable location (e.g. ``/opt/rp2040`` or ``c:\tools\rp2040``) and set :envvar:`PICO_TOOLCHAIN_PATH` accordingly.
 
-   You can alternatively use the toolchains provided in your GNU/Linux distribution.
+- Linux and MacOS: ``Tools/install.sh rp2040``.
+- Windows: ``Tools\install rp2040``.
 
-   Ubuntu
+See :envvar:`PICO_TOOLCHAIN_PATH` for details of the toolchains.
 
-      ::
+Note that you can use the toolchains provided in your GNU/Linux distribution.
+These are not extensively tested though.
 
-         sudo apt install gcc-arm-none-eabi gdb-multiarch
+Ubuntu
 
-      To use gdb-multiarch you'll need to do this::
+   ::
 
-         make gdb GDB=gdb-multiarch
+      sudo apt install gcc-arm-none-eabi gdb-multiarch
 
-   Fedora
+   To use gdb-multiarch you'll need to do this::
 
-      ::
+      make gdb GDB=gdb-multiarch
 
-         sudo dnf install arm-none-eabi-gcc-cs-c++ arm-none-eabi-newlib
+Fedora
 
-      The standard GDB appears to work OK.
+   ::
 
-Ninja
+      sudo dnf install arm-none-eabi-gcc-cs-c++ arm-none-eabi-newlib
 
-   This is used to build the RP2040 SDK code::
-
-      sudo apt install ninja-build
-
-   It is available for other platforms at https://ninja-build.org/
-   and consists of a single executable file.
-   The application should either be in the system path, or set :envvar:`NINJA`
-   to the full path of the executable file.
-
-   If you have Sming working with the ESP32 then you'll already have it installed.
+   The standard GDB appears to work OK.
 
 
 Setup and programming
@@ -131,7 +113,7 @@ Serial support requires a 3.3v USB adapter connected to the appropriate pins:
 To program your device, unplug the USB cable (i.e. remove power from the device)
 then hold down the ``BOOTSEL`` button whilst plugging it back in again.
 
-You can then run:
+You can then run::
 
    make flash
 
@@ -207,14 +189,19 @@ Networking
 ----------
 
 The Pico-W variant includes an Infineon CYW43439 bluetooth/WiFi SoC.
-
-Raspberry Pi use the ... driver. The SDK also includes an LWIP implementation.
+Raspberry Pi makes use of the
+`CYW43xx WiFi/BT SoC driver <https://github.com/georgerobotics/cyw43-driver>`
+driver under
+`special license <https://github.com/georgerobotics/cyw43-driver/blob/main/LICENSE.RP>`.
+The SDK also includes an LWIP2 implementation.
 
 The physical interface is SPI using a custom (PIO) implementation.
-This requires the use of GPIOxx which can no longer be accessed directly,
-but instead via xxxxx.
+This requires the use of several GPIO pins which can no longer be
+controlled via standard :cpp:func:`digitalWrite` calls.
+The user LED, for example, is connected to a GPIO on the CYW43 chip ``WL_GPIO0``.
+Those pins are controlled using a separate API which is far more involved.
 
-The CYW43 chip is initialised (via `cyw43_ensure_up`) when application code
+The CYW43 chip is initialised (via :c:func:`cyw43_ensure_up`) when application code
 makes the first call into the networking API, for example by enabling station
 or AP access. Part of the hardware configuration here is to download firmware
 to the CYW43 chip (about 240KB) plus the CLM BLOB (< 1KB).
@@ -228,12 +215,13 @@ to the CYW43 chip (about 240KB) plus the CLM BLOB (< 1KB).
 Sming contains patches which compresses this data (based on https://github.com/raspberrypi/pico-sdk/issues/909)
 to about 145KB.
 By default, it is linked into the application image, but can also be read from a separate partition.
+See :envvar:`LINK_CYW43_FIRMWARE`.
 
 
 Source code
 -----------
 
-The RP2040 is a very capable SOC, albeit without WiFi.
+The RP2040 is a very capable SOC, similar to Espressif offerings but without integrated WiFi.
 A massive advantage is that the platform is fully open-source.
 Even the bootrom is published!
 
@@ -276,8 +264,13 @@ Configuration Variables
 .. envvar:: PICO_TOOLCHAIN_PATH
 
    This contains the base directory for the toolchain used to build the framework.
+
+   The RP2040 contains two ARM Cortex-M0+ cores.
    Pre-compiled toolchains can be downloaded from the
-   `ARM Developer website <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads>`__.
+   `ARM Developer website <https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads>`__.
+
+   These can be unzipped to a suitable location and :envvar:`PICO_TOOLCHAIN_PATH` set accordingly.
+   The Sming installer scripts use ``/opt/rp2040`` or ``c:\tools\rp2040``.
 
 
 Components

Sming/Arch/Rp2040/Tools/install.sh

@@ -19,8 +19,3 @@ elif [ -n "$PICO_TOOLCHAIN_PATH" ]; then
     tar -xf "$DOWNLOADS/$TOOLCHAIN_FILE" -C "$PICO_TOOLCHAIN_PATH" --totals #--transform='s|^/*||'
     mv "$PICO_TOOLCHAIN_PATH/"*/* "$PICO_TOOLCHAIN_PATH"
 fi
-
-# https://developer.arm.com/-/media/Files/downloads/gnu/
-# 13.2.rel1/
-# binrel/
-# arm-gnu-toolchain-13.2.rel1-darwin-x86_64-arm-none-eabi.tar.xz