source: rtems-central/spec/rtems/userext/if/create.yml @ 45b6997

Last change on this file since 45b6997 was 45b6997, checked in by Sebastian Huber <sebastian.huber@…>, on 01/13/21 at 13:05:42

spec: Document all create directives

  • Property mode set to 100644
File size: 3.2 KB
RevLine 
[3e061f5]1SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
[45b6997]2brief: |
3  Creates an extension set.
[3e061f5]4copyrights:
[45b6997]5- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
[3e061f5]6- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
7definition:
8  default:
[d3edaca]9    attributes: null
[3e061f5]10    body: null
11    params:
[3bdf817]12    - ${../../type/if/name:/name} ${.:/params[0]/name}
[3e061f5]13    - const ${table:/name} *${.:/params[1]/name}
[3bdf817]14    - ${../../type/if/id:/name} *${.:/params[2]/name}
15    return: ${../../status/if/code:/name}
[3e061f5]16  variants: []
[45b6997]17description: |
18  This directive creates an extension set which resides on the local node.  The
19  extension set has the user-defined object name specified in
20  ${.:/params[0]/name}.  The assigned object identifier is returned in
21  ${.:/params[2]/name}.  This identifier is used to access the extension set
22  with other extension set related directives.
23
24  The extension set is initialized using the extension table specified in
25  ${.:/params[1]/name}.
[3e061f5]26enabled-by: true
[45b6997]27index-entries:
28- create an extension set
[3e061f5]29interface-type: function
30links:
31- role: interface-placement
32  uid: header
33- role: interface-ingroup
[cead53e]34  uid: group
[45b6997]35- role: constraint
36  uid: /constraint/directive-ctx-devinit
37- role: constraint
38  uid: /constraint/directive-ctx-task
39- role: constraint
40  uid: /constraint/object-allocator
41- role: constraint
42  uid: ../constraint/max
[3e061f5]43name: rtems_extension_create
[45b6997]44notes: |
45  The user-provided extension set table is not used after the return of the
46  directive.
47
48  Newly created extension sets are immediately installed and are invoked upon
49  the next system event supporting an extension.
50
51  An alternative to dynamically created extension sets are initial extensions,
52  see ${/acfg/if/initial-extensions:/name}.  Initial extensions are recommended
53  for extension sets which provide a fatal error extension.
54
55  For control and maintenance of the extension set, RTEMS allocates a
56  ${/glossary/escb:/term} from the local ESCB free pool and initializes it.
[3e061f5]57params:
[45b6997]58- description: |
59    is the object name of the extension set.
[3e061f5]60  dir: null
61  name: name
[45b6997]62- description: |
[3e061f5]63  dir: null
64  name: extension_table
[45b6997]65- description: |
66    is the pointer to an object identifier variable.  The identifier of the
67    created extension set will be stored in this variable, in case of a
68    successful operation.
69  dir: out
[3e061f5]70  name: id
71return:
72  return: null
[45b6997]73  return-values:
74  - description: |
75      The requested operation was successful.
76    value: ${../../status/if/successful:/name}
77  - description: |
78      The ${.:/params[0]/name} parameter was invalid.
79    value: ${../../status/if/invalid-name:/name}
80  - description: |
81      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
82    value: ${../../status/if/invalid-address:/name}
83  - description: |
84      The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
85    value: ${../../status/if/invalid-address:/name}
86  - description: |
87      There was no inactive object available to create an extension set.  The
88      number of extension sets available to the application is configured
89      through the ${/acfg/if/max-user-extensions:/name} application
90      configuration option.
91    value: ${../../status/if/too-many:/name}
[3e061f5]92type: interface
Note: See TracBrowser for help on using the repository browser.