From 51eacee9b7c880f564f7f76f62256563f10e21d4 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 28 Oct 2002 13:44:39 +0000 Subject: 2002-10-24 Eugeny S. Mints * ata.t, ide-ctrl.t: New file. * .cvsignore: Added new .texi files. * Makefile.am:: Added new files to generate. * bsp_howto.texi: Added new chapters. * stamp-vti, version.texi: Regenerated. --- doc/bsp_howto/ata.t | 199 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 doc/bsp_howto/ata.t (limited to 'doc/bsp_howto/ata.t') 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) + + + -- cgit v1.2.3