From 1c036bbb871d2e1246ab7a84f814de1b6a6d38d2 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 22 Apr 2021 14:03:25 +0200 Subject: spec: Update /rtems/intr/* documentation --- spec-glossary/glossary/target-arch.yml | 14 +++++ spec/constraint/cpu-simple-vectored-interrupts.yml | 11 ++++ spec/constraint/interrupt-enable.yml | 13 +++++ spec/constraint/no-impl.yml | 10 ++++ spec/rtems/intr/constraint/no-smp.yml | 13 +++++ spec/rtems/intr/if/catch.yml | 56 +++++++++++++++--- spec/rtems/intr/if/cause.yml | 15 +++-- spec/rtems/intr/if/clear.yml | 15 +++-- spec/rtems/intr/if/disable.yml | 65 ++++++++++++++++++--- spec/rtems/intr/if/enable.yml | 35 ++++++++--- spec/rtems/intr/if/flash.yml | 33 ++++++++--- spec/rtems/intr/if/group.yml | 44 +++++++++++++- spec/rtems/intr/if/header.yml | 2 +- spec/rtems/intr/if/is-in-progress.yml | 22 +++++-- spec/rtems/intr/if/isr-entry.yml | 2 +- spec/rtems/intr/if/isr.yml | 9 ++- spec/rtems/intr/if/level.yml | 5 +- spec/rtems/intr/if/local-disable.yml | 68 +++++++++++++++++++--- spec/rtems/intr/if/local-enable.yml | 33 ++++++++--- spec/rtems/intr/if/lock-acquire-isr.yml | 42 ++++++++++--- spec/rtems/intr/if/lock-acquire.yml | 54 ++++++++++++++--- spec/rtems/intr/if/lock-context.yml | 5 +- spec/rtems/intr/if/lock-declare.yml | 17 ++++-- spec/rtems/intr/if/lock-define.yml | 24 +++++--- spec/rtems/intr/if/lock-destroy.yml | 22 +++++-- spec/rtems/intr/if/lock-initialize.yml | 18 ++++-- spec/rtems/intr/if/lock-initializer.yml | 13 +++-- spec/rtems/intr/if/lock-isr-disable.yml | 18 ++++-- spec/rtems/intr/if/lock-member.yml | 11 ++-- spec/rtems/intr/if/lock-reference.yml | 14 +++-- spec/rtems/intr/if/lock-release-isr.yml | 32 +++++++--- spec/rtems/intr/if/lock-release.yml | 34 ++++++++--- spec/rtems/intr/if/lock.yml | 5 +- spec/rtems/intr/if/vector-number.yml | 5 +- 34 files changed, 632 insertions(+), 147 deletions(-) create mode 100644 spec-glossary/glossary/target-arch.yml create mode 100644 spec/constraint/cpu-simple-vectored-interrupts.yml create mode 100644 spec/constraint/interrupt-enable.yml create mode 100644 spec/constraint/no-impl.yml create mode 100644 spec/rtems/intr/constraint/no-smp.yml diff --git a/spec-glossary/glossary/target-arch.yml b/spec-glossary/glossary/target-arch.yml new file mode 100644 index 00000000..364ddfb5 --- /dev/null +++ b/spec-glossary/glossary/target-arch.yml @@ -0,0 +1,14 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +glossary-type: term +links: +- role: glossary-member + uid: ../glossary-general +term: target architecture +text: | + The target architecture is the instruction set architecture (ISA) of the + ${target:/term}. Some RTEMS features depend on the target architecture. For + the details consult the *RTEMS CPU Architecture Supplement*. +type: glossary diff --git a/spec/constraint/cpu-simple-vectored-interrupts.yml b/spec/constraint/cpu-simple-vectored-interrupts.yml new file mode 100644 index 00000000..30878e5f --- /dev/null +++ b/spec/constraint/cpu-simple-vectored-interrupts.yml @@ -0,0 +1,11 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +links: [] +rationale: null +scope: user +text: | + The directive is only available where the ${/glossary/target-arch:/term} + support enabled simple vectored interrupts. +type: constraint diff --git a/spec/constraint/interrupt-enable.yml b/spec/constraint/interrupt-enable.yml new file mode 100644 index 00000000..67663129 --- /dev/null +++ b/spec/constraint/interrupt-enable.yml @@ -0,0 +1,13 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +links: [] +rationale: null +scope: user +text: | + While at least one maskable interrupt is pending, when the directive enables + maskable interrupts, the pending interrupts are immediately serviced. The + interrupt service routines may unblock higher priority tasks which may + preempt the calling task. +type: constraint diff --git a/spec/constraint/no-impl.yml b/spec/constraint/no-impl.yml new file mode 100644 index 00000000..338c1b99 --- /dev/null +++ b/spec/constraint/no-impl.yml @@ -0,0 +1,10 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +links: [] +rationale: null +scope: user +text: | + The directive is not implemented. +type: constraint diff --git a/spec/rtems/intr/constraint/no-smp.yml b/spec/rtems/intr/constraint/no-smp.yml new file mode 100644 index 00000000..401d6875 --- /dev/null +++ b/spec/rtems/intr/constraint/no-smp.yml @@ -0,0 +1,13 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +links: [] +rationale: null +scope: user +text: | + Where the system was built with SMP support enabled, the directive is not + available. Its use will result in compiler warnings and linker errors. The + ${../if/local-disable:/name} and ${../if/local-enable:/name} directives are + available in all build configurations. +type: constraint diff --git a/spec/rtems/intr/if/catch.yml b/spec/rtems/intr/if/catch.yml index 8ab54be6..14dd7feb 100644 --- a/spec/rtems/intr/if/catch.yml +++ b/spec/rtems/intr/if/catch.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Establishes an interrupt service routine. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: @@ -13,28 +14,65 @@ definition: - ${isr-entry:/name} *${.:/params[2]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive establishes an interrupt service routine (ISR) for the + interrupt specified by the ${.:/params[1]/name} number. The + ${.:/params[0]/name} parameter specifies the entry point of the ISR. The + entry point of the previous ISR for the specified vector is returned in + ${.:/params[2]/name}. + + To release an interrupt vector, pass the old handler's address obtained when + the vector was first capture. enabled-by: true -index-entries: [] +index-entries: +- establish an ISR +- install an ISR interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-isr +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/directive-no-preempt +- role: constraint + uid: /constraint/cpu-simple-vectored-interrupts name: rtems_interrupt_catch notes: null params: -- description: '%' +- description: | + is the new interrupt service routine. dir: null name: new_isr_handler -- description: '%' +- description: | + is the interrupt vector number. dir: null name: vector -- description: '%' - dir: null +- description: | + is the pointer to an ${isr-entry:/name} variable. When the directive call + is successful, the previous interrupt service routine established for this + interrupt vector will be stored in this variable. + dir: out name: old_isr_handler return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + The interrupt vector number was illegal. + value: ${../../status/if/invalid-number:/name} + - description: | + The ${.:/params[0]/name} parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + The ${.:/params[2]/name} parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} type: interface diff --git a/spec/rtems/intr/if/cause.yml b/spec/rtems/intr/if/cause.yml index f22fecac..0ab332e8 100644 --- a/spec/rtems/intr/if/cause.yml +++ b/spec/rtems/intr/if/cause.yml @@ -1,10 +1,12 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Causes the interrupt. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: - default: '%' + default: | + do { } while ( 0 ) variants: [] description: null enabled-by: true @@ -15,12 +17,15 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/no-impl name: rtems_interrupt_cause notes: null params: -- description: '%' +- description: | + is the vector number of the interrupt to cause. dir: null - name: _interrupt_to_cause + name: _vector return: return: null return-values: [] diff --git a/spec/rtems/intr/if/clear.yml b/spec/rtems/intr/if/clear.yml index 3004ab2d..f92bbede 100644 --- a/spec/rtems/intr/if/clear.yml +++ b/spec/rtems/intr/if/clear.yml @@ -1,10 +1,12 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Clears the interrupt. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: - default: '%' + default: | + do { } while ( 0 ) variants: [] description: null enabled-by: true @@ -15,12 +17,15 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/no-impl name: rtems_interrupt_clear notes: null params: -- description: '%' +- description: | + is the vector number of the interrupt to clear. dir: null - name: _interrupt_to_clear + name: _vector return: return: null return-values: [] diff --git a/spec/rtems/intr/if/disable.yml b/spec/rtems/intr/if/disable.yml index 72856248..08208e7d 100644 --- a/spec/rtems/intr/if/disable.yml +++ b/spec/rtems/intr/if/disable.yml @@ -1,26 +1,77 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Disables the maskable interrupts on the current processor. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/local-disable:/name}( ${.:/params[0]/name} ) variants: [] -description: null +description: | + This directive disables all maskable interrupts on the current processor and + returns the previous interrupt level in ${.:/params[0]/name}. enabled-by: not: RTEMS_SMP -index-entries: [] +index-entries: +- disable interrupts interface-type: macro links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-any +- role: constraint + uid: /constraint/directive-no-preempt +- role: constraint + uid: ../constraint/no-smp name: rtems_interrupt_disable -notes: null +notes: | + A later invocation of the ${enable:/name} directive should be used to restore + the previous interrupt level. + + This directive is implemented as a macro which sets the ${.:/params[0]/name} + parameter. + + .. code-block:: c + :linenos: + + #include + + void local_critical_section( void ) + { + rtems_interrupt_level level; + + // Please note that the rtems_interrupt_disable() is a macro. The + // previous interrupt level (before the maskable interrupts are + // disabled) is returned here in the level macro parameter. This + // would be wrong: + // + // rtems_interrupt_disable( &level ); + rtems_interrupt_disable( level ); + + // Here is the critical section: maskable interrupts are disabled + + { + rtems_interrupt_level nested_level; + + rtems_interrupt_disable( nested_level ); + + // Here is a nested critical section + + rtems_interrupt_enable( nested_level ); + } + + // Maskable interrupts are still disabled + + rtems_interrupt_enable( level ); + } params: -- description: '%' - dir: null +- description: | + is a variable of type ${level:/name} which will be used to save the + previous interrupt level. + dir: out name: _isr_cookie return: return: null diff --git a/spec/rtems/intr/if/enable.yml b/spec/rtems/intr/if/enable.yml index 49a6a024..97d7dbf4 100644 --- a/spec/rtems/intr/if/enable.yml +++ b/spec/rtems/intr/if/enable.yml @@ -1,26 +1,47 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Restores the previous interrupt level on the current processor. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/local-enable:/name}( ${.:/params[0]/name} ) variants: [] -description: null +description: | + This directive restores the interrupt level specified by + ${.:/params[0]/name} on the current processor. enabled-by: not: RTEMS_SMP -index-entries: [] +index-entries: +- enable interrupts +- restore interrupt level interface-type: macro links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-any +- role: constraint + uid: /constraint/directive-no-preempt +- role: constraint + uid: /constraint/interrupt-enable +- role: constraint + uid: ../constraint/no-smp name: rtems_interrupt_enable -notes: null +notes: | + The ${.:/params[0]/name} parameter value must be obtained by a previous + call to ${disable:/name} or ${flash:/name}. Using an otherwise obtained + value is undefined behaviour. + + This directive is unsuitable to enable particular interrupt sources, for + example in an interrupt controller. params: -- description: '%' - dir: null +- description: | + is the previous interrupt level to restore. The value must be obtained by + a previous call to ${disable:/name} or ${flash:/name}. + dir: in name: _isr_cookie return: return: null diff --git a/spec/rtems/intr/if/flash.yml b/spec/rtems/intr/if/flash.yml index 2832326a..05e8ef76 100644 --- a/spec/rtems/intr/if/flash.yml +++ b/spec/rtems/intr/if/flash.yml @@ -1,26 +1,45 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Flashes interrupts on the current processor. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/local-flash:/name}( ${.:/params[0]/name} ) variants: [] -description: null +description: | + This directive is functionally equivalent to a calling ${enable:/name} + immediately followed by a ${disable:/name}. On some architectures it is + possible to provide an optimized implementation for this sequence. enabled-by: not: RTEMS_SMP -index-entries: [] +index-entries: +- flash interrupts interface-type: macro links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-any +- role: constraint + uid: /constraint/directive-no-preempt +- role: constraint + uid: ../constraint/no-smp name: rtems_interrupt_flash -notes: null +notes: | + The ${.:/params[0]/name} parameter value must be obtained by a previous + call to ${disable:/name} or ${flash:/name}. Using an otherwise obtained + value is undefined behaviour. + + Historically, the interrupt flash directive was heavily used in the + operating system implementation. However, this is no longer the case. The + interrupt flash directive is provided for backward compatibility reasons. params: -- description: '%' - dir: null +- description: | + is the previous interrupt level. + dir: inout name: _isr_cookie return: return: null diff --git a/spec/rtems/intr/if/group.yml b/spec/rtems/intr/if/group.yml index 43c7651a..22a0e229 100644 --- a/spec/rtems/intr/if/group.yml +++ b/spec/rtems/intr/if/group.yml @@ -7,7 +7,7 @@ brief: | ability to alter task execution which allows a task to be preempted upon exit from an ISR. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) description: null enabled-by: true @@ -19,6 +19,48 @@ links: uid: header - role: interface-ingroup uid: ../../if/group +- role: placement-order + uid: catch +- role: placement-order + uid: disable +- role: placement-order + uid: enable +- role: placement-order + uid: flash +- role: placement-order + uid: local-disable +- role: placement-order + uid: local-enable +- role: placement-order + uid: is-in-progress +- role: placement-order + uid: cause +- role: placement-order + uid: clear +- role: placement-order + uid: lock-initialize +- role: placement-order + uid: lock-destroy +- role: placement-order + uid: lock-acquire +- role: placement-order + uid: lock-release +- role: placement-order + uid: lock-acquire-isr +- role: placement-order + uid: lock-release-isr +- role: placement-order + uid: lock-isr-disable +- role: placement-order + uid: lock-declare +- role: placement-order + uid: lock-define +- role: placement-order + uid: lock-initializer +- role: placement-order + uid: lock-member +- role: placement-order + uid: lock-reference name: Interrupt Manager text: | The Classic API shall provide an interface to the Interrupt Manager. diff --git a/spec/rtems/intr/if/header.yml b/spec/rtems/intr/if/header.yml index ce24f473..dd23f997 100644 --- a/spec/rtems/intr/if/header.yml +++ b/spec/rtems/intr/if/header.yml @@ -1,7 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: This header file defines the Interrupt Manager API. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) enabled-by: true index-entries: [] interface-type: header-file diff --git a/spec/rtems/intr/if/is-in-progress.yml b/spec/rtems/intr/if/is-in-progress.yml index 3d9ded00..0ced88d1 100644 --- a/spec/rtems/intr/if/is-in-progress.yml +++ b/spec/rtems/intr/if/is-in-progress.yml @@ -1,24 +1,36 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Checks if an ISR is in progress on the current processor. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/is-in-progress:/name}() variants: [] -description: null +description: | + This directive returns ``true``, if the current processor is currently + servicing an interrupt, and ``false`` otherwise. A return value of ``true`` + indicates that the caller is an interrupt service routine, **not** a task. + The directives available to an interrupt service routine are restricted. enabled-by: true -index-entries: [] +index-entries: +- is interrupt in progress interface-type: macro links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-any +- role: constraint + uid: /constraint/directive-no-preempt name: rtems_interrupt_is_in_progress notes: null params: [] return: - return: null + return: | + Returns true, if the current processor is currently servicing an interrupt, + otherwise false. return-values: [] type: interface diff --git a/spec/rtems/intr/if/isr-entry.yml b/spec/rtems/intr/if/isr-entry.yml index 5f5b1d0b..fa4c706a 100644 --- a/spec/rtems/intr/if/isr-entry.yml +++ b/spec/rtems/intr/if/isr-entry.yml @@ -3,7 +3,7 @@ brief: | Interrupt service routines installed by ${catch:/name} shall have this function pointer type. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: void ( *${.:/name} )( void * ) diff --git a/spec/rtems/intr/if/isr.yml b/spec/rtems/intr/if/isr.yml index e1247657..e0952248 100644 --- a/spec/rtems/intr/if/isr.yml +++ b/spec/rtems/intr/if/isr.yml @@ -1,12 +1,15 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This type defines the return type of interrupt service routines. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/handler:/name} ${.:/name} variants: [] -description: null +description: | + This type can be used to document interrupt service routines in the source + code. enabled-by: true index-entries: [] interface-type: typedef diff --git a/spec/rtems/intr/if/level.yml b/spec/rtems/intr/if/level.yml index d102f3ef..0f69faf6 100644 --- a/spec/rtems/intr/if/level.yml +++ b/spec/rtems/intr/if/level.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This integer type represents interrupt levels. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/level:/name} ${.:/name} diff --git a/spec/rtems/intr/if/local-disable.yml b/spec/rtems/intr/if/local-disable.yml index 92826ccf..baee1537 100644 --- a/spec/rtems/intr/if/local-disable.yml +++ b/spec/rtems/intr/if/local-disable.yml @@ -1,25 +1,79 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Disables the maskable interrupts on the current processor. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/local-disable:/name}( ${.:/params[0]/name} ) variants: [] -description: null +description: | + This directive disables all maskable interrupts on the current processor and + returns the previous interrupt level in ${.:/params[0]/name}. enabled-by: true -index-entries: [] +index-entries: +- disable interrupts interface-type: macro links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-any +- role: constraint + uid: /constraint/directive-no-preempt name: rtems_interrupt_local_disable -notes: null +notes: | + A later invocation of the ${local-enable:/name} directive should be used to + restore the previous interrupt level. + + This directive is implemented as a macro which sets the ${.:/params[0]/name} + parameter. + + Where the system was built with SMP support enabled, this will not ensure + system wide mutual exclusion. Use interrupt locks instead, see + ${lock-acquire:/name}. Interrupt disabled critical sections may be used to + access processor-specific data structures or disable thread dispatching. + + .. code-block:: c + :linenos: + + #include + + void local_critical_section( void ) + { + rtems_interrupt_level level; + + // Please note that the rtems_interrupt_local_disable() is a macro. + // The previous interrupt level (before the maskable interrupts are + // disabled) is returned here in the level macro parameter. This would + // be wrong: + // + // rtems_interrupt_local_disable( &level ); + rtems_interrupt_local_disable( level ); + + // Here is the critical section: maskable interrupts are disabled + + { + rtems_interrupt_level nested_level; + + rtems_interrupt_local_disable( nested_level ); + + // Here is a nested critical section + + rtems_interrupt_local_enable( nested_level ); + } + + // Maskable interrupts are still disabled + + rtems_interrupt_local_enable( level ); + } params: -- description: '%' - dir: null +- description: | + is a variable of type ${level:/name} which will be used to save the + previous interrupt level. + dir: out name: _isr_cookie return: return: null diff --git a/spec/rtems/intr/if/local-enable.yml b/spec/rtems/intr/if/local-enable.yml index 2091377b..da08a124 100644 --- a/spec/rtems/intr/if/local-enable.yml +++ b/spec/rtems/intr/if/local-enable.yml @@ -1,25 +1,44 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Restores the previous interrupt level on the current processor. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/local-enable:/name}( ${.:/params[0]/name} ) variants: [] -description: null +description: | + This directive restores the interrupt level specified by + ${.:/params[0]/name} on the current processor. enabled-by: true -index-entries: [] +index-entries: +- enable interrupts +- restore interrupt level interface-type: macro links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-any +- role: constraint + uid: /constraint/directive-no-preempt +- role: constraint + uid: /constraint/interrupt-enable name: rtems_interrupt_local_enable -notes: null +notes: | + The ${.:/params[0]/name} parameter value must be obtained by a previous call + to ${local-disable:/name}. Using an otherwise obtained value is undefined + behaviour. + + This directive is unsuitable to enable particular interrupt sources, for + example in an interrupt controller. params: -- description: '%' - dir: null +- description: | + is the previous interrupt level to restore. The value must be obtained by + a previous call to ${local-disable:/name}. + dir: in name: _isr_cookie return: return: null diff --git a/spec/rtems/intr/if/lock-acquire-isr.yml b/spec/rtems/intr/if/lock-acquire-isr.yml index 5fb41dd9..fe0e03d4 100644 --- a/spec/rtems/intr/if/lock-acquire-isr.yml +++ b/spec/rtems/intr/if/lock-acquire-isr.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Acquires the ISR lock from within an ISR. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: do { (void) ${.:/params[1]/name}; } while ( 0 ) @@ -12,7 +13,10 @@ definition: &( ${.:/params[1]/name} )->Lock_context ) enabled-by: defined(${/build-options/if/smp:/name}) -description: null +description: | + This directive acquires the ISR lock specified by ${.:/params[0]/name} using + the lock context provided by ${.:/params[1]/name}. The interrupt level will + remain unchanged. enabled-by: true index-entries: [] interface-type: macro @@ -21,14 +25,36 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-any +- role: constraint + uid: /constraint/directive-no-preempt name: rtems_interrupt_lock_acquire_isr -notes: null +notes: | + A caller-specific lock context shall be provided for each acquire/release + pair, for example an automatic variable. + + Where the system was built with SMP support enabled, this directive acquires + an SMP lock. An attempt to recursively acquire the lock may result in an + infinite loop. + + This directive is intended for device drivers and should be called from the + corresponding interrupt service routine. + + In case the corresponding interrupt service routine can be interrupted by + higher priority interrupts and these interrupts enter the critical section + protected by this lock, then the result is unpredictable. This directive may + be used under specific circumstances as an optimization. In doubt, use + ${lock-acquire:/name} and ${lock-release:/name}. params: -- description: '%' - dir: null +- description: | + is the ISR lock to acquire within an ISR. + dir: inout name: _lock -- description: '%' - dir: null +- description: | + is the ISR lock context. This lock context shall be used to release the + lock by calling ${lock-release-isr:/name}. + dir: out name: _lock_context return: return: null diff --git a/spec/rtems/intr/if/lock-acquire.yml b/spec/rtems/intr/if/lock-acquire.yml index c4f7185a..7c05fd94 100644 --- a/spec/rtems/intr/if/lock-acquire.yml +++ b/spec/rtems/intr/if/lock-acquire.yml @@ -1,13 +1,17 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Acquires the ISR lock. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: | ${/score/isr/if/lock-isr-disable-acquire:/name}( ${.:/params[0]/name}, ${.:/params[1]/name} ) variants: [] -description: null +description: | + This directive acquires the ISR lock specified by ${.:/params[0]/name} using + the lock context provided by ${.:/params[1]/name}. Maskable interrupts will + be disabled on the current processor. enabled-by: true index-entries: [] interface-type: macro @@ -16,14 +20,48 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-any +- role: constraint + uid: /constraint/directive-no-preempt name: rtems_interrupt_lock_acquire -notes: null +notes: | + A caller-specific lock context shall be provided for each acquire/release + pair, for example an automatic variable. + + Where the system was built with SMP support enabled, this directive acquires + an SMP lock. An attempt to recursively acquire the lock may result in an + infinite loop with maskable interrupts disabled. + + This directive establishes a non-preemptive critical section with system wide + mutual exclusion on the local node in all RTEMS build configurations. + + .. code-block:: c + :linenos: + + #include + + void critical_section( rtems_interrupt_lock *lock ) + { + rtems_interrupt_lock_context lock_context; + + rtems_interrupt_lock_acquire( lock, &lock_context ); + + // Here is the critical section. Maskable interrupts are disabled. + // Where the system was built with SMP support enabled, this section + // is protected by an SMP lock. + + rtems_interrupt_lock_release( lock, &lock_context ); + } params: -- description: '%' - dir: null +- description: | + is the ISR lock to acquire. + dir: inout name: _lock -- description: '%' - dir: null +- description: | + is the ISR lock context. This lock context shall be used to release the + lock by calling ${lock-release:/name}. + dir: out name: _lock_context return: return: null diff --git a/spec/rtems/intr/if/lock-context.yml b/spec/rtems/intr/if/lock-context.yml index d85e2354..10ddbf7d 100644 --- a/spec/rtems/intr/if/lock-context.yml +++ b/spec/rtems/intr/if/lock-context.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This structure provides an ISR lock context for acquire and release pairs. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/lock-context:/name} ${.:/name} diff --git a/spec/rtems/intr/if/lock-declare.yml b/spec/rtems/intr/if/lock-declare.yml index 105ec99e..3f42f2ea 100644 --- a/spec/rtems/intr/if/lock-declare.yml +++ b/spec/rtems/intr/if/lock-declare.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Declares an ISR lock object. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: | @@ -17,12 +18,16 @@ links: - role: interface-ingroup uid: group name: RTEMS_INTERRUPT_LOCK_DECLARE -notes: null +notes: | + Do not add a ";" after this macro. params: -- description: '%' +- description: | + is the storage-class specifier for the ISR lock to declare, for example ``extern`` + or ``static``. dir: null - name: _qualifier -- description: '%' + name: _specifier +- description: | + is the ISR lock object designator. dir: null name: _designator return: diff --git a/spec/rtems/intr/if/lock-define.yml b/spec/rtems/intr/if/lock-define.yml index b45b5ecc..378a1026 100644 --- a/spec/rtems/intr/if/lock-define.yml +++ b/spec/rtems/intr/if/lock-define.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Defines an ISR lock object. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: | @@ -17,15 +18,24 @@ links: - role: interface-ingroup uid: group name: RTEMS_INTERRUPT_LOCK_DEFINE -notes: null +notes: | + Do not add a ";" after this macro. + + ISR locks may also be dynamically initialized by ${lock-initialize:/name} or + statically by ${lock-initializer:/name}. params: -- description: '%' +- description: | + is the storage-class specifier for the ISR lock to declare, for example ``extern`` + or ``static``. dir: null - name: _qualifier -- description: '%' + name: _specifier +- description: | + is the ISR lock object designator. dir: null name: _designator -- description: '%' +- description: | + is the ISR lock name. It shall be a string. The name is only used where + the system was built with profiling support enabled. dir: null name: _name return: diff --git a/spec/rtems/intr/if/lock-destroy.yml b/spec/rtems/intr/if/lock-destroy.yml index e769dc4d..d69da341 100644 --- a/spec/rtems/intr/if/lock-destroy.yml +++ b/spec/rtems/intr/if/lock-destroy.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Destroys the ISR lock. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/lock-destroy:/name}( ${.:/params[0]/name} ) @@ -15,11 +16,22 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-any +- role: constraint + uid: /constraint/directive-no-preempt name: rtems_interrupt_lock_destroy -notes: null +notes: | + The lock must have been dynamically initialized by ${lock-initialize:/name}, + statically defined by ${lock-define:/name}, or statically initialized by + ${lock-initializer:/name}. + + Concurrent lock use during the destruction or concurrent destruction leads to + unpredictable results. params: -- description: '%' - dir: null +- description: | + is the ISR lock to destroy. + dir: inout name: _lock return: return: null diff --git a/spec/rtems/intr/if/lock-initialize.yml b/spec/rtems/intr/if/lock-initialize.yml index 69a3a443..d9922e7f 100644 --- a/spec/rtems/intr/if/lock-initialize.yml +++ b/spec/rtems/intr/if/lock-initialize.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Initializes the ISR lock. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: | @@ -17,12 +18,17 @@ links: - role: interface-ingroup uid: group name: rtems_interrupt_lock_initialize -notes: null +notes: | + ISR locks may also be statically defined by ${lock-define:/name} or + statically initialized by ${lock-initializer:/name}. params: -- description: '%' - dir: null +- description: | + is the ISR lock to initialize. + dir: out name: _lock -- description: '%' +- description: | + is the ISR lock name. It shall be a string. The name is only used where + the system was built with profiling support enabled. dir: null name: _name return: diff --git a/spec/rtems/intr/if/lock-initializer.yml b/spec/rtems/intr/if/lock-initializer.yml index c57b1729..fb100549 100644 --- a/spec/rtems/intr/if/lock-initializer.yml +++ b/spec/rtems/intr/if/lock-initializer.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Statically initializes an ISR lock object. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/lock-initializer:/name}( ${.:/params[0]/name} ) @@ -16,9 +17,13 @@ links: - role: interface-ingroup uid: group name: RTEMS_INTERRUPT_LOCK_INITIALIZER -notes: null +notes: | + ISR locks may also be dynamically initialized by ${lock-initialize:/name} or + statically defined by ${lock-define:/name}. params: -- description: '%' +- description: | + is the ISR lock name. It shall be a string. The name is only used where + the system was built with profiling support enabled. dir: null name: _name return: diff --git a/spec/rtems/intr/if/lock-isr-disable.yml b/spec/rtems/intr/if/lock-isr-disable.yml index 088e00f8..acf184b3 100644 --- a/spec/rtems/intr/if/lock-isr-disable.yml +++ b/spec/rtems/intr/if/lock-isr-disable.yml @@ -1,12 +1,15 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Disables maskable interrupts on the current processor. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/lock-isr-disable:/name}( ${.:/params[0]/name} ) variants: [] -description: null +description: | + This directive disables maskable interrupts on the current processor and + stores the previous interrupt level in ${.:/params[0]/name}. enabled-by: true index-entries: [] interface-type: macro @@ -15,11 +18,16 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-any +- role: constraint + uid: /constraint/directive-no-preempt name: rtems_interrupt_lock_interrupt_disable notes: null params: -- description: '%' - dir: null +- description: | + is the ISR lock context for an acquire and release pair. + dir: out name: _lock_context return: return: null diff --git a/spec/rtems/intr/if/lock-member.yml b/spec/rtems/intr/if/lock-member.yml index 5a463730..a5035ef5 100644 --- a/spec/rtems/intr/if/lock-member.yml +++ b/spec/rtems/intr/if/lock-member.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Defines an ISR lock member. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/lock-member:/name}( ${.:/params[0]/name} ) @@ -16,9 +17,11 @@ links: - role: interface-ingroup uid: group name: RTEMS_INTERRUPT_LOCK_MEMBER -notes: null +notes: | + Do not add a ";" after this macro. params: -- description: '%' +- description: | + is the ISR lock member designator. dir: null name: _designator return: diff --git a/spec/rtems/intr/if/lock-reference.yml b/spec/rtems/intr/if/lock-reference.yml index abc443af..3aa3f7e9 100644 --- a/spec/rtems/intr/if/lock-reference.yml +++ b/spec/rtems/intr/if/lock-reference.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Defines an ISR lock object reference. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: | @@ -17,12 +18,15 @@ links: - role: interface-ingroup uid: group name: RTEMS_INTERRUPT_LOCK_REFERENCE -notes: null +notes: | + Do not add a ";" after this macro. params: -- description: '%' +- description: | + is the ISR lock reference designator. dir: null name: _designator -- description: '%' +- description: | + is the target object to reference. dir: null name: _target return: diff --git a/spec/rtems/intr/if/lock-release-isr.yml b/spec/rtems/intr/if/lock-release-isr.yml index 647178d8..d82a7d52 100644 --- a/spec/rtems/intr/if/lock-release-isr.yml +++ b/spec/rtems/intr/if/lock-release-isr.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Releases the ISR lock from within an ISR. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: do { (void) ${.:/params[1]/name}; } while ( 0 ) @@ -12,7 +13,10 @@ definition: &( ${.:/params[1]/name} )->Lock_context ) enabled-by: defined(${/build-options/if/smp:/name}) -description: null +description: | + This directive releases the ISR lock specified by ${.:/params[0]/name} using + the lock context provided by ${.:/params[1]/name}. The interrupt level will + remain unchanged. enabled-by: true index-entries: [] interface-type: macro @@ -21,14 +25,26 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-any +- role: constraint + uid: /constraint/directive-no-preempt name: rtems_interrupt_lock_release_isr -notes: null +notes: | + The lock context shall be the one used to acquire the lock, otherwise the + result is unpredictable. + + Where the system was built with SMP support enabled, this directive releases + an SMP lock. params: -- description: '%' - dir: null +- description: | + is the ISR lock to release within an ISR. + dir: inout name: _lock -- description: '%' - dir: null +- description: | + is the ISR lock context. This lock context shall have been used to acquire + the lock by calling ${lock-acquire-isr:/name}. + dir: inout name: _lock_context return: return: null diff --git a/spec/rtems/intr/if/lock-release.yml b/spec/rtems/intr/if/lock-release.yml index 39e5dfa0..f407413a 100644 --- a/spec/rtems/intr/if/lock-release.yml +++ b/spec/rtems/intr/if/lock-release.yml @@ -1,13 +1,17 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Releases the ISR lock. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: | ${/score/isr/if/lock-release-isr-enable:/name}( ${.:/params[0]/name}, ${.:/params[1]/name} ) variants: [] -description: null +description: | + This directive releases the ISR lock specified by ${.:/params[0]/name} using + the lock context provided by ${.:/params[1]/name}. The previous interrupt + level will be restored on the current processor. enabled-by: true index-entries: [] interface-type: macro @@ -16,14 +20,28 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-any +- role: constraint + uid: /constraint/directive-no-preempt +- role: constraint + uid: /constraint/interrupt-enable name: rtems_interrupt_lock_release -notes: null +notes: | + The lock context shall be the one used to acquire the lock, otherwise the + result is unpredictable. + + Where the system was built with SMP support enabled, this directive releases + an SMP lock. params: -- description: '%' - dir: null +- description: | + is the ISR lock to release. + dir: inout name: _lock -- description: '%' - dir: null +- description: | + is the ISR lock context. This lock context shall have been used to acquire + the lock by calling ${lock-acquire:/name}. + dir: inout name: _lock_context return: return: null diff --git a/spec/rtems/intr/if/lock.yml b/spec/rtems/intr/if/lock.yml index 04148dd6..3d30cca3 100644 --- a/spec/rtems/intr/if/lock.yml +++ b/spec/rtems/intr/if/lock.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This structure represents an ISR lock. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/lock-control:/name} ${.:/name} diff --git a/spec/rtems/intr/if/vector-number.yml b/spec/rtems/intr/if/vector-number.yml index 29808e01..5b7f5b29 100644 --- a/spec/rtems/intr/if/vector-number.yml +++ b/spec/rtems/intr/if/vector-number.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This integer type represents interrupt vector numbers. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/isr/if/vector-number:/name} ${.:/name} -- cgit v1.2.3