[PATCH v2] rtems: Generate <rtems/io.h>
Gedare Bloom
gedare at rtems.org
Thu Oct 8 16:12:38 UTC 2020
Hi Sebastian,
On Thu, Oct 8, 2020 at 12:35 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:
>
> * Fix some typos.
>
> Doxygen output can be reviewed here:
>
> https://ftp.rtems.org/pub/rtems/people/sebh/doc/html/group__RTEMSAPIClassicIO.html
>
This one looks good to me.
> https://ftp.rtems.org/pub/rtems/people/sebh/doc/html/group__RTEMSAPIClassicEvent.html
However, I was reviewing the doxygen output of event.h and see that it
generates the bitmask macros in a strange order. I think these need to
be fixed to keep them grouped and order them with respect to each
other in ascending/descending order. I guess this can be complex, but
it is needed for human readability in this case.
>
> https://ftp.rtems.org/pub/rtems/people/sebh/doc/html/group__RTEMSAPIClassicPart.html
>
> cpukit/include/rtems/io.h | 499 ++++++++++++++++++++++++++++----------
> 1 file changed, 377 insertions(+), 122 deletions(-)
>
> diff --git a/cpukit/include/rtems/io.h b/cpukit/include/rtems/io.h
> index 67364df280..5fc984ed44 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 *
> );
>
> +/* 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().
> + */
> 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.
> + *
> + * This directive calls the device driver close entry registered in the Device
> + * Driver Table for the specified device major number.
> *
> - * 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.
> + * The close entry point is commonly used by device drivers to relinquish
> + * exclusive access to a device.
> *
> - * After a successful registration rtems_io_initialize() will be called to
> - * initialize the device.
> + * @param major is the major number of the 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 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
> );
>
> +/* 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.
> + *
> + * @param argument is the argument passed to the device driver I/O control
> + * entry.
> *
> - * @retval RTEMS_SUCCESSFUL Name successfully registered.
> - * @retval RTEMS_TOO_MANY Name already in use or other errors.
> + * @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.
> + *
> + * 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.
> *
> - * This routine is the initialization directive of the IO manager.
> + * @param major is the major number of the device.
> *
> - * @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 is the minor number of the device.
> *
> - * @return status code
> + * @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 minor is the minor 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 argument is the argument passed to the device driver close entry.
> *
> - * @return Status code.
> + * @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 minor is the minor 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 argument is the argument passed to the device driver read entry.
> *
> - * @return Status code.
> + * @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.
> + *
> + * @retval ::RTEMS_RESOURCE_IN_USE The device major number was already 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 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