RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

rtems: Generate <rtems/io.h>

Browse Source 
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.
This commit is contained in:
Sebastian Huber
2020-05-28 15:52:11 +02:00
parent 243d3ed51d
commit 8111a6ba88
1 changed files with 373 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

491
cpukit/include/rtems/io.h
View File

@@ -1,228 +1,483 @@
/* SPDX-License-Identifier: BSD-2-Clause */
/** /**
* @file * @file
* *
* @brief Classic Input/Output Manager API * @ingroup RTEMSAPIClassicIO
* *
* This file emulates the old Classic RTEMS IO manager directives * @brief This header file defines the IO Manager API.
* which register names using the in-memory filesystem.
*/ */
/* /*
* COPYRIGHT (c) 1989-2008. * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
* On-Line Applications Research Corporation (OAR). * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
* *
* The license and distribution terms for this file may be * Redistribution and use in source and binary forms, with or without
* found in the file LICENSE in this distribution or at * modification, are permitted provided that the following conditions
* http://www.rtems.org/license/LICENSE. * 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.
*/ */
/*
* 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:
*
* https://docs.rtems.org/branches/master/eng/req/howto.html
*/
/* Generated from spec:/rtems/io/if/header */
#ifndef _RTEMS_IO_H #ifndef _RTEMS_IO_H
#define _RTEMS_IO_H #define _RTEMS_IO_H
#include <stdint.h>
#include <rtems/rtems/status.h> #include <rtems/rtems/status.h>
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
/* Generated from spec:/rtems/io/if/group */
/** /**
* @defgroup ClassicIO Input/Output * @defgroup RTEMSAPIClassicIO I/O Manager
* *
* @ingroup RTEMSAPIClassic * @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-driver */
typedef uint32_t rtems_device_minor_number;
/**
* @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_status_code rtems_device_driver;
typedef rtems_device_driver (*rtems_device_driver_entry)( /* 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-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-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_major_number,
rtems_device_minor_number, rtems_device_minor_number,
void * 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 { 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; 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; 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; 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; 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; 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_device_driver_entry control_entry;
} rtems_driver_address_table; } rtems_driver_address_table;
/** /* Generated from spec:/rtems/io/if/register-driver */
* @name Device Driver Maintainance
*/
/**@{**/
/** /**
* @brief Registers and initializes the device with the device driver table * @ingroup RTEMSAPIClassicIO
* @a driver_table and major number @a major.
* *
* If the major number equals zero a major number will be obtained. The major * @brief Registers and initializes the device with the specified device driver
* number of the registered driver will be returned in @a registered_major. * address table and device major number in the Device Driver Table.
* *
* After a successful registration rtems_io_initialize() will be called to * If the device major number equals zero a device major number will be
* initialize the device. * obtained. The device major number of the registered driver will be
* returned.
* *
* @retval RTEMS_SUCCESSFUL Device successfully registered and initialized. * After a successful registration, the rtems_io_initialize() directive will be
* @retval RTEMS_INVALID_ADDRESS Pointer to driver table or to registered * called to initialize the device.
* major number are invalid. Device driver table is empty. *
* @retval RTEMS_INVALID_NUMBER Invalid major number. * @param major is the device major number. Use a value of zero to let the
* @retval RTEMS_TOO_MANY No major number available. * system obtain a device major number automatically.
* @retval RTEMS_RESOURCE_IN_USE Major number in use. *
* @retval RTEMS_CALLED_FROM_ISR Called from interrupt context. * @param driver_table is the device driver address table.
* @retval * Status code depends on rtems_io_initialize(). *
* @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.
*
* @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_register_driver( rtems_status_code rtems_io_register_driver(
rtems_device_major_number major, rtems_device_major_number major,
const rtems_driver_address_table *driver_table, const rtems_driver_address_table *driver_table,
rtems_device_major_number *registered_major rtems_device_major_number *registered_major
); );
/* Generated from spec:/rtems/io/if/unregister-driver */
/** /**
* @brief Unregister a driver from the device driver table. * @ingroup RTEMSAPIClassicIO
* *
* @param[in] major is the device major number. * @brief Removes a device driver specified by the device major number from the
* Device Driver Table.
* *
* @retval RTEMS_SUCCESSFUL Device driver successfully unregistered. * Currently no specific checks are made and the driver is not closed.
* @retval RTEMS_UNSATISFIED Invalid major number. *
* @retval RTEMS_CALLED_FROM_ISR Called from interrupt context. * @param major is the major number of the device.
*
* @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_unregister_driver( rtems_status_code rtems_io_unregister_driver(
rtems_device_major_number major rtems_device_major_number major
); );
/* Generated from spec:/rtems/io/if/initialize */
/** /**
* @brief Registers the name @a device_name in the file system for the device * @ingroup RTEMSAPIClassicIO
* with number tuple @a major and @a minor.
*
* This assumes that all registered devices are character devices.
* *
* @retval RTEMS_SUCCESSFUL Name successfully registered. * @brief Initializes the device specified by the device major and minor
* @retval RTEMS_TOO_MANY Name already in use or other errors. * 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.
*
* @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 entry.
*/
rtems_status_code rtems_io_initialize(
rtems_device_major_number major,
rtems_device_minor_number minor,
void *argument
);
/* Generated from spec:/rtems/io/if/register-name */
/**
* @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.
*
* @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_register_name( rtems_status_code rtems_io_register_name(
const char *device_name, const char *device_name,
rtems_device_major_number major, rtems_device_major_number major,
rtems_device_minor_number minor rtems_device_minor_number minor
); );
/** @} */ /* Generated from spec:/rtems/io/if/open */
/** /**
* @brief IO driver initialization. * @ingroup RTEMSAPIClassicIO
* *
* This routine is the initialization directive of the IO manager. * @brief Opens the device specified by the device major and minor numbers.
* *
* @param[in] major is the device drive number * This directive calls the device driver open entry registered in the Device
* @param[in] minor is the device number * Driver Table for the specified device major number.
* @param[in] argument is the pointer to the argument(s)
* *
* @return status code * The open entry point is commonly used by device drivers to provide exclusive
*/ * access to a device.
rtems_status_code rtems_io_initialize(
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.
* *
* @param[in] major is the device driver number. * @param major is the major number of the device.
* @param[in] minor is the device number.
* @param[in] argument is the pointer to the argument(s).
* *
* @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 entry.
*/ */
rtems_status_code rtems_io_open( rtems_status_code rtems_io_open(
rtems_device_major_number major, rtems_device_major_number major,
rtems_device_minor_number minor, rtems_device_minor_number minor,
void *argument void *argument
); );
/* Generated from spec:/rtems/io/if/close */
/** /**
* @brief Closing for the IO manager. * @ingroup RTEMSAPIClassicIO
*
* This routine is the close directive of the IO manager.
* *
* @param[in] major is the device driver number. * @brief Closes the device specified by the device major and minor numbers.
* @param[in] minor is the device number.
* @param[in] argument is the pointer to the argument(s).
* *
* @return Status code. * 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.
*
* @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_close( rtems_status_code rtems_io_close(
rtems_device_major_number major, rtems_device_major_number major,
rtems_device_minor_number minor, rtems_device_minor_number minor,
void *argument void *argument
); );
/* Generated from spec:/rtems/io/if/read */
/** /**
* @brief Reading for the IO manager. * @ingroup RTEMSAPIClassicIO
*
* This routine is the read directive of the IO manager.
* *
* @param[in] major is the device driver number. * @brief Reads from the device specified by the device major and minor
* @param[in] minor is the device number. * numbers.
* @param[in] argument is the pointer to the argument(s).
* *
* @return Status code. * 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 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_read( rtems_status_code rtems_io_read(
rtems_device_major_number major, rtems_device_major_number major,
rtems_device_minor_number minor, rtems_device_minor_number minor,
void *argument void *argument
); );
/* Generated from spec:/rtems/io/if/write */
/** /**
* @brief Writing for the IO manager. * @ingroup RTEMSAPIClassicIO
*
* This routine is the write directive of the IO manager.
* *
* @param[in] major is the device driver number. * @brief Writes to the device specified by the device major and minor numbers.
* @param[in] minor is the device number.
* @param[in] argument is the pointer to the argument(s).
* *
* @return Status code. * 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_status_code rtems_io_write(
rtems_device_major_number major, rtems_device_major_number major,
rtems_device_minor_number minor, rtems_device_minor_number minor,
void *argument void *argument
); );
/* Generated from spec:/rtems/io/if/control */
/** /**
* @brief Control for the IO manager. * @ingroup RTEMSAPIClassicIO
*
* This routine is the control directive of the IO manager.
* *
* @param[in] major is the device driver number. * @brief Controls the device specified by the device major and minor numbers.
* @param[in] minor is the device number.
* @param[in] argument is the pointer to the argument(s).
* *
* @return Status code. * 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 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_control( rtems_status_code rtems_io_control(
rtems_device_major_number major, rtems_device_major_number major,
rtems_device_minor_number minor, rtems_device_minor_number minor,
void *argument void *argument
); );
/** @} */
/** @} */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
#endif #endif /* _RTEMS_IO_H */
/* end of include file */