20.4. Directives

This section details the directives of the I/O Manager. A subsection is dedicated to each of this manager’s directives and lists the calling sequence, parameters, description, return values, and notes of the directive.

20.4.1. rtems_io_register_driver()

Registers and initializes the device with the specified device driver address table and device major number in the Device Driver Table.

CALLING SEQUENCE:

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
);

PARAMETERS:

major

This parameter is the device major number. Use a value of zero to let the system obtain a device major number automatically.

driver_table

This parameter is the device driver address table.

registered_major

This parameter is the pointer to an rtems_device_major_number object. When the directive call is successful, the device major number of the registered device will be stored in this object.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The device major number of the device was NULL.

RTEMS_INVALID_ADDRESS

The device driver address table was empty.

RTEMS_INVALID_NUMBER

The device major number of the device was out of range, see CONFIGURE_MAXIMUM_DRIVERS.

RTEMS_TOO_MANY

The system was unable to obtain a device major number.

RTEMS_RESOURCE_IN_USE

The device major number was already in use.

RTEMS_CALLED_FROM_ISR

The directive was called from interrupt context.

Other status codes may be returned by rtems_io_initialize().

NOTES:

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.

20.4.2. rtems_io_unregister_driver()

Removes a device driver specified by the device major number from the Device Driver Table.

CALLING SEQUENCE:

rtems_status_code rtems_io_unregister_driver(
  rtems_device_major_number major
);

PARAMETERS:

major

This parameter is the major number of the device.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_UNSATISFIED

The device major number was invalid.

RTEMS_CALLED_FROM_ISR

The directive was called from interrupt context.

NOTES:

Currently no specific checks are made and the driver is not closed.

20.4.3. rtems_io_initialize()

Initializes the device specified by the device major and minor numbers.

CALLING SEQUENCE:

rtems_status_code rtems_io_initialize(
  rtems_device_major_number major,
  rtems_device_minor_number minor,
  void                     *argument
);

PARAMETERS:

major

This parameter is the major number of the device.

minor

This parameter is the minor number of the device.

argument

This parameter is the argument passed to the device driver initialization entry.

DESCRIPTION:

This directive calls the device driver initialization entry registered in the Device Driver Table for the specified device major number.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_NUMBER

The device major number was invalid.

Other status codes may be returned by the device driver initialization entry.

NOTES:

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.

20.4.4. rtems_io_register_name()

Registers the device specified by the device major and minor numbers in the file system under the specified name.

CALLING SEQUENCE:

rtems_status_code rtems_io_register_name(
  const char               *device_name,
  rtems_device_major_number major,
  rtems_device_minor_number minor
);

PARAMETERS:

device_name

This parameter is the device name in the file system.

major

This parameter is the device major number.

minor

This parameter is the device minor number.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_TOO_MANY

The name was already in use or other errors occurred.

NOTES:

The device is registered as a character device.

20.4.5. rtems_io_open()

Opens the device specified by the device major and minor numbers.

CALLING SEQUENCE:

rtems_status_code rtems_io_open(
  rtems_device_major_number major,
  rtems_device_minor_number minor,
  void                     *argument
);

PARAMETERS:

major

This parameter is the major number of the device.

minor

This parameter is the minor number of the device.

argument

This parameter is the argument passed to the device driver close entry.

DESCRIPTION:

This directive calls the device driver open entry registered in the Device Driver Table for the specified device major number.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_NUMBER

The device major number was invalid.

Other status codes may be returned by the device driver open entry.

NOTES:

The open entry point is commonly used by device drivers to provide exclusive access to a device.

20.4.6. rtems_io_close()

Closes the device specified by the device major and minor numbers.

CALLING SEQUENCE:

rtems_status_code rtems_io_close(
  rtems_device_major_number major,
  rtems_device_minor_number minor,
  void                     *argument
);

PARAMETERS:

major

This parameter is the major number of the device.

minor

This parameter is the minor number of the device.

argument

This parameter is the argument passed to the device driver close entry.

DESCRIPTION:

This directive calls the device driver close entry registered in the Device Driver Table for the specified device major number.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_NUMBER

The device major number was invalid.

Other status codes may be returned by the device driver close entry.

NOTES:

The close entry point is commonly used by device drivers to relinquish exclusive access to a device.

20.4.7. rtems_io_read()

Reads from the device specified by the device major and minor numbers.

CALLING SEQUENCE:

rtems_status_code rtems_io_read(
  rtems_device_major_number major,
  rtems_device_minor_number minor,
  void                     *argument
);

PARAMETERS:

major

This parameter is the major number of the device.

minor

This parameter is the minor number of the device.

argument

This parameter is the argument passed to the device driver read entry.

DESCRIPTION:

This directive calls the device driver read entry registered in the Device Driver Table for the specified device major number.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_NUMBER

The device major number was invalid.

Other status codes may be returned by the device driver read entry.

NOTES:

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.

20.4.8. rtems_io_write()

Writes to the device specified by the device major and minor numbers.

CALLING SEQUENCE:

rtems_status_code rtems_io_write(
  rtems_device_major_number major,
  rtems_device_minor_number minor,
  void                     *argument
);

PARAMETERS:

major

This parameter is the major number of the device.

minor

This parameter is the minor number of the device.

argument

This parameter is the argument passed to the device driver write entry.

DESCRIPTION:

This directive calls the device driver write entry registered in the Device Driver Table for the specified device major number.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_NUMBER

The device major number was invalid.

Other status codes may be returned by the device driver write entry.

NOTES:

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.

20.4.9. rtems_io_control()

Controls the device specified by the device major and minor numbers.

CALLING SEQUENCE:

rtems_status_code rtems_io_control(
  rtems_device_major_number major,
  rtems_device_minor_number minor,
  void                     *argument
);

PARAMETERS:

major

This parameter is the major number of the device.

minor

This parameter is the minor number of the device.

argument

This parameter is the argument passed to the device driver I/O control entry.

DESCRIPTION:

This directive calls the device driver I/O control entry registered in the Device Driver Table for the specified device major number.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_NUMBER

The device major number was invalid.

Other status codes may be returned by the device driver I/O control entry.

NOTES:

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.