diff options
author | Chris Johns <chrisj@rtems.org> | 2016-11-08 15:26:50 +1100 |
---|---|---|
committer | Chris Johns <chrisj@rtems.org> | 2016-11-08 15:28:32 +1100 |
commit | 53bb72e99669750ecbd7a418047711a21e32ac40 (patch) | |
tree | b0cd10cb72041c45696ae9540c406b83ed1e62cb /c-user/io_manager.rst | |
parent | pdf: Format lists for directives to sit on the next line. (diff) | |
download | rtems-docs-53bb72e99669750ecbd7a418047711a21e32ac40.tar.bz2 |
c-user: Format the directives as descriptions.
This change combined with the element list change in latex generates
a much better looking PDF.
Add a page break before each directive to like th previous versions of the
manuals.
Diffstat (limited to 'c-user/io_manager.rst')
-rw-r--r-- | c-user/io_manager.rst | 535 |
1 files changed, 263 insertions, 272 deletions
diff --git a/c-user/io_manager.rst b/c-user/io_manager.rst index 50340c9..74ca5b1 100644 --- a/c-user/io_manager.rst +++ b/c-user/io_manager.rst @@ -221,371 +221,367 @@ 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. +.. raw:: latex + + \clearpage + .. _rtems_io_register_driver: IO_REGISTER_DRIVER - Register a device driver --------------------------------------------- .. index:: register a device driver - -**CALLING SEQUENCE:** - .. index:: rtems_io_register_driver -.. code-block:: c - - rtems_status_code rtems_io_register_driver( - rtems_device_major_number major, - rtems_driver_address_table *driver_table, - rtems_device_major_number *registered_major - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``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. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_io_register_driver( + rtems_device_major_number major, + rtems_driver_address_table *driver_table, + rtems_device_major_number *registered_major + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``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. + +.. raw:: latex + + \clearpage .. _rtems_io_unregister_driver: IO_UNREGISTER_DRIVER - Unregister a device driver ------------------------------------------------- .. index:: unregister a device driver - -**CALLING SEQUENCE:** - .. index:: rtems_io_unregister_driver -.. code-block:: c - - rtems_status_code rtems_io_unregister_driver( - rtems_device_major_number major - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_unregister_driver( + rtems_device_major_number major + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully registered - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number + * - ``RTEMS_SUCCESSFUL`` + - successfully registered + * - ``RTEMS_INVALID_NUMBER`` + - invalid major device number -**DESCRIPTION:** +DESCRIPTION: + This directive removes a device driver from the Device Driver Table. -This directive removes a device driver from the Device Driver Table. +NOTES: + Currently no specific checks are made and the driver is not closed. -**NOTES:** +.. raw:: latex -Currently no specific checks are made and the driver is not closed. + \clearpage .. _rtems_io_initialize: IO_INITIALIZE - Initialize a device driver ------------------------------------------ .. index:: initialize a device driver - -**CALLING SEQUENCE:** - .. index:: rtems_io_initialize -.. code-block:: c - - rtems_status_code rtems_io_initialize( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_initialize( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_INVALID_NUMBER`` + - invalid major device number -**DESCRIPTION:** +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. -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. -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. -**NOTES:** +.. raw:: latex -This directive may or may not cause the calling task to be preempted. This is -dependent on the device driver being initialized. + \clearpage .. _rtems_io_register_name: IO_REGISTER_NAME - Register a device ------------------------------------ .. index:: register device - -**CALLING SEQUENCE:** - .. index:: rtems_io_register_name -.. code-block:: c - - rtems_status_code rtems_io_register_name( - const char *name, - rtems_device_major_number major, - rtems_device_minor_number minor - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_register_name( + const char *name, + rtems_device_major_number major, + rtems_device_minor_number minor + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_TOO_MANY`` - - too many devices registered + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_TOO_MANY`` + - too many devices registered -**DESCRIPTION:** +DESCRIPTION: + This directive associates name with the specified major/minor number pair. -This directive associates name with the specified major/minor number pair. +NOTES: + This directive will not cause the calling task to be preempted. -**NOTES:** +.. raw:: latex -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_io_lookup_name: IO_LOOKUP_NAME - Lookup a device -------------------------------- .. index:: lookup device major and minor number - -**CALLING SEQUENCE:** - .. index:: rtems_io_lookup_name -.. code-block:: c - - rtems_status_code rtems_io_lookup_name( - const char *name, - rtems_driver_name_t *device_info - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_lookup_name( + const char *name, + rtems_driver_name_t *device_info + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_UNSATISFIED`` - - name not registered + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_UNSATISFIED`` + - name not registered -**DESCRIPTION:** +DESCRIPTION: + This directive returns the major/minor number pair associated with the + given device name in ``device_info``. -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. -**NOTES:** +.. raw:: latex -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_io_open: IO_OPEN - Open a device ----------------------- .. index:: open a devive - -**CALLING SEQUENCE:** - .. index:: rtems_io_open -.. code-block:: c - - rtems_status_code rtems_io_open( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_open( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_INVALID_NUMBER`` + - invalid major device number -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive may or may not cause the calling task to be preempted. This is -dependent on the device driver being invoked. + \clearpage .. _rtems_io_close: IO_CLOSE - Close a device ------------------------- .. index:: close a device - -**CALLING SEQUENCE:** - .. index:: rtems_io_close -.. code-block:: c - - rtems_status_code rtems_io_close( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_close( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_INVALID_NUMBER`` + - invalid major device number -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive may or may not cause the calling task to be preempted. This is -dependent on the device driver being invoked. + \clearpage .. _rtems_io_read: IO_READ - Read from a device ---------------------------- .. index:: read from a device - -**CALLING SEQUENCE:** - .. index:: rtems_io_read -.. code-block:: c - - rtems_status_code rtems_io_read( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_read( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_INVALID_NUMBER`` + - invalid major device number -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive may or may not cause the calling task to be preempted. This is -dependent on the device driver being invoked. + \clearpage .. _rtems_io_write: IO_WRITE - Write to a device ---------------------------- .. index:: write to a device - -**CALLING SEQUENCE:** - .. index:: rtems_io_write -.. code-block:: c - - rtems_status_code rtems_io_write( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_io_write( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - successfully initialized - * - ``RTEMS_INVALID_NUMBER`` - - invalid major device number + * - ``RTEMS_SUCCESSFUL`` + - successfully initialized + * - ``RTEMS_INVALID_NUMBER`` + - invalid major device number -**DESCRIPTION:** +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. -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. -**NOTES:** +.. raw:: latex -This directive may or may not cause the calling task to be preempted. This is -dependent on the device driver being invoked. + \clearpage .. _rtems_io_control: @@ -593,40 +589,35 @@ IO_CONTROL - Special device services ------------------------------------ .. index:: special device services .. index:: IO Control - -**CALLING SEQUENCE:** - .. index:: rtems_io_control -.. code-block:: c - - rtems_status_code rtems_io_control( - rtems_device_major_number major, - rtems_device_minor_number minor, - void *argument - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``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. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_io_control( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``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. |