diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-01-19 07:48:35 +0100 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-02-03 06:26:37 +0100 |
commit | f665caf3a8dc0054ce0c28c9943ab337168850b1 (patch) | |
tree | 75f2c7f56655e8270fcdc28ef399bd67ac6039a5 /spec | |
parent | spec: Document all create directives (diff) | |
download | rtems-central-f665caf3a8dc0054ce0c28c9943ab337168850b1.tar.bz2 |
spec: Document all delete directives
Diffstat (limited to 'spec')
-rw-r--r-- | spec/rtems/barrier/if/delete.yml | 38 | ||||
-rw-r--r-- | spec/rtems/dpmem/if/delete.yml | 36 | ||||
-rw-r--r-- | spec/rtems/message/if/delete.yml | 57 | ||||
-rw-r--r-- | spec/rtems/part/if/delete.yml | 25 | ||||
-rw-r--r-- | spec/rtems/ratemon/if/delete.yml | 37 | ||||
-rw-r--r-- | spec/rtems/region/if/delete.yml | 41 | ||||
-rw-r--r-- | spec/rtems/sem/if/delete.yml | 58 | ||||
-rw-r--r-- | spec/rtems/task/if/delete.yml | 64 | ||||
-rw-r--r-- | spec/rtems/timer/if/delete.yml | 21 | ||||
-rw-r--r-- | spec/rtems/userext/if/delete.yml | 35 |
10 files changed, 338 insertions, 74 deletions
diff --git a/spec/rtems/barrier/if/delete.yml b/spec/rtems/barrier/if/delete.yml index fd22d0f3..1fc73962 100644 --- a/spec/rtems/barrier/if/delete.yml +++ b/spec/rtems/barrier/if/delete.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Deletes the barrier. 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: @@ -11,22 +12,45 @@ definition: - ${../../type/if/id:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive deletes the barrier specified by ${.:/params[0]/name}. All + tasks blocked waiting for the barrier to be released will be readied and + returned a status code which indicates that the barrier was deleted. enabled-by: true -index-entries: [] +index-entries: +- delete a barrier interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/object-allocator +- role: constraint + uid: ../../constraint/delete-by-any-task +- role: constraint + uid: /constraint/obj-unlimited-free name: rtems_barrier_delete -notes: null +notes: | + The ${/glossary/bcb:/term} for the deleted barrier is reclaimed by RTEMS. params: -- description: '%' +- description: | + is the barrier identifier. dir: null name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no barrier associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} type: interface diff --git a/spec/rtems/dpmem/if/delete.yml b/spec/rtems/dpmem/if/delete.yml index b7567b84..1b3f0183 100644 --- a/spec/rtems/dpmem/if/delete.yml +++ b/spec/rtems/dpmem/if/delete.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Deletes the port. 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: @@ -11,22 +12,43 @@ definition: - ${../../type/if/id:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive deletes the port specified by ${.:/params[0]/name}. enabled-by: true -index-entries: [] +index-entries: +- delete a port interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/object-allocator +- role: constraint + uid: ../../constraint/delete-by-any-task +- role: constraint + uid: /constraint/obj-unlimited-free name: rtems_port_delete -notes: null +notes: | + The ${/glossary/dpcb:/term} for the deleted port is reclaimed by RTEMS. params: -- description: '%' +- description: | + is the port identifier. dir: null name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no port associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} type: interface diff --git a/spec/rtems/message/if/delete.yml b/spec/rtems/message/if/delete.yml index c7c12375..72afc6ca 100644 --- a/spec/rtems/message/if/delete.yml +++ b/spec/rtems/message/if/delete.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Deletes the message queue. 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: @@ -11,22 +12,64 @@ definition: - ${../../type/if/id:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive deletes the message queue specified by ${.:/params[0]/name}. + As a result of this directive, all tasks blocked waiting to receive a message + from this queue will be readied and returned a status code which indicates + that the message queue was deleted. enabled-by: true -index-entries: [] +index-entries: +- delete a message queue interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/object-allocator +- role: constraint + uid: ../../constraint/delete-by-any-task +- role: constraint + uid: /constraint/obj-unlimited-free name: rtems_message_queue_delete -notes: null +notes: | + When the message queue is deleted, any messages in the queue are returned to + the free message buffer pool. Any information stored in those messages is + lost. The message buffers allocated for the message queue are reclaimed. + + The ${/glossary/qcb:/term} for the deleted message queue is reclaimed by + RTEMS. + + When a global message queue is deleted, the message queue identifier must be + transmitted to every node in the system for deletion from the local copy of + the global object table. + + The message queue must reside on the local node, even if the message queue + was created with the ${../../attr/if/global:/name} attribute. + + Proxies, used to represent remote tasks, are reclaimed when the message queue + is deleted. params: -- description: '%' +- description: | + is the message queue identifier. dir: null name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no message queue associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The semaphore resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} type: interface diff --git a/spec/rtems/part/if/delete.yml b/spec/rtems/part/if/delete.yml index 5dad046b..7d2976cb 100644 --- a/spec/rtems/part/if/delete.yml +++ b/spec/rtems/part/if/delete.yml @@ -2,7 +2,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | Deletes the partition. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: @@ -13,9 +13,7 @@ definition: return: ${../../status/if/code:/name} variants: [] description: | - This directive deletes the partition specified by the ${.:/params[0]/name} - parameter. The partition cannot be deleted if any of its buffers are still - allocated. + This directive deletes the partition specified by ${.:/params[0]/name}. enabled-by: true index-entries: - delete a partition @@ -25,16 +23,22 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/object-allocator +- role: constraint + uid: ../../constraint/delete-by-any-task +- role: constraint + uid: /constraint/obj-unlimited-free name: rtems_partition_delete notes: | - This directive may cause the calling task to be preempted due to an obtain - and release of the object allocator mutex. + The partition cannot be deleted if any of its buffers are still allocated. The ${/glossary/ptcb:/term} for the deleted partition is reclaimed by RTEMS. - The calling task does not have to be the task that created the partition. - Any local task that knows the partition identifier can delete the partition. - When a global partition is deleted, the partition identifier must be transmitted to every node in the system for deletion from the local copy of the global object table. @@ -42,7 +46,8 @@ notes: | The partition must reside on the local node, even if the partition was created with the ${../../attr/if/global:/name} attribute. params: -- description: is the partition identifier. +- description: | + is the partition identifier. dir: null name: id return: diff --git a/spec/rtems/ratemon/if/delete.yml b/spec/rtems/ratemon/if/delete.yml index 7764ac8e..19097a06 100644 --- a/spec/rtems/ratemon/if/delete.yml +++ b/spec/rtems/ratemon/if/delete.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Deletes the period. 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: @@ -11,22 +12,44 @@ definition: - ${../../type/if/id:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive deletes the period specified by ${.:/params[0]/name}. If the + period is running, it is automatically canceled. enabled-by: true -index-entries: [] +index-entries: +- delete a period interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/object-allocator +- role: constraint + uid: ../../constraint/delete-by-any-task +- role: constraint + uid: /constraint/obj-unlimited-free name: rtems_rate_monotonic_delete -notes: null +notes: | + The ${/glossary/pcb:/term} for the deleted period is reclaimed by RTEMS. params: -- description: '%' +- description: | + is the period identifier. dir: null name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no period associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} type: interface diff --git a/spec/rtems/region/if/delete.yml b/spec/rtems/region/if/delete.yml index 8d73049e..d6fd991d 100644 --- a/spec/rtems/region/if/delete.yml +++ b/spec/rtems/region/if/delete.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Deletes the region. 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: @@ -11,22 +12,48 @@ definition: - ${../../type/if/id:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive deletes the region specified by ${.:/params[0]/name}. enabled-by: true -index-entries: [] +index-entries: +- delete a region interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/object-allocator +- role: constraint + uid: ../../constraint/delete-by-any-task +- role: constraint + uid: /constraint/obj-unlimited-free name: rtems_region_delete -notes: null +notes: | + The region cannot be deleted if any of its segments are still allocated. + + The ${/glossary/rncb:/term} for the deleted region is reclaimed by RTEMS. params: -- description: '%' +- description: | + is the region identifier. dir: null name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no region associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + There were segments of the region still in use. + value: ${../../status/if/resource-in-use:/name} type: interface diff --git a/spec/rtems/sem/if/delete.yml b/spec/rtems/sem/if/delete.yml index 103f9998..6b22b603 100644 --- a/spec/rtems/sem/if/delete.yml +++ b/spec/rtems/sem/if/delete.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Deletes the semaphore. 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: @@ -11,22 +12,65 @@ definition: - ${../../type/if/id:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive deletes the semaphore specified by ${.:/params[0]/name}. enabled-by: true -index-entries: [] +index-entries: +- delete a semaphore interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/object-allocator +- role: constraint + uid: ../../constraint/delete-by-any-task +- role: constraint + uid: /constraint/obj-unlimited-free name: rtems_semaphore_delete -notes: null +notes: | + Binary semaphores with an owner cannot be deleted. + + When a semaphore is deleted, all tasks blocked waiting to obtain the + semaphore will be readied and returned a status code which indicates that the + semaphore was deleted. + + The ${/glossary/smcb:/term} for the deleted semaphore is reclaimed by RTEMS. + + When a global semaphore is deleted, the semaphore identifier must be + transmitted to every node in the system for deletion from the local copy of + the global object table. + + The semaphore must reside on the local node, even if the semaphore was + created with the ${../../attr/if/global:/name} attribute. + + Proxies, used to represent remote tasks, are reclaimed when the semaphore is + deleted. params: -- description: '%' +- description: | + is the semaphore identifier. dir: null name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no semaphore associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The semaphore resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} + - description: | + The binary semaphore had an owner. + value: ${../../status/if/resource-in-use:/name} type: interface diff --git a/spec/rtems/task/if/delete.yml b/spec/rtems/task/if/delete.yml index b0df6a99..d34ed0ec 100644 --- a/spec/rtems/task/if/delete.yml +++ b/spec/rtems/task/if/delete.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Deletes the task. 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, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -11,22 +12,71 @@ definition: - ${../../type/if/id:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive deletes the task, either the calling task or another task, as + specified by ${.:/params[0]/name}. enabled-by: true -index-entries: [] +index-entries: +- delete a task interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/object-allocator +- role: constraint + uid: ../../constraint/delete-by-any-task +- role: constraint + uid: /constraint/obj-unlimited-free name: rtems_task_delete -notes: null +notes: | + RTEMS stops the execution of the task and reclaims the stack memory, any + allocated delay or timeout timers, the TCB, and, if the task is + ${../../attr/if/floating-point:/name}, its floating point context area. + RTEMS explicitly does not reclaim the following resources: region segments, + partition buffers, semaphores, timers, or rate monotonic periods. + + A task is responsible for releasing its resources back to RTEMS before + deletion. To insure proper deallocation of resources, a task should not be + deleted unless it is unable to execute or does not hold any RTEMS resources. + If a task holds RTEMS resources, the task should be allowed to deallocate its + resources before deletion. A task can be directed to release its resources + and delete itself by restarting it with a special argument or by sending it a + message, an event, or a signal. + + Deletion of the current task (${self-define:/name}) will force RTEMS to + select another task to execute. + + The ${/glossary/tcb:/term} for the deleted task is reclaimed by RTEMS. + + When a global task is deleted, the task identifier must be transmitted to + every node in the system for deletion from the local copy of the global + object table. + + The task must reside on the local node, even if the task was created with the + ${../../attr/if/global:/name} attribute. params: -- description: '%' +- description: | + is the task identifier. dir: null name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no task associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The task resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} type: interface diff --git a/spec/rtems/timer/if/delete.yml b/spec/rtems/timer/if/delete.yml index 5bc65bdc..975f6526 100644 --- a/spec/rtems/timer/if/delete.yml +++ b/spec/rtems/timer/if/delete.yml @@ -2,7 +2,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | Deletes the timer. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: @@ -13,8 +13,8 @@ definition: return: ${../../status/if/code:/name} variants: [] description: | - This directive deletes the timer specified by the ${.:/params[0]/name} - parameter. If the timer is running, it is automatically canceled. + This directive deletes the timer specified by ${.:/params[0]/name}. If the + timer is running, it is automatically canceled. enabled-by: true index-entries: - delete a timer @@ -24,14 +24,19 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/object-allocator +- role: constraint + uid: ../../constraint/delete-by-any-task +- role: constraint + uid: /constraint/obj-unlimited-free name: rtems_timer_delete notes: | - This directive may cause the calling task to be preempted due to an obtain - and release of the object allocator mutex. - The ${/glossary/tmcb:/term} for the deleted timer is reclaimed by RTEMS. - - A timer can be deleted by a task other than the task which created the timer. params: - description: is the timer identifier. dir: null diff --git a/spec/rtems/userext/if/delete.yml b/spec/rtems/userext/if/delete.yml index b8c37b39..13fa2e2e 100644 --- a/spec/rtems/userext/if/delete.yml +++ b/spec/rtems/userext/if/delete.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Deletes the extension set. 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: @@ -11,22 +12,42 @@ definition: - ${../../type/if/id:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive deletes the extension set specified by ${.:/params[0]/name}. enabled-by: true -index-entries: [] +index-entries: +- delete an extension set interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/object-allocator +- role: constraint + uid: ../../constraint/delete-by-any-task name: rtems_extension_delete -notes: null +notes: | + The ${/glossary/escb:/term} for the deleted extension set is reclaimed by + RTEMS. params: -- description: '%' +- description: | + is the extension set identifier. dir: null name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no extension set associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} type: interface |