rtos/freertos/doc/lib/platform.txt

/**
@mainpage
@anchor platform
@brief The platform layer provides portability across different operating systems. <br><br>

All system calls (including networking) used in this SDK's libraries go through a lightweight platform layer. The functions of the platform layer are intended to be easily implementable on a wide variety of operating systems. The current platform layer has the following components:
- @ref platform_clock <br>
  @copybrief platform_clock
- @ref platform_threads <br>
  @copybrief platform_threads
- @ref platform_network <br>
  @copybrief platform_network
- @ref platform_metrics <br>
  <i>Only used by [Device Defender](@ref defender); does not need to be ported if not using Defender.</i> <br>
  @copybrief platform_metrics <br>
- @ref platform_atomic <br>
  @copybrief platform_atomic

Currently, implementations exist for the following platforms:
Component                   | Supported platforms
---------                   | -------------------
@ref platform_clock         | [FreeRTOS Software Timers](https://www.freertos.org/RTOS-software-timer.html)
@ref platform_threads       | [FreeRTOS Semaphores](https://www.freertos.org/Inter-Task-Communication.html) + [FreeRTOS Tasks](https://www.freertos.org/a00015.html)
@ref platform_network       | [Berkeley sockets](https://en.wikipedia.org/wiki/Berkeley_sockets)
@ref platform_metrics       | Sample implementation using [Berkeley sockets](https://en.wikipedia.org/wiki/Berkeley_sockets). <br> This implementation is not intended for production use.
@ref platform_atomic        | [FreeRTOS Kernel Control](https://www.freertos.org/a00020.html)
*/

/**
@config_page{platform}
@config_brief{platform layer}

@section IOT_LOG_LEVEL_PLATFORM
@brief Set the log level of all platform components except the [networking component](@ref platform_network).

This setting overrides @ref IOT_LOG_LEVEL_GLOBAL for the platform layer components that it affects. All log messages with a level at or below this setting will be printed. The [platform networking component](@ref platform_network) is generally more verbose than others, so its logging is controlled separately by @ref IOT_LOG_LEVEL_NETWORK.

@configpossible One of the @ref logging_constants_levels.<br>
@configdefault @ref IOT_LOG_LEVEL_GLOBAL; if that is undefined, then #IOT_LOG_NONE.

@section IOT_LOG_LEVEL_NETWORK
@brief Set the log level of the [platform networking component](@ref platform_network).

This setting overrides @ref IOT_LOG_LEVEL_GLOBAL for the [platform networking component](@ref platform_network). All log messages with a level at or below this setting will be printed. See @ref IOT_LOG_LEVEL_PLATFORM to set the log level of other platform components.

@configpossible One of the @ref logging_constants_levels.<br>
@configdefault @ref IOT_LOG_LEVEL_GLOBAL; if that is undefined, then #IOT_LOG_NONE.

@section platform_config_memory Memory allocation
@brief Memory allocation function overrides for the platform layer.

Some platform layers are not affected by @ref IOT_STATIC_MEMORY_ONLY. Currently, the following platform implementations require memory allocation:
- POSIX <br>
  This implementation is not affected by @ref IOT_STATIC_MEMORY_ONLY. However, its memory allocation functions may be overridden by setting the following constants. All memory allocation functions must have the same signatures as [malloc](http://pubs.opengroup.org/onlinepubs/9699919799/functions/malloc.html) and [free](http://pubs.opengroup.org/onlinepubs/9699919799/functions/free.html).
  - `IotThreads_Malloc` and `IotThreads_Free`.
  - `IotNetwork_Malloc` and `IotNetwork_Free`.
*/

/**
@page platform_clock Clock
@brief @copybrief iot_clock.h

The platform clock component provides other libraries with functions relating to timers and clocks. It interfaces directly with the operation system to provide:
- Clocks for reading the current time.
- Timers that create a notification thread when they expire.

@dependencies_section{platform_clock}
@dependencies_brief{platform clock component}

@dot "Clock direct dependencies"
digraph clock_dependencies
{
    node[shape=box, fontname=Helvetica, fontsize=10, style=filled];
    edge[fontname=Helvetica, fontsize=10];
    subgraph { rank=min; logging[label="Logging", fillcolor="#aed8a9ff" URL="@ref logging"]; }
    subgraph
    {
        platform_clock[label="Clock", fillcolor="#e89025ff"];
    }
    subgraph
    {
        rank = same;
        rankdir = LR;
        operating_system[label="Operating system", fillcolor="#999999ff"]
        standard_library[label="Standard library\nstdbool, stddef, stdint", fillcolor="#d15555ff"];
    }
    platform_clock -> operating_system;
    platform_clock -> standard_library;
    platform_clock -> logging [label=" if logging enabled", style="dashed"];
}
@enddot

Currently, the platform clock component has the following dependencies:
- The operating system must provide the necessary APIs to implement the clock component's functions.
- The logging library may be used if @ref IOT_LOG_LEVEL_PLATFORM is not #IOT_LOG_NONE.
*/

/**
@page platform_threads Thread Management
@brief @copybrief iot_threads.h

The platform thread management component provides other libraries with functions relating to threading and synchronization. It interfaces directly with the operating system to provide:
- A function to create new threads.
- Synchronization mechanisms such as [mutexes](@ref IotMutex_t) and [counting semaphores](@ref IotSemaphore_t).

@dependencies_section{platform_threads}
@dependencies_brief{platform thread management component}

@dot "Thread management direct dependencies"
digraph threads_dependencies
{
    node[shape=box, fontname=Helvetica, fontsize=10, style=filled];
    edge[fontname=Helvetica, fontsize=10];
    subgraph { rank=min; logging[label="Logging", fillcolor="#aed8a9ff" URL="@ref logging"]; }
    subgraph
    {
        platform_threads[label="Thread management", fillcolor="#e89025ff"];
    }
    subgraph
    {
        rank = same;
        operating_system[label="Operating system", fillcolor="#999999ff"]
        standard_library[label="Standard library\nstdbool, stddef, stdint", fillcolor="#d15555ff"];
    }
    platform_threads -> operating_system;
    platform_threads -> standard_library;
    platform_threads -> logging [label=" if logging enabled", style="dashed"];
}
@enddot

Currently, the platform thread management component has the following dependencies:
- The operating system must provide the necessary APIs to implement the [thread management functions](@ref platform_threads_functions).
- The logging library may be used if @ref IOT_LOG_LEVEL_PLATFORM is not #IOT_LOG_NONE.
*/

/**
@page platform_network Networking
@brief @copybrief iot_network.h

The platform networking component provides other libraries with an abstraction for interacting with the network through an #IotNetworkInterface_t. Libraries that require the network will request an #IotNetworkInterface_t as a parameter and use those function pointers to access the network. This allows libraries to use different network stacks simultaneously.

@dependencies_section{platform_network}
@dependencies_brief{platform networking component}

@dot "Networking direct dependencies"
digraph network_dependencies
{
    node[shape=box, fontname=Helvetica, fontsize=10, style=filled];
    edge[fontname=Helvetica, fontsize=10];
    subgraph { rank=min; logging[label="Logging", fillcolor="#aed8a9ff", URL="@ref logging"]; }
    subgraph
    {
        rank = same;
        platform_network[label="Networking", fillcolor="#e89025ff"];
    }
    subgraph
    {
        rank = same;
        rankdir = LR;
        operating_system[label="Operating system", fillcolor="#999999ff"];
        security_library[label="Security library", fillcolor="#999999ff"];
        standard_library[label="Standard library", fillcolor="#d15555ff"];
    }
    platform_network -> operating_system;
    platform_network -> security_library [label=" secured connection", style="dashed"];
    platform_network -> standard_library;
    platform_network -> logging [label=" if logging enabled", style="dashed"];
    security_library -> operating_system;
}
@enddot

Functions should be implemented against the system's network stack to match the signatures given in an #IotNetworkInterface_t.
- The operating system must provide the necessary networking APIs, such as a sockets API.
- A third-party security library is needed to encrypt secured connections.
- The logging library may be used if @ref IOT_LOG_LEVEL_PLATFORM is not @ref IOT_LOG_NONE.
*/

/**
@page platform_metrics Metrics
@brief @copybrief iot_metrics.h

Device Defender reports metrics to monitor devices. This component of the platform layer is only required by Device Defender. It does not need to be implemented if Device Defender is not used.

@dependencies_section{platform_metrics}
@dependencies_brief{platform metrics component}
@dot "Metrics direct dependencies"
digraph metrics_dependencies
{
    node[shape=box, fontname=Helvetica, fontsize=10, style=filled];
    edge[fontname=Helvetica, fontsize=10];
    subgraph
    {
        platform_metrics[label="Metrics", fillcolor="#e89025ff"];
    }
    subgraph
    {
        rank = same;
        rankdir = LR;
        operating_system[label="Operating system", fillcolor="#999999ff"]
        standard_library[label="Standard library\nstdbool, stddef, stdint", fillcolor="#d15555ff"];
    }
    platform_metrics -> operating_system;
    platform_metrics -> standard_library;
}
@enddot

The platform metrics component is meant to query its data directory from the operating system.

@note Platform metrics implementations are generally not portable, since they depend on non-portable operating system APIs. Because maintaining OS-specific implementations is beyond the scope of this SDK, the provided metrics implementation is a sample that calls in to other platform components, instead of the operating system.
*/

/**
@page platform_atomic Atomics
@brief Atomic operations: small inlined functions used for atomically manipulating memory.

The platform atomic component provides lock-free and wait-free mutually exclusive access to a memory location.

Unlike the other components of the platform layer, which rely on APIs provided by the host operating system, the atomic component relies on facilities provided by compilers. Many compilers, particularly recent versions that support C11 atomic features, provide compiler intrinsics for atomic operations. 

FreeRTOS ported atomic.h provides a generic implementation. Compiler/architecture dependent implementation of atomic.h is to be provided under each port directory.

@dependencies_section{platform_atomic}
@dependencies_brief{platform atomics component}
@dot "Atomics direct dependencies"
digraph atomic_dependencies
{
    node[shape=box, fontname=Helvetica, fontsize=10, style=filled];
    edge[fontname=Helvetica, fontsize=10];
    subgraph
    {
        platform_atomic[label="Atomics", fillcolor="#e89025ff"];
    }
    subgraph
    {
        rank = same;
        rankdir = LR;
        compiler[label="Compiler", fillcolor="#999999ff"]
    }
    platform_atomic -> compiler;
}
@enddot
*/

/**
@handles_group{platform}
@handles_brief{platform layer}
@enums_group{platform}
@enums_brief{platform layer}
@paramstructs_group{platform}
@paramstructs_brief{platform, platform layer}
*/

/**
@functions_page{platform, platform layer}
@functions_brief{platform layer}
- @subpage platform_clock_functions <br>
  @copybrief platform_clock_functions
- @subpage platform_network_functions <br>
  @copybrief platform_network_functions
- @subpage platform_threads_functions <br>
  @copybrief platform_threads_functions
- @subpage platform_metrics_functions <br>
  @copybrief platform_metrics_functions
- @subpage platform_atomic_functions <br>
  @copybrief platform_atomic_functions
*/