Split document into seperate files by section.

1 files changed, 178 insertions, 0 deletions

diff --git a/bsp_howto/ata.rst b/bsp_howto/ata.rst
new file mode 100644
index 0000000..dbf9f72
--- /dev/null
+++ b/bsp_howto/ata.rst
@@ -0,0 +1,178 @@
+ATA Driver
+##########
+
+Terms
+=====
+
+ATA device - physical device attached to an IDE controller
+
+Introduction
+============
+
+ATA driver provides generic interface to an ATA device. ATA driver is
+hardware independent implementation of ATA standard defined in working draft
+"AT Attachment Interface with Extensions (ATA-2)" X3T10/0948D revision 4c,
+March 18, 1996. ATA Driver based on IDE Controller Driver and may be used for
+computer systems with single IDE controller and with multiple as well. Although
+current implementation has several restrictions detailed below ATA driver
+architecture allows easily extend the driver. Current restrictions are:
+
+- Only mandatory (see draft p.29) and two optional (READ/WRITE MULTIPLE)
+  commands are implemented
+
+- Only PIO mode is supported but both poll and interrupt driven
+
+The reference implementation for ATA driver can be found in``cpukit/libblock/src/ata.c``.
+
+Initialization
+==============
+
+The ``ata_initialize`` routine is responsible for ATA driver
+initialization. The main goal of the initialization is to detect and
+register in the system all ATA devices attached to IDE controllers
+successfully initialized by the IDE Controller driver.
+
+In the implementation of the driver, the following actions are performed:
+.. code:: c
+
+    rtems_device_driver ata_initialize(
+    rtems_device_major_number  major,
+    rtems_device_minor_number  minor,
+    void                      \*arg
+    )
+    {
+    initialize internal ATA driver data structure
+    for each IDE controller successfully initialized by the IDE Controller
+    driver
+    if the controller is interrupt driven
+    set up interrupt handler
+    obtain information about ATA devices attached to the controller
+    with help of EXECUTE DEVICE DIAGNOSTIC command
+    for each ATA device detected on the controller
+    obtain device parameters with help of DEVICE IDENTIFY command
+    register new ATA device as new block device in the system
+    }
+
+Special processing of ATA commands is required because of absence of
+multitasking environment during the driver initialization.
+
+Detected ATA devices are registered in the system as physical block devices
+(see libblock library description). Device names are formed based on IDE
+controller minor number device is attached to and device number on the
+controller (0 - Master, 1 - Slave). In current implementation 64 minor
+numbers are reserved for each ATA device which allows to support up to 63
+logical partitions per device.
+.. code:: c
+
+    controller minor    device number    device name    ata device minor
+    0                  0             hda                0
+    0                  1             hdb               64
+    1                  0             hdc              128
+    1                  1             hdd              172
+    ...                ...            ...
+
+ATA Driver Architecture
+=======================
+
+ATA Driver Main Internal Data Structures
+----------------------------------------
+
+ATA driver works with ATA requests. ATA request is described by the
+following structure:
+.. code:: c
+
+    /* ATA request \*/
+    typedef struct ata_req_s {
+    Chain_Node        link;   /* link in requests chain \*/
+    char              type;   /* request type \*/
+    ata_registers_t   regs;   /* ATA command \*/
+    uint32_t          cnt;    /* Number of sectors to be exchanged \*/
+    uint32_t          cbuf;   /* number of current buffer from breq in use \*/
+    uint32_t          pos;    /* current position in 'cbuf' \*/
+    blkdev_request   \*breq;   /* blkdev_request which corresponds to the
+    * ata request
+    \*/
+    rtems_id          sema;   /* semaphore which is used if synchronous
+    * processing of the ata request is required
+    \*/
+    rtems_status_code status; /* status of ata request processing \*/
+    int               error;  /* error code \*/
+    } ata_req_t;
+
+ATA driver supports separate ATA requests queues for each IDE
+controller (one queue per controller). The following structure contains
+information about controller’s queue and devices attached to the controller:
+.. code:: c
+
+    /*
+    * This structure describes controller state, devices configuration on the
+    * controller and chain of ATA requests to the controller.
+    \*/
+    typedef struct ata_ide_ctrl_s {
+    bool          present;   /* controller state \*/
+    ata_dev_t     device[2]; /* ata devices description \*/
+    Chain_Control reqs;      /* requests chain \*/
+    } ata_ide_ctrl_t;
+
+Driver uses array of the structures indexed by the controllers minor
+number.
+
+The following structure allows to map an ATA device to the pair (IDE
+controller minor number device is attached to, device number
+on the controller):
+.. code:: c
+
+    /*
+    * Mapping of rtems ATA devices to the following pairs:
+    * (IDE controller number served the device, device number on the controller)
+    \*/
+    typedef struct ata_ide_dev_s {
+    int ctrl_minor;/* minor number of IDE controller serves rtems ATA device \*/
+    int device;    /* device number on IDE controller (0 or 1) \*/
+    } ata_ide_dev_t;
+
+Driver uses array of the structures indexed by the ATA devices minor
+number.
+
+ATA driver defines the following internal events:
+.. code:: c
+
+    /* ATA driver events \*/
+    typedef enum ata_msg_type_s {
+    ATA_MSG_GEN_EVT = 1,     /* general event \*/
+    ATA_MSG_SUCCESS_EVT,     /* success event \*/
+    ATA_MSG_ERROR_EVT,       /* error event \*/
+    ATA_MSG_PROCESS_NEXT_EVT /* process next ata request event \*/
+    } ata_msg_type_t;
+
+Brief ATA Driver Core Overview
+------------------------------
+
+All ATA driver functionality is available via ATA driver ioctl. Current
+implementation supports only two ioctls: BLKIO_REQUEST and
+ATAIO_SET_MULTIPLE_MODE. Each ATA driver ioctl() call generates an
+ATA request which is appended to the appropriate controller queue depending
+on ATA device the request belongs to. If appended request is single request in
+the controller’s queue then ATA driver event is generated.
+
+ATA driver task which manages queue of ATA driver events is core of ATA
+driver. In current driver version queue of ATA driver events implemented
+as RTEMS message queue. Each message contains event type, IDE controller
+minor number on which event happened and error if an error occurred. Events
+may be generated either by ATA driver ioctl call or by ATA driver task itself.
+Each time ATA driver task receives an event it gets controller minor number
+from event, takes first ATA request from controller queue and processes it
+depending on request and event types. An ATA request processing may also
+includes sending of several events. If ATA request processing is finished
+the ATA request is removed from the controller queue. Note, that in current
+implementation maximum one event per controller may be queued at any moment
+of the time.
+
+(This part seems not very clear, hope I rewrite it soon)
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+