summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/bsp_howto/.cvsignore2
-rw-r--r--doc/bsp_howto/ChangeLog8
-rw-r--r--doc/bsp_howto/Makefile.am13
-rw-r--r--doc/bsp_howto/ata.t199
-rw-r--r--doc/bsp_howto/bsp_howto.texi4
-rw-r--r--doc/bsp_howto/ide-ctrl.t153
-rw-r--r--doc/bsp_howto/stamp-vti8
-rw-r--r--doc/bsp_howto/version.texi8
8 files changed, 386 insertions, 9 deletions
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 <Eugeny.Mints@oktet.ru>
+
+ * 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 <joel@OARcorp.com>
* 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