sid/component/ide/hw-disk-ide.txt

   1 * Name
   2   hw-disk-ide
   3
   4 * Synopsis
   5   This component models a simple ATA (IDE) hard drive controller plus up to two
   6   disk drives.
   7
   8   Buses: control-block-bus command-block-bus
   9   Pins: interrupt
  10   Attributes: state-snapshot drive0-present? drive1-present? drive0-file
  11               drive1-file drive0-num-cylinders drive1-num-cylinders
  12               drive0-num-heads drive1-num-heads drive0-num-sectors-per-track
  13               drive1-num-sectors-per-track altstatus control drive-address
  14               data error precomp sector-count sector-number cylinder-low
  15               cylinder-high drive/head command
  16   Library: libide.la
  17   Symbol name: ide_component_library
  18
  19 * Functionality
  20   - Modelling
  21     * This component models a PC-style ATA (IDE) hard drive controller
  22       plus up to two disk drives.  The two individually configured drives
  23       use host files for storage of the disk image.  Access time
  24       appears to be instantaneous to the simulated target.
  25
  26     * This model supports only old IDE programming interfaces.  These
  27       should be a common subset of most real IDE-like devices (hard
  28       drives, CD-ROMs, CompactFlash drives, etc.).  Only PIO
  29       (programmed I/O) is supported, so no ATAPI or DMA functions are
  30       available.  However, the drive models are self-describing, so
  31       they can indicate that these missing functions are not
  32       available.
  33
  34   - Behaviors
  35     * Initialization
  36       All parameters must be set for the selected simulated drive (N=0
  37       or 1) to become available.  The given disk image file will be
  38       opened for read and write as long as the "driveN-file" attribute
  39       is set.  Undefined behaviour occurs if these settings are
  40       changed while the drive model is in use, or if the values are
  41       illegal.  Undefined behaviour occurs if the same disk image file
  42       is shared by more than one simulated drive.
  43
  44     * Register access
  45
  46       Several standard IDE registers may be accessed across the
  47       "control-block-bus" and "command-block-bus", and also via
  48       watchable attributes.
  49
  50       The "data port" register lives at address 0 in the
  51       command-block-bus.  As a quirk of the IDE interface standard,
  52       either an 8- or 16-bit access to address 0 on this bus will
  53       access this register.
  54
  55     * Command execution
  56       To control IDE devices, you set the registers that specify the
  57       location of an intended transfer, then write a command byte into
  58       the command register.  An IDE interface standard provides for
  59       synchronization between a processor and the IDE controller.  The DRQ,
  60       DRDY, and ERROR bits in the status register are emulated for this.
  61
  62     * Command execution: read/write
  63       IDE commands 0x20, 0x21, 0x30, 0x31 are supported.  Multiple-sector
  64       transfers are supported and involve DRQ/interrupt synchronization.
  65       LBA and CHS addressing are both supported.
  66
  67     * Command execution: identify
  68       IDE command 0xEC is supported.  It arranges to copy data into or out of
  69       the selected drive's sector buffers
  70
  71     * Command execution: stub commands
  72       IDE commands 0x10-0x1F (RECALIBRATE) and 0x70-0x7F (SEEK) are simulated
  73       by instantaneous stubs.
  74
  75     * Command execution: unknown commands
  76       An attempt to execute illegal commands, or commands on nonexistent drives,
  77       results in an ERROR bit in the status register, and an interrupt.
  78
  79   - SID conventions
  80     * This is a functional component.
  81
  82     * It supports state save/restore for controller state (including
  83       registers and sector buffers).  It does not include a snapshot
  84       of the disk images, however.
  85
  86     * It supports triggerpoints for most control registers.
  87
  88 * Environment
  89   - Related components
  90     * The IDE model is a self-contained slave peripheral.  It does not
  91       need to be coupled with other specific components to operate.
  92
  93     * To use an IDE model in a system simulation, you must map its
  94       two buses into an address space, connect its interrupt line
  95       (if needed), and configure its drives.  The following
  96       configuration file fragment shows how:
  97
  98         # Add the IDE drive model library
  99         load libide.la ide_component_library
 100         # Instantiate component
 101         new hw-disk-ide ide0
 102         # ... assume memory mapper named "mapper"
 103         # ... assume PC standard IDE channel 0 addresses
 104         connect-bus mapper [0x3F0-0x3F7] ide0 control-block-bus
 105         connect-bus mapper [0x1F0-0x1F7] ide0 command-block-bus
 106         # ... assume some fictional interrupt controller
 107         connect-pin ide0 interrupt -> fic irq14
 108         #
 109         # (For PC standard IDE channel 1,
 110         #  use base addresses 0x370 and 0x170,
 111         #  and irq15 respectively.)
 112         #
 113         # ... configure drive 0 (master): 128*10*32 sectors = 20 MB capacity
 114         set ide0 drive0-present? 1
 115         set ide0 drive0-file "/tmp/drive-0-image"
 116         set ide0 drive0-num-cylinders 128
 117         set ide0 drive0-num-heads 10
 118         set ide0 drive0-num-sectors-per-track 32
 119
 120   - Host system
 121     * The IDE drive model relies on up to two external files for
 122       storage of the virtual disk images.  These files may be accessed
 123       in a sparse way by the target program, so the resulting files
 124       may have "holes".  Configuring a virtual drive that is larger
 125       than 2 GB is not supported.  The various "driveN-num-*"
 126       parameters are multiplied together to arrive at the number of
 127       512-byte sectors to model.
 128
 129     * Some error conditions are signalled by messages to cerr.  These
 130       include some host I/O errors, and some simulated violations of
 131       IDE command synchronization.
 132
 133 * SID interface reference
 134   - low level:
 135
 136     * pins
 137       - interrupt | output | 0,1 | command execution
 138
 139     * buses
 140       - control-block-bus | 0x6-0x7 | read/write | register access
 141       - command-block-bus | 0x0-0x7 | read/write | register access, command execution
 142
 143     * attributes
 144       - state-snapshot | | opaque string | n/a | state save/restore
 145       - driveN-present? | setting | boolean | no | initialization
 146       - driveN-file | setting | file name | "/dev/null" | initialization
 147       - driveN-num-cylinders | setting | numeric | 0 | initialization
 148       - driveN-num-heads | setting | numeric | 0 | initialization
 149       - driveN-num-sectors-per-track | setting | numeric | 0 | initialization
 150       - altstatus | watchable, register | numeric | n/a | register access
 151       - control | watchable, register | numeric | n/a | register access
 152       - drive address | watchable, register | numeric | n/a | register access
 153       - data | watchable, register | numeric | n/a | register access
 154       - error | watchable, register | numeric | n/a | register access
 155       - precomp | watchable, register | numeric | n/a | register access
 156       - sector-count | watchable, register | numeric | n/a | register access
 157       - sector-number | watchable, register | numeric | n/a | register access
 158       - cylinder-low | watchable, register | numeric | n/a | register access
 159       - cylinder-high | watchable, register | numeric | n/a | register access
 160       - drive/head | watchable, register | numeric | n/a | register access
 161       - command | watchable, register | numeric | n/a | register access
 162       - interrupt | pin | 0-1 | n/a | command execution
 163
 164 * References
 165   The IDE specifications used for constructing this model were gleaned from
 166   several sources.  The official ATA specs were not available.
 167
 168   - The Quantum Bigfoot AT hard drive reference manual.
 169   - The psim PowerPC simulator's "hw-ide" module.
 170   - The Linux kernel IDE drivers.