From 15264e100b9b5f9c902974b1a5dedf5f2f3cbf85 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Sat, 26 Sep 2020 15:43:02 +0200 Subject: 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(-) delete mode 100644 spec/rtems/io/if/driver-error.yml 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 -- cgit v1.2.3