Generate <rtems/io.h>

1 files changed, 213 insertions, 137 deletions

diff --git a/cpukit/include/rtems/io.h b/cpukit/include/rtems/io.h
index f4066b647a..1ce2828876 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) 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.
+ *
+ * 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.
  */
 
 /*
- *  COPYRIGHT (c) 1989-2008.
- *  On-Line Applications Research Corporation (OAR).
+ * This file was automatically generated.  Do not edit it manually.
+ * Please have a look at
  *
- *  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.
+ * 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,214 +54,262 @@ 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 %
+ */
 typedef uint32_t rtems_device_minor_number;
 
+/**
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief %
+ */
+typedef uint32_t rtems_device_major_number;
+
+/**
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief %
+ */
 typedef rtems_status_code rtems_device_driver;
 
-typedef rtems_device_driver (*rtems_device_driver_entry)(
+/**
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief %
+ *
+ * @param major %
+ *
+ * @param minor %
+ *
+ * @param argument %
+ */
+rtems_status_code rtems_io_close(
+  rtems_device_major_number major,
+  rtems_device_minor_number minor,
+  void                     *argument
+);
+
+/**
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief %
+ *
+ * @param major %
+ *
+ * @param minor %
+ *
+ * @param argument %
+ */
+rtems_status_code rtems_io_control(
+  rtems_device_major_number major,
+  rtems_device_minor_number minor,
+  void                     *argument
+);
+
+/**
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief %
+ */
+typedef rtems_device_driver ( *rtems_device_driver_entry )(
   rtems_device_major_number,
   rtems_device_minor_number,
   void *
-);
+);;
 
+/**
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief %
+ */
 typedef struct {
+  /**
+   * @brief This member is
+   *
+   * %
+   */
   rtems_device_driver_entry initialization_entry;
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
   rtems_device_driver_entry open_entry;
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
   rtems_device_driver_entry close_entry;
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
   rtems_device_driver_entry read_entry;
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
   rtems_device_driver_entry write_entry;
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
   rtems_device_driver_entry control_entry;
 } rtems_driver_address_table;
 
 /**
- * @name Device Driver Maintainance
- */
-/**@{**/
-
-/**
- * @brief Returns @c RTEMS_IO_ERROR.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief %
  *
- * @retval RTEMS_IO_ERROR Only this one.
+ * @param major %
+ *
+ * @param minor %
+ *
+ * @param arg %
  */
 rtems_status_code rtems_io_driver_io_error(
   rtems_device_major_number major,
   rtems_device_minor_number minor,
-  void *arg
+  void                     *arg
 );
 
 /**
- * @brief Registers and initializes the device with the device driver table
- * @a driver_table and major number @a major.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief %
  *
- * 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 major %
  *
- * After a successful registration rtems_io_initialize() will be called to
- * initialize the device.
+ * @param minor %
  *
- * @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().
+ * @param argument %
  */
-rtems_status_code rtems_io_register_driver(
+rtems_status_code rtems_io_initialize(
   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
  *
- * @param[in] major is the device major number.
+ * @brief %
  *
- * @retval RTEMS_SUCCESSFUL Device driver successfully unregistered.
- * @retval RTEMS_UNSATISFIED Invalid major number.
- * @retval RTEMS_CALLED_FROM_ISR Called from interrupt context.
- */
-rtems_status_code rtems_io_unregister_driver(
-  rtems_device_major_number major
-);
-
-/**
- * @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.
+ * @param major %
+ *
+ * @param minor %
  *
- * @retval RTEMS_SUCCESSFUL Name successfully registered.
- * @retval RTEMS_TOO_MANY Name already in use or other errors. 
+ * @param argument %
  */
-rtems_status_code rtems_io_register_name(
-  const char *device_name,
+rtems_status_code rtems_io_open(
   rtems_device_major_number major,
-  rtems_device_minor_number minor
+  rtems_device_minor_number minor,
+  void                     *argument
 );
 
-/** @} */
-
 /**
- * @brief IO driver initialization.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief %
  *
- * This routine is the initialization directive of the IO manager.
+ * @param major %
  *
- * @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)
+ * @param minor %
  *
- * @return status code
+ * @param argument %
  */
-rtems_status_code rtems_io_initialize(
-  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 Opening for the IO manager.
- *  
- * Opens a device driver with the number @a major.
+ * @ingroup RTEMSAPIClassicIO
  *
- * @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).
+ * @brief %
  *
- * @return Status code.
- */
-rtems_status_code rtems_io_open(
-  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.
+ * @param major %
  *
- * @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 driver_table %
  *
- * @return Status code.
+ * @param registered_major %
  */
-rtems_status_code rtems_io_close(
-  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 Reading for the IO manager.
- *  
- * This routine is the read directive of the IO manager.
+ * @ingroup RTEMSAPIClassicIO
+ *
+ * @brief %
+ *
+ * @param device_name %
  *
- * @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 %
  *
- * @return Status code.
+ * @param minor %
  */
-rtems_status_code rtems_io_read(
-  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 Writing for the IO manager.
- *  
- * This routine is the write directive of the IO manager.
+ * @ingroup RTEMSAPIClassicIO
  *
- * @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).
+ * @brief %
  *
- * @return Status code.
+ * @param major %
  */
-rtems_status_code rtems_io_write(
-  rtems_device_major_number  major,
-  rtems_device_minor_number  minor,
-  void                      *argument
+rtems_status_code rtems_io_unregister_driver(
+  rtems_device_major_number major
 );
 
 /**
- * @brief Control for the IO manager.
- *  
- * This routine is the control directive of the IO manager.
+ * @ingroup RTEMSAPIClassicIO
  *
- * @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).
+ * @brief %
  *
- * @return Status code.
+ * @param major %
+ *
+ * @param minor %
+ *
+ * @param argument %
  */
-rtems_status_code rtems_io_control(
-  rtems_device_major_number  major,
-  rtems_device_minor_number  minor,
-  void                      *argument
+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 */