summaryrefslogtreecommitdiffstats
path: root/doc/bsp_howto/ata.t
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/bsp_howto/ata.t199
1 files changed, 199 insertions, 0 deletions
diff --git a/doc/bsp_howto/ata.t b/doc/bsp_howto/ata.t
new file mode 100644
index 0000000000..507ae2dc17
--- /dev/null
+++ b/doc/bsp_howto/ata.t
@@ -0,0 +1,199 @@
+@c
+@c COPYRIGHT (c) 1988-2002.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+@c $Id$
+@c
+
+@chapter ATA Driver
+
+@section Terms
+
+ATA device - physical device attached to an IDE controller
+
+@section Introduction
+
+ATA driver provides generic interface to an ATA device. ATA driver is
+hardware independant implementation of ATA standart defined in working draft
+"AT Attachment Interface with Extentions (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:
+
+@itemize @bullet
+@item Only mandatory (see draft p.29) and two optional (READ/WRITE MULTIPLE)
+commands are implemented
+@item Only PIO mode is supported but both poll and interrupt driven
+@end itemize
+
+The reference implementation for ATA driver can be found in
+@code{c/src/exec/libblock/src/ata.c}.
+
+@section Initialization
+
+The @code{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:
+
+@example
+@group
+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 interuupt 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
+@}
+@end group
+@end example
+
+Special processing of ATA commands is required because of absence of
+multitasking enviroment 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.
+
+@example
+@group
+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
+ ... ... ...
+@end group
+@end example
+
+@section ATA Driver Architecture
+
+@subsection ATA Driver Main Internal Data Structures
+
+ATA driver works with ATA requests. ATA request is described by the
+following structure:
+
+@example
+@group
+/* ATA request */
+typedef struct ata_req_s @{
+ Chain_Node link; /* link in requests chain */
+ char type; /* request type */
+ ata_registers_t regs; /* ATA command */
+ rtems_unsigned32 cnt; /* Number of sectors to be exchanged */
+ rtems_unsigned32 cbuf; /* number of current buffer from breq in use */
+ rtems_unsigned32 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;
+@end group
+@end example
+
+ATA driver supports separate ATA requests queues for each IDE
+controller (one queue per controller). The following structure contains
+inforamtion about controller's queue and devices attached to the controller:
+
+@example
+@group
+/*
+ * This structure describes controller state, devices configuration on the
+ * controller and chain of ATA requests to the controller.
+ */
+typedef struct ata_ide_ctrl_s @{
+ rtems_boolean present; /* controller state */
+ ata_dev_t device[2]; /* ata diveces description */
+ Chain_Control reqs; /* requests chain */
+@} ata_ide_ctrl_t;
+@end group
+@end example
+
+Driver uses array of the structures indexed by the controllers minor
+number.
+
+The following struture allows to map an ATA device to the pair (IDE
+controller minor number device is attached to, device number
+on the controller):
+
+@example
+@group
+/*
+ * 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;
+@end group
+@end example
+
+Driver uses array of the structures indexed by the ATA devices minor
+number.
+
+ATA driver defines the following internal events:
+
+@example
+@group
+/* 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;
+@end group
+@end example
+
+@subsection 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 apropriate 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 happaned and error if an error occured. 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)
+
+
+