[rtems-central commit] spec: Update /rtems/support/* documentation
Sebastian Huber
sebh at rtems.org
Thu Apr 22 05:15:37 UTC 2021
Module: rtems-central
Branch: master
Commit: 929a974cdd0f1971266fd20f53b688feb18f5624
Changeset: http://git.rtems.org/rtems-central/commit/?id=929a974cdd0f1971266fd20f53b688feb18f5624
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Wed Apr 21 19:32:58 2021 +0200
spec: Update /rtems/support/* documentation
---
spec/rtems/support/if/is-name-valid.yml | 20 ++++++++--------
spec/rtems/support/if/microseconds-to-ticks.yml | 13 +++++++----
.../support/if/milliseconds-to-microseconds.yml | 13 +++++++----
spec/rtems/support/if/milliseconds-to-ticks.yml | 13 +++++++----
spec/rtems/support/if/name-to-characters.yml | 12 ++++++----
spec/rtems/support/if/workspace-allocate.yml | 27 ++++++++++++++++------
spec/rtems/support/if/workspace-free.yml | 17 ++++++++++----
.../rtems/support/if/workspace-get-information.yml | 18 +++++++++++----
...orkspace-greedy-allocate-all-except-largest.yml | 27 +++++++++++++++++-----
.../rtems/support/if/workspace-greedy-allocate.yml | 20 +++++++++++-----
spec/rtems/support/if/workspace-greedy-free.yml | 18 +++++++++++----
11 files changed, 142 insertions(+), 56 deletions(-)
diff --git a/spec/rtems/support/if/is-name-valid.yml b/spec/rtems/support/if/is-name-valid.yml
index aff5750..cbf9435 100644
--- a/spec/rtems/support/if/is-name-valid.yml
+++ b/spec/rtems/support/if/is-name-valid.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
- Returns true, if the specified object name is valid, otherwise returns false.
+ Checks if the object name is valid.
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) 1989, 2008 On-Line Applications Research Corporation (OAR)
definition:
default:
@@ -22,17 +22,19 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_is_name_valid
notes: null
params:
-- description: is the object name to check.
+- description: |
+ is the object name to check.
dir: null
name: name
return:
- return: null
- return-values:
- - description: The specified object name is valid.
- value: 'true'
- - description: Otherwise.
- value: 'false'
+ return: |
+ Returns true, if the object name is valid, otherwise false.
+ return-values: []
type: interface
diff --git a/spec/rtems/support/if/microseconds-to-ticks.yml b/spec/rtems/support/if/microseconds-to-ticks.yml
index 6aa6591..57d7591 100644
--- a/spec/rtems/support/if/microseconds-to-ticks.yml
+++ b/spec/rtems/support/if/microseconds-to-ticks.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
- Returns the number of clock ticks for the specified microseconds value.
+ Gets the number of clock ticks for the microseconds value.
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) 2008 On-Line Applications Research Corporation (OAR)
definition:
default: |
@@ -17,16 +17,21 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: RTEMS_MICROSECONDS_TO_TICKS
notes: |
The number of clock ticks per second is defined by the
${/acfg/if/microseconds-per-tick:/name} application configuration option.
params:
-- description: is the microseconds value to convert to clock ticks.
+- description: |
+ is the microseconds value to convert to clock ticks.
dir: null
name: _us
return:
return: |
- The number of clock ticks for the specified microseconds value is returned.
+ Returns the number of clock ticks for the specified microseconds value.
return-values: []
type: interface
diff --git a/spec/rtems/support/if/milliseconds-to-microseconds.yml b/spec/rtems/support/if/milliseconds-to-microseconds.yml
index d80362b..19cd055 100644
--- a/spec/rtems/support/if/milliseconds-to-microseconds.yml
+++ b/spec/rtems/support/if/milliseconds-to-microseconds.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
- Returns the number of microseconds for the specified milliseconds value.
+ Gets the number of microseconds for the milliseconds value.
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) 2008 On-Line Applications Research Corporation (OAR)
definition:
default: |
@@ -17,14 +17,19 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-const
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: RTEMS_MILLISECONDS_TO_MICROSECONDS
notes: null
params:
-- description: is the milliseconds value to convert to microseconds.
+- description: |
+ is the milliseconds value to convert to microseconds.
dir: null
name: _ms
return:
return: |
- The number of microseconds for the specified milliseconds value is returned.
+ Returns the number of microseconds for the milliseconds value.
return-values: []
type: interface
diff --git a/spec/rtems/support/if/milliseconds-to-ticks.yml b/spec/rtems/support/if/milliseconds-to-ticks.yml
index c2524f1..d62e097 100644
--- a/spec/rtems/support/if/milliseconds-to-ticks.yml
+++ b/spec/rtems/support/if/milliseconds-to-ticks.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
- Returns the number of clock ticks for the specified milliseconds value.
+ Gets the number of clock ticks for the milliseconds value.
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) 2008 On-Line Applications Research Corporation (OAR)
definition:
default: |
@@ -17,16 +17,21 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: RTEMS_MILLISECONDS_TO_TICKS
notes: |
The number of clock ticks per second is defined by the
${/acfg/if/microseconds-per-tick:/name} application configuration option.
params:
-- description: is the milliseconds value to convert to clock ticks.
+- description: |
+ is the milliseconds value to convert to clock ticks.
dir: null
name: _ms
return:
return: |
- The number of clock ticks for the specified milliseconds value is returned.
+ Returns the number of clock ticks for the milliseconds value.
return-values: []
type: interface
diff --git a/spec/rtems/support/if/name-to-characters.yml b/spec/rtems/support/if/name-to-characters.yml
index b492d99..99c01dc 100644
--- a/spec/rtems/support/if/name-to-characters.yml
+++ b/spec/rtems/support/if/name-to-characters.yml
@@ -8,10 +8,10 @@ definition:
default:
attributes: null
body: |
- *${.:/params[1]/name} = (char) ( ${.:/params[0]/name} >> 24 );
- *${.:/params[2]/name} = (char) ( ${.:/params[0]/name} >> 16 );
- *${.:/params[3]/name} = (char) ( ${.:/params[0]/name} >> 8 );
- *${.:/params[4]/name} = (char) ${.:/params[0]/name};
+ *${.:/params[1]/name} = (char) ( ( ( ${.:/params[0]/name} ) >> 24 ) & 0xff );
+ *${.:/params[2]/name} = (char) ( ( ( ${.:/params[0]/name} ) >> 16 ) & 0xff );
+ *${.:/params[3]/name} = (char) ( ( ( ${.:/params[0]/name} ) >> 8 ) & 0xff );
+ *${.:/params[4]/name} = (char) ( ( ${.:/params[0]/name} ) & 0xff );
params:
- ${../../type/if/name:/name} ${.:/params[0]/name}
- char *${.:/params[1]/name}
@@ -29,6 +29,10 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_name_to_characters
notes: null
params:
diff --git a/spec/rtems/support/if/workspace-allocate.yml b/spec/rtems/support/if/workspace-allocate.yml
index 8d0499c..feb84b4 100644
--- a/spec/rtems/support/if/workspace-allocate.yml
+++ b/spec/rtems/support/if/workspace-allocate.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Allocates a memory area from the RTEMS Workspace.
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:
@@ -21,16 +22,28 @@ 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
name: rtems_workspace_allocate
-notes: null
+notes: |
+ This directive is intended to be used by tests of the RTEMS test suites.
params:
-- description: '%'
+- description: |
+ is the number of bytes to allocated.
dir: null
name: bytes
-- description: '%'
- dir: null
+- description: |
+ is the pointer to a pointer variable. When the directive call is
+ successful, the begin address of the allocated memory area will be stored
+ in this variable.
+ dir: out
name: pointer
return:
- return: null
+ return: |
+ Returns true, if the allocation was successful, otherwise false.
return-values: []
type: interface
diff --git a/spec/rtems/support/if/workspace-free.yml b/spec/rtems/support/if/workspace-free.yml
index 8f9a2f1..e10d5b3 100644
--- a/spec/rtems/support/if/workspace-free.yml
+++ b/spec/rtems/support/if/workspace-free.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Frees the memory area allocated from the RTEMS Workspace.
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:
@@ -20,13 +21,21 @@ 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
name: rtems_workspace_free
notes: null
params:
-- description: '%'
+- description: |
+ is the begin address of the memory area to free.
dir: null
name: pointer
return:
- return: null
+ return: |
+ Returns true, if freeing the memory area was successful, otherwise false.
return-values: []
type: interface
diff --git a/spec/rtems/support/if/workspace-get-information.yml b/spec/rtems/support/if/workspace-get-information.yml
index 4aa2d30..1625385 100644
--- a/spec/rtems/support/if/workspace-get-information.yml
+++ b/spec/rtems/support/if/workspace-get-information.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Gets information about the RTEMS Workspace.
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:
@@ -20,13 +21,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
name: rtems_workspace_get_information
notes: null
params:
-- description: '%'
+- description: |
+ is the pointer to a heap information variable. When the directive call is
+ successful, the heap information will be stored in this variable.
dir: null
name: the_info
return:
- return: null
+ return: |
+ Returns true, if getting the information was successful, otherwise false.
return-values: []
type: interface
diff --git a/spec/rtems/support/if/workspace-greedy-allocate-all-except-largest.yml b/spec/rtems/support/if/workspace-greedy-allocate-all-except-largest.yml
index 1aa782e..afbae87 100644
--- a/spec/rtems/support/if/workspace-greedy-allocate-all-except-largest.yml
+++ b/spec/rtems/support/if/workspace-greedy-allocate-all-except-largest.yml
@@ -1,7 +1,9 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Greedy allocates all blocks of the RTEMS Workspace except the largest free
+ block.
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,7 +13,10 @@ definition:
- ${/c/if/uintptr_t:/name} *${.:/params[0]/name}
return: void *
variants: []
-description: null
+description: |
+ Afterwards the heap has at most one allocatable block. This block is the
+ largest free block if it exists. The allocatable size of this block is
+ stored in ${.:/params[0]/name}. All other blocks are used.
enabled-by: true
index-entries: []
interface-type: function
@@ -20,13 +25,23 @@ 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
name: rtems_workspace_greedy_allocate_all_except_largest
-notes: null
+notes: |
+ This directive is intended to be used by tests of the RTEMS test suites.
params:
-- description: '%'
+- description: |
+ is the remaining allocatable size.
dir: null
name: allocatable_size
return:
- return: null
+ return: |
+ The returned pointer value may be used to free the greedy allocation by
+ calling ${workspace-greedy-free:/name}.
return-values: []
type: interface
diff --git a/spec/rtems/support/if/workspace-greedy-allocate.yml b/spec/rtems/support/if/workspace-greedy-allocate.yml
index 78860e8..eda9f51 100644
--- a/spec/rtems/support/if/workspace-greedy-allocate.yml
+++ b/spec/rtems/support/if/workspace-greedy-allocate.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Greedy allocates that empties the RTEMS Workspace.
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:
@@ -12,7 +13,10 @@ definition:
- ${/c/if/size_t:/name} ${.:/params[1]/name}
return: void *
variants: []
-description: null
+description: |
+ Afterwards the heap has at most ${.:/params[1]/name} allocatable blocks of
+ sizes specified by ${.:/params[0]/name}. The ${.:/params[0]/name} must point
+ to an array with ${.:/params[1]/name} members. All other blocks are used.
enabled-by: true
index-entries: []
interface-type: function
@@ -24,13 +28,17 @@ links:
name: rtems_workspace_greedy_allocate
notes: null
params:
-- description: '%'
+- description: |
+ is the array of block sizes.
dir: null
name: block_sizes
-- description: '%'
+- description: |
+ is the block count.
dir: null
name: block_count
return:
- return: null
+ return: |
+ The returned pointer value may be used to free the greedy allocation by
+ calling ${workspace-greedy-free:/name}.
return-values: []
type: interface
diff --git a/spec/rtems/support/if/workspace-greedy-free.yml b/spec/rtems/support/if/workspace-greedy-free.yml
index a54a4b0..0a6b592 100644
--- a/spec/rtems/support/if/workspace-greedy-free.yml
+++ b/spec/rtems/support/if/workspace-greedy-free.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Frees space of a greedy allocation to the RTEMS Workspace.
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:
@@ -20,10 +21,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
name: rtems_workspace_greedy_free
-notes: null
+notes: |
+ This directive is intended to be used by tests of the RTEMS test suites.
params:
-- description: '%'
+- description: |
+ is the pointer value returned by ${workspace-greedy-allocate:/name} or
+ ${workspace-greedy-allocate-all-except-largest:/name}.
dir: null
name: opaque
return:
More information about the vc
mailing list