From fa0b4b801f70346f75a49f28d077424eb820fec4 Mon Sep 17 00:00:00 2001
From: Gunar Schorcht <gunar@schorcht.net>
Date: Sun, 23 Dec 2018 18:28:08 +0100
Subject: [PATCH] cpu/esp8266: doc fixes

---
 boards/common/esp8266/include/board_modules.h |  17 ++-
 cpu/esp8266/README.md                         | 114 ++++++++---------
 cpu/esp8266/doc.txt                           | 119 +++++++++---------
 cpu/esp8266/include/irq_arch.h                |   2 +-
 4 files changed, 119 insertions(+), 133 deletions(-)

diff --git a/boards/common/esp8266/include/board_modules.h b/boards/common/esp8266/include/board_modules.h
index 3fde8b1e8c..1bfe644963 100644
--- a/boards/common/esp8266/include/board_modules.h
+++ b/boards/common/esp8266/include/board_modules.h
@@ -17,9 +17,11 @@
  * All ESP8266 boards can be used with different off-board hardware modules.
  * This file contains the default configurations for those external hardware
  * modules that have been tested with the ESP8266 and are preconfigured here.
- * Most of these configurations can be overridden by application-specific
- * configurations. The configuration for a hardware module is only used if the
- * corresponding driver modules are used.
+ * Most of these configurations can be overridden by an
+ * \ref esp8266_app_spec_conf "application-specific configuration".
+ *
+ * The configurations of the respective hardware modules only take place if
+ * the corresponding driver modules are used.
  *
  * @file
  * @author      Gunar Schorcht <gunar@schorcht.net>
@@ -28,11 +30,6 @@
 
 #include <stdint.h>
 
-#include "cpu.h"
-#include "periph_conf.h"
-#include "periph_conf_common.h"
-#include "periph/gpio.h"
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -59,7 +56,7 @@ extern "C" {
 #define ENC28J60_PARAM_CS       GPIO4       /**< ENC28J60 CS signal (can be overriden) */
 #endif
 #ifndef ENC28J60_PARAM_INT
-#define ENC28J60_PARAM_INT      GPIO9       /**< ENC28J60 CS signal (can be overriden) */
+#define ENC28J60_PARAM_INT      GPIO9       /**< ENC28J60 INT signal (can be overriden) */
 #endif
 #ifndef ENC28J60_PARAM_RESET
 #define ENC28J60_PARAM_RESET    GPIO10      /**< ENC28J60 RESET signal (can be overriden) */
@@ -91,7 +88,7 @@ extern "C" {
 #define MRF24J40_PARAM_CS       GPIO16          /**< MRF24J40 CS signal (can be overriden) */
 #endif
 #ifndef MRF24J40_PARAM_INT
-#define MRF24J40_PARAM_INT      GPIO0           /**< MRF24J40 CS signal (can be overriden) */
+#define MRF24J40_PARAM_INT      GPIO0           /**< MRF24J40 INT signal (can be overriden) */
 #endif
 #ifndef MRF24J40_PARAM_RESET
 #define MRF24J40_PARAM_RESET    GPIO2           /**< MRF24J40 RESET signal (can be overriden) */
diff --git a/cpu/esp8266/README.md b/cpu/esp8266/README.md
index 6dd3d90823..a77700f077 100644
--- a/cpu/esp8266/README.md
+++ b/cpu/esp8266/README.md
@@ -96,7 +96,7 @@ You have the following options to install the Toolchain:
 
 ## <a name="esp8266_riot_docker_toolchain"> RIOT Docker Toolchain (riotdocker) </a> &nbsp;[[TOC](#esp8266_toc)]
 
-The easiest use the toolchain is Docker.
+The easiest way to use the toolchain is Docker.
 
 ### <a name="esp8266_preparing_the_environment"> Preparing the Environment </a> &nbsp;[[TOC](#esp8266_toc)]
 
@@ -335,8 +335,7 @@ Option | Values | Default | Description
 -------|--------|---------|------------
 ENABLE_GDB | 0, 1 | 0 | Enable compilation with debug information for debugging with QEMU (```QEMU=1```), see section [QEMU Mode and GDB](#esp8266_qemu_mode_and_gdb)
 FLASH_MODE | dout, dio, qout, qio | dout | Set the flash mode, please take care with your module, see section [Flash Modes](#esp8266_flash_modes)
-NETDEV_DEFAULT | module name | mrf24j40 | Set the module that is used as default network device, see section [Network Devices](#esp8266_network_devices)
-PORT | /dev/ttyUSBx | /dev/ttyUSB0 | Set the USB port for flashing the firmware
+PORT | /dev/ttyUSBx | /dev/* | Set the USB port for flashing the firmware
 QEMU | 0, 1 | 0 | Generate an image for QEMU, see section [QEMU Mode and GDB](#esp8266_qemu_mode_and_gdb).
 USE_SDK | 0, 1 | 0 | Compile the SDK version (```USE_SDK=1```), see section [SDK Task Handling](#esp8266_sdk_task_handling)
 
@@ -348,11 +347,23 @@ Optional features of ESP8266 can be enabled by ```USEMODULE``` definitions in th
 
 Module | Description
 -------|------------
-esp_spiffs | Enables the SPIFFS file system, see section [SPIFFS Device](#esp8266_spiffs_device)
-esp_sw_timer | Enables software timer implementation, implies the setting ```USE_SDK=1```, see section [Timers](#esp8266_timers)
+[esp_gdb](#esp8266_qemu_mode_and_gdb) | Enable the compilation with debug information, which is equivalent to using ```ENABLE_GDB=1```
+[esp_sdk](#esp8266_sdk_task_handling) | Enable the SDK version, which is equivalent to using ```USE_SDK=1```
+[esp_spiffs](#esp8266_spiffs_device) | Enable the SPIFFS drive in on-board flash memory
+[esp_sw_timer](#esp8266_timers) | Enable software timer implementation, implies the setting ```USE_SDK=1``` (module ```esp_sdk```)
 
 </center><br>
 
+For example, to activate the SPIFFS drive in on-board flash memory, the makefile of application has simply to add the ```esp_spiffs``` module to ```USEMODULE``` make variable:
+```
+USEMODULE += esp_spiffs
+```
+
+Modules can also be activated temporarily at the command line when calling the make command:
+```
+USEMODULE="esp_spiffs" make BOARD=...
+```
+
 ## <a name="esp8266_flash_modes"> Flash Modes </a> &nbsp;[[TOC](#esp8266_toc)]
 
 The ```FLASH_MODE``` make command variable determines the mode that is used for flash access in normal operation.
@@ -528,7 +539,7 @@ The software timer uses SDK's software timers to implement the timer channels. A
 
 ## <a name="esp8266_spiffs_device"> SPIFFS Device </a> &nbsp;[[TOC](#esp8266_toc)]
 
-If SPIFFS module is enabled (```USEMODULE += esp_spiffs```), the implemented MTD device ```mtd0``` for the on-board SPI flash memory is used together with modules ```spiffs``` and ```vfs``` to realize a persistent file system.
+If SPIFFS module is enabled (```USEMODULE += esp_spiffs```), the implemented MTD system drive ```mtd0``` for the on-board SPI flash memory is used together with modules ```spiffs``` and ```vfs``` to realize a persistent file system.
 
 For this purpose, the flash memory is formatted as SPIFFS starting at the address ```0x80000``` (512 kByte) on first boot. All sectors up to the last 5 sectors of the flash memory are then used for the file system. With a fixed sector size of 4096 bytes, the top address of the SPIFF is ```flash_size - 5 * 4096```, e.g., ```0xfb000``` for a flash memory of 1 MByte. The size of the SPIFF then results from:
 ```
@@ -554,84 +565,67 @@ The ESP8266 port of RIOT has been tested with several common external devices th
 
 ## <a name="esp8266_network_devices"> Network Devices </a> &nbsp;[[TOC](#esp8266_toc)]
 
-RIOT provides a number of driver modules for different types of network devices, e.g., IEEE 802.15.4 radio modules and Ethernet modules. The RIOT ESP8266 port has been tested with the following network devices and is preconfigured to create RIOT network applications with these devices:
-
-- [mrf24j40](http://riot-os.org/api/group__drivers__mrf24j40.html) (driver for Microchip MRF24j40 based IEEE 802.15.4
-- [enc28j60](http://riot-os.org/api/group__drivers__enc28j60.html) (driver for Microchip ENC28J60 based Ethernet modules)
+RIOT provides a number of driver modules for different types of network devices, e.g., IEEE 802.15.4 radio modules and Ethernet modules. The RIOT port for ESP8266 has been tested with the following network devices:
 
-If the RIOT network application uses a default network device (module ```netdev_default```), the ```NETDEV_DEFAULT``` make command variable can be used to define the device that will be used as the default network device. The value of this variable must match the name of the driver module for this network device. If ```NETDEV_DEFAULT``` is not defined, the ```mrf24j40```  module is used as default network device.
+- [mrf24j40](https://riot-os.org/api/group__drivers__mrf24j40.html) (driver for Microchip MRF24j40 based IEEE 802.15.4
+- [enc28j60](https://riot-os.org/api/group__drivers__enc28j60.html) (driver for Microchip ENC28J60 based Ethernet modules)
 
 ### <a name="esp8266_using_mrf24j40"> Using MRF24J40 (module ```mrf24j40```) </a> &nbsp;[[TOC](#esp8266_toc)]
 
-To use MRF24J40 based IEEE 802.15.4 modules as network device, module ```mrf24j40``` has to be added to a makefile:
+To use MRF24J40 based IEEE 802.15.4 modules as network device, the ```mrf24j40``` driver module has to be added to the makefile of the application:
 
 ```
 USEMODULE += mrf24j40
 ```
 
-**Please note:** If module ```netdev_default``` is used (which is usually the case in all networking applications), module ```mrf24j40``` is added automatically.
-
-Module ```mrf24j40``` uses the following interface parameters by default:
+The ```mrf24j40``` driver module uses the following preconfigured interface parameters for ESP8266 boards:
 
 <center>
 
 Parameter              | Default      | Remarks
 -----------------------|--------------|----------------------------
-MRF24J40_PARAM_SPI     | SPI_DEV(0)   | fix, see section [SPI Interfaces](#esp8266_spi_interfaces)
-MRF24J40_PARAM_SPI_CLK | SPI_CLK_1MHZ | fix
+MRF24J40_PARAM_SPI     | SPI_DEV(0)   | fixed, see section [SPI Interfaces](#esp8266_spi_interfaces)
+MRF24J40_PARAM_SPI_CLK | SPI_CLK_1MHZ | fixed
 MRF24J40_PARAM_CS      | GPIO16       | can be overridden
 MRF24J40_PARAM_INT     | GPIO0        | can be overridden
 MRF24J40_PARAM_RESET   | GPIO2        | can be overridden
 
 </center><br>
 
-Used GPIOs can be overridden by corresponding make command variables, e.g,:
-```
-make flash BOARD=esp8266-esp-12x -C examples/gnrc_networking MRF24J40_PARAM_CS=GPIO15
-```
-or by an [application-specific board configuration](#esp8266_application_specific_board_configuration).
+The GPIOs in this configuration can be overridden by [application-specific board configurations](#esp8266_application_specific_board_configuration).
 
 ### <a name="esp8266_using_enc28j60"> Using ENC28J60 (module ```enc28j60```) </a> &nbsp;[[TOC](#esp8266_toc)]
 
-To use ENC28J60 Ethernet modules as network device, module ```enc28j60``` has to be added to your makefile:
+To use ENC28J60 Ethernet modules as network device, the ```enc28j60``` driver module has to be added to the makefile of the application:
 
 ```
 USEMODULE += enc28j60
 ```
 
-Module ```enc28j60``` uses the following interface parameters by default:
+The ```enc28j60``` driver module uses the following preconfigured interface parameters for ESP8266 boards:
 
 <center>
 
 Parameter            | Default      | Remarks
 ---------------------|--------------|----------------------------
-ENC28J60_PARAM_SPI   | SPI_DEV(0)   | fix, see section [SPI Interfaces](#esp8266_spi_interfaces)
+ENC28J60_PARAM_SPI   | SPI_DEV(0)   | fixed, see section [SPI Interfaces](#esp8266_spi_interfaces)
 ENC28J60_PARAM_CS    | GPIO4        | can be overridden
 ENC28J60_PARAM_INT   | GPIO9        | can be overridden
 ENC28J60_PARAM_RESET | GPIO10       | can be overridden
 
 </center>
 
-Used GPIOs can be overridden by corresponding make command variables, e.g.:
-```
-make flash BOARD=esp8266-esp-12x -C examples/gnrc_networking ENC28J60_PARAM_CS=GPIO15
-```
-or by an [application-specific board configuration](#esp8266_application_specific_board_configuration).
-
-To use module ```enc28j60``` as default network device, the ```NETDEV_DEFAULT``` make command variable has to set, for example:
-```
-make flash BOARD=esp8266-esp-12x -C examples/gnrc_networking NETDEV_DEFAULT=enc28j60
-```
+The GPIOs in this configuration can be overridden by [application-specific board configurations](#esp8266_application_specific_board_configuration).
 
 ## <a name="esp8266_sd_card_device"> SD-Card Device </a> &nbsp;[[TOC](#esp8266_toc)]
 
-ESP8266 port of RIOT is preconfigured for RIOT applications that use the [SPI SD-Card driver](http://riot-os.org/api/group__drivers__sdcard__spi.html). To use SPI SD-Card driver, the ```sdcard_spi``` module has to be added to a makefile:
+ESP8266 port of RIOT is preconfigured for RIOT applications that use the [SPI SD-Card driver](https://riot-os.org/api/group__drivers__sdcard__spi.html). To use SPI SD-Card driver, the ```sdcard_spi``` module has to be added to a makefile:
 
 ```
 USEMODULE += sdcard_spi
 ```
 
-Module ```sdcard_spi``` uses the following interface parameters by default:
+The ```sdcard_spi``` driver module uses the following preconfigured interface parameters for ESP8266 boards:
 
 <center>
 
@@ -642,22 +636,19 @@ SDCARD_SPI_PARAM_CS    | SPI0_CS0_GPIO | can be overridden
 
 </center>
 
-The GPIO used as CS signal can be overridden by an [application-specific board configuration](#esp8266_application_specific_board_configuration).
+The GPIO used as CS signal can be overridden by [application-specific board configurations](#esp8266_application_specific_board_configuration).
 
 
+\anchor esp8266_app_spec_conf
 # <a name="esp8266_application_specific_configurations"> Application-Specific Configurations </a> &nbsp;[[TOC](#esp8266_toc)]
 
-Configuration used for peripheral devices and for device driver modules, such as GPIO pins, bus interfaces or bus speeds are typically defined in the board-specific configurations ```board.h``` and ```periph_conf.h``` or in the driver parameter configuration ```< driver>_params.h```. Most of these definitions are enclosed by
-```
-#ifndef ANY_PARAMETER
-...
-#endif
-```
-constructs, so it is possible to override them by defining them in front of these constructs.
+The board-specific configuration files ```board.h``` and ```periph_conf.h``` as well as the driver parameter configuration files ```<driver>_params.h``` define the default configurations for peripherals and device driver modules. These are, for example, the GPIOs used, bus interfaces used or available bus speeds. Because there are many possible configurations and many different application requirements, these default configurations are usually only a compromise between different requirements.
+
+Therefore, it is often necessary to change some of these default configurations for individual applications. For example, while many PWM channels are needed in one application, another application does not need PWM channels, but many ADC channels.
 
 ## <a name="esp8266_application_specific_board_configuration"> Application-Specific Board Configuration </a> &nbsp;[[TOC](#esp8266_toc)]
 
-To override standard board configurations, simply create an application-specific board configuration file ```$APPDIR/board.h``` in the source directory of the application ```$APPDIR``` and add the definitions to be overridden. To force the preprocessor to include board's original ```board.h``` after that, add the ```include_next``` preprocessor directive as the **last** line.
+To override default board configurations, simply create an application-specific board configuration file ```$APPDIR/board.h``` in the source directory ```$APPDIR``` of the application and add the definitions to be overridden. To force the preprocessor to include board's original ```board.h``` after that, add the ```include_next``` preprocessor directive as the <b>last</b> line.
 
 For example to override the default definition of the GPIOs that are used as PWM channels, the application-specific board configuration file ```$APPDIR/board.h``` could look like the following:
 ```
@@ -668,24 +659,25 @@ For example to override the default definition of the GPIOs that are used as PWM
 #include_next "board.h"
 ```
 
-To make such application-specific board configurations dependent on the ESP8266 MCU or a particular ESP8266 card, you should always enclose these definitions in the following constructs:
+It is important to ensure that the application-specific board configuration ```$APPDIR/board.h``` is included first. Insert the following line as the <b>first</b> line to the application makefile ```$APPDIR/Makefile```.
+```
+INCLUDES += -I$(APPDIR)
+```
+
+**Please note:** To make such application-specific board configurations dependent on the ESP8266 MCU or a particular ESP8266 board, you should always enclose these definitions in the following constructs
 ```
 #ifdef CPU_ESP8266
 ...
 #endif
 
-#ifdef BOARD_ESP8266_ESP_12X
+#ifdef BOARD_ESP8266_ESP-12X
 ...
 #endif
 ```
-To ensure that the application-specific board configuration ```$APPDIR/board.h``` is included first, insert the following line as the **first** line to the application makefile ```$APPDIR/Makefile```.
-```
-INCLUDES += -I$(APPDIR)
-```
 
 ## <a name="esp8266_application_specific_driver_configuration"> Application-Specific Driver Configuration </a> &nbsp;[[TOC](#esp8266_toc)]
 
-Using the approach for overriding board configurations, the parameters of drivers that are typically defined in ```drivers/<device>/include/<device>_params.h``` can also be overridden. For that purpose just create an application-specific driver parameter file ```$APPDIR/<device>_params.h``` in the source directory ```$APPDIR``` of the application and add the definitions to be overridden. To force the preprocessor to include driver's original ```<device>_params.h``` after that, add the ```include_next``` preprocessor directive as the **last** line.
+Using the approach for overriding board configurations, the parameters of drivers that are typically defined in ```drivers/<device>/include/<device>_params.h``` can be overridden. For that purpose just create an application-specific driver parameter file ```$APPDIR/<device>_params.h``` in the source directory ```$APPDIR``` of the application and add the definitions to be overridden. To force the preprocessor to include driver's original ```<device>_params.h``` after that, add the ```include_next``` preprocessor directive as the <b>last</b> line.
 
 For example, to override a GPIO used for LIS3DH sensor, the application-specific driver parameter file ```$APPDIR/<device>_params.h``` could look like the following:
 ```
@@ -695,20 +687,22 @@ For example, to override a GPIO used for LIS3DH sensor, the application-specific
 
 #include_next "lis3dh_params.h"
 ```
-To make such application-specific board configurations dependent on the ESP8266 MCU or a particular ESP8266 card, you should always enclose these definitions in the following constructs:
+
+It is important to ensure that the application-specific driver parameter file ```$APPDIR/<device>_params.h``` is included first. Insert the following line as the <b>first</b> line to the application makefile ```$APPDIR/Makefile```.
+```
+INCLUDES += -I$(APPDIR)
+```
+
+**Pleae note:** To make such application-specific board configurations dependent on the ESP8266 MCU or a particular ESP8266 board, you should always enclose these definitions in the following constructs:
 ```
 #ifdef CPU_ESP8266
 ...
 #endif
 
-#ifdef BOARD_ESP8266_ESP_12X
+#ifdef BOARD_ESP8266_ESP-12X
 ...
 #endif
 ```
-To ensure that the application-specific driver parameter file ```$APPDIR/<device>_params.h``` is included first, insert the following line as the **first** line to the application makefile ```$APPDIR/Makefile```.
-```
-INCLUDES += -I$(APPDIR)
-```
 
 # <a name="esp8266_sdk_task_handling"> SDK Task Handling </a> &nbsp;[[TOC](#esp8266_toc)]
 
@@ -724,7 +718,7 @@ In the RIOT port, the task management of the SDK is replaced by the task managem
 
 When QEMU mode is enabled (```QEMU=1```), instead of loading the image to the target hardware, a binary image ```$ELFFILE.bin``` is created in the target directory. This binary image file can be used together with QEMU to debug the code in GDB.
 
-The binary image can be compiled with debugging information (```ENABLE_GDB=1```) or optimized without debugging information (```ENABLE_GDB=0```). The latter one is the default. The version with debugging information can be debugged in source code while the optimized version can only be debugged in assembler mode.
+The binary image can be compiled with debugging information (```ENABLE_GDB=1``` or module ```esp_gdb```) or optimized without debugging information (```ENABLE_GDB=0```). The latter one is the default. The version with debugging information can be debugged in source code while the optimized version can only be debugged in assembler mode.
 
 To use QEMU, you have to install QEMU for Xtensa with ESP8266 machine implementation as following.
 
diff --git a/cpu/esp8266/doc.txt b/cpu/esp8266/doc.txt
index cb5a5037be..721456eccd 100644
--- a/cpu/esp8266/doc.txt
+++ b/cpu/esp8266/doc.txt
@@ -101,7 +101,7 @@ You have the following options to install the Toolchain:
 
 ## <a name="esp8266_riot_docker_toolchain"> RIOT Docker Toolchain (riotdocker) </a> &nbsp;[[TOC](#esp8266_toc)]
 
-The easiest use the toolchain is Docker.
+The easiest way to use the toolchain is Docker.
 
 ### <a name="esp8266_preparing_the_environment"> Preparing the Environment </a> &nbsp;[[TOC](#esp8266_toc)]
 
@@ -340,24 +340,35 @@ Option | Values | Default | Description
 -------|--------|---------|------------
 ENABLE_GDB | 0, 1 | 0 | Enable compilation with debug information for debugging with QEMU (```QEMU=1```), see section [QEMU Mode and GDB](#esp8266_qemu_mode_and_gdb)
 FLASH_MODE | dout, dio, qout, qio | dout | Set the flash mode, please take care with your module, see section [Flash Modes](#esp8266_flash_modes)
-NETDEV_DEFAULT | module name | mrf24j40 | Set the module that is used as default network device, see section [Network Devices](#esp8266_network_devices)
-PORT | /dev/ttyUSBx | /dev/ttyUSB0 | Set the USB port for flashing the firmware
+PORT | /dev/ttyUSBx | /dev/* | Set the USB port for flashing the firmware
 QEMU | 0, 1 | 0 | Generate an image for QEMU, see section [QEMU Mode and GDB](#esp8266_qemu_mode_and_gdb).
 USE_SDK | 0, 1 | 0 | Compile the SDK version (```USE_SDK=1```), see section [SDK Task Handling](#esp8266_sdk_task_handling)
 
 </center><br>
 
-Optional features of ESP8266 can be enable by ```USEMODULE``` definitions in the makefile of the application. These are:
+Optional features of ESP8266 can be enabled by ```USEMODULE``` definitions in the makefile of the application. These are:
 
 <center>
 
 Module | Description
 -------|------------
-esp_spiffs | Enables the SPIFFS file system, see section [SPIFFS Device](#esp8266_spiffs_device)
-esp_sw_timer | Enables software timer implementation, implies the setting ```USE_SDK=1```, see section [Timers](#esp8266_timers)
+[esp_gdb](#esp8266_qemu_mode_and_gdb) | Enable the compilation with debug information, which is equivalent to using ```ENABLE_GDB=1```
+[esp_sdk](#esp8266_sdk_task_handling) | Enable the SDK version, which is equivalent to using ```USE_SDK=1```
+[esp_spiffs](#esp8266_spiffs_device) | Enable the SPIFFS drive in on-board flash memory
+[esp_sw_timer](#esp8266_timers) | Enable software timer implementation, implies the setting ```USE_SDK=1``` (module ```esp_sdk```)
 
 </center><br>
 
+For example, to activate the SPIFFS drive in on-board flash memory, the makefile of application has simply to add the ```esp_spiffs``` module to ```USEMODULE``` make variable:
+```
+USEMODULE += esp_spiffs
+```
+
+Modules can also be activated temporarily at the command line when calling the make command:
+```
+USEMODULE="esp_spiffs" make BOARD=...
+```
+
 ## <a name="esp8266_flash_modes"> Flash Modes </a> &nbsp;[[TOC](#esp8266_toc)]
 
 The ```FLASH_MODE``` make command variable determines the mode that is used for flash access in normal operation.
@@ -532,7 +543,7 @@ The software timer uses SDK's software timers to implement the timer channels. A
 
 ## <a name="esp8266_spiffs_device"> SPIFFS Device </a> &nbsp;[[TOC](#esp8266_toc)]
 
-If SPIFFS module is enabled (```USE_SPIFFS=1```), the implemented MTD device ```mtd0``` for the on-board SPI flash memory is used together with modules ```spiffs``` and ```vfs``` to realize a persistent file system.
+If SPIFFS module is enabled (```USEMODULE += esp_spiffs```), the implemented MTD system drive ```mtd0``` for the on-board SPI flash memory is used together with modules ```spiffs``` and ```vfs``` to realize a persistent file system.
 
 For this purpose, the flash memory is formatted as SPIFFS starting at the address ```0x80000``` (512 kByte) on first boot. All sectors up to the last 5 sectors of the flash memory are then used for the file system. With a fixed sector size of 4096 bytes, the top address of the SPIFF is ```flash_size - 5 * 4096```, e.g., ```0xfb000``` for a flash memory of 1 MByte. The size of the SPIFF then results from:
 ```
@@ -558,84 +569,67 @@ The ESP8266 port of RIOT has been tested with several common external devices th
 
 ## <a name="esp8266_network_devices"> Network Devices </a> &nbsp;[[TOC](#esp8266_toc)]
 
-RIOT provides a number of driver modules for different types of network devices, e.g., IEEE 802.15.4 radio modules and Ethernet modules. The RIOT ESP8266 port has been tested with the following network devices and is preconfigured to create RIOT network applications with these devices:
-
-- [mrf24j40](http://riot-os.org/api/group__drivers__mrf24j40.html) (driver for Microchip MRF24j40 based IEEE 802.15.4
-- [enc28j60](http://riot-os.org/api/group__drivers__enc28j60.html) (driver for Microchip ENC28J60 based Ethernet modules)
+RIOT provides a number of driver modules for different types of network devices, e.g., IEEE 802.15.4 radio modules and Ethernet modules. The RIOT port for ESP8266 has been tested with the following network devices:
 
-If the RIOT network application uses a default network device (module ```netdev_default```), the ```NETDEV_DEFAULT``` make command variable can be used to define the device that will be used as the default network device. The value of this variable must match the name of the driver module for this network device. If ```NETDEV_DEFAULT``` is not defined, the ```mrf24j40```  module is used as default network device.
+- [mrf24j40](https://riot-os.org/api/group__drivers__mrf24j40.html) (driver for Microchip MRF24j40 based IEEE 802.15.4
+- [enc28j60](https://riot-os.org/api/group__drivers__enc28j60.html) (driver for Microchip ENC28J60 based Ethernet modules)
 
 ### <a name="esp8266_using_mrf24j40"> Using MRF24J40 (module ```mrf24j40```) </a> &nbsp;[[TOC](#esp8266_toc)]
 
-To use MRF24J40 based IEEE 802.15.4 modules as network device, module ```mrf24j40``` has to be added to a makefile:
+To use MRF24J40 based IEEE 802.15.4 modules as network device, the ```mrf24j40``` driver module has to be added to the makefile of the application:
 
 ```
 USEMODULE += mrf24j40
 ```
 
-@note If module ```netdev_default``` is used (which is usually the case in all networking applications), module ```mrf24j40``` is added automatically.
-
-Module ```mrf24j40``` uses the following interface parameters by default:
+The ```mrf24j40``` driver module uses the following preconfigured interface parameters for ESP8266 boards:
 
 <center>
 
 Parameter              | Default      | Remarks
 -----------------------|--------------|----------------------------
-MRF24J40_PARAM_SPI     | SPI_DEV(0)   | fix, see section [SPI Interfaces](#esp8266_spi_interfaces)
-MRF24J40_PARAM_SPI_CLK | SPI_CLK_1MHZ | fix
+MRF24J40_PARAM_SPI     | SPI_DEV(0)   | fixed, see section [SPI Interfaces](#esp8266_spi_interfaces)
+MRF24J40_PARAM_SPI_CLK | SPI_CLK_1MHZ | fixed
 MRF24J40_PARAM_CS      | GPIO16       | can be overridden
 MRF24J40_PARAM_INT     | GPIO0        | can be overridden
 MRF24J40_PARAM_RESET   | GPIO2        | can be overridden
 
 </center><br>
 
-Used GPIOs can be overridden by corresponding make command variables, e.g,:
-```
-make flash BOARD=esp8266-esp-12x -C examples/gnrc_networking MRF24J40_PARAM_CS=GPIO15
-```
-or by an [application-specific board configuration](#esp8266_application_specific_board_configuration).
+The GPIOs in this configuration can be overridden by [application-specific board configurations](#esp8266_application_specific_board_configuration).
 
 ### <a name="esp8266_using_enc28j60"> Using ENC28J60 (module ```enc28j60```) </a> &nbsp;[[TOC](#esp8266_toc)]
 
-To use ENC28J60 Ethernet modules as network device, module ```enc28j60``` has to be added to your makefile:
+To use ENC28J60 Ethernet modules as network device, the ```enc28j60``` driver module has to be added to the makefile of the application:
 
 ```
 USEMODULE += enc28j60
 ```
 
-Module ```enc28j60``` uses the following interface parameters by default:
+The ```enc28j60``` driver module uses the following preconfigured interface parameters for ESP8266 boards:
 
 <center>
 
 Parameter            | Default      | Remarks
 ---------------------|--------------|----------------------------
-ENC28J60_PARAM_SPI   | SPI_DEV(0)   | fix, see section [SPI Interfaces](#esp8266_spi_interfaces)
+ENC28J60_PARAM_SPI   | SPI_DEV(0)   | fixed, see section [SPI Interfaces](#esp8266_spi_interfaces)
 ENC28J60_PARAM_CS    | GPIO4        | can be overridden
 ENC28J60_PARAM_INT   | GPIO9        | can be overridden
 ENC28J60_PARAM_RESET | GPIO10       | can be overridden
 
 </center>
 
-Used GPIOs can be overridden by corresponding make command variables, e.g.:
-```
-make flash BOARD=esp8266-esp-12x -C examples/gnrc_networking ENC28J60_PARAM_CS=GPIO15
-```
-or by an [application-specific board configuration](#esp8266_application_specific_board_configuration).
-
-To use module ```enc28j60``` as default network device, the ```NETDEV_DEFAULT``` make command variable has to set, for example:
-```
-make flash BOARD=esp8266-esp-12x -C examples/gnrc_networking NETDEV_DEFAULT=enc28j60
-```
+The GPIOs in this configuration can be overridden by [application-specific board configurations](#esp8266_application_specific_board_configuration).
 
 ## <a name="esp8266_sd_card_device"> SD-Card Device </a> &nbsp;[[TOC](#esp8266_toc)]
 
-ESP8266 port of RIOT is preconfigured for RIOT applications that use the [SPI SD-Card driver](http://riot-os.org/api/group__drivers__sdcard__spi.html). To use SPI SD-Card driver, the ```sdcard_spi``` module has to be added to a makefile:
+ESP8266 port of RIOT is preconfigured for RIOT applications that use the [SPI SD-Card driver](https://riot-os.org/api/group__drivers__sdcard__spi.html). To use SPI SD-Card driver, the ```sdcard_spi``` module has to be added to a makefile:
 
 ```
 USEMODULE += sdcard_spi
 ```
 
-Module ```sdcard_spi``` uses the following interface parameters by default:
+The ```sdcard_spi``` driver module uses the following preconfigured interface parameters for ESP8266 boards:
 
 <center>
 
@@ -646,22 +640,19 @@ SDCARD_SPI_PARAM_CS    | SPI0_CS0_GPIO | can be overridden
 
 </center>
 
-The GPIO used as CS signal can be overridden by an [application-specific board configuration](#esp8266_application_specific_board_configuration).
+The GPIO used as CS signal can be overridden by [application-specific board configurations](#esp8266_application_specific_board_configuration).
 
+
+\anchor esp8266_app_spec_conf
 # <a name="esp8266_application_specific_configurations"> Application-Specific Configurations </a> &nbsp;[[TOC](#esp8266_toc)]
 
-Configuration used for peripheral devices and for device driver modules, such as GPIO pins, bus interfaces or bus speeds are typically defined in the board-specific configurations ```board.h``` and ```periph_conf.h``` or in the driver parameter configuration ```< driver>_params.h```. Most of these definitions are enclosed by
-```
-#ifndef ANY_PARAMETER
-...
-#endif
-```
-constructs, so it is possible to override them by defining them in front of these constructs.
+The board-specific configuration files ```board.h``` and ```periph_conf.h``` as well as the driver parameter configuration files ```<driver>_params.h``` define the default configurations for peripherals and device driver modules. These are, for example, the GPIOs used, bus interfaces used or available bus speeds. Because there are many possible configurations and many different application requirements, these default configurations are usually only a compromise between different requirements.
+
+Therefore, it is often necessary to change some of these default configurations for individual applications. For example, while many PWM channels are needed in one application, another application does not need PWM channels, but many ADC channels.
 
-\anchor esp8266_app_spec_conf
 ## <a name="esp8266_application_specific_board_configuration"> Application-Specific Board Configuration </a> &nbsp;[[TOC](#esp8266_toc)]
 
-To override standard board configurations, simply create an application-specific board configuration file ```$APPDIR/board.h``` in the source directory of the application ```$APPDIR``` and add the definitions to be overridden. To force the preprocessor to include board's original ```board.h``` after that, add the ```include_next``` preprocessor directive as the **last** line.
+To override default board configurations, simply create an application-specific board configuration file ```$APPDIR/board.h``` in the source directory ```$APPDIR``` of the application and add the definitions to be overridden. To force the preprocessor to include board's original ```board.h``` after that, add the ```include_next``` preprocessor directive as the <b>last</b> line.
 
 For example to override the default definition of the GPIOs that are used as PWM channels, the application-specific board configuration file ```$APPDIR/board.h``` could look like the following:
 ```
@@ -672,24 +663,25 @@ For example to override the default definition of the GPIOs that are used as PWM
 #include_next "board.h"
 ```
 
-To make such application-specific board configurations dependent on the ESP8266 MCU or a particular ESP8266 card, you should always enclose these definitions in the following constructs:
+It is important to ensure that the application-specific board configuration ```$APPDIR/board.h``` is included first. Insert the following line as the <b>first</b> line to the application makefile ```$APPDIR/Makefile```.
+```
+INCLUDES += -I$(APPDIR)
+```
+
+@note To make such application-specific board configurations dependent on the ESP8266 MCU or a particular ESP8266 board, you should always enclose these definitions in the following constructs
 ```
 #ifdef CPU_ESP8266
 ...
 #endif
 
-#ifdef BOARD_ESP8266_ESP_12X
+#ifdef BOARD_ESP8266_ESP-12X
 ...
 #endif
 ```
-To ensure that the application-specific board configuration ```$APPDIR/board.h``` is included first, insert the following line as the **first** line to the application makefile ```$APPDIR/Makefile```.
-```
-INCLUDES += -I$(APPDIR)
-```
 
 ## <a name="esp8266_application_specific_driver_configuration"> Application-Specific Driver Configuration </a> &nbsp;[[TOC](#esp8266_toc)]
 
-Using the approach for overriding board configurations, the parameters of drivers that are typically defined in ```drivers/<device>/include/<device>_params.h``` can also be overridden. For that purpose just create an application-specific driver parameter file ```$APPDIR/<device>_params.h``` in the source directory ```$APPDIR``` of the application and add the definitions to be overridden. To force the preprocessor to include driver's original ```<device>_params.h``` after that, add the ```include_next``` preprocessor directive as the **last** line.
+Using the approach for overriding board configurations, the parameters of drivers that are typically defined in ```drivers/<device>/include/<device>_params.h``` can be overridden. For that purpose just create an application-specific driver parameter file ```$APPDIR/<device>_params.h``` in the source directory ```$APPDIR``` of the application and add the definitions to be overridden. To force the preprocessor to include driver's original ```<device>_params.h``` after that, add the ```include_next``` preprocessor directive as the <b>last</b> line.
 
 For example, to override a GPIO used for LIS3DH sensor, the application-specific driver parameter file ```$APPDIR/<device>_params.h``` could look like the following:
 ```
@@ -699,20 +691,22 @@ For example, to override a GPIO used for LIS3DH sensor, the application-specific
 
 #include_next "lis3dh_params.h"
 ```
-To make such application-specific board configurations dependent on the ESP8266 MCU or a particular ESP8266 card, you should always enclose these definitions in the following constructs:
+
+It is important to ensure that the application-specific driver parameter file ```$APPDIR/<device>_params.h``` is included first. Insert the following line as the <b>first</b> line to the application makefile ```$APPDIR/Makefile```.
+```
+INCLUDES += -I$(APPDIR)
+```
+
+**Pleae note:** To make such application-specific board configurations dependent on the ESP8266 MCU or a particular ESP8266 board, you should always enclose these definitions in the following constructs:
 ```
 #ifdef CPU_ESP8266
 ...
 #endif
 
-#ifdef BOARD_ESP8266_ESP_12X
+#ifdef BOARD_ESP8266_ESP-12X
 ...
 #endif
 ```
-To ensure that the application-specific driver parameter file ```$APPDIR/<device>_params.h``` is included first, insert the following line as the **first** line to the application makefile ```$APPDIR/Makefile```.
-```
-INCLUDES += -I$(APPDIR)
-```
 
 # <a name="esp8266_sdk_task_handling"> SDK Task Handling </a> &nbsp;[[TOC](#esp8266_toc)]
 
@@ -728,7 +722,7 @@ In the RIOT port, the task management of the SDK is replaced by the task managem
 
 When QEMU mode is enabled (```QEMU=1```), instead of loading the image to the target hardware, a binary image ```$ELFFILE.bin``` is created in the target directory. This binary image file can be used together with QEMU to debug the code in GDB.
 
-The binary image can be compiled with debugging information (```ENABLE_GDB=1```) or optimized without debugging information (```ENABLE_GDB=0```). The latter one is the default. The version with debugging information can be debugged in source code while the optimized version can only be debugged in assembler mode.
+The binary image can be compiled with debugging information (```ENABLE_GDB=1``` or module ```esp_gdb```) or optimized without debugging information (```ENABLE_GDB=0```). The latter one is the default. The version with debugging information can be debugged in source code while the optimized version can only be debugged in assembler mode.
 
 To use QEMU, you have to install QEMU for Xtensa with ESP8266 machine implementation as following.
 
@@ -765,4 +759,5 @@ To start debugging, you have to connect to QEMU with command:
 ```
 (gdb) target remote :1234
 ```
+
 */
diff --git a/cpu/esp8266/include/irq_arch.h b/cpu/esp8266/include/irq_arch.h
index f0e3c7020e..4a15c8c6bf 100644
--- a/cpu/esp8266/include/irq_arch.h
+++ b/cpu/esp8266/include/irq_arch.h
@@ -38,7 +38,7 @@ extern uint32_t irq_interrupt_nesting;
 
 #if defined(MODULE_ESP_SDK_INT_HANDLING) || defined(DOXYGEN)
 /**
- * @brief   Macros that have to be used on entry into and reset from an ISR
+ * @brief   Macros that have to be used on entry into and exit from an ISR
  *
  * NOTE: since they use a local variable they can be used only in same function
  * @{
-- 
GitLab