From 72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 3 Nov 2016 16:58:08 +1100 Subject: Rename all manuals with an _ to have a -. It helps released naming of files. --- bsp-howto/ide_controller.rst | 156 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 bsp-howto/ide_controller.rst (limited to 'bsp-howto/ide_controller.rst') diff --git a/bsp-howto/ide_controller.rst b/bsp-howto/ide_controller.rst new file mode 100644 index 0000000..82961da --- /dev/null +++ b/bsp-howto/ide_controller.rst @@ -0,0 +1,156 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +IDE Controller Driver +##################### + +Introduction +============ + +The IDE Controller driver is responsible for providing an interface to an IDE +Controller. The capabilities provided by this driver are: + +- Read IDE Controller register + +- Write IDE Controller register + +- Read data block through IDE Controller Data Register + +- Write data block through IDE Controller Data Register + +The reference implementation for an IDE Controller driver can be found in +``$RTEMS_SRC_ROOT/c/src/libchip/ide``. This driver is based on the libchip +concept and allows to work with any of the IDE Controller chips simply by +appropriate configuration of BSP. Drivers for a particular IDE Controller chips +locate in the following directories: drivers for well-known IDE Controller +chips locate into ``$RTEMS_SRC_ROOT/c/src/libchip/ide``, drivers for IDE +Controller chips integrated with CPU locate into +``$RTEMS_SRC_ROOT/c/src/lib/libcpu/myCPU`` and drivers for custom IDE +Controller chips (for example, implemented on FPGA) locate into +``$RTEMS_SRC_ROOT/c/src/lib/libbsp/myBSP``. There is a README file in these +directories for each supported IDE Controller chip. Each of these README +explains how to configure a BSP for that particular IDE Controller chip. + +Initialization +============== + +IDE Controller chips used by a BSP are statically configured into +``IDE_Controller_Table``. The ``ide_controller_initialize`` routine is +responsible for initialization of all configured IDE controller chips. +Initialization order of the chips based on the order the chips are defined in +the ``IDE_Controller_Table``. + +The following actions are performed by the IDE Controller driver initialization +routine: + +.. code-block:: c + + rtems_device_driver ide_controller_initialize( + rtems_device_major_number major, + rtems_device_minor_number minor_arg, + void *arg + ) + { + for each IDE Controller chip configured in IDE_Controller_Table + if (BSP dependent probe(if exists) AND device probe for this IDE chip + indicates it is present) + perform initialization of the particular chip + register device with configured name for this chip + } + +Read IDE Controller Register +============================ + +The ``ide_controller_read_register`` routine reads the content of the IDE +Controller chip register. IDE Controller chip is selected via the minor +number. This routine is not allowed to be called from an application. + +.. code-block:: c + + void ide_controller_read_register( + rtems_device_minor_number minor, + unsigned32 reg, + unsigned32 *value + ) + { + get IDE Controller chip configuration information from + IDE_Controller_Table by minor number + + invoke read register routine for the chip + } + +Write IDE Controller Register +============================= + +The ``ide_controller_write_register`` routine writes IDE Controller chip +register with specified value. IDE Controller chip is selected via the minor +number. This routine is not allowed to be called from an application. + +.. code-block:: c + + void ide_controller_write_register( + rtems_device_minor_number minor, + unsigned32 reg, + unsigned32 value + ) + { + get IDE Controller chip configuration information from + IDE_Controller_Table by minor number + + invoke write register routine for the chip + } + +Read Data Block Through IDE Controller Data Register +==================================================== + +The ``ide_controller_read_data_block`` provides multiple consequent read of the +IDE Controller Data Register. IDE Controller chip is selected via the minor +number. The same functionality may be achieved via separate multiple calls of +``ide_controller_read_register`` routine but ``ide_controller_read_data_block`` +allows to escape functions call overhead. This routine is not allowed to be +called from an application. + +.. code-block:: c + + void ide_controller_read_data_block( + rtems_device_minor_number minor, + unsigned16 block_size, + blkdev_sg_buffer *bufs, + uint32_t *cbuf, + uint32_t *pos + ) + { + get IDE Controller chip configuration information from + IDE_Controller_Table by minor number + + invoke read data block routine for the chip + } + +Write Data Block Through IDE Controller Data Register +===================================================== + +The ``ide_controller_write_data_block`` provides multiple consequent write into +the IDE Controller Data Register. IDE Controller chip is selected via the minor +number. The same functionality may be achieved via separate multiple calls of +``ide_controller_write_register`` routine but +``ide_controller_write_data_block`` allows to escape functions call +overhead. This routine is not allowed to be called from an application. + +.. code-block:: c + + void ide_controller_write_data_block( + rtems_device_minor_number minor, + unsigned16 block_size, + blkdev_sg_buffer *bufs, + uint32_t *cbuf, + uint32_t *pos + ) + { + get IDE Controller chip configuration information from + IDE_Controller_Table by minor number + + invoke write data block routine for the chip + } -- cgit v1.2.3