[PATCH 1/1] rtems: Generate <rtems/io.h>
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue Sep 29 15:02:46 UTC 2020
The manager documentation is a consolidation of the comments in Doxygen
markup and the documentation sources in Sphinx markup. The
documentation was transfered to interface specification items. This
header file was generated from the items by a script.
Change license to BSD-2-Clause according to file histories and
documentation re-licensing agreement.
Update #3899.
Update #3993.
---
cpukit/include/rtems/io.h | 480 ++++++++++++++++++++++++++++----------
1 file changed, 351 insertions(+), 129 deletions(-)
diff --git a/cpukit/include/rtems/io.h b/cpukit/include/rtems/io.h
index 67364df280..9d0de33c30 100644
--- a/cpukit/include/rtems/io.h
+++ b/cpukit/include/rtems/io.h
@@ -1,24 +1,52 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
/**
* @file
*
- * @brief Classic Input/Output Manager API
- *
- * This file emulates the old Classic RTEMS IO manager directives
- * which register names using the in-memory filesystem.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief This header file defines the IO Manager API.
*/
/*
- * COPYRIGHT (c) 1989-2008.
- * On-Line Applications Research Corporation (OAR).
+ * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+ * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
*
- * The license and distribution terms for this file may be
- * found in the file LICENSE in this distribution or at
- * http://www.rtems.org/license/LICENSE.
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This file was automatically generated. Do not edit it manually.
+ * Please have a look at
+ *
+ * https://docs.rtems.org/branches/master/eng/req/howto.html
+ *
+ * for information how to maintain and re-generate this file.
*/
#ifndef _RTEMS_IO_H
#define _RTEMS_IO_H
+#include <stdint.h>
#include <rtems/rtems/status.h>
#ifdef __cplusplus
@@ -26,203 +54,397 @@ extern "C" {
#endif
/**
- * @defgroup ClassicIO Input/Output
+ * @defgroup RTEMSAPIClassicIO Input/Output Interface Manager
*
* @ingroup RTEMSAPIClassic
*
+ * @brief The Input/Output Interface Manager provides a well-defined mechanism
+ * for accessing device drivers and a structured methodology for organizing
+ * device drivers.
*/
-/**@{**/
-
-typedef uint32_t rtems_device_major_number;
+/**
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief This integer type represents the minor number of devices.
+ *
+ * The minor number of devices is managed by the device driver.
+ */
typedef uint32_t rtems_device_minor_number;
-typedef rtems_status_code rtems_device_driver;
+/**
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief This integer type represents the major number of devices.
+ *
+ * The major number of a device is determined by rtems_io_register_driver() and
+ * the application configuration (see #CONFIGURE_MAXIMUM_DRIVERS) .
+ */
+typedef uint32_t rtems_device_major_number;
-typedef rtems_device_driver (*rtems_device_driver_entry)(
- rtems_device_major_number,
- rtems_device_minor_number,
- void *
-);
+/**
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief This type shall be used in device driver entry declarations and
+ * definitions.
+ *
+ * Device driver entries return an #rtems_status_code status code. This type
+ * definition helps to document device driver entries in the source code.
+ */
+typedef rtems_status_code rtems_device_driver;
+/**
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief This structure contains the device driver entries.
+ *
+ * This structure is used to register a device driver via
+ * rtems_io_register_driver().
+ */
typedef struct {
+ /**
+ * @brief This member is the device driver initialization entry.
+ *
+ * This entry is called by rtems_io_initialize()
+ */
rtems_device_driver_entry initialization_entry;
+
+ /**
+ * @brief This member is the device driver open entry.
+ *
+ * This entry is called by rtems_io_open().
+ */
rtems_device_driver_entry open_entry;
+
+ /**
+ * @brief This member is the device driver close entry.
+ *
+ * This entry is called by rtems_io_close().
+ */
rtems_device_driver_entry close_entry;
+
+ /**
+ * @brief This member is the device driver read entry.
+ *
+ * This entry is called by rtems_io_read().
+ */
rtems_device_driver_entry read_entry;
+
+ /**
+ * @brief This member is the device driver write entry.
+ *
+ * This entry is called by rtems_io_write().
+ */
rtems_device_driver_entry write_entry;
+
+ /**
+ * @brief This member is the device driver control entry.
+ *
+ * This entry is called by rtems_io_control().
+ */
rtems_device_driver_entry control_entry;
} rtems_driver_address_table;
/**
- * @name Device Driver Maintainance
- */
-/**@{**/
-
-/**
- * @brief Registers and initializes the device with the device driver table
- * @a driver_table and major number @a major.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief Closes the device specified by the device major and minor numbers.
+ *
+ * This directive calls the device driver close entry registered in the Device
+ * Driver Table for the specified device major number.
+ *
+ * The close entry point is commonly used by device drivers to relinquish
+ * exclusive access to a device.
+ *
+ * @param major is the major number of the device.
*
- * If the major number equals zero a major number will be obtained. The major
- * number of the registered driver will be returned in @a registered_major.
+ * @param minor is the minor number of the device.
*
- * After a successful registration rtems_io_initialize() will be called to
- * initialize the device.
+ * @param argument is the argument passed to the device driver close entry.
*
- * @retval RTEMS_SUCCESSFUL Device successfully registered and initialized.
- * @retval RTEMS_INVALID_ADDRESS Pointer to driver table or to registered
- * major number are invalid. Device driver table is empty.
- * @retval RTEMS_INVALID_NUMBER Invalid major number.
- * @retval RTEMS_TOO_MANY No major number available.
- * @retval RTEMS_RESOURCE_IN_USE Major number in use.
- * @retval RTEMS_CALLED_FROM_ISR Called from interrupt context.
- * @retval * Status code depends on rtems_io_initialize().
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_NUMBER The device major number was invalid.
+ *
+ * @return Other status codes may be returned by the device driver close entry.
*/
-rtems_status_code rtems_io_register_driver(
+rtems_status_code rtems_io_close(
rtems_device_major_number major,
- const rtems_driver_address_table *driver_table,
- rtems_device_major_number *registered_major
+ rtems_device_minor_number minor,
+ void *argument
);
/**
- * @brief Unregister a driver from the device driver table.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief Controls the device specified by the device major and minor numbers.
+ *
+ * This directive calls the device driver I/O control entry registered in the
+ * Device Driver Table for the specified device major number.
+ *
+ * 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.
+ *
+ * @param major is the major number of the device.
*
- * @param[in] major is the device major number.
+ * @param minor is the minor number of the device.
*
- * @retval RTEMS_SUCCESSFUL Device driver successfully unregistered.
- * @retval RTEMS_UNSATISFIED Invalid major number.
- * @retval RTEMS_CALLED_FROM_ISR Called from interrupt context.
+ * @param argument is the argument passed to the device driver I/O control
+ * entry.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_NUMBER The device major number was invalid.
+ *
+ * @return Other status codes may be returned by the device driver I/O control
+ * entry.
*/
-rtems_status_code rtems_io_unregister_driver(
- rtems_device_major_number major
+rtems_status_code rtems_io_control(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
);
/**
- * @brief Registers the name @a device_name in the file system for the device
- * with number tuple @a major and @a minor.
- *
- * This assumes that all registered devices are character devices.
+ * @ingroup RTEMSAPIClassicIO
*
- * @retval RTEMS_SUCCESSFUL Name successfully registered.
- * @retval RTEMS_TOO_MANY Name already in use or other errors.
+ * @brief Device driver entries shall have this type.
*/
-rtems_status_code rtems_io_register_name(
- const char *device_name,
- rtems_device_major_number major,
- rtems_device_minor_number minor
-);
-
-/** @} */
+typedef rtems_device_driver ( *rtems_device_driver_entry )(
+ rtems_device_major_number,
+ rtems_device_minor_number,
+ void *
+);;
/**
- * @brief IO driver initialization.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief Initializes the device specified by the device major and minor
+ * numbers.
+ *
+ * This directive calls the device driver initialization entry registered in
+ * the Device Driver Table for the specified device major number.
*
- * This routine is the initialization directive of the IO manager.
+ * This directive is automatically invoked for each device driver defined by
+ * the application configuration during the system initialization and via the
+ * rtems_io_register_driver() directive.
*
- * @param[in] major is the device drive number
- * @param[in] minor is the device number
- * @param[in] argument is the pointer to the argument(s)
+ * 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.
*
- * @return status code
+ * @param major is the major number of the device.
+ *
+ * @param minor is the minor number of the device.
+ *
+ * @param argument is the argument passed to the device driver initialization
+ * entry.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_NUMBER The device major number was invalid.
+ *
+ * @return Other status codes may be returned by the device driver
+ * initialization routine.
*/
rtems_status_code rtems_io_initialize(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
);
/**
- * @brief Opening for the IO manager.
- *
- * Opens a device driver with the number @a major.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief Opens the device specified by the device major and minor numbers.
+ *
+ * This directive calls the device driver open entry registered in the Device
+ * Driver Table for the specified device major number.
+ *
+ * The open entry point is commonly used by device drivers to provide exclusive
+ * access to a device.
*
- * @param[in] major is the device driver number.
- * @param[in] minor is the device number.
- * @param[in] argument is the pointer to the argument(s).
+ * @param major is the major number of the device.
*
- * @return Status code.
+ * @param minor is the minor number of the device.
+ *
+ * @param argument is the argument passed to the device driver close entry.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_NUMBER The device major number was invalid.
+ *
+ * @return Other status codes may be returned by the device driver open
+ * routine.
*/
rtems_status_code rtems_io_open(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
);
/**
- * @brief Closing for the IO manager.
- *
- * This routine is the close directive of the IO manager.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief Reads from the device specified by the device major and minor
+ * numbers.
+ *
+ * This directive calls the device driver read entry registered in the Device
+ * Driver Table for the specified device major number.
+ *
+ * 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.
+ *
+ * @param major is the major number of the device.
*
- * @param[in] major is the device driver number.
- * @param[in] minor is the device number.
- * @param[in] argument is the pointer to the argument(s).
+ * @param minor is the minor number of the device.
*
- * @return Status code.
+ * @param argument is the argument passed to the device driver read entry.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_NUMBER The device major number was invalid.
+ *
+ * @return Other status codes may be returned by the device driver read
+ * routine.
*/
-rtems_status_code rtems_io_close(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
+rtems_status_code rtems_io_read(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
);
/**
- * @brief Reading for the IO manager.
- *
- * This routine is the read directive of the IO manager.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief Registers and initializes the device with the specified device driver
+ * address table and device major number in the Device Driver Table.
+ *
+ * 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 rtems_io_initialize() routine will be called
+ * to initialize the device.
+ *
+ * @param major is the device major number. Use a value of zero to let the
+ * system obtain a device major number automatically.
+ *
+ * @param driver_table is the device driver address table.
+ *
+ * @param[out] registered_major 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.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The device major number of the device was
+ * NULL.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The device driver address table was empty.
+ *
+ * @retval ::RTEMS_INVALID_NUMBER The device major number of the device was out
+ * of range, see #CONFIGURE_MAXIMUM_DRIVERS.
+ *
+ * @retval ::RTEMS_TOO_MANY The system was unable to obtain a device major
+ * number.
+ *
+ * @retval ::RTEMS_RESOURCE_IN_USE The device major number was in use.
*
- * @param[in] major is the device driver number.
- * @param[in] minor is the device number.
- * @param[in] argument is the pointer to the argument(s).
+ * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from interrupt
+ * context.
*
- * @return Status code.
+ * @return Other status codes may be returned by the device driver
+ * initialization routine.
*/
-rtems_status_code rtems_io_read(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
+rtems_status_code rtems_io_register_driver(
+ rtems_device_major_number major,
+ const rtems_driver_address_table *driver_table,
+ rtems_device_major_number *registered_major
);
/**
- * @brief Writing for the IO manager.
- *
- * This routine is the write directive of the IO manager.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief Registers the device specified by the device major and minor numbers
+ * in the file system under the specified name.
+ *
+ * The device is registered as a character device.
*
- * @param[in] major is the device driver number.
- * @param[in] minor is the device number.
- * @param[in] argument is the pointer to the argument(s).
+ * @param device_name is the device name in the file system.
*
- * @return Status code.
+ * @param major is the device major number.
+ *
+ * @param minor is the device minor number.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_TOO_MANY The name was already in use or other errors
+ * occurred.
*/
-rtems_status_code rtems_io_write(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
+rtems_status_code rtems_io_register_name(
+ const char *device_name,
+ rtems_device_major_number major,
+ rtems_device_minor_number minor
);
/**
- * @brief Control for the IO manager.
- *
- * This routine is the control directive of the IO manager.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief Removes a device driver specified by the device major number from the
+ * Device Driver Table.
+ *
+ * Currently no specific checks are made and the driver is not closed.
*
- * @param[in] major is the device driver number.
- * @param[in] minor is the device number.
- * @param[in] argument is the pointer to the argument(s).
+ * @param major is the major number of the device.
*
- * @return Status code.
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_UNSATISFIED The device major number was invalid.
+ *
+ * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from interrupt
+ * context.
*/
-rtems_status_code rtems_io_control(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
+rtems_status_code rtems_io_unregister_driver(
+ rtems_device_major_number major
);
-/** @} */
-
-/** @} */
+/**
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief Writes to the device specified by the device major and minor numbers.
+ *
+ * This directive calls the device driver write entry registered in the Device
+ * Driver Table for the specified device major number.
+ *
+ * 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.
+ *
+ * @param major is the major number of the device.
+ *
+ * @param minor is the minor number of the device.
+ *
+ * @param argument is the argument passed to the device driver write entry.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_NUMBER The device major number was invalid.
+ *
+ * @return Other status codes may be returned by the device driver write
+ * routine.
+ */
+rtems_status_code rtems_io_write(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
+);
#ifdef __cplusplus
}
#endif
-#endif
-/* end of include file */
+#endif /* _RTEMS_IO_H */
--
2.26.2
More information about the devel
mailing list