From 4f014e5c007c942be09f0380f1e0d8ecc4ae4ff8 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 12 Sep 2022 09:39:55 +0200 Subject: spec: Generate acfg info section --- config.yml | 3 ++ spec/rtems/config/if/group.yml | 119 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 119 insertions(+), 3 deletions(-) diff --git a/config.yml b/config.yml index acd88d00..16105bf1 100644 --- a/config.yml +++ b/config.yml @@ -131,6 +131,9 @@ interface-documentation: - directives-target: modules/rtems-docs/c-user/cache/directives.rst group: /rtems/cache/if/group introduction-target: modules/rtems-docs/c-user/cache/introduction.rst + - directives-target: modules/rtems-docs/c-user/config/directives.rst + group: /rtems/config/if/group + introduction-target: modules/rtems-docs/c-user/config/introduction.rst - directives-target: modules/rtems-docs/c-user/dual-ported-memory/directives.rst group: /rtems/dpmem/if/group introduction-target: modules/rtems-docs/c-user/dual-ported-memory/introduction.rst diff --git a/spec/rtems/config/if/group.yml b/spec/rtems/config/if/group.yml index c0631b9d..ad13c9ac 100644 --- a/spec/rtems/config/if/group.yml +++ b/spec/rtems/config/if/group.yml @@ -4,18 +4,131 @@ brief: | configuration of an application. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) description: | - Some interfaces of this API are also used to define application configuration - option values, for example ${resource-unlimited:/name}. + RTEMS must be configured for an application. This configuration encompasses a + variety of information including the length of each clock tick, the maximum + number of each information RTEMS object that can be created, the application + initialization tasks, the task scheduling algorithm to be used, and the device + drivers in the application. + + Although this information is contained in data structures that are used by + RTEMS at system initialization time, the data structures themselves must not be + generated by hand. RTEMS provides a set of macros system which provides a + simple standard mechanism to automate the generation of these structures. + + The RTEMS header file ```` is at the core of the automatic + generation of system configuration. It is based on the idea of setting macros + which define configuration parameters of interest to the application and + defaulting or calculating all others. This variety of macros can automatically + produce all of the configuration data required for an RTEMS application. The + term ``confdefs`` is shorthand for a *Configuration Defaults*. + + As a general rule, application developers only specify values for the + configuration parameters of interest to them. They define what resources or + features they require. In most cases, when a parameter is not specified, it + defaults to zero (0) instances, a standards compliant value, or disabled as + appropriate. For example, by default there will be 256 task priority levels but + this can be lowered by the application. This number of priority levels is + required to be compliant with the RTEID/ORKID standards upon which the Classic + API is based. There are similar cases where the default is selected to be + compliant with the POSIX standard. + + For each configuration parameter in the configuration tables, the macro + corresponding to that field is discussed. The RTEMS Maintainers expect that all + systems can be easily configured using the ```` mechanism and + that using this mechanism will avoid internal RTEMS configuration changes + impacting applications. + + Some application configuration settings and other system parameters can be + queried by the application. enabled-by: true identifier: RTEMSAPIConfig -index-entries: [] +index-entries: +- confdefs.h +- interface-type: group links: - role: interface-placement uid: header - role: interface-ingroup uid: /if/group +- role: placement-order + uid: get-build-label +- role: placement-order + uid: get-copyright-notice +- role: placement-order + uid: get-target-hash +- role: placement-order + uid: get-version-string +- role: placement-order + uid: get-do-zero-of-workspace +- role: placement-order + uid: get-idle-task-stack-size +- role: placement-order + uid: get-idle-task +- role: placement-order + uid: get-interrupt-stack-size +- role: placement-order + uid: get-maximum-barriers +- role: placement-order + uid: get-maximum-extensions +- role: placement-order + uid: get-maximum-message-queues +- role: placement-order + uid: get-maximum-partitions +- role: placement-order + uid: get-maximum-periods +- role: placement-order + uid: get-maximum-ports +- role: placement-order + uid: get-maximum-processors +- role: placement-order + uid: get-maximum-regions +- role: placement-order + uid: get-maximum-semaphores +- role: placement-order + uid: get-maximum-tasks +- role: placement-order + uid: get-maximum-timers +- role: placement-order + uid: get-microseconds-per-tick +- role: placement-order + uid: get-milliseconds-per-tick +- role: placement-order + uid: get-nanoseconds-per-tick +- role: placement-order + uid: get-number-of-initial-extensions +- role: placement-order + uid: get-stack-allocate-for-idle-hook +- role: placement-order + uid: get-stack-allocate-hook +- role: placement-order + uid: get-stack-allocate-init-hook +- role: placement-order + uid: get-stack-allocator-avoids-work-space +- role: placement-order + uid: get-stack-free-hook +- role: placement-order + uid: get-stack-space-size +- role: placement-order + uid: get-ticks-per-timeslice +- role: placement-order + uid: get-unified-work-area +- role: placement-order + uid: get-user-extension-table +- role: placement-order + uid: get-user-multiprocessing-table +- role: placement-order + uid: get-work-space-size +- role: placement-order + uid: get-api-configuration +- role: placement-order + uid: resource-is-unlimited +- role: placement-order + uid: resource-maximum-per-allocation +- role: placement-order + uid: resource-unlimited name: Application Configuration Information text: | The RTEMS API shall provide an interface to get the configuration of an -- cgit v1.2.3