From e2942aff61464d6f0328abc10f82fd35172e5b8e Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.huber@embedded-brains.de>
Date: Wed, 21 Apr 2021 19:33:40 +0200
Subject: spec: Update /rtems/dpmen/* documentatation

---
 spec/rtems/dpmem/if/create.yml               |  2 +-
 spec/rtems/dpmem/if/external-to-internal.yml | 46 +++++++++++++++++++++------
 spec/rtems/dpmem/if/group.yml                | 12 +++++++
 spec/rtems/dpmem/if/internal-to-external.yml | 47 ++++++++++++++++++++++------
 4 files changed, 88 insertions(+), 19 deletions(-)

diff --git a/spec/rtems/dpmem/if/create.yml b/spec/rtems/dpmem/if/create.yml
index eac83783..f07ec2a4 100644
--- a/spec/rtems/dpmem/if/create.yml
+++ b/spec/rtems/dpmem/if/create.yml
@@ -81,7 +81,7 @@ return:
       The ${.:/params[0]/name} parameter was invalid.
     value: ${../../status/if/invalid-name:/name}
   - description: |
-      The ${.:/params[3]/name} parameter was ${/c/if/null:/name}.
+      The ${.:/params[4]/name} parameter was ${/c/if/null:/name}.
     value: ${../../status/if/invalid-address:/name}
   - description: |
       The ${.:/params[1]/name} parameter was not properly aligned.
diff --git a/spec/rtems/dpmem/if/external-to-internal.yml b/spec/rtems/dpmem/if/external-to-internal.yml
index 6640a5c8..98112205 100644
--- a/spec/rtems/dpmem/if/external-to-internal.yml
+++ b/spec/rtems/dpmem/if/external-to-internal.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Converts the external address to the internal address.
 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:
@@ -13,28 +14,55 @@ definition:
     - void **${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive converts a dual-ported memory address from external to
+  internal representation for the specified port.  If the given external
+  address is invalid for the specified port, then the internal address is set
+  to the given external address.
 enabled-by: true
-index-entries: []
+index-entries:
+- convert external to internal address
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-isr
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_port_external_to_internal
 notes: null
 params:
-- description: '%'
+- description: |
+    is the port identifier.
   dir: null
   name: id
-- description: '%'
+- description: |
+     is the external address to convert.
   dir: null
   name: external
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to a pointer variable.  When the directive call is
+    successful, the external address associated with the internal address will
+    be stored in this variable.
+  dir: out
   name: internal
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The ${.:/params[0]/name} parameter was invalid.
+    value: ${../../status/if/invalid-name:/name}
+  - description: |
+      The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
 type: interface
diff --git a/spec/rtems/dpmem/if/group.yml b/spec/rtems/dpmem/if/group.yml
index 5c615e99..ece28431 100644
--- a/spec/rtems/dpmem/if/group.yml
+++ b/spec/rtems/dpmem/if/group.yml
@@ -16,6 +16,18 @@ links:
   uid: header
 - role: interface-ingroup
   uid: ../../if/group
+- role: interface-ingroup
+  uid: ../../if/group
+- role: placement-order
+  uid: create
+- role: placement-order
+  uid: ident
+- role: placement-order
+  uid: delete
+- role: placement-order
+  uid: external-to-internal
+- role: placement-order
+  uid: internal-to-external
 name: Dual-Ported Memory Manager
 text: |
   The Classic API shall provide an interface to the Dual-Ported Memory Manager.
diff --git a/spec/rtems/dpmem/if/internal-to-external.yml b/spec/rtems/dpmem/if/internal-to-external.yml
index 30772809..8d0528ed 100644
--- a/spec/rtems/dpmem/if/internal-to-external.yml
+++ b/spec/rtems/dpmem/if/internal-to-external.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Converts the internal address to the external address.
 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:
@@ -13,28 +14,56 @@ definition:
     - void **${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive converts a dual-ported memory address from internal to
+  external representation so that it can be passed to owner of the DPMA
+  represented by the specified port.  If the given internal address is an
+  invalid dual-ported address, then the external address is set to the given
+  internal address.
 enabled-by: true
-index-entries: []
+index-entries:
+- convert internal to external address
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-isr
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_port_internal_to_external
 notes: null
 params:
-- description: '%'
+- description: |
+    is the port identifier.
   dir: null
   name: id
-- description: '%'
+- description: |
+     is the internal address to convert.
   dir: null
   name: internal
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to a pointer variable.  When the directive call is
+    successful, the external address associated with the internal address will
+    be stored in this variable.
+  dir: out
   name: external
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The ${.:/params[0]/name} parameter was invalid.
+    value: ${../../status/if/invalid-name:/name}
+  - description: |
+      The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
 type: interface
-- 
cgit v1.2.3