From 4d688f702b528a54242656844bec149082211146 Mon Sep 17 00:00:00 2001 From: MAY Date: Sun, 21 Sep 2025 22:43:03 +0200 Subject: [PATCH] convert .md files to .adoc file --- CONTRIBUTING.md => CONTRIBUTING.adoc | 58 ++++++++---- README.md => README.adoc | 135 +++++++++++++++------------ 2 files changed, 115 insertions(+), 78 deletions(-) rename CONTRIBUTING.md => CONTRIBUTING.adoc (79%) rename README.md => README.adoc (71%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.adoc similarity index 79% rename from CONTRIBUTING.md rename to CONTRIBUTING.adoc index 4bf9770..8698ac3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.adoc @@ -1,31 +1,48 @@ -# Contributing to Eclipse ThreadX +//// + + Copyright (c) Microsoft + Copyright (c) 2024-present Eclipse ThreadX contributors + + This program and the accompanying materials are made available + under the terms of the MIT license which is available at + https://opensource.org/license/mit. + + SPDX-License-Identifier: MIT + + Contributors: + * Frédéric Desbiens - Initial AsciiDoc version. + +//// += Contributing to Eclipse ThreadX Thanks for your interest in this project. -## Project description +== Project description Eclipse ThreadX provides a vendor-neutral, open source, safety-certified OS for real-time applications published on under a permissive license. The Eclipse ThreadX suite encompasses: -* ThreadX - advanced real-time operating system (RTOS) designed specifically for deeply embedded applications -* NetX Duo - advanced, industrial-grade TCP/IP network stack designed specifically for deeply embedded real-time and IoT applications -* FileX - high-performance, FAT-compatible file system that’s fully integrated with ThreadX kernel -* GUIX - provides a complete, embedded graphical user interface (GUI) library -* USBX - high-performance USB host, device, and on-the-go (OTG) embedded stack, that is fully integrated with ThreadX kernel -* LevelX - flash wear leveling for FileX and stand-alone purposes -* GuiX Studio - design environment, facilitating the creation and maintenance of all graphical elements for GUIX -* TraceX - analysis tool that provides a graphical view of real-time system events to better understand the behavior of real-time systems + +* ThreadX - advanced real-time operating system (RTOS) designed specifically for deeply embedded applications. +* NetX Duo - advanced, industrial-grade TCP/IP network stack designed specifically for deeply embedded real-time and IoT applications. +* FileX - high-performance, FAT-compatible file system that’s fully integrated with ThreadX kernel. +* GUIX - provides a complete, embedded graphical user interface (GUI) library. +* USBX - high-performance USB host, device, and on-the-go (OTG) embedded stack, that is fully integrated with ThreadX kernel. +* LevelX - flash wear leveling for FileX and stand-alone purposes. +* GuiX Studio - design environment, facilitating the creation and maintenance of all graphical elements for GUIX. +* TraceX - analysis tool that provides a graphical view of real-time system events to better understand the behavior of real-time systems. Project websites: + * https://threadx.io * https://projects.eclipse.org/projects/iot.threadx -## Terms of Use +== Terms of Use This repository is subject to the Terms of Use of the Eclipse Foundation https://www.eclipse.org/legal/termsofuse.php -## Developer resources +== Developer resources Information regarding source code management, builds, coding standards, and more. https://projects.eclipse.org/projects/iot.threadx/developer @@ -47,7 +64,7 @@ The project maintains the following source code repositories * https://github.com/eclipse-threadx/tracex * https://github.com/eclipse-threadx/usbx -## Eclipse Development Process +== Eclipse Development Process This Eclipse Foundation open project is governed by the Eclipse Foundation Development Process and operates under the terms of the Eclipse IP Policy. @@ -55,9 +72,10 @@ Development Process and operates under the terms of the Eclipse IP Policy. * https://eclipse.org/projects/dev_process * https://www.eclipse.org/org/documents/Eclipse_IP_Policy.pdf -## Eclipse Contributor Agreement +== Eclipse Contributor Agreement In order to be able to contribute to Eclipse Foundation projects you must electronically sign the Eclipse Contributor Agreement (ECA). + https://www.eclipse.org/legal/ECA.php The ECA provides the Eclipse Foundation with a permanent record that you agree @@ -67,21 +85,25 @@ the email address matching the "Author" field of your contribution's Git commits fulfills the DCO's requirement that you sign-off on your contributions. For more information, please see the Eclipse Committer Handbook: + https://www.eclipse.org/projects/handbook/#resources-commit -## Contact +== Contact The project owns several mailing lists. -### Main ThreadX mailing list +=== Main ThreadX mailing list News and updates about the ThreadX project and the ThreadX Alliance. + https://accounts.eclipse.org/mailing-list/threadx -### Developer mailing list +=== Developer mailing list Project team conversations. Feel free to jump in and ask non-technical questions there. + https://accounts.eclipse.org/mailing-list/threadx-dev -### User mailing list +=== User mailing list Ask your technical questions and discuss issues here. + https://accounts.eclipse.org/mailing-list/threadx-users diff --git a/README.md b/README.adoc similarity index 71% rename from README.md rename to README.adoc index f3b4dad..88744f9 100644 --- a/README.md +++ b/README.adoc @@ -1,9 +1,23 @@ -# About this repository -This is the AsciiDoc source for the Eclipse ThreadX documentation. The project team generates HTML and PDF versions from the contents of this repository. +//// -If you want to propse changes or addition to the documentation, this is the right place! + Copyright (c) Microsoft + Copyright (c) 2024-present Eclipse ThreadX contributors + + This program and the accompanying materials are made available + under the terms of the MIT license which is available at + https://opensource.org/license/mit. + + SPDX-License-Identifier: MIT + + Contributors: + * Frédéric Desbiens - Initial AsciiDoc version. -# What is Eclipse ThreadX? +//// + += About this repository +:description: This is the AsciiDoc source for the Eclipse ThreadX documentation. The project team generates HTML and PDF versions from the contents of this repository. + +== What is Eclipse ThreadX? Eclipse ThreadX is a real time operating system (RTOS) for Internet of Things (IoT) and edge devices powered by microcontroller units (MCUs). Eclipse ThreadX is designed to support most highly constrained devices (battery powered and having less than 64 KB of flash memory). @@ -13,72 +27,73 @@ Eclipse ThreadX provides full IP layer security via IPsec and socket layer secur With Eclipse Foundation as the new home, Azure RTOS becomes Eclipse ThreadX. For more information, see the following pages: -* [Microsoft IoT blog](https://techcommunity.microsoft.com/t5/internet-of-things-blog/microsoft-contributes-azure-rtos-to-open-source/ba-p/3986318) -* [Eclipse ThreadX project](https://threadx.io/) +* https://techcommunity.microsoft.com/t5/internet-of-things-blog/microsoft-contributes-azure-rtos-to-open-source/ba-p/3986318[Microsoft IoT blog] +* https://threadx.io[Eclipse ThreadX project] -## Eclipse ThreadX resources +== Eclipse ThreadX resources -[Eclipse ThreadX repositories](https://github.com/eclipse-threadx/) +https://github.com/eclipse-threadx[Eclipse ThreadX repositories] Documentation for components: -- [ThreadX](./rtos-docs/threadx/index.md) -- [ThreadX Modules](./rtos-docs/threadx-modules/index.md) -- [NetX Duo](./rtos-docs/netx-duo/index.md) -- [GUIX](./rtos-docs/guix/index.md) -- [FileX](./rtos-docs/filex/index.md) -- [LevelX](./rtos-docs/levelx/index.md) -- [USBX](./rtos-docs/usbx/index.md) -- [TraceX](./rtos-docs/tracex/index.md) +* xref:./rtos-docs/threadx/index.adoc[ThreadX] +* xref:./rtos-docs/threadx-modules/index.adoc[ThreadX Modules] +* xref:./rtos-docs/netx-duo/index.adoc[NetX Duo] +* xref:./rtos-docs/guix/index.adoc[GUIX] +* xref:./rtos-docs/filex/index.adoc[FileX] +* xref:./rtos-docs/levelx/index.adoc[LevelX] +* xref:./rtos-docs/usbx/index.adoc[USBX] +* xref:./rtos-docs/tracex/index.adoc[TraceX] Other resources: -- [Product Support Policy](./rtos-docs/general/lts.md) -- [Security Updates](./rtos-docs/general/security-updates.md) +* xref:./rtos-docs/general/lts.adoc[Product Support Policy] +* xref:./rtos-docs/general/security-updates.adoc[Security Updates] -## Components of Eclipse ThreadX +== Components of Eclipse ThreadX The Eclipse ThreadX platform is the collection of run-time solutions including ThreadX, NetX Duo, FileX, GUIX and USBX. -![The diagram of Eclipse ThreadX system components.](./rtos-docs/media/eclipse-threadx-system-components.png) +image::./rtos-docs/media/eclipse-threadx-system-components.png[] -### ThreadX +=== ThreadX ThreadX is an advanced Real-Time Operating System (RTOS) designed specifically for deeply embedded applications. Among the multiple benefits ThreadX provides are advanced scheduling facilities, message passing, interrupt management, and messaging services. ThreadX has many advanced features, including its picokernel architecture, preemption-threshold scheduling, event-chaining, and a rich set of system services. -### FileX +=== FileX FileX is a high-performance FAT-compatible file system. It is fully integrated with ThreadX and is available for all supported processors. Like ThreadX, FileX is designed to have a small footprint and high performance, making it ideal for today's deeply embedded applications that require file operations. FileX supports most physical media, including RAM disk, USBX, SD CARD, and NAND/NOR flash memories via LevelX. -### GUIX +=== GUIX GUIX is a professional quality graphical user interface package, created to meet the needs of embedded systems developers. Unlike the alternatives, GUIX is small, fast, and easily ported to virtually any hardware configuration capable of supporting graphical output. GUIX also delivers exceptional visual appeal and an intuitive and powerful API for application-level user interface development. -### NetX Duo +=== NetX Duo NetX Duo is an advanced, Industrial Grade TCP/IP network stacks designed specifically for deeply embedded, real-time, and IoT applications. NetX Duo is a dual IPv4 and IPv6 network stack. -### USBX +=== USBX USBX is a high-performance USB host, device, and On-The-Go (OTG) embedded stack. It is fully integrated with ThreadX and is available for all ThreadX supported processors. Like ThreadX, USBX is designed to have a small footprint and high performance, making it ideal for deeply embedded applications that require an interface with USB devices. -### Windows tools +=== Windows tools GUIX Studio provides a complete GUI application design environment, facilitating the creation and maintenance of all graphical elements in the application's GUI. GUIX Studio automatically generates C code compatible with the GUIX library, ready to be compiled and run on the target. +=== TRACEX TraceX is a host-based analysis tool that provides developers with a graphical view of real-time system events and enables them to visualize and better understand the behavior of their real-time systems. -## The Eclipse ThreadX Advantage +== The Eclipse ThreadX Advantage Eclipse ThreadX provides the following advantages over other real-time operating systems. -### Most deployed RTOS +=== Most deployed RTOS Eclipse ThreadX has over 12 billion deployments worldwide. The popularity of Eclipse ThreadX is a testament to its reliability, quality, size, performance, advanced features, ease-of-use, and overall time-to-market advantages. > _"We have followed the growth trajectory of THREADX in the wireless and IoT markets since the company's founding, and are increasingly impressed by the widespread industry adoption of THREADX."_ – Chris Rommel, Executive Vice President, VDC Research -### Intuitive and consistent API design +=== Intuitive and consistent API design - Intuitive and consistent API. - Noun-verb naming convention. @@ -88,13 +103,13 @@ Eclipse ThreadX has over 12 billion deployments worldwide. The popularity of Ecl - Optional user-notification callbacks for media and file operations. - Event-driven programming model (API). -### High efficiency +=== High efficiency - Small code footprint. - Scalable code footprint based on the services used. - Fast execution. Eclipse ThreadX is designed for speed and has minimal internal function call layering to help achieve the fastest possible performance. -### Fastest time-to-market +=== Fastest time-to-market Eclipse ThreadX is easy to install, learn, use, debug, verify, certify, and maintain. As a result, Eclipse ThreadX is one of the most popular real time operating systems for embedded IoT devices, including many SoCs from Broadcom, Gainspan, and so forth. Our consistent time-to-market advantage is built on: @@ -103,80 +118,80 @@ Eclipse ThreadX is easy to install, learn, use, debug, verify, certify, and main - Comprehensive and advanced feature set. - Quality documentation. -### Full, highest-quality source code +=== Full, highest-quality source code Throughout the years, Eclipse ThreadX source code has set the bar in quality and ease of understanding. In addition, the convention of having one function per file provides for easy source navigation. -### Pre-certified by TÜV and UL to many safety standards +=== Pre-certified by TÜV and UL to many safety standards Eclipse ThreadX has been certified by SGS-TÜV Saar for use in safety-critical systems, according to IEC-61508 SIL 4. The certification confirms that Eclipse ThreadX can be used in the development of safety-related software for the highest safety integrity levels of IEC-61508 for the "Functional Safety of electrical, electronic, and programmable electronic safety-related systems." SGS-TUV Saar, formed through a joint venture of Germany's SGS-Group and TUV Saarland, has become the leading accredited, independent company for testing, auditing, verifying, and certifying embedded software for safety-related systems worldwide. -![SGS-TUV certification](./rtos-docs/media/partener-logo-sgs-tuv-saar.png) +image::./rtos-docs/media/partener-logo-sgs-tuv-saar.png[] Eclipse ThreadX has been recognized by UL for compliance with UL 60730-1 Annex H, CSA E60730-1 Annex H, IEC 60730-1 Annex H, UL 60335-1 Annex R, IEC 60335-1 Annex R, and UL 1998 safety standards for software in programmable components. UL is a global, independent, safety-science company with more than a century of expertise innovating safety solutions, ranging from the public adoption of electricity to breakthroughs in sustainability, renewable energy, and nanotechnology. -![CRU UL certification](./rtos-docs/media/cru-logo-certification.png) +image::./rtos-docs/media/cru-logo-certification.png[] Artifacts (Certificate, Safety Manual, Test Report, etc.) associated with the TUV and UL certifications are available to license. In cases where the application needs additional certification, a certification service is available through Eclipse Foundation for providing turn-key certification to various standards using the actual hardware platform and even covering the application code. Contact us for more details on our certification service. -### EAL4+ Common Criteria security certification +=== EAL4+ Common Criteria security certification ThreadX has achieved EAL4+ Common Criteria security certification. The Target of Evaluation (TOE) covers ThreadX, NetX Duo, NetX Secure TLS, and NetX MQTT. This represents the most typical IoT protocols required by deeply embedded sensors, devices, edge routers, and gateways. -![EAL certification](./rtos-docs/media/eal-logo-certification.png) +image::./rtos-docs/media/eal-logo-certification.png[] The IT Security Evaluation Facility used for the Eclipse ThreadX SC security certification is Brightsight BV and the Certification Authority is SERTIT. -### FIPS 140-2 Validated +=== FIPS 140-2 Validated Eclipse ThreadX Crypto libraries have achieved Federal Information Processing Standardization 140-2 (FIPS 140-2) Certification for software, which specifies requirements for cryptography modules. FIPS 140-2 requires all federal government agencies and departments that use cryptographic-based security to meet specific standards related to encryption strength and capabilities. These cryptographic-based security standards are also recognized in Canada and the European Union. -The Information Security evaluation lab used for Eclipse ThreadX Crypto libraries was atsec and the certification authority is [The National Institute of Standards and Technology (NIST)](https://csrc.nist.gov/projects/cryptographic-module-validation-program/Certificate/3394). +The Information Security evaluation lab used for Eclipse ThreadX Crypto libraries was atsec and the certification authority is https://csrc.nist.gov/projects/cryptographic-module-validation-program/Certificate/3394[The National Institute of Standards and Technology (NIST)]. -### Supports most popular architectures +=== Supports most popular architectures Eclipse ThreadX works on most popular 32/64-bit microprocessors, out-of-the-box, fully tested and fully supported, including the following advanced architectures: -- **Analog Devices**: SHARC, Blackfin, CM4xx +- *Analog Devices*: SHARC, Blackfin, CM4xx -- **Andes Core**: RISC-V +- *Andes Core*: RISC-V -- **Ambiqmicro**: Apollo MCUs +- *Ambiqmicro*: Apollo MCUs -- **ARM**: ARM7, ARM9, ARM11, Cortex-M0/M3/M4/M7/A15/A5/A7/A8/A9/A5x 64-bi/A7x 64-bit/R4/R5, TrustZone ARMv8-M +- *ARM*: ARM7, ARM9, ARM11, Cortex-M0/M3/M4/M7/A15/A5/A7/A8/A9/A5x 64-bi/A7x 64-bit/R4/R5, TrustZone ARMv8-M -- **Cadence**: Xtensa, Diamond +- *Cadence*: Xtensa, Diamond -- **CEVA**: PSoC, PSoC 4, PSoC 5, PSoC 6, FM0+, FM3, MF4, WICED WiFi +- *CEVA*: PSoC, PSoC 4, PSoC 5, PSoC 6, FM0+, FM3, MF4, WICED WiFi -- **Cypress**: RISC-V +- *Cypress*: RISC-V -- **EnSilica**: eSi-RISC +- *EnSilica*: eSi-RISC -- **Infineon**: XMC1000, XMC4000, TriCore +- *Infineon*: XMC1000, XMC4000, TriCore -- **Intel; Intel FPGA**: x36/Pentium, XScale, NIOS II, Cyclone, Arria 10 +- *Intel; Intel FPGA*: x36/Pentium, XScale, NIOS II, Cyclone, Arria 10 -- **Microchip**: AVR32, ARM7, ARM9, Cortex-M3/M4/M7, SAM3/4/7/9/A/C/D/E/G/L/SV, PIC24/PIC32 +- *Microchip*: AVR32, ARM7, ARM9, Cortex-M3/M4/M7, SAM3/4/7/9/A/C/D/E/G/L/SV, PIC24/PIC32 -- **Microsemi**: RISC-V +- *Microsemi*: RISC-V -- **NXP**: i.MX RT10xx and RT116x/7x series crossover MCUs, LPC5500 series +- *NXP*: i.MX RT10xx and RT116x/7x series crossover MCUs, LPC5500 series -- **Renesas**: SH, HS, V850, RA, RX, RZ, Synergy +- *Renesas*: SH, HS, V850, RA, RX, RZ, Synergy -- **Silicon Labs**: EFM32 +- *Silicon Labs*: EFM32 -- **Synopsys**: ARC 600, 700, ARC EM, ARC HS +- *Synopsys*: ARC 600, 700, ARC EM, ARC HS -- **ST**: STM32, ARM7, ARM9, Cortex-M3/M4/M7 +- *ST*: STM32, ARM7, ARM9, Cortex-M3/M4/M7 -- **Tl**: C5xxx, C6xxx, Stellaris, Sitara, Tiva-C +- *Tl*: C5xxx, C6xxx, Stellaris, Sitara, Tiva-C -- **Wave Computing**: MIPS32 4K, 24 K, 34 K, 1004 K, MIPS64 5K, microAptiv, interAptiv, proAptiv, M-Class +- *Wave Computing*: MIPS32 4K, 24 K, 34 K, 1004 K, MIPS64 5K, microAptiv, interAptiv, proAptiv, M-Class -- **Xilinx**: MicroBlaze, PowerPC 405, ZYNQ, ZYNQ UltraSCALE +- *Xilinx*: MicroBlaze, PowerPC 405, ZYNQ, ZYNQ UltraSCALE _All timing and size figures listed are estimates and may be different on your development platform._