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/.cvsignore | 2 + doc/bsp_howto/ChangeLog | 8 ++ doc/bsp_howto/Makefile.am | 13 ++- doc/bsp_howto/ata.t | 199 +++++++++++++++++++++++++++++++++++++++++++ doc/bsp_howto/bsp_howto.texi | 4 + doc/bsp_howto/ide-ctrl.t | 153 +++++++++++++++++++++++++++++++++ doc/bsp_howto/stamp-vti | 8 +- doc/bsp_howto/version.texi | 8 +- 8 files changed, 386 insertions(+), 9 deletions(-) create mode 100644 doc/bsp_howto/ata.t create mode 100644 doc/bsp_howto/ide-ctrl.t (limited to 'doc/bsp_howto') diff --git a/doc/bsp_howto/.cvsignore b/doc/bsp_howto/.cvsignore index 656162df2d..d4913bec7a 100644 --- a/doc/bsp_howto/.cvsignore +++ b/doc/bsp_howto/.cvsignore @@ -2,6 +2,7 @@ Makefile Makefile.in adaintr.texi analog.texi +ata.texi bsp_howto bsp_howto*.html bsp_howto-? @@ -21,6 +22,7 @@ bsp_howto.vr clock.texi console.texi discrete.texi +ide-ctrl.texi index.html init.texi intro.texi diff --git a/doc/bsp_howto/ChangeLog b/doc/bsp_howto/ChangeLog index a4f60ac0f5..63c7b49ca6 100644 --- a/doc/bsp_howto/ChangeLog +++ b/doc/bsp_howto/ChangeLog @@ -1,3 +1,11 @@ +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. + 2002-10-24 Joel Sherrill * stamp-vti, version.texi: Regenerated. diff --git a/doc/bsp_howto/Makefile.am b/doc/bsp_howto/Makefile.am index 925a65378c..1b0915f632 100644 --- a/doc/bsp_howto/Makefile.am +++ b/doc/bsp_howto/Makefile.am @@ -15,7 +15,8 @@ include $(top_srcdir)/main.am GENERATED_FILES = intro.texi target.texi makefiles.texi linkcmds.texi \ support.texi adaintr.texi init.texi console.texi clock.texi timer.texi \ - rtc.texi nvmem.texi network.texi shmsupp.texi analog.texi discrete.texi + rtc.texi ata.texi ide-ctrl.texi nvmem.texi network.texi shmsupp.texi \ + analog.texi discrete.texi COMMON_FILES = $(top_srcdir)/common/setup.texi \ $(top_srcdir)/common/cpright.texi @@ -84,6 +85,16 @@ $(srcdir)/rtc.texi: rtc.t -u "Top" \ -n "" < $< > $@ +$(srcdir)/ata.texi: ata.t + $(BMENU2) -p "" \ + -u "Top" \ + -n "" < $< > $@ + +$(srcdir)/ide-ctrl.texi: ide-ctrl.t + $(BMENU2) -p "" \ + -u "Top" \ + -n "" < $< > $@ + $(srcdir)/nvmem.texi: nvmem.t $(BMENU2) -p "" \ -u "Top" \ 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) + + + diff --git a/doc/bsp_howto/bsp_howto.texi b/doc/bsp_howto/bsp_howto.texi index 368c5fea9b..6605eda48c 100644 --- a/doc/bsp_howto/bsp_howto.texi +++ b/doc/bsp_howto/bsp_howto.texi @@ -66,6 +66,8 @@ @include clock.texi @include timer.texi @include rtc.texi +@include ata.texi +@include ide-ctrl.texi @include nvmem.texi @include network.texi @include shmsupp.texi @@ -90,6 +92,8 @@ This is the online version of the RTEMS BSP and Device Driver Development Guide. * Clock Driver:: * Timer Driver:: * Real-Time Clock Driver:: +* ATA Driver:: +* IDE Controller Driver:: * Networking Driver:: * Non-Volatile Memory Driver:: * Shared Memory Support Driver:: diff --git a/doc/bsp_howto/ide-ctrl.t b/doc/bsp_howto/ide-ctrl.t new file mode 100644 index 0000000000..ca23572cac --- /dev/null +++ b/doc/bsp_howto/ide-ctrl.t @@ -0,0 +1,153 @@ +@c +@c COPYRIGHT (c) 1988-2002. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter IDE Controller Driver + +@section Introduction + +The IDE Controller driver is responsible for providing an +interface to an IDE Controller. The capabilities provided by this +driver are: + +@itemize @bullet +@item Read IDE Controller register +@item Write IDE Controller register +@item Read data block through IDE Controller Data Register +@item Write data block through IDE Controller Data Register +@end itemize + +The reference implementation for an IDE Controller driver can +be found in @code{$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 +paticular IDE Controller chips locate in the following directories: drivers +for well-known IDE Controller chips locate into +@code{$RTEMS_SRC_ROOT/c/src/libchip/ide}, drivers for IDE Controller chips +integrated with CPU locate into +@code{$RTEMS_SRC_ROOT/c/src/lib/libcpu/myCPU} and +drivers for custom IDE Controller chips (for example, implemented on FPGA) +locate into @code{$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. + +@section Initialization + +IDE Controller chips used by a BSP are statically confiured into +@code{IDE_Controller_Table}. The @code{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 @code{IDE_Controller_Table}. + +The following actions are performed by the IDE Controller driver +initialization routine: + +@example +@group +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 dependant 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 +@} +@end group +@end example + +@section Read IDE Controller Register + +The @code{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. + +@example +@group +void ide_controller_read_register(rtems_device_minor_number minor, + unsigned32 reg, unsiged32 *value) +@{ + get IDE Controller chip configuration information from + IDE_Controller_Table by minor number + + invoke read register routine for the chip +@} +@end group +@end example + +@section Write IDE Controller Register + +The @code{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. + +@example +@group +void ide_controller_write_register(rtems_device_minor_number minor, + unsigned32 reg, unsiged32 value) +@{ + get IDE Controller chip configuration information from + IDE_Controller_Table by minor number + + invoke write register routine for the chip +@} +@end group +@end example + +@section Read Data Block Through IDE Controller Data Register + +The @code{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 @code{ide_controller_read_register} routine but +@code{ide_controller_read_data_block} allows to escape functions call +overhead. This routine is not allowed to be called from an application. + +@example +@group +void ide_controller_read_data_block(rtems_device_minor_number minor, + unsigned16 block_size, + blkdev_sg_buffer *bufs, + rtems_unsigned32 *cbuf, + rtems_unsigned32 *pos) +@{ + get IDE Controller chip configuration information from + IDE_Controller_Table by minor number + + invoke read data block routine for the chip +@} +@end group +@end example + +@section Write Data Block Through IDE Controller Data Register + +The @code{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 @code{ide_controller_write_register} routine but +@code{ide_controller_write_data_block} allows to escape functions call +overhead. This routine is not allowed to be called from an application. + +@example +@group +void ide_controller_write_data_block(rtems_device_minor_number minor, + unsigned16 block_size, + blkdev_sg_buffer *bufs, + rtems_unsigned32 *cbuf, + rtems_unsigned32 *pos) +@{ + get IDE Controller chip configuration information from + IDE_Controller_Table by minor number + + invoke write data block routine for the chip +@} +@end group +@end example diff --git a/doc/bsp_howto/stamp-vti b/doc/bsp_howto/stamp-vti index ccb1ff9ee0..b6c97b4758 100644 --- a/doc/bsp_howto/stamp-vti +++ b/doc/bsp_howto/stamp-vti @@ -1,4 +1,4 @@ -@set UPDATED 17 January 2002 -@set UPDATED-MONTH January 2002 -@set EDITION ss-20021007 -@set VERSION ss-20021007 +@set UPDATED 24 October 2002 +@set UPDATED-MONTH October 2002 +@set EDITION 20021021-test +@set VERSION 20021021-test diff --git a/doc/bsp_howto/version.texi b/doc/bsp_howto/version.texi index ccb1ff9ee0..b6c97b4758 100644 --- a/doc/bsp_howto/version.texi +++ b/doc/bsp_howto/version.texi @@ -1,4 +1,4 @@ -@set UPDATED 17 January 2002 -@set UPDATED-MONTH January 2002 -@set EDITION ss-20021007 -@set VERSION ss-20021007 +@set UPDATED 24 October 2002 +@set UPDATED-MONTH October 2002 +@set EDITION 20021021-test +@set VERSION 20021021-test -- cgit v1.2.3