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

Last change on this file since 45b6997 was 45b6997, checked in by Sebastian Huber <sebastian.huber@…>, on Jan 13, 2021 at 1:05:42 PM

spec: Document all create directives

  • Property mode set to 100644
File size: 3.2 KB
Line 
1SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
2brief: |
3  Creates a port.
4copyrights:
5- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
6- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
7definition:
8  default:
9    attributes: null
10    body: null
11    params:
12    - ${../../type/if/name:/name} ${.:/params[0]/name}
13    - void *${.:/params[1]/name}
14    - void *${.:/params[2]/name}
15    - ${/c/if/uint32_t:/name} ${.:/params[3]/name}
16    - ${../../type/if/id:/name} *${.:/params[4]/name}
17    return: ${../../status/if/code:/name}
18  variants: []
19description: |
20  This directive creates a port which resides on the local node.  The port has
21  the user-defined object name specified in ${.:/params[0]/name}.  The assigned
22  object identifier is returned in ${.:/params[4]/name}.  This identifier is
23  used to access the port with other dual-ported memory port related
24  directives.
25enabled-by: true
26index-entries:
27- create a port
28interface-type: function
29links:
30- role: interface-placement
31  uid: header
32- role: interface-ingroup
33  uid: group
34- role: constraint
35  uid: /constraint/directive-ctx-devinit
36- role: constraint
37  uid: /constraint/directive-ctx-task
38- role: constraint
39  uid: /constraint/object-allocator
40- role: constraint
41  uid: ../constraint/max
42- role: constraint
43  uid: /constraint/obj-unlimited-alloc
44name: rtems_port_create
45notes: |
46  The ${.:/params[1]/name} and ${.:/params[2]/name} parameters must be on a
47  boundary defined by the target processor architecture.
48
49  For control and maintenance of the port, RTEMS allocates a
50  ${/glossary/dpcb:/term} from the local DPCB free pool and initializes it.
51params:
52- description: |
53    is the object name of the port.
54  dir: null
55  name: name
56- description: |
57    is the internal start address of the memory area.
58  dir: null
59  name: internal_start
60- description: |
61    is the external start address of the memory area.
62  dir: null
63  name: external_start
64- description: |
65    is the length in bytes of the memory area.
66  dir: null
67  name: length
68- description: |
69    is the pointer to an object identifier variable.  The identifier of the
70    created port will be stored in this variable, in case of a successful
71    operation.
72  dir: out
73  name: id
74return:
75  return: null
76  return-values:
77  - description: |
78      The requested operation was successful.
79    value: ${../../status/if/successful:/name}
80  - description: |
81      The ${.:/params[0]/name} parameter was invalid.
82    value: ${../../status/if/invalid-name:/name}
83  - description: |
84      The ${.:/params[3]/name} parameter was ${/c/if/null:/name}.
85    value: ${../../status/if/invalid-address:/name}
86  - description: |
87      The ${.:/params[1]/name} parameter was not properly aligned.
88    value: ${../../status/if/invalid-address:/name}
89  - description: |
90      The ${.:/params[2]/name} parameter was not properly aligned.
91    value: ${../../status/if/invalid-address:/name}
92  - description: |
93      There was no inactive object available to create a port.  The number of
94      port available to the application is configured through the
95      ${/acfg/if/max-ports:/name} application configuration option.
96    value: ${../../status/if/too-many:/name}
97type: interface
Note: See TracBrowser for help on using the repository browser.