diff options
Diffstat (limited to '')
| -rw-r--r-- | ada_user/io_manager.rst | 571 |
1 files changed, 0 insertions, 571 deletions
diff --git a/ada_user/io_manager.rst b/ada_user/io_manager.rst deleted file mode 100644 index 2fa37d2..0000000 --- a/ada_user/io_manager.rst +++ /dev/null @@ -1,571 +0,0 @@ -I/O Manager -########### - -.. index:: device drivers -.. index:: IO Manager - -Introduction -============ - -The input/output interface manager provides a -well-defined mechanism for accessing device drivers and a -structured methodology for organizing device drivers. The -directives provided by the I/O manager are: - -- ``rtems.io_initialize`` - Initialize a device driver - -- ``rtems.io_register_driver`` - Register a device driver - -- ``rtems.io_unregister_driver`` - Unregister a device driver - -- ``rtems.io_register_name`` - Register a device name - -- ``rtems.io_lookup_name`` - Look up a device name - -- ``rtems.io_open`` - Open a device - -- ``rtems.io_close`` - Close a device - -- ``rtems.io_read`` - Read from a device - -- ``rtems.io_write`` - Write to a device - -- ``rtems.io_control`` - Special device services - -Background -========== - -Device Driver Table -------------------- -.. index:: Device Driver Table - -Each application utilizing the RTEMS I/O manager must specify the -address of a Device Driver Table in its Configuration Table. This table -contains each device driver’s entry points that is to be initialised by -RTEMS during initialization. Each device driver may contain the -following entry points: - -- Initialization - -- Open - -- Close - -- Read - -- Write - -- Control - -If the device driver does not support a particular -entry point, then that entry in the Configuration Table should -be NULL. RTEMS will return``RTEMS.SUCCESSFUL`` as the executive’s and -zero (0) as the device driver’s return code for these device -driver entry points. - -Applications can register and unregister drivers with the RTEMS I/O -manager avoiding the need to have all drivers statically defined and -linked into this table. - -The :file:`confdefs.h` entry ``CONFIGURE_MAXIMUM_DRIVERS`` configures -the number of driver slots available to the application. - -Major and Minor Device Numbers ------------------------------- -.. index:: major device number -.. index:: minor device number - -Each call to the I/O manager must provide a device’s -major and minor numbers as arguments. The major number is the -index of the requested driver’s entry points in the Device -Driver Table, and is used to select a specific device driver. -The exact usage of the minor number is driver specific, but is -commonly used to distinguish between a number of devices -controlled by the same driver... index:: rtems_device_major_number -.. index:: rtems_device_minor_number - -The data types ``rtems.device_major_number`` and``rtems.device_minor_number`` are used to -manipulate device major and minor numbers, respectively. - -Device Names ------------- -.. index:: device names - -The I/O Manager provides facilities to associate a -name with a particular device. Directives are provided to -register the name of a device and to look up the major/minor -number pair associated with a device name. - -Device Driver Environment -------------------------- - -Application developers, as well as device driver -developers, must be aware of the following regarding the RTEMS -I/O Manager: - -- A device driver routine executes in the context of the - invoking task. Thus if the driver blocks, the invoking task - blocks. - -- The device driver is free to change the modes of the - invoking task, although the driver should restore them to their - original values. - -- Device drivers may be invoked from ISRs. - -- Only local device drivers are accessible through the I/O - manager. - -- A device driver routine may invoke all other RTEMS - directives, including I/O directives, on both local and global - objects. - -Although the RTEMS I/O manager provides a framework -for device drivers, it makes no assumptions regarding the -construction or operation of a device driver. - -Runtime Driver Registration ---------------------------- -.. index:: runtime driver registration - -Board support package and application developers can select wether a -device driver is statically entered into the default device table or -registered at runtime. - -Dynamic registration helps applications where: - -# The BSP and kernel libraries are common to a range of applications - for a specific target platform. An application may be built upon a - common library with all drivers. The application selects and registers - the drivers. Uniform driver name lookup protects the application. - -# The type and range of drivers may vary as the application probes a - bus during initialization. - -# Support for hot swap bus system such as Compact PCI. - -# Support for runtime loadable driver modules. - -Device Driver Interface ------------------------ -.. index:: device driver interface - -When an application invokes an I/O manager directive, -RTEMS determines which device driver entry point must be -invoked. The information passed by the application to RTEMS is -then passed to the correct device driver entry point. RTEMS -will invoke each device driver entry point assuming it is -compatible with the following prototype: - -.. code:: c - - function IO_Entry ( - Major : in RTEMS.Device_Major_Number; - Minor : in RTEMS.Device_Major_Number; - Argument_Block : in RTEMS.Address - ) return RTEMS.Status_Code; - -The format and contents of the parameter block are -device driver and entry point dependent. - -It is recommended that a device driver avoid -generating error codes which conflict with those used by -application components. A common technique used to generate -driver specific error codes is to make the most significant part -of the status indicate a driver specific code. - -Device Driver Initialization ----------------------------- - -RTEMS automatically initializes all device drivers -when multitasking is initiated via the``rtems.initialize_executive`` -directive. RTEMS initializes the device drivers by invoking -each device driver initialization entry point with the following -parameters: - -major - the major device number for this device driver. - -minor - zero. - -argument_block - will point to the Configuration Table. - -The returned status will be ignored by RTEMS. If the driver -cannot successfully initialize the device, then it should invoke -the fatal_error_occurred directive. - -Operations -========== - -Register and Lookup Name ------------------------- - -The ``rtems.io_register`` directive associates a name with the -specified device (i.e. major/minor number pair). Device names -are typically registered as part of the device driver -initialization sequence. The ``rtems.io_lookup`` -directive is used to -determine the major/minor number pair associated with the -specified device name. The use of these directives frees the -application from being dependent on the arbitrary assignment of -major numbers in a particular application. No device naming -conventions are dictated by RTEMS. - -Accessing an Device Driver --------------------------- - -The I/O manager provides directives which enable the -application program to utilize device drivers in a standard -manner. There is a direct correlation between the RTEMS I/O -manager directives``rtems.io_initialize``,``rtems.io_open``,``rtems.io_close``,``rtems.io_read``,``rtems.io_write``, and``rtems.io_control`` -and the underlying device driver entry points. - -Directives -========== - -This section details the I/O manager’s directives. A -subsection is dedicated to each of this manager’s directives and -describes the calling sequence, related constants, usage, and -status codes. - -IO_REGISTER_DRIVER - Register a device driver ---------------------------------------------- -.. index:: register a device driver - -**CALLING SEQUENCE:** - -.. code:: c - - No Ada implementation. - -**DIRECTIVE STATUS CODES:** - -``RTEMS.SUCCESSFUL`` - successfully registered -``RTEMS.INVALID_ADDRESS`` - invalid registered major pointer -``RTEMS.INVALID_ADDRESS`` - invalid driver table -``RTEMS.INVALID_NUMBER`` - invalid major device number -``RTEMS.TOO_MANY`` - no available major device table slot -``RTEMS.RESOURCE_IN_USE`` - major device number entry in use - -**DESCRIPTION:** - -This directive attempts to add a new device driver to the Device Driver -Table. The user can specify a specific major device number via the -directive’s ``major`` parameter, or let the registration routine find -the next available major device number by specifing a major number of``0``. The selected major device number is returned via the``registered_major`` directive parameter. The directive automatically -allocation major device numbers from the highest value down. - -This directive automatically invokes the IO_INITIALIZE directive if -the driver address table has an initialization and open entry. - -The directive returns RTEMS.TOO_MANY if Device Driver Table is -full, and RTEMS.RESOURCE_IN_USE if a specific major device -number is requested and it is already in use. - -**NOTES:** - -The Device Driver Table size is specified in the Configuration Table -condiguration. This needs to be set to maximum size the application -requires. - -IO_UNREGISTER_DRIVER - Unregister a device driver -------------------------------------------------- -.. index:: unregister a device driver - -**CALLING SEQUENCE:** - -.. code:: c - - No Ada implementation. - -**DIRECTIVE STATUS CODES:** - -``RTEMS.SUCCESSFUL`` - successfully registered -``RTEMS.INVALID_NUMBER`` - invalid major device number - -**DESCRIPTION:** - -This directive removes a device driver from the Device Driver Table. - -**NOTES:** - -Currently no specific checks are made and the driver is not closed. - -IO_INITIALIZE - Initialize a device driver ------------------------------------------- -.. index:: initialize a device driver - -**CALLING SEQUENCE:** - -.. code:: c - - procedure IO_Initialize ( - Major : in RTEMS.Device_Major_Number; - Minor : in RTEMS.Device_Minor_Number; - Argument : in RTEMS.Address; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``RTEMS.SUCCESSFUL`` - successfully initialized -``RTEMS.INVALID_NUMBER`` - invalid major device number - -**DESCRIPTION:** - -This directive calls the device driver initialization -routine specified in the Device Driver Table for this major -number. This directive is automatically invoked for each device -driver when multitasking is initiated via the -initialize_executive directive. - -A device driver initialization module 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. - -**NOTES:** - -This directive may or may not cause the calling task -to be preempted. This is dependent on the device driver being -initialized. - -IO_REGISTER_NAME - Register a device ------------------------------------- -.. index:: register device - -**CALLING SEQUENCE:** - -.. code:: c - - procedure IO_Register_Name ( - Name : in String; - Major : in RTEMS.Device_Major_Number; - Minor : in RTEMS.Device_Minor_Number; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``RTEMS.SUCCESSFUL`` - successfully initialized -``RTEMS.TOO_MANY`` - too many devices registered - -**DESCRIPTION:** - -This directive associates name with the specified -major/minor number pair. - -**NOTES:** - -This directive will not cause the calling task to be -preempted. - -IO_LOOKUP_NAME - Lookup a device --------------------------------- -.. index:: lookup device major and minor number - -**CALLING SEQUENCE:** - -.. code:: c - - procedure IO_Lookup_Name ( - Name : in String; - Device_Info : out RTEMS.Driver_Name_t_Pointer; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``RTEMS.SUCCESSFUL`` - successfully initialized -``RTEMS.UNSATISFIED`` - name not registered - -**DESCRIPTION:** - -This directive returns the major/minor number pair -associated with the given device name in ``device_info``. - -**NOTES:** - -This directive will not cause the calling task to be -preempted. - -IO_OPEN - Open a device ------------------------ -.. index:: open a devive - -**CALLING SEQUENCE:** - -.. code:: c - - procedure IO_Open ( - Major : in RTEMS.Device_Major_Number; - Minor : in RTEMS.Device_Minor_Number; - Argument : in RTEMS.Address; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``RTEMS.SUCCESSFUL`` - successfully initialized -``RTEMS.INVALID_NUMBER`` - invalid major device number - -**DESCRIPTION:** - -This directive calls the device driver open routine -specified in the Device Driver Table for this major number. The -open entry point is commonly used by device drivers to provide -exclusive access to a device. - -**NOTES:** - -This directive may or may not cause the calling task -to be preempted. This is dependent on the device driver being -invoked. - -IO_CLOSE - Close a device -------------------------- -.. index:: close a device - -**CALLING SEQUENCE:** - -.. code:: c - - procedure IO_Close ( - Major : in RTEMS.Device_Major_Number; - Minor : in RTEMS.Device_Minor_Number; - Argument : in RTEMS.Address; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``RTEMS.SUCCESSFUL`` - successfully initialized -``RTEMS.INVALID_NUMBER`` - invalid major device number - -**DESCRIPTION:** - -This directive calls the device driver close routine -specified in the Device Driver Table for this major number. The -close entry point is commonly used by device drivers to -relinquish exclusive access to a device. - -**NOTES:** - -This directive may or may not cause the calling task -to be preempted. This is dependent on the device driver being -invoked. - -IO_READ - Read from a device ----------------------------- -.. index:: read from a device - -**CALLING SEQUENCE:** - -.. code:: c - - procedure IO_Read ( - Major : in RTEMS.Device_Major_Number; - Minor : in RTEMS.Device_Minor_Number; - Argument : in RTEMS.Address; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``RTEMS.SUCCESSFUL`` - successfully initialized -``RTEMS.INVALID_NUMBER`` - invalid major device number - -**DESCRIPTION:** - -This directive calls the device driver read routine -specified in the Device Driver Table for this 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. - -**NOTES:** - -This directive may or may not cause the calling task -to be preempted. This is dependent on the device driver being -invoked. - -IO_WRITE - Write to a device ----------------------------- -.. index:: write to a device - -**CALLING SEQUENCE:** - -.. code:: c - - procedure IO_Write ( - Major : in RTEMS.Device_Major_Number; - Minor : in RTEMS.Device_Minor_Number; - Argument : in RTEMS.Address; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``RTEMS.SUCCESSFUL`` - successfully initialized -``RTEMS.INVALID_NUMBER`` - invalid major device number - -**DESCRIPTION:** - -This directive calls the device driver write routine -specified in the Device Driver Table for this 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. - -**NOTES:** - -This directive may or may not cause the calling task -to be preempted. This is dependent on the device driver being -invoked. - -IO_CONTROL - Special device services ------------------------------------- -.. index:: special device services -.. index:: IO Control - -**CALLING SEQUENCE:** - -.. code:: c - - procedure IO_Control ( - Major : in RTEMS.Device_Major_Number; - Minor : in RTEMS.Device_Minor_Number; - Argument : in RTEMS.Address; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``RTEMS.SUCCESSFUL`` - successfully initialized -``RTEMS.INVALID_NUMBER`` - invalid major device number - -**DESCRIPTION:** - -This directive calls the device driver I/O control -routine specified in the Device Driver Table for this 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. - -**NOTES:** - -This directive may or may not cause the calling task -to be preempted. This is dependent on the device driver being -invoked. - -.. COMMENT: COPYRIGHT (c) 1988-2002. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - |