Porting header changes

Author: iriark01

docs/porting/connectivity/NetworkStack.md

@@ -1,4 +1,4 @@
-## NetworkStack
+# NetworkStack
 
 As explained in the [IP networking architecture](../reference/ip-networking.html) page, the [Socket API](../apis/network-socket.html) provides a TCP or UDP API on top of any IP based network stack. With the Socket API, you can write applications and libraries that use TCP or UDP sockets without regard to the type of IP connectivity. In addition to providing the TCP or UDP API, the Socket API includes virtual base classes for the different IP interface types.
 

docs/porting/connectivity/connectivity.md

@@ -1,8 +1,6 @@
 <h1 id="contributing-connectivity">Connectivity</h1>
 
-## The network socket API
-
-### New device
+## The network socket API - new device
 
 The NetworkSocketAPI is designed to make porting new devices as easy as possible and only requires a handful of methods for a minimal implementation.
 

docs/porting/custom-target-porting.md

@@ -4,13 +4,13 @@ When designing a custom microcontroller board to run Mbed OS, you may need to ma
 
 This tutorial covers the most common methods used to create a custom port of Mbed OS when starting from an existing Mbed Enabled board. For detailed information on how to create a port from scratch, go to the [Mbed Porting guide](../porting/index.html). Additionally, not all possible aspects of target configuration are covered. For detailed information on all the ways you can configure targets, go to [adding and configuring targets](../reference/adding-and-configuring-targets.html).
 
-# Extending an existing MCU target configuration
+## Extending an existing MCU target configuration
 
-Consider a situation in which you are creating a new board based on an existing Mbed Enabled board. This tutorial lists the steps to create the software for a new board we will call `ImaginaryBoard`. This board is based on [DISCO-L475VG-IOT01A](https://os.mbed.com/platforms/ST-Discovery-L475E-IOT01A/). It shares most of the features of DISCO-L475VG-IOT01A, but it does not use `AnalogOut`, `AnalogIn`, `CAN` or `USB`. Some pins are connected differently on the new board. 
+Consider a situation in which you are creating a new board based on an existing Mbed Enabled board. This tutorial lists the steps to create the software for a new board we will call `ImaginaryBoard`. This board is based on [DISCO-L475VG-IOT01A](https://os.mbed.com/platforms/ST-Discovery-L475E-IOT01A/). It shares most of the features of DISCO-L475VG-IOT01A, but it does not use `AnalogOut`, `AnalogIn`, `CAN` or `USB`. Some pins are connected differently on the new board.
 
 Follow these steps to create a custom port for Mbed OS:
 
-## Preparing
+### Preparing
 
 1. [Install Mbed CLI](../tools/installation-and-setup.html) if you don't already have it.
 
@@ -21,22 +21,22 @@ Follow these steps to create a custom port for Mbed OS:
    ```
    mbed new --program mbed-os-imaginary-port
    ```
-   
+
    This command creates a new program folder called `mbed-os-imaginary-port` and then imports `mbed-os` from the [official Mbed OS source repository](https://github.com/armmbed/mbed-os) into it.
 
 1. Change directories into your new project:
 
    ```
    cd mbed-os-imaginary-port
    ```
-   
+
 1. Create a new file named `custom_targets.json` at the same level as the `mbed-os` directory.
 
 1. Inspect the contents of `mbed-os/targets/targets.json`. For this example, search for `DISCO_L475VG_IOT01A`.
 
 1. Copy the contents from the `DISCO_L475VG_IOT01A` section into your `custom_targets.json` file. Be sure to include brackets `{ }` surrounding the content.
 
-## Customizing
+### Customizing
 
 1. Make changes to `custom_targets.json` for your board.
 
@@ -48,7 +48,7 @@ Follow these steps to create a custom port for Mbed OS:
    1. The `device_has_add` section changes to remove the `ANALOGOUT`, `CAN`, and `USBDEVICE` drivers because the new board doesn't use those features.
 
    After making changes, the full contents look like this:
-   
+
    ```
    {
      "IMAGINARYBOARD": {
@@ -92,11 +92,11 @@ Follow these steps to create a custom port for Mbed OS:
    }
    ```
 
-### Additions
+#### Additions
 
 A new section, `device_has_remove`, was added. This removes the `ANALOGIN`, `I2CSLAVE` and `I2C_ASYNCH` drivers because these features are also not used. The reason why `device_has_remove` is used in this case is because the board is inheriting from the MCU Family configuration `FAMILY_STM32`, which has those drivers added by default.
 
-### Other possible additions 
+#### Other possible additions
 
 Other changes you may need include:
 
@@ -105,11 +105,11 @@ Other changes you may need include:
 
    <span class="notes">**Note:** If you choose to add a driver that is not already available for your hardware, you will have to provide the driver implementation.</span>
 
-### Where other configurations live 
+#### Where other configurations live
 
 All the other configurations for the board are inherited from the MCU Family configuration called `FAMILY_STM32`.
 
-# Configuring the target code directories
+## Configuring the target code directories
 
 In some cases, the target source code directories follow a similar structure to the target configuration, but they could have a few more levels.
 
@@ -128,43 +128,43 @@ Boards typically inherit files that support the MCU, MCU family and MCU vendor.
 
 There are more directory levels than target configuration levels because many targets use the `extra_labels_add` feature in the target configuration. The keywords `STM32L4`, `STM32L475xG` and `STM32L475VG` resolve to `TARGET_STM32L4`, `TARGET_STM32L475xG` and `TARGET_STM32L475VG`, respectively. With those labels applied, the build includes these directory names for this target.
 
-## Preparing
+### Preparing
 
 1. Create a new directory called `TARGET_IMAGINARYBOARD` at the top level of your project to store the source files for your board.
-      
+
 1. Inspect the files at `mbed-os\targets\TARGET_STM\TARGET_STM32L4\TARGET_STM32L475xG\TARGET_DISCO_L475VG_IOT01A`. You should find the following files or similar:
-   
+
    `PeripheralNames.h`, `PeripheralPins.c`, `PinNames.h`, `system_clock.c`
-   
+
 1. Copy the files into your new `TARGET_IMAGINARYBOARD` directory.
-   
+
    The files provide these capabilities:
-      
+
    - `PeripheralNames.h` describes the available peripherals and their base addresses.
    - `PeripheralPins.c` describes the available pins and their association with peripherals.
    - `PinNames.h` sets macros for pins that define their function.
    - `system_clock.c` vendor specific file that initializes the system and sets up the clocks.
 
-## Customizing
-      
+### Customizing
+
 1. Modify the files.
 
    `PinNames.h` is the most common file to be edited. For this tutorial, the ImaginaryBoard uses I2C but connected to different supported signals. Change the I2C pin macro definitions from:
-   
+
    ```
    I2C_SCL     = D15,
    I2C_SDA     = D14,
    ```
-   
+
    to
-   
+
    ```
    I2C_SCL     = PC_0,
    I2C_SDA     = PC_1,
    ```
-   
+
    You may also choose to add or remove peripherals, add or remove pins or change the clock frequency by editing `PeripheralNames.h`, `PeripheralPins.c`, or `system_clock.c`. For simplicity, this tutorial doesn't edit these files.
-   
+
 1. (Optional) Add additional source files for drivers or middleware you have implemented for the new board. This tutorial doesn't have any files to add.
 
 1. (Optional) Add a simple application source file for testing.
@@ -173,7 +173,7 @@ There are more directory levels than target configuration levels because many ta
 
    ```  
    #include "mbed.h"
-   
+
    DigitalOut led1(LED1);
 
    int main()
@@ -183,12 +183,12 @@ There are more directory levels than target configuration levels because many ta
            wait_ms(500);
        }
    }
-   ``` 
-   
+   ```
+
    This blinks an LED. If `LED1` is not defined, inspect `PinNames.h` for a valid pin definition for an available LED.
-       
+
    Your directory now looks something like this:
-    
+
    ```
    main.cpp
    custom_target.json
@@ -199,60 +199,60 @@ There are more directory levels than target configuration levels because many ta
    mbed-os.lib
    ```
 
-# Testing your code 
-    
+## Testing your code
+
 1. Compile the application:
-   
+
    ```
    mbed compile -m IMAGINARYBOARD -t <toolchain>
    ```
-   
+
    When successful, it compiles, links and generates a `.bin` file (or `.hex` file for some other boards).
 
    For example, it prints to the screen:
-   
+
    ```
    Image: .\BUILD\IMAGINARYBOARD\GCC_ARM\mbed-os-imaginary-port.bin
    ```
 
 1. Program the board.
 
    You can test this using a `DISCO-L475VG-IOT01A`. If you actually created an `ImaginaryBoard` board, you could use that, too.
-  
+
    <span class="notes">**Note:** Unless your board has an Mbed Enabled debug interface, you need a method of flashing the memory on your board.</span>
-  
+
    Because the `DISCO-L475VG-IOT01A` has an Mbed Enabled debug interface (STLink in this case), you can use drag-and-drop programming to flash the board.
-  
+
 1. Locate the binary file, and drag it onto the disk drive name for the board (for example, `DIS_L4IOT`).
-  
+
 1. Wait for the file transfer to complete.
-   
+
 1. Run the application
 
    Press the reset button on the board. You should see the LED blinking.
- 
+
 1. (Optional) Run automated tests.
 
    With an Mbed Enabled debug interface, you can also run the Mbed OS automated tests on your port. Because a new board has a new name unknown to the Mbed tools, you need to tell the tools which `Platform ID` (aka `detect_code`) to associate it to.
-   
+
    To do this, you can use the `mbedls` `mock` command option. This tutorial tests with a `DISCO-L475VG-IOT01A`, which has a debug interface that exposes `0764` as its `Platform ID`. If you have a new board that uses a different `Platform ID`, such as `1234`, then use that.
-  
+
    For the `ImaginaryBoard` based on `DISCO-L475VG-IOT01A`, run this command.
 
    ```
    mbedls --mock 0764:IMAGINARYBOARD
    ```
-   
+
   <span class="notes">**Note:** If you intend to release a new target to the Mbed community, it needs a unique Platform ID. To get one, please contact your technical account manager or email [our support team](mailto:[email protected]).</span>
 
 1. Run the tests, with the following command:
-   
+
    ```
    mbed test -m IMAGINARYBOARD -t <toolchain>
    ```
-   
+
    The tests start running.
-   
+
    For more information on testing a new board, go to the [Testing your port](../porting/testing.html) section of the porting guide.
 
 Now you have successfully ported Mbed OS to a new board.

docs/porting/porting_full_process/built_in_tests.md

@@ -5,13 +5,13 @@ It's important to test your port at the end of each module porting, rather than
 1. Running the Mbed OS built-in tests with [*Greentea*](../tools/greentea-testing-applications.html).
 1. Manually running the Mbed OS built-in tests.
 
-# Testing with the Greentea framework
+## Testing with the Greentea framework
 
 Read the following page to understand how tests are structured:
 
-## Prerequisites
+### Prerequisites
 
-### Minimum HAL module support
+#### Minimum HAL module support
 
 To run the Mbed OS built-in tests, you need to have ported and verified at least these HAL modules:
 
@@ -23,7 +23,7 @@ To run the Mbed OS built-in tests, you need to have ported and verified at least
 You'll also need to have ported DAPLink or compatible interface firmware to your interface chip.
     <span class="notes">If DAPLink is still under development, you can still [run tests manually](../porting/manual-testing.html).</span>
 
-### mbedls
+#### mbedls
 
 The platform under test needs to be supported in mbedls for automated tests to work.
 
@@ -47,7 +47,7 @@ If an updated mbedls pip package including support for your platform hasn't been
 
     Where `"33000000e062afa300000000000000000000000097969902"` is the correct target id.
 
-## Compiling and running tests
+### Compiling and running tests
 
 1. Compile the tests:
     - To compile all tests, run `mbed test --compile`.

docs/porting/psa/TLS-on-PSA.md

@@ -1,14 +1,14 @@
 # Using PSA-enabled Mbed TLS
 
-# Building PSA-enabled Mbed TLS from Git
+## Building PSA-enabled Mbed TLS from Git
 
 The version of Mbed TLS shipped in Mbed OS builds with PSA enabled by default. However, you can build a PSA-enabled version of Mbed TLS from [our Git repository](https://github.com/ARMmbed/mbedtls):
 
 1. Clone the repository, switch to the `development-psa` branch and initialize the submodule: `git checkout development-psa && git submodule update --init`.
 1. Enable the `MBEDTLS_USE_PSA_CRYPTO` build-time configuration option in `include/mbedtls/config.h`, either by editing the file manually, or using the config script: `scripts/config.pl set MBEDTLS_USE_PSA_CRYPTO`.
 1. Build normally, for example (with GNU Make) make all test or (with CMake) `mkdir build && cd build && cmake .. && make all test`.
 
-# Using PSA-enabled Mbed TLS
+## Using PSA-enabled Mbed TLS
 
 If an application was built with Mbed TLS that was not PSA enabled, you can still use the application with PSA-enabled Mbed TLS by recompiling it against a PSA-enabled version of Mbed TLS. (Note that relinking is not enough, though.) In other words, PSA-enabled Mbed TLS is fully API compatible with non-PSA-enabled Mbed TLS but not ABI compatible. All existing (pre-PSA) APIs are preserved and continue to exist in parallel with PSA-based APIs.
 
@@ -18,17 +18,17 @@ If your application doesn't use any of the PSA-specific APIs described below, th
 
 If your application uses one of the PSA-specific APIs described below, then you need to change its source code because the APIs have changed in an incompatible way between Mbed OS 5.11 and Mbed OS 5.12 to reflect changes in PSA Crypto, whose API wasn't stable as of Mbed OS 5.11.
 
-# PSA-based APIs in Mbed TLS
+## PSA-based APIs in Mbed TLS
 
 As mentioned in the previous section, you can use PSA-neabled Mbed TLS to build applications that are not PSA enabled. Doing so is enough to benefit from PSA in some areas (for example, some PSA-based hardware acceleration, depending on platform support), but in other areas, changes in the application source code are necessary. This mainly means replacing calls to pre-PSA APIs with calls to their PSA-based versions.
 
 The new APIs allow using PSA-managed keys for a few purposes, such as TLS client authentication, CSR generation and TLS PSK connections. Letting the key be managed by PSA is good for security because PSA can isolate the keys from the rest of the applications (referred to below as "opaque keys"). To use such PSA-managed keys, you need to modify your code to use the new APIs as described below.
 
-# Using opaque ECDSA keys for TLS client authentication
+## Using opaque ECDSA keys for TLS client authentication
 
 This mainly involves using the new API function `mbedtls_pk_setup_opaque()` to wrap a PSA-managed key into a PK context, then using that context with the usual TLS APIs.
 
-## Application flow without PSA
+### Application flow without PSA
 
 1. At application startup, make sure `mbedtls_platform_setup()` is called if relevant.
 1. Declare (and allocate) an object of type `mbedtls_pk_context`.
@@ -37,7 +37,7 @@ This mainly involves using the new API function `mbedtls_pk_setup_opaque()` to w
 1. Use the resulting SSL configuration for TLS connections as usual.
 1. When you're done using TLS connections based on that configuration, _and no longer want to use that key for anything else_, free the PK context using `mbedtls_pk_free()`.
 
-## Application flow with PSA
+### Application flow with PSA
 
 1. At application startup, make sure `mbedtls_platform_setup()` is called if relevant, and make sure `psa_crypto_init()` is called, too.
 1. Declare (and allocate) an object of type `mbedtls_pk_context` *and an object of type `psa_key_handle_t`*.
@@ -47,11 +47,11 @@ This mainly involves using the new API function `mbedtls_pk_setup_opaque()` to w
 1. Use the resulting SSL configuration for TLS connections as usual.
 1. When you're done using TLS connections based on that configuration, free the PK context using `mbedtls_pk_free()`. This only frees the PK context itself and leaves the key handle untouched. You can either keep using the key handle or call `psa_destroy_key()` on it depending on your application flow.
 
-# Using opaque ECDSA keys to generate certificate signing requests (CSRs)
+## Using opaque ECDSA keys to generate certificate signing requests (CSRs)
 
 This mainly involves using the API function `mbedtls_pk_setup_opaque()` to wrap a PSA-managed key into a PK context, then using that context with the usual TLS APIs.
 
-## Application flow without PSA
+### Application flow without PSA
 
 1. At application startup, make sure `mbedtls_platform_setup() is called if relevant.
 1. Declare (and allocate) an object of type `mbedtls_pk_context`
@@ -60,7 +60,7 @@ This mainly involves using the API function `mbedtls_pk_setup_opaque()` to wrap
 1. Call any other function you need to configure and generate the CSR.
 1. When you're done generating the CSR, _and no longer want to use that key for anything else_, free the PK context using `mbedtls_pk_free()`.
 
-## Application flow with PSA
+### Application flow with PSA
 
 1. At application startup, make sure `mbedtls_platform_setup()` is called if relevant, and make sure `psa_crypto_init()` is called, too.
 1. Declare (and allocate) an object of type `mbedtls_pk_context` and an object of type *`psa_key_handle_t`*.
@@ -70,18 +70,18 @@ This mainly involves using the API function `mbedtls_pk_setup_opaque()` to wrap
 1. Call any other function that you need to configure and generate the CSR.
 1. When you're done generating the CSR, free the PK context using `mbedtls_pk_free()`. This only frees the PK context itself and leaves the key *handle* untouched. You can either keep using the key *handle* or call `psa_destroy_key()` on it, depending on your application flow.
 
-# Using opaque pre-shared keys with TLS PSK ciphersuites
+## Using opaque pre-shared keys with TLS PSK ciphersuites
 
 This mainly involves using the API function `mbedtls_ssl_conf_psk_opaque()` in place of `mbedtls_ssl_conf_psk()` client-side or, server-side using `mbedtls_ssl_set_hs_psk_opaque()` instead of `mbedtls_ssl_set_hs_psk()` in the PSK callback.
 
-## Application flow without PSA
+### Application flow without PSA
 
 1. At application startup, make sure `mbedtls_platform_setup()` is called if relevant.
 1. Set up an `unsigned char *` to point to a memory area holding your pre-shared key.
 1. Call `mbedtls_ssl_conf_psk()` on the SSL configuration object.
 1. Use that configuration object in TLS connections.
 
-## Application flow with PSA
+### Application flow with PSA
 
 1. At application startup, make sure `mbedtls_platform_setup()` is called if relevant, and make sure `psa_crypto_init()` is called, too.
 1. Set up a *`psa_key_handle_t`* to point to a configured slot holding your pre-shared key.