[PATCH v2] rtems: Generate <rtems/io.h>
Gedare Bloom
gedare at rtems.org
Wed Oct 7 15:26:58 UTC 2020
it would be good to review the generated doxygen. some comments below.
overall a positive improvement.
On Wed, Oct 7, 2020 at 4:19 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> 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.
> ---
> v2:
>
> * Add "Generated from ..." comments.
>
> * Improve file header comment.
>
> cpukit/include/rtems/io.h | 501 ++++++++++++++++++++++++++++----------
> 1 file changed, 378 insertions(+), 123 deletions(-)
>
> diff --git a/cpukit/include/rtems/io.h b/cpukit/include/rtems/io.h
> index 67364df280..4cac884756 100644
> --- a/cpukit/include/rtems/io.h
> +++ b/cpukit/include/rtems/io.h
> @@ -1,228 +1,483 @@
> +/* 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).
> + * Do not manually edit this file. It is part of the RTEMS quality process
> + * and was automatically generated.
> + *
> + * If you find something that needs to be fixed or worded better please
> + * post a report to an RTEMS mailing list or raise a bug report:
> + *
> + * https://docs.rtems.org/branches/master/user/support/bugs.html
> + *
> + * For information on updating and regenerating please refer to:
> *
> - * 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
> */
>
> +/* Generated from spec:/rtems/io/if/header */
> +
> #ifndef _RTEMS_IO_H
> #define _RTEMS_IO_H
>
> +#include <stdint.h>
> #include <rtems/rtems/status.h>
>
> #ifdef __cplusplus
> extern "C" {
> #endif
>
> +/* Generated from spec:/rtems/io/if/group */
> +
> /**
> - * @defgroup ClassicIO Input/Output
> + * @defgroup RTEMSAPIClassicIO I/O Manager
> *
> * @ingroup RTEMSAPIClassic
> *
> + * @brief The Input/Output (I/O) 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;
> +/* Generated from spec:/rtems/io/if/device-minor-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;
>
> +/* Generated from spec:/rtems/io/if/device-major-number */
> +
> +/**
> + * @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;
> +
> +/* Generated from spec:/rtems/io/if/device-driver */
> +
> +/**
> + * @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;
>
> -typedef rtems_device_driver (*rtems_device_driver_entry)(
> +/* Generated from spec:/rtems/io/if/device-driver-entry */
> +
> +/**
> + * @ingroup RTEMSAPIClassicIO
> + *
> + * @brief Device driver entries shall have this type.
> + */
> +typedef rtems_device_driver ( *rtems_device_driver_entry )(
> rtems_device_major_number,
> rtems_device_minor_number,
> void *
> -);
> +);;
two semi-colons
> +
> +/* Generated from spec:/rtems/io/if/driver-address-table */
>
> +/**
> + * @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()
add period
> + */
> 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
> - */
> -/**@{**/
> +/* Generated from spec:/rtems/io/if/close */
>
> /**
> - * @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.
> *
> - * 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.
> + * This directive calls the device driver close entry registered in the Device
> + * Driver Table for the specified device major number.
> *
> - * After a successful registration rtems_io_initialize() will be called to
> - * initialize the device.
> + * The close entry point is commonly used by device drivers to relinquish
> + * exclusive access to a device.
> *
> - * @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 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 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 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
> );
>
Thinking about the discussion about ordering directives in the docs,
the generated header reorders directives also. Is it also doing
generation by alphabetical order?
Should we consider using the same order as defined for the API
documentation? I guess this would make the Doxygen consistently
ordered wrt the docs.
> +/* Generated from spec:/rtems/io/if/control */
> +
> /**
> - * @brief Unregister a driver from the device driver table.
> + * @ingroup RTEMSAPIClassicIO
> *
> - * @param[in] major is the device major number.
> + * @brief Controls the device specified by the device major and minor numbers.
> *
> - * @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.
> + * 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 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 minor is the minor number of the device.
> *
> - * @retval RTEMS_SUCCESSFUL Name successfully registered.
> - * @retval RTEMS_TOO_MANY Name already in use or other errors.
> + * @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_register_name(
> - const char *device_name,
> +rtems_status_code rtems_io_control(
> rtems_device_major_number major,
> - rtems_device_minor_number minor
> + rtems_device_minor_number minor,
> + void *argument
> );
>
> -/** @} */
> +/* Generated from spec:/rtems/io/if/initialize */
>
> /**
> - * @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 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.
> *
> - * This routine is the initialization directive of the IO manager.
> + * 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.
> *
> - * @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 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 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 entry.
> */
> 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
> );
>
> +/* Generated from spec:/rtems/io/if/open */
> +
> /**
> - * @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 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 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 entry.
> */
> 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
> );
>
> +/* Generated from spec:/rtems/io/if/read */
> +
> /**
> - * @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 entry.
> */
> -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
> );
>
> +/* Generated from spec:/rtems/io/if/register-driver */
> +
> /**
> - * @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, the rtems_io_initialize() directive 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.
> *
> - * @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_RESOURCE_IN_USE The device major number was already in use.
> *
> - * @return Status code.
> + * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from interrupt
> + * context.
> + *
> + * @return Other status codes may be returned by rtems_io_initialize().
> */
> -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
> );
>
> +/* Generated from spec:/rtems/io/if/register-name */
> +
> /**
> - * @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 device_name is the device name in the file system.
> + *
> + * @param major is the device major number.
> + *
> + * @param minor is the device minor number.
> *
> - * @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_SUCCESSFUL The requested operation was successful.
> *
> - * @return Status code.
> + * @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
> );
>
> +/* Generated from spec:/rtems/io/if/unregister-driver */
> +
> /**
> - * @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 major is the major number of the device.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> *
> - * @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_UNSATISFIED The device major number was invalid.
> *
> - * @return Status code.
> + * @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
> );
>
> -/** @} */
> +/* Generated from spec:/rtems/io/if/write */
>
> -/** @} */
> +/**
> + * @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 entry.
> + */
> +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
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
More information about the devel
mailing list