1 | SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause |
---|
2 | brief: | |
---|
3 | Creates a port. |
---|
4 | copyrights: |
---|
5 | - Copyright (C) 2021 embedded brains GmbH & Co. KG |
---|
6 | - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) |
---|
7 | definition: |
---|
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: [] |
---|
19 | description: | |
---|
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. |
---|
25 | enabled-by: true |
---|
26 | index-entries: |
---|
27 | - create a port |
---|
28 | interface-type: function |
---|
29 | links: |
---|
30 | - role: interface-placement |
---|
31 | uid: header |
---|
32 | - role: interface-ingroup |
---|
33 | uid: group |
---|
34 | - role: constraint |
---|
35 | uid: /constraint/directive-not-pre-qualified |
---|
36 | - role: constraint |
---|
37 | uid: /constraint/directive-ctx-devinit |
---|
38 | - role: constraint |
---|
39 | uid: /constraint/directive-ctx-task |
---|
40 | - role: constraint |
---|
41 | uid: /constraint/object-allocator |
---|
42 | - role: constraint |
---|
43 | uid: ../constraint/max |
---|
44 | - role: constraint |
---|
45 | uid: /constraint/obj-unlimited-alloc |
---|
46 | name: rtems_port_create |
---|
47 | notes: | |
---|
48 | The ${.:/params[1]/name} and ${.:/params[2]/name} parameters must be on a |
---|
49 | boundary defined by the target processor architecture. |
---|
50 | |
---|
51 | For control and maintenance of the port, RTEMS allocates a |
---|
52 | ${/glossary/dpcb:/term} from the local DPCB free pool and initializes it. |
---|
53 | params: |
---|
54 | - description: | |
---|
55 | is the object name of the port. |
---|
56 | dir: null |
---|
57 | name: name |
---|
58 | - description: | |
---|
59 | is the internal start address of the memory area. |
---|
60 | dir: null |
---|
61 | name: internal_start |
---|
62 | - description: | |
---|
63 | is the external start address of the memory area. |
---|
64 | dir: null |
---|
65 | name: external_start |
---|
66 | - description: | |
---|
67 | is the length in bytes of the memory area. |
---|
68 | dir: null |
---|
69 | name: length |
---|
70 | - description: | |
---|
71 | is the pointer to an ${../../type/if/id:/name} object. When the directive |
---|
72 | call is successful, the identifier of the created port will be stored in |
---|
73 | this object. |
---|
74 | dir: out |
---|
75 | name: id |
---|
76 | return: |
---|
77 | return: null |
---|
78 | return-values: |
---|
79 | - description: | |
---|
80 | The requested operation was successful. |
---|
81 | value: ${../../status/if/successful:/name} |
---|
82 | - description: | |
---|
83 | The ${.:/params[0]/name} parameter was invalid. |
---|
84 | value: ${../../status/if/invalid-name:/name} |
---|
85 | - description: | |
---|
86 | The ${.:/params[4]/name} parameter was ${/c/if/null:/name}. |
---|
87 | value: ${../../status/if/invalid-address:/name} |
---|
88 | - description: | |
---|
89 | The ${.:/params[1]/name} parameter was not properly aligned. |
---|
90 | value: ${../../status/if/invalid-address:/name} |
---|
91 | - description: | |
---|
92 | The ${.:/params[2]/name} parameter was not properly aligned. |
---|
93 | value: ${../../status/if/invalid-address:/name} |
---|
94 | - description: | |
---|
95 | There was no inactive object available to create a port. The number of |
---|
96 | port available to the application is configured through the |
---|
97 | ${/acfg/if/max-ports:/name} application configuration option. |
---|
98 | value: ${../../status/if/too-many:/name} |
---|
99 | type: interface |
---|