[rtems-central commit] spec: Review IO Manager
Sebastian Huber
sebh at rtems.org
Tue Sep 29 14:26:36 UTC 2020
Module: rtems-central
Branch: master
Commit: 15264e100b9b5f9c902974b1a5dedf5f2f3cbf85
Changeset: http://git.rtems.org/rtems-central/commit/?id=15264e100b9b5f9c902974b1a5dedf5f2f3cbf85
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Sat Sep 26 15:43:02 2020 +0200
spec: Review IO Manager
---
spec/rtems/io/if/close.yml | 31 ++++++++++++-----
spec/rtems/io/if/control.yml | 35 +++++++++++++++-----
spec/rtems/io/if/device-driver-entry.yml | 3 +-
spec/rtems/io/if/device-driver.yml | 8 +++--
spec/rtems/io/if/device-major-number.yml | 7 ++--
spec/rtems/io/if/device-minor-number.yml | 6 ++--
spec/rtems/io/if/driver-address-table.yml | 37 +++++++++++++--------
spec/rtems/io/if/driver-error.yml | 38 ---------------------
spec/rtems/io/if/header-3.yml | 3 +-
spec/rtems/io/if/header.yml | 3 +-
spec/rtems/io/if/initialize.yml | 37 ++++++++++++++++-----
spec/rtems/io/if/open.yml | 31 ++++++++++++-----
spec/rtems/io/if/read.yml | 32 +++++++++++++-----
spec/rtems/io/if/register-driver.yml | 55 ++++++++++++++++++++++++++-----
spec/rtems/io/if/register-name.yml | 24 ++++++++++----
spec/rtems/io/if/unregister-driver.yml | 21 +++++++++---
spec/rtems/io/if/write.yml | 31 ++++++++++++-----
17 files changed, 274 insertions(+), 128 deletions(-)
diff --git a/spec/rtems/io/if/close.yml b/spec/rtems/io/if/close.yml
index 0321a93..1dab576 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 0960813..c9a0de2 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 a3ba8c6..ed23a99 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 7ed1cdb..e962d2a 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 f49bbc6..311db34 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 dde1815..0759dd9 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 503ed03..06c1304 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 e9d1f0a..0000000
--- 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 a38a3b1..e1901c9 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 70a8d08..6ff719f 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 6125051..3e61ccf 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 6ec33a0..f3f3c1c 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 b28a127..265e747 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 a51ec9c..853add2 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 0b08640..8cf2e54 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 0f7cf26..6f1b425 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 0cd9c27..1629500 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
More information about the vc
mailing list