spec: Review IO Manager

17 files changed, 274 insertions, 128 deletions

diff --git a/spec/rtems/io/if/close.yml b/spec/rtems/io/if/close.yml
index 0321a932..1dab5764 100644
--- a/spec/rtems/io/if/close.yml
+++ b/spec/rtems/io/if/close.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Closes the device specified by device major and minor number.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,7 +13,9 @@ definition:
     - void *${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive calls the device driver close entry registered in the Device
+  Driver Table for the specified device major number.
 enabled-by: true
 interface-type: function
 links:
@@ -21,18 +24,30 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_io_close
-notes: null
+notes: |
+  The close entry point is commonly used by device drivers to relinquish
+  exclusive access to a device.
 params:
-- description: '%'
+- description: |
+    is the major number of the device.
   dir: null
   name: major
-- description: '%'
+- description: |
+    is the minor number of the device.
   dir: null
   name: minor
-- description: '%'
+- description: |
+    is the argument passed to the device driver close entry.
   dir: null
   name: argument
 return:
-  return: null
-  return-values: []
+  return: |
+    Other status codes may be returned by the device driver close entry.
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The device major number was invalid.
+    value: ${../../status/if/invalid-number:/name}
 type: interface
diff --git a/spec/rtems/io/if/control.yml b/spec/rtems/io/if/control.yml
index 09608139..c9a0de26 100644
--- a/spec/rtems/io/if/control.yml
+++ b/spec/rtems/io/if/control.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Controls the device specified by device major and minor number.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,7 +13,9 @@ definition:
     - void *${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive calls the device driver I/O control entry registered in the
+  Device Driver Table for the specified device major number.
 enabled-by: true
 interface-type: function
 links:
@@ -21,18 +24,34 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_io_control
-notes: null
+notes: |
+  The exact functionality of the driver entry called by this directive is
+  driver dependent.  It should not be assumed that the control entries of two
+  device drivers are compatible.  For example, an RS-232 driver I/O control
+  operation may change the baud rate of a serial line, while an I/O control
+  operation for a floppy disk driver may cause a seek operation.
 params:
-- description: '%'
+- description: |
+    is the major number of the device.
   dir: null
   name: major
-- description: '%'
+- description: |
+    is the minor number of the device.
   dir: null
   name: minor
-- description: '%'
+- description: |
+    is the argument passed to the device driver I/O control entry.
   dir: null
   name: argument
 return:
-  return: null
-  return-values: []
+  return: |
+    Other status codes may be returned by the device driver I/O control
+    entry.
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The device major number was invalid.
+    value: ${../../status/if/invalid-number:/name}
 type: interface
diff --git a/spec/rtems/io/if/device-driver-entry.yml b/spec/rtems/io/if/device-driver-entry.yml
index a3ba8c60..ed23a994 100644
--- a/spec/rtems/io/if/device-driver-entry.yml
+++ b/spec/rtems/io/if/device-driver-entry.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Device driver entries shall have this type.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/rtems/io/if/device-driver.yml b/spec/rtems/io/if/device-driver.yml
index 7ed1cdb0..e962d2a0 100644
--- a/spec/rtems/io/if/device-driver.yml
+++ b/spec/rtems/io/if/device-driver.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This type shall be used in device driver entry declarations and definitions.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -15,5 +16,8 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_device_driver
-notes: null
+notes: |
+  Device driver entries return an ${../../status/if/code:/name} status code.
+  This type definition helps to document device driver entries in the source
+  code.
 type: interface
diff --git a/spec/rtems/io/if/device-major-number.yml b/spec/rtems/io/if/device-major-number.yml
index f49bbc6b..311db34a 100644
--- a/spec/rtems/io/if/device-major-number.yml
+++ b/spec/rtems/io/if/device-major-number.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This integer type represents the major number of devices.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -15,5 +16,7 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_device_major_number
-notes: null
+notes: |
+  The major number of a device is determined by ${register-driver:/name} and
+  the application configuration (see ${/acfg/if/max-drivers:/name}) .
 type: interface
diff --git a/spec/rtems/io/if/device-minor-number.yml b/spec/rtems/io/if/device-minor-number.yml
index dde18153..0759dd92 100644
--- a/spec/rtems/io/if/device-minor-number.yml
+++ b/spec/rtems/io/if/device-minor-number.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This integer type represents the minor number of devices.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -15,5 +16,6 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_device_minor_number
-notes: null
+notes: |
+  The minor number of devices is managed by the device driver.
 type: interface
diff --git a/spec/rtems/io/if/driver-address-table.yml b/spec/rtems/io/if/driver-address-table.yml
index 503ed033..06c13046 100644
--- a/spec/rtems/io/if/driver-address-table.yml
+++ b/spec/rtems/io/if/driver-address-table.yml
@@ -1,59 +1,68 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This structure contains the device driver entries.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
 - default:
     brief: |
-      This member is
+      This member is the device driver initialization entry.
     definition: rtems_device_driver_entry ${.:name}
-    description: '%'
+    description: |
+      This entry is called by ${initialize:/name}
     kind: member
     name: initialization_entry
   variants: []
 - default:
     brief: |
-      This member is
+      This member is the device driver open entry.
     definition: rtems_device_driver_entry ${.:name}
-    description: '%'
+    description: |
+      This entry is called by ${open:/name}.
     kind: member
     name: open_entry
   variants: []
 - default:
     brief: |
-      This member is
+      This member is the device driver close entry.
     definition: rtems_device_driver_entry ${.:name}
-    description: '%'
+    description: |
+      This entry is called by ${close:/name}.
     kind: member
     name: close_entry
   variants: []
 - default:
     brief: |
-      This member is
+      This member is the device driver read entry.
     definition: rtems_device_driver_entry ${.:name}
-    description: '%'
+    description: |
+      This entry is called by ${read:/name}.
     kind: member
     name: read_entry
   variants: []
 - default:
     brief: |
-      This member is
+      This member is the device driver write entry.
     definition: rtems_device_driver_entry ${.:name}
-    description: '%'
+    description: |
+      This entry is called by ${write:/name}.
     kind: member
     name: write_entry
   variants: []
 - default:
     brief: |
-      This member is
+      This member is the device driver control entry.
     definition: rtems_device_driver_entry ${.:name}
-    description: '%'
+    description: |
+      This entry is called by ${control:/name}.
     kind: member
     name: control_entry
   variants: []
 definition-kind: typedef-only
-description: null
+description: |
+  This structure is used to register a device driver via
+  ${register-driver:/name}.
 enabled-by: true
 interface-type: struct
 links:
diff --git a/spec/rtems/io/if/driver-error.yml b/spec/rtems/io/if/driver-error.yml
deleted file mode 100644
index e9d1f0aa..00000000
--- a/spec/rtems/io/if/driver-error.yml
+++ /dev/null
@@ -1,38 +0,0 @@
-SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
-copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-definition:
-  default:
-    body: null
-    params:
-    - ${device-major-number:/name} ${.:/params[0]/name}
-    - ${device-minor-number:/name} ${.:/params[1]/name}
-    - void *${.:/params[2]/name}
-    return: ${../../status/if/code:/name}
-  variants: []
-description: null
-enabled-by: true
-interface-type: function
-links:
-- role: interface-placement
-  uid: header
-- role: interface-ingroup
-  uid: group
-name: rtems_io_driver_io_error
-notes: null
-params:
-- description: '%'
-  dir: null
-  name: major
-- description: '%'
-  dir: null
-  name: minor
-- description: '%'
-  dir: null
-  name: arg
-return:
-  return: null
-  return-values: []
-type: interface
diff --git a/spec/rtems/io/if/header-3.yml b/spec/rtems/io/if/header-3.yml
index a38a3b19..e1901c9b 100644
--- a/spec/rtems/io/if/header-3.yml
+++ b/spec/rtems/io/if/header-3.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: This header file defines the polled character IO driver API.
+brief: |
+  This header file defines the polled character IO driver API.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 enabled-by: true
diff --git a/spec/rtems/io/if/header.yml b/spec/rtems/io/if/header.yml
index 70a8d08e..6ff719fe 100644
--- a/spec/rtems/io/if/header.yml
+++ b/spec/rtems/io/if/header.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: This header file defines the IO Manager API.
+brief: |
+  This header file defines the IO Manager API.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 enabled-by: true
diff --git a/spec/rtems/io/if/initialize.yml b/spec/rtems/io/if/initialize.yml
index 61250511..3e61ccfe 100644
--- a/spec/rtems/io/if/initialize.yml
+++ b/spec/rtems/io/if/initialize.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Initializes the device specified by device major and minor number.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,7 +13,9 @@ definition:
     - void *${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive calls the device driver initialization entry registered in the
+  Device Driver Table for the specified device major number.
 enabled-by: true
 interface-type: function
 links:
@@ -21,18 +24,36 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_io_initialize
-notes: null
+notes: |
+  This directive is automatically invoked for each device driver defined by the
+  application configuration during the system initialization and via the
+  {register-driver:/name} directive.
+
+  A device driver initialization entry is responsible for initializing all
+  hardware and data structures associated with a device.  If necessary, it can
+  allocate memory to be used during other operations.
 params:
-- description: '%'
+- description: |
+    is the major number of the device.
   dir: null
   name: major
-- description: '%'
+- description: |
+    is the minor number of the device.
   dir: null
   name: minor
-- description: '%'
+- description: |
+    is the argument passed to the device driver initialization entry.
   dir: null
   name: argument
 return:
-  return: null
-  return-values: []
+  return: |
+    Other status codes may be returned by the device driver initialization
+    routine.
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The device major number was invalid.
+    value: ${../../status/if/invalid-number:/name}
 type: interface
diff --git a/spec/rtems/io/if/open.yml b/spec/rtems/io/if/open.yml
index 6ec33a03..f3f3c1c5 100644
--- a/spec/rtems/io/if/open.yml
+++ b/spec/rtems/io/if/open.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Opens the device specified by device major and minor number.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,7 +13,9 @@ definition:
     - void *${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive calls the device driver open entry registered in the Device
+  Driver Table for the specified device major number.
 enabled-by: true
 interface-type: function
 links:
@@ -21,18 +24,30 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_io_open
-notes: null
+notes: |
+  The open entry point is commonly used by device drivers to provide exclusive
+  access to a device.
 params:
-- description: '%'
+- description: |
+    is the major number of the device.
   dir: null
   name: major
-- description: '%'
+- description: |
+    is the minor number of the device.
   dir: null
   name: minor
-- description: '%'
+- description: |
+    is the argument passed to the device driver close entry.
   dir: null
   name: argument
 return:
-  return: null
-  return-values: []
+  return: |
+    Other status codes may be returned by the device driver open routine.
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The device major number was invalid.
+    value: ${../../status/if/invalid-number:/name}
 type: interface
diff --git a/spec/rtems/io/if/read.yml b/spec/rtems/io/if/read.yml
index b28a1279..265e7477 100644
--- a/spec/rtems/io/if/read.yml
+++ b/spec/rtems/io/if/read.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Reads from the device specified by device major and minor number.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,7 +13,9 @@ definition:
     - void *${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive calls the device driver read entry registered in the Device
+  Driver Table for the specified device major number.
 enabled-by: true
 interface-type: function
 links:
@@ -21,18 +24,31 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_io_read
-notes: null
+notes: |
+  Read operations typically require a buffer address as part of the argument
+  parameter block.  The contents of this buffer will be replaced with data from
+  the device.
 params:
-- description: '%'
+- description: |
+    is the major number of the device.
   dir: null
   name: major
-- description: '%'
+- description: |
+    is the minor number of the device.
   dir: null
   name: minor
-- description: '%'
+- description: |
+    is the argument passed to the device driver read entry.
   dir: null
   name: argument
 return:
-  return: null
-  return-values: []
+  return: |
+    Other status codes may be returned by the device driver read routine.
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The device major number was invalid.
+    value: ${../../status/if/invalid-number:/name}
 type: interface
diff --git a/spec/rtems/io/if/register-driver.yml b/spec/rtems/io/if/register-driver.yml
index a51ec9c5..853add2b 100644
--- a/spec/rtems/io/if/register-driver.yml
+++ b/spec/rtems/io/if/register-driver.yml
@@ -1,5 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Registers and initializes the device with the specified device driver address
+  table and device major number in the Device Driver Table.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -8,7 +10,7 @@ definition:
     body: null
     params:
     - ${device-major-number:/name} ${.:/params[0]/name}
-    - const rtems_driver_address_table *${.:/params[1]/name}
+    - const ${driver-address-table:/name} *${.:/params[1]/name}
     - ${device-major-number:/name} *${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
@@ -21,18 +23,53 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_io_register_driver
-notes: null
+notes: |
+  If the device major number equals zero a device major number will be
+  obtained.  The device major number of the registered driver will be returned.
+
+  After a successful registration ${initialize:/name} routine will be called to
+  initialize the device.
 params:
-- description: '%'
+- description: |
+    is the device major number.  Use a value of zero to let the system obtain a
+    device major number automatically.
   dir: null
   name: major
-- description: '%'
+- description: |
+    is the device driver address table.
   dir: null
   name: driver_table
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to a device major number variable.  The device major number
+    of the registered device will be stored in this variable, in case of a
+    successful operation.
+  dir: out
   name: registered_major
 return:
-  return: null
-  return-values: []
+  return: |
+    Other status codes may be returned by the device driver initialization
+    routine.
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The device major number of the device was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The device driver address table was empty.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The device major number of the device was out of range, see
+      ${/acfg/if/max-drivers:/name}.
+    value: ${../../status/if/invalid-number:/name}
+  - description: |
+      The system was unable to obtain a device major number.
+    value: ${../../status/if/too-many:/name}
+  - description: |
+      The device major number was in use.
+    value: ${../../status/if/resource-in-use:/name}
+  - description: |
+      The directive was called from interrupt context.
+    value: ${../../status/if/called-from-isr:/name}
 type: interface
diff --git a/spec/rtems/io/if/register-name.yml b/spec/rtems/io/if/register-name.yml
index 0b086407..8cf2e544 100644
--- a/spec/rtems/io/if/register-name.yml
+++ b/spec/rtems/io/if/register-name.yml
@@ -1,5 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Registers the device specified by the device major and minor numbers in the
+  file system under the specified name.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -21,18 +23,28 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_io_register_name
-notes: null
+notes: |
+  The device is registered as a character device.
 params:
-- description: '%'
+- description: |
+    is the device name in the file system.
   dir: null
   name: device_name
-- description: '%'
+- description: |
+    is the device major number.
   dir: null
   name: major
-- description: '%'
+- description: |
+    is the device minor number.
   dir: null
   name: minor
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The name was already in use or other errors occurred.
+    value: ${../../status/if/too-many:/name}
 type: interface
diff --git a/spec/rtems/io/if/unregister-driver.yml b/spec/rtems/io/if/unregister-driver.yml
index 0f7cf261..6f1b4253 100644
--- a/spec/rtems/io/if/unregister-driver.yml
+++ b/spec/rtems/io/if/unregister-driver.yml
@@ -1,5 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Removes a device driver specified by the device major number from the Device
+  Driver Table.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -19,12 +21,23 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_io_unregister_driver
-notes: null
+notes: |
+  Currently no specific checks are made and the driver is not closed.
 params:
-- description: '%'
+- description: |
+    is the major number of the device.
   dir: null
   name: major
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The device major number was invalid.
+    value: ${../../status/if/unsatisfied:/name}
+  - description: |
+      The directive was called from interrupt context.
+    value: ${../../status/if/called-from-isr:/name}
 type: interface
diff --git a/spec/rtems/io/if/write.yml b/spec/rtems/io/if/write.yml
index 0cd9c278..16295002 100644
--- a/spec/rtems/io/if/write.yml
+++ b/spec/rtems/io/if/write.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Writes to the device specified by device major and minor number.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,7 +13,9 @@ definition:
     - void *${.:/params[2]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive calls the device driver write entry registered in the Device
+  Driver Table for the specified device major number.
 enabled-by: true
 interface-type: function
 links:
@@ -21,18 +24,30 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_io_write
-notes: null
+notes: |
+  Write operations typically require a buffer address as part of the argument
+  parameter block.  The contents of this buffer will be sent to the device.
 params:
-- description: '%'
+- description: |
+    is the major number of the device.
   dir: null
   name: major
-- description: '%'
+- description: |
+    is the minor number of the device.
   dir: null
   name: minor
-- description: '%'
+- description: |
+    is the argument passed to the device driver write entry.
   dir: null
   name: argument
 return:
-  return: null
-  return-values: []
+  return: |
+    Other status codes may be returned by the device driver write routine.
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The device major number was invalid.
+    value: ${../../status/if/invalid-number:/name}
 type: interface