diff options
Diffstat (limited to 'c-user/config/mpci.rst')
| -rw-r--r-- | c-user/config/mpci.rst | 360 |
1 files changed, 213 insertions, 147 deletions
diff --git a/c-user/config/mpci.rst b/c-user/config/mpci.rst index 800aa30..ab9d568 100644 --- a/c-user/config/mpci.rst +++ b/c-user/config/mpci.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2022 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically .. generated. If you find something that needs to be fixed or @@ -23,15 +23,20 @@ Multiprocessing Configuration ============================= -This section describes multiprocessing related configuration options. The -options are only used if RTEMS was built with the ``--enable-multiprocessing`` -build configuration option. Additionally, this class of configuration options -are only applicable if the configuration option :ref:`CONFIGURE_MP_APPLICATION` -is defined. The multiprocessing (MPCI) support must not be confused with the -SMP support. +This section describes multiprocessing related configuration options. +The options are only used if RTEMS was built when the multiprocessing +build configuration option is enabled. The multiprocessing configuration +is distinct from the SMP configuration. Additionally, this class of +configuration options are only applicable if the configuration option +:ref:`CONFIGURE_MP_APPLICATION` is defined. The multiprocessing (MPCI) +support must not be confused with the SMP support. .. Generated from spec:/acfg/if/mp-extra-server-stack +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK .. _CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK: @@ -39,39 +44,49 @@ SMP support. CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK ----------------------------------------- -CONSTANT: - ``CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK`` +.. rubric:: CONSTANT: + +``CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 0. +The value of this configuration option defines the number of bytes the +applications wishes to add to the MPCI task stack on top of +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: NOTES: - * It shall be greater than or equal to zero. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: - * It shall be small enough so that the MPCI receive server stack area - calculation carried out by ``<rtems/confdefs.h>`` does not overflow an - integer of type `size_t <https://en.cppreference.com/w/c/types/size_t>`_. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the number of bytes the - applications wishes to add to the MPCI task stack on top of - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be small enough so that the MPCI + receive server stack area calculation carried out by ``<rtems/confdefs.h>`` + does not overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. .. Generated from spec:/acfg/if/mp-appl +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_APPLICATION .. _CONFIGURE_MP_APPLICATION: @@ -79,29 +94,38 @@ NOTES: CONFIGURE_MP_APPLICATION ------------------------ -CONSTANT: - ``CONFIGURE_MP_APPLICATION`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_APPLICATION`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the multiprocessing services +are not initialized. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the multiprocessing services - are not initialized. +.. rubric:: DESCRIPTION: -DESCRIPTION: - This configuration option is defined to indicate that the application intends - to be part of a multiprocessing configuration. Additional configuration - options are assumed to be provided. +This configuration option is defined to indicate that the application intends +to be part of a multiprocessing configuration. Additional configuration +options are assumed to be provided. -NOTES: - This configuration option shall be undefined if the multiprocessing support - is not enabled (e.g. RTEMS was built without the ``--enable-multiprocessing`` - build configuration option). Otherwise a compile time error in the - configuration file will occur. +.. rubric:: NOTES: + +This configuration option shall be undefined if the multiprocessing support +is not enabled (e.g. RTEMS was built without the multiprocessing build +configuration option enabled). Otherwise a compile time error in the +configuration file will occur. .. Generated from spec:/acfg/if/mp-max-global-objects +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS .. _CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS: @@ -109,37 +133,46 @@ NOTES: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS ----------------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 32. -DEFAULT VALUE: - The default value is 32. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of +concurrently active global objects in a multiprocessor system. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +This value corresponds to the total number of objects which can be created +with the :c:macro:`RTEMS_GLOBAL` attribute. -DESCRIPTION: - The value of this configuration option defines the maximum number of - concurrently active global objects in a multiprocessor system. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -NOTES: - This value corresponds to the total number of objects which can be created - with the :c:macro:`RTEMS_GLOBAL` attribute. +.. rubric:: CONSTRAINTS: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/mp-max-nodes +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_MAXIMUM_NODES .. _CONFIGURE_MP_MAXIMUM_NODES: @@ -147,34 +180,43 @@ NOTES: CONFIGURE_MP_MAXIMUM_NODES -------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_NODES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_NODES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 2. +The default value is 2. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to zero. +The value of this configuration option defines the maximum number of nodes in +a multiprocessor system. - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum number of nodes in - a multiprocessor system. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -NOTES: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/mp-max-proxies +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_MAXIMUM_PROXIES .. _CONFIGURE_MP_MAXIMUM_PROXIES: @@ -182,40 +224,49 @@ NOTES: CONFIGURE_MP_MAXIMUM_PROXIES ---------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_PROXIES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_PROXIES`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 32. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 32. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +The value of this configuration option defines the maximum number of +concurrently active thread/task proxies on this node in a multiprocessor +system. -DESCRIPTION: - The value of this configuration option defines the maximum number of - concurrently active thread/task proxies on this node in a multiprocessor - system. +.. rubric:: NOTES: -NOTES: - Since a proxy is used to represent a remote task/thread which is blocking - on this node. This configuration parameter reflects the maximum number of - remote tasks/threads which can be blocked on objects on this node, see - :ref:`MPCIProxies`. +Since a proxy is used to represent a remote task/thread which is blocking +on this node. This configuration parameter reflects the maximum number of +remote tasks/threads which can be blocked on objects on this node, see +:ref:`MPCIProxies`. - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/mp-mpci-table-pointer +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_MPCI_TABLE_POINTER .. _CONFIGURE_MP_MPCI_TABLE_POINTER: @@ -223,33 +274,43 @@ NOTES: CONFIGURE_MP_MPCI_TABLE_POINTER ------------------------------- -CONSTANT: - ``CONFIGURE_MP_MPCI_TABLE_POINTER`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MPCI_TABLE_POINTER`` -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is ``&MPCI_table``. +This configuration option is an initializer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be a pointer to - :c:type:`rtems_mpci_table`. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option initializes the MPCI Configuration - Table. +The default value is ``&MPCI_table``. -NOTES: - RTEMS provides a Shared Memory MPCI Device Driver which can be used on any - Multiprocessor System assuming the BSP provides the proper set of - supporting methods. +.. rubric:: DESCRIPTION: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +The value of this configuration option initializes the MPCI Configuration +Table. + +.. rubric:: NOTES: + +RTEMS provides a Shared Memory MPCI Device Driver which can be used on any +Multiprocessor System assuming the BSP provides the proper set of +supporting methods. + +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a pointer to +:c:type:`rtems_mpci_table`. .. Generated from spec:/acfg/if/mp-node-number +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_NODE_NUMBER .. _CONFIGURE_MP_NODE_NUMBER: @@ -257,33 +318,38 @@ NOTES: CONFIGURE_MP_NODE_NUMBER ------------------------ -CONSTANT: - ``CONFIGURE_MP_NODE_NUMBER`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_NODE_NUMBER`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``NODE_NUMBER``. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the node number of this node +in a multiprocessor system. -DEFAULT VALUE: - The default value is ``NODE_NUMBER``. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +In the RTEMS Multiprocessing Test Suite, the node number is derived from +the Makefile variable ``NODE_NUMBER``. The same code is compiled with the +``NODE_NUMBER`` set to different values. The test programs behave +differently based upon their node number. - * It shall be greater than or equal to zero. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the node number of this node - in a multiprocessor system. +The following constraints apply to this configuration option: -NOTES: - In the RTEMS Multiprocessing Test Suite, the node number is derived from - the Makefile variable ``NODE_NUMBER``. The same code is compiled with the - ``NODE_NUMBER`` set to different values. The test programs behave - differently based upon their node number. +* The value of the configuration option shall be greater than or equal to zero. - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. |