[PATCH] doxygen: Replace and move main page
Sebastian Huber
sebastian.huber at embedded-brains.de
Thu Oct 12 11:29:38 UTC 2023
Hello Joel,
thanks for having a look at it. I used the features list here as a
template for the mainpage:
https://docs.rtems.org/branches/master/user/overview/index.html#features
Maybe it needs to be updated as well.
On 10.10.23 20:43, Joel Sherrill wrote:
> Sorry. Not sure how this kept slipping through the cracks. The 13
> September ping did coincide with me being on a trip and then sick.
>
> This is the only revision I see in my inbox. There is an email which
> says "how about this version?" but I don't see anything on it.
>
> A few comments inline.
>
> On Fri, Jul 28, 2023 at 9:37 AM Sebastian Huber
> <sebastian.huber at embedded-brains.de
> <mailto:sebastian.huber at embedded-brains.de>> wrote:
>
> Replace the main page with a high level description of the RTEMS feature
> set similar to:
>
> https://docs.rtems.org/branches/master/user/overview/index.html#features <https://docs.rtems.org/branches/master/user/overview/index.html#features>
>
> The replaced content can be found in the RTEMS Classic API Guide:
>
> https://docs.rtems.org/branches/master/c-user/overview.html
> <https://docs.rtems.org/branches/master/c-user/overview.html>
>
> https://docs.rtems.org/branches/master/c-user/key_concepts.html
> <https://docs.rtems.org/branches/master/c-user/key_concepts.html>
>
> Update #3705.
> ---
> v2:
>
> * Add OAR copyright.
>
> * Move to cpukit/doxygen/mainpage.h
>
> * Not not install
>
> cpukit/doxygen/mainpage.h | 204 ++++++
> cpukit/include/rtems/rtems/mainpage.h | 951 --------------------------
> spec/build/cpukit/librtemscpu.yml | 1 -
> 3 files changed, 204 insertions(+), 952 deletions(-)
> create mode 100644 cpukit/doxygen/mainpage.h
> delete mode 100644 cpukit/include/rtems/rtems/mainpage.h
>
> diff --git a/cpukit/doxygen/mainpage.h b/cpukit/doxygen/mainpage.h
> new file mode 100644
> index 0000000000..ce341e0ffd
> --- /dev/null
> +++ b/cpukit/doxygen/mainpage.h
> @@ -0,0 +1,204 @@
> +/* SPDX-License-Identifier: BSD-2-Clause */
> +
> +/**
> + * @file
> + *
> + * @ingroup RTEMSImplDoxygen
> + *
> + * @brief This file exists to provide a top level description of
> RTEMS for
> + * Doxygen.
> + */
> +
> +/*
> + * Copyright (C) 2021 embedded brains GmbH & Co. KG
> + * Copyright (C) 1989, 2014 On-Line Applications Research
> Corporation (OAR)
> + *
> + * Redistribution and use in source and binary forms, with or without
> + * modification, are permitted provided that the following conditions
> + * are met:
> + * 1. Redistributions of source code must retain the above copyright
> + * notice, this list of conditions and the following disclaimer.
> + * 2. Redistributions in binary form must reproduce the above copyright
> + * notice, this list of conditions and the following disclaimer
> in the
> + * documentation and/or other materials provided with the
> distribution.
> + *
> + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
> CONTRIBUTORS "AS IS"
> + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
> LIMITED TO, THE
> + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
> PARTICULAR PURPOSE
> + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
> CONTRIBUTORS BE
> + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
> + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
> + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
> BUSINESS
> + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
> WHETHER IN
> + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
> OTHERWISE)
> + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
> ADVISED OF THE
> + * POSSIBILITY OF SUCH DAMAGE.
> + */
> +
> +/**
> + * @mainpage
> + *
> + * The Real-Time Executive for Multiprocessor Systems (RTEMS) is a
> + * multi-threaded, single address-space, real-time operating system
> with no
> + * kernel-space/user-space separation. It is capable to operate in
> an SMP
> + * configuration providing a state of the art feature set.
> + *
> + * RTEMS and all third-party software distributed with RTEMS which
> may be
> + * linked to the application is licensed under permissive open
> source licenses.
> + * This means that the licenses do not properagate to the
> application software.
>
>
> properagate -> propagate
>
> + * Most of the original RTEMS code is now under the [BSD 2-Clause
> + * license](https://git.rtems.org/rtems/tree/LICENSE.BSD-2-Clause
> <https://git.rtems.org/rtems/tree/LICENSE.BSD-2-Clause>). Legacy
>
>
> GPLv2 does not imply legacy. Some code in RTEMS is under a legacy license.
Which alternative wording would you use?
>
> + * code of RTEMS is under a [modified GPL 2.0 or later license with an
> + * exception for static
> linking](https://git.rtems.org/rtems/tree/LICENSE
> <https://git.rtems.org/rtems/tree/LICENSE>>).
> + * It exposes no license requirements on application code. Everything
> + * necessary to build RTEMS applications is available as open
> source software.
> + * This makes you completely vendor independent.
> + *
> + * RTEMS provides the following basic feature set:
> + *
> + * - @ref RTEMSAPI
> + *
> + * - POSIX with
> + *
> [pthreads](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html>)
> + * (enables a broad range of standard software to run on RTEMS)
> + *
> + * - @ref RTEMSAPIClassic
> + *
> + * - C11 (including
> + * [thread](https://en.cppreference.com/w/c/thread
> <https://en.cppreference.com/w/c/thread>) support)
> + *
> + * - C++11 (including
> + * [thread](https://en.cppreference.com/w/cpp/thread
> <https://en.cppreference.com/w/cpp/thread>>) support)
> + *
> + * - Newlib and GCC internal
> + *
> + * - Programming languages
> + *
> + * - C/C++/OpenMP (RTEMS Source Builder, RSB)
> + *
> + * - Ada (RSB, ``--with-ada``)
> + *
> + * - Erlang
> + *
> + * - Fortran (RSB, ``--with-fortran``)
>
>
> FWIW I have a Fortran RTEMS hello world and need to add it to
> rtems-examples.
Great, maybe this could be added to the normal test suite.
>
> + *
> + * - Python and MicroPython
> + *
> + * - Parallel languages
> + *
> + * - [Embedded Multicore Building Blocks](https://embb.io/
> <https://embb.io/>)
> + *
> + * - [OpenMP](https://www.openmp.org/ <https://www.openmp.org/>)
> + *
> + * - Thread synchronization and communication
> + *
> + * - Mutexes with and without locking protocols
> + *
> + * - Counting semaphores
> + *
> + * - Binary semaphores
> + *
> + * - Condition variables
> + *
> + * - Events
> + *
> + * - Message queues
> + *
> + * - Barriers
> + *
> + * - [Futex](@ref RTEMSScoreFutex) (used by OpenMP barriers)
> + *
> + * - Epoch Based Reclamation (libbsd)
> + *
> + * - Locking protocols
> + *
> + * - Transitive Priority Inheritance
> + *
> + * - OMIP (SMP feature)
> + *
> + * - Priority Ceiling
> + *
> + * - MrsP (SMP feature)
> + *
> + * - Scalable timer and timeout support
> + *
> + * - Lock-free timestamps (FreeBSD timecounters)
> + *
> + * - Responsive interrupt management
> + *
> + * - C11/C++11 Thread-Local Storage (TLS)
>
>
> TLS is also in newer versions of both languages so how about rephrasing
> to include C17, C++14, etc
C11/C++11 were the first standard revisions which defined thread-local
storage.
What about this:
- Thread-Local Storage (TLS) as specified by C11/C++11 and later
standard revisions
>
> + *
> + * - Link-time configurable schedulers
> + *
> + * - Fixed-priority
> + *
> + * - Job-level fixed-priority (EDF)
> + *
> + * - Constant Bandwidth Server (experimental)
> + *
> + * - Clustered scheduling (SMP feature)
> + *
> + * - Flexible link-time configuration
> + *
> + * - Job-level fixed-priority scheduler (EDF) with support for
> one-to-one
> + * and one-to-all thread to processor affinities (default
> SMP scheduler)
> + *
> + * - Fixed-priority scheduler
> + *
> + * - Proof-of-concept strong APA scheduler
> + *
> + * - Focus on link-time application-specific configuration
> + *
> + * - Linker-set based initialization (similar to global C++
> constructors)
> + *
> + * - Operating system uses fine-grained locking (SMP feature)
> + *
> + * - Dynamic memory allocators
> + *
> + * - First-fit (default)
> + *
> + * - Universal Memory Allocator
> + *
> ([UMA](https://www.freebsd.org/cgi/man.cgi?query=uma&sektion=9
> <https://www.freebsd.org/cgi/man.cgi?query=uma&sektion=9>),
> + * libbsd)
> + *
> + * - File systems
> + *
> + * - IMFS
> + *
> + * - FAT
> + *
> + * - RFS
> + *
> + * - NFSv2
>
>
> NFSv4 in libbsd.
>
> + *
> + * - JFFS2 (NOR flashes)
>
>
> Kinsey just enabled NAND I think.
Does this really work? Who else uses JFFS2 on NAND flashes?
>
> + *
> + * - [YAFFS2](https://git.rtems.org/sebh/rtems-yaffs2.git/
> <https://git.rtems.org/sebh/rtems-yaffs2.git/>)
> + * (NAND flashes, GPL or commercial license required)
> + *
> + * - Device drivers
> + *
> + * - Termios (serial interfaces)
> + *
> + * - I2C (Linux user-space API compatible)
> + *
> + * - SPI (Linux user-space API compatible)
> + *
> + * - Network stacks (legacy, libbsd, lwIP)
> + *
> + * - USB stack (libbsd)
> + *
> + * - SD/MMC card stack (libbsd)
> + *
> + * - Framebuffer (Linux user-space API compatible, Qt)
> + *
> + * - Application runs in kernel-space and can access hardware
> directly
> + *
> + * - [libbsd](https://git.rtems.org/rtems-libbsd/
> <https://git.rtems.org/rtems-libbsd/>)
> + *
> + * - Port of FreeBSD user-space and kernel-space components to
> RTEMS
> + *
> + * - Easy access to FreeBSD software for RTEMS
> + *
> + * - Support to stay in synchronization with FreeBSD
>
>
> Does lwip rate a bit like that?
It is also missing on the user manual features list.
--
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
phone: +49-89-18 94 741 - 16
fax: +49-89-18 94 741 - 08
Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/
More information about the devel
mailing list