Documentation: add top-level information to README.md

Author: RobertRostohar

Documentation/Overview.md

@@ -1,15 +1,26 @@
-# MDK-Middleware Documentation
+# MDK-Middleware
 
-Middleware Documentation in HTML format is published online at [https://arm-software.github.io/MDK-Middeware](https://arm-software.github.io/MDK-Middleware).
+The MDK-Middleware software pack contains components for IPv4 and IPv6 networking, USB Host and Device communication, as well as file system for data storage. It is restricted for commercial free-of-charge usage with Arm-based devices.
 
-The version drop-down menu in the "Overview" book allows to switch between the documentation provided with official releases and the latest draft documentation for the main branch.
+![MDK-Middleware](./MDK-Middleware.png)
 
-The documentation source is maintained in `/Documentation/Doxygen/` folder as a mixture of markdown and doxygen formats. Software source and header files, templates and examples may also contribute information that gets integrated into the final documentation.
+The MDK-Middleware can be used by any user application. It is used by the [Synchronous Data Streaming Framework](https://github.com/ARM-software/SDS-Framework) to save data recorded from sensors. IoT Connectors can use the *Network* component to connect to the Internet.
 
-Generating the HTML-formatted documentation from the source is done with `gen_doc.sh` script:
+MDK-Middleware uses a CMSIS-RTOS2-based real-time operating system for task scheduling, for example [Keil RTX5](https://github.com/ARM-software/CMSIS-RTX) or [CMSIS-FreeRTOS](https://github.com/arm-software/CMSIS-freertos).
 
-```sh
-MDK-Middleware $ ./Documentation/Doxygen/gen_doc.sh
-```
+The *Network* component uses the [Arm Mbed TLS](https://www.keil.com/pack/ARM.mbedTLS.3.1.0.pack) stack to secure the TCP/IP communication. [CMSIS-Drivers](https://arm-software.github.io/CMSIS_6/latest/Driver/index.html) are a required for the components to work with the underlying hardware.
 
-The script expects specific version of [doxygen](https://www.doxygen.nl/) to be installed locally. After successful execution the resulting documentation package is then available in `./Documentation/html/`.
+The [CMSIS-Compiler](https://github.com/arm-software/cmsis-compiler) and [CMSIS-View](https://github.com/arm-software/cmsis-view) components can display events and static information from all MDK-Middleware components.
+
+The software components that are part of this [CMSIS-Pack](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/index.html) are:
+
+- **File System Component**: create, save, read, and modify files in storage devices such as RAM, Flash, SD/SDHC/MMC memory cards, or USB memory devices.
+- **Network Component**: services, protocol sockets, and physical communication interfaces for creating networking applications. It supports both, IPv4 and IPv6.
+- **USB Component**: create USB Device and USB Host applications with standard USB device classes.
+
+> *Note:*  
+> Each component is configurable for a wide range of applications and requires the driver interface as described by the [CMSIS-Driver standard](https://arm-software.github.io/CMSIS_6/latest/Driver/index.html). Check with your silicon vendor about the availability of CMSIS-Drivers for your selected microcontroller device.
+
+## Availability
+
+The MDK-Middleware is available free-of-charge to all users of Arm Cortex-M-based processors. It does not require a specific toolchain or IDE license and can be built with major toolchains, such as Arm Compiler 6, GCC, and LLVM.

Documentation/README.md

@@ -2,7 +2,7 @@
 <package schemaVersion="1.7.36" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/v1.7.36/schema/PACK.xsd">
   <vendor>Keil</vendor>
   <name>MDK-Middleware</name>
-  <description overview="Documentation/Overview.md">Middleware for Arm based processors</description>
+  <description overview="Documentation/README.md">Middleware for Arm based processors</description>
   <url>https://www.keil.com/pack/</url>
   <license>license_terms/license_agreement.txt</license>
   <licenseSets>

Keil.MDK-Middleware.pdsc

@@ -1 +1,72 @@
+[![Version](https://img.shields.io/github/v/release/arm-software/MDK-Middleware)](https://github.com/ARM-software/MDK-Middleware/releases/latest)
+
 # MDK-Middleware
+
+This is the development repository of the [Keil MDK-Middleware](https://www.keil.arm.com/packs/mdk-middleware-keil) Version 8. MDK-Middleware uses the [CMSIS](https://arm-software.github.io/CMSIS_6/main/General/index.html) software framework and can be compiled with various toolchains such as Arm Compiler 6, GCC, IAR, and LLVM.
+
+## Useful Links
+
+- [Documentation](https://arm-software.github.io/MDK-Middleware/latest/General/index.html) - access to MDK-Middleware user's manual.
+- [Raise Issues](https://github.com/ARM-software/MDK-Middleware/issues) - to provide feedback or report problems.
+
+## Software Pack
+
+The MDK-Middleware is released as [CMSIS software pack](https://www.keil.arm.com/packs/mdk-middleware-keil/versions/) and therefore accessible by CMSIS-Pack enabled software development tools. The pack is compatible with tools such as [µVision 5.40](https://www.keil.arm.com/#km6-pro-tools) and the [CMSIS-Pack Management for Eclipse](https://github.com/ARM-software/cmsis-pack-eclipse). Examples utilize new features of the [CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/cmsis-toolbox) and the VS Code integration.
+
+The MDK-Middleware is annotated for the [CMSIS-View](https://arm-software.github.io/CMSIS-View/latest/index.html) Event Recorder and Component Viewer and uses [CMSIS-Compiler](https://arm-software.github.io/CMSIS-Compiler/main/index.html) for retargeting of standard C run-time library functions. It works therefore with the following other software packs:
+
+- [ARM::CMSIS](https://www.keil.arm.com/packs/cmsis-arm) version 5.9.0 or higher.
+- [ARM::CMSIS-Compiler](https://www.keil.arm.com/packs/cmsis-compiler-arm) version 2.0.0 or higher.
+- [ARM::CMSIS-View](https://www.keil.arm.com/packs/cmsis-view-arm) version 1.0.0 or higher.
+
+The MDK-Middleware examples use the *csolution project* format of the [CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/cmsis-toolbox) and are framed as [Reference Applications](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/ReferenceApplications.md) that require an additional software layer to run on an evaluation board. The CMSIS-Toolbox is developed under the [Open-CMSIS-Pack project](https://github.com/Open-CMSIS-Pack) and an integral part of several IDEs.
+
+### Using the development repository
+
+This development repository of the MDK-Middleware can be used in a local directory and [mapped as software pack](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/build-tools.md#install-a-repository) using for example `cpackget` with:
+
+    packget add <path>/Keil.MDK-Middleware.pdsc
+
+### Generate software pack
+
+The software pack is generated using bash shell scripts.
+
+- `./gen_pack.sh` (provided via [Open-CMSIS-Pack/gen-pack](
+https://github.com/Open-CMSIS-Pack/gen-pack)) generates the software pack. Run this script locally with:
+
+      MDK-Middleware $ ./gen_pack.sh
+
+- `./Documentation/Doxygen/gen_doc.sh` generates the HTML documentation from the input in the folder `/Documentation/Doxygen/`. Run this script locally with:
+
+      MDK-Middleware $ ./Documentation/Doxygen/gen_doc.sh
+
+### GitHub Actions
+
+The repository uses GitHub Actions to generate the pack, publish documentation, and verify reference applications:
+
+- `.github/workflows/pack.yml` based on [Open-CMSIS-Pack/gen-pack-action](https://github.com/Open-CMSIS-Pack/gen-pack-action) generates pack and documentation using the [Generate software pack](#generate-software-pack) scripts.
+
+- `.github/workflows/gh-pages.yml` publishes the documentation to [arm-software.github.io/MDK-Middleware](https://arm-software.github.io/MDK-Middleware/latest/General/index.html). The version drop-down selects previous documentation releases.
+
+- `.github/workflows/build_fs.yml` is a build test for the [File System reference applications](https://github.com/ARM-software/MDK-Middleware/tree/main/Examples/FileSystem).
+
+- `.github/workflows/build_net.yml` is a build test for the [Network reference applications](https://github.com/ARM-software/MDK-Middleware/tree/main/Examples/Network).
+
+- `.github/workflows/build_usb.yml` is a build test for the [USB reference applications](https://github.com/ARM-software/MDK-Middleware/tree/main/Examples/USB).
+
+## Repository top-level structure
+
+Directory                   | Description
+:---------------------------|:--------------
+[.ci](https://github.com/ARM-software/MDK-Middleware/tree/main/.ci)                              | Build tests for components and reference applications.
+[.github/workflows](https://github.com/ARM-software/MDK-Middleware/tree/main/.github/workflows)  | [GitHub Actions](#github-actions).
+[Components](https://github.com/ARM-software/MDK-Middleware/tree/main/Components)                | Source code of MDK-Middleware components.
+[Documentation](https://github.com/ARM-software/MDK-Middleware/tree/main/Documentation)          | Doxygen source of the [documentation](https://arm-software.github.io/MDK-Middleware/latest/General/index.html).
+[Examples](https://github.com/ARM-software/MDK-Middleware/tree/main/Examples)                    | Reference applications that show the usage of MDK-Middleware.
+[license_terms](https://github.com/ARM-software/MDK-Middleware/tree/main/license_terms)          | Standard Arm Tools license with MDK-Middleware usage permission.
+
+## License
+
+The MDK-Middleware can be used free-of-charge with Arm-based devices and deployed as part of software applications. Refer to [redistributables.txt](https://github.com/ARM-software/MDK-Middleware/blob/main/license_terms/redistributables.txt) for more information.
+
+Users of the [MDK-Professional or MDK-Essential edition](https://www.keil.arm.com/keil-mdk/#mdk-v6-editions) are entitled to contact Arm for support and maintenance.