5.6. How-To¶
5.6.1. Interface Specification¶
5.6.1.1. Specify an API Header File¶
The RTEMS API header files are specified under spec:/if/rtems/*
.
Create a subdirectory with a corresponding name for the API, for example in
spec/if/rtems/foo
for the foo API. In this new subdirectory place an
Interface Header File Item Type item named header.yml
(spec/if/rtems/foo/header.yml
) and populate it with the required
attributes.
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
interface-type: header-file
links:
- role: interface-placement
uid: /if/domains/api
path: rtems/rtems/foo.h
prefix: cpukit/include
type: interface
5.6.1.2. Specify an API Element¶
Figure out the corresponding header file item. If it does not exist, see
Specify an API Header File. Place a specialization of an
Interface Item Type item into the directory of the header file
item, for example spec/if/rtems/foo/bar.yml
for the bar()
function. Add the required attributes for the new interface item. Do not hard
code interface names which are used to define the new interface. Use
${uid-of-interface-item:/name}
instead. If the referenced interface is
specified in the same directory, then use a relative UID. Using interface
references creates implicit dependencies and helps the header file generator to
resolve the interface dependencies and header file includes for you. Use
Interface Unspecified Item Type items for interface dependencies to
other domains such as the C language, the compiler, the implementation, or
user-provided defines. To avoid cyclic dependencies between types you may use
an Interface Forward Declaration Item Type item.
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: Tries to create a magic object and returns it.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
body: null
params:
- ${magic-wand:/name} ${.:/params[0]/name}
return: ${magic-type:/name} *
variants: []
description: |
The magic object is created out of nothing with the help of a magic wand.
enabled-by: true
interface-type: function
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: /groups/api/classic/foo
name: bar
notes: null
params:
- description: is the magic wand.
dir: null
name: magic_wand
return:
return: Otherwise, the magic object is returned.
return-values:
- description: The caller did not have enough magic power.
value: ${/if/c/null}
type: interface