org/jpc/diskimages/BlockDevice.java

   1 /*
   2     JPC-RR: A x86 PC Hardware Emulator
   3     Release 1
   4
   5     Copyright (C) 2007-2009 Isis Innovation Limited
   6     Copyright (C) 2009 H. Ilari Liusvaara
   7
   8     This program is free software; you can redistribute it and/or modify
   9     it under the terms of the GNU General Public License version 2 as published by
  10     the Free Software Foundation.
  11
  12     This program is distributed in the hope that it will be useful,
  13     but WITHOUT ANY WARRANTY; without even the implied warranty of
  14     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15     GNU General Public License for more details.
  16
  17     You should have received a copy of the GNU General Public License along
  18     with this program; if not, write to the Free Software Foundation, Inc.,
  19     51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  20
  21     Based on JPC x86 PC Hardware emulator,
  22     A project from the Physics Dept, The University of Oxford
  23
  24     Details about original JPC can be found at:
  25
  26     www-jpc.physics.ox.ac.uk
  27
  28 */
  29
  30 package org.jpc.diskimages;
  31
  32 import java.io.*;
  33 import org.jpc.emulator.StatusDumper;
  34 import org.jpc.emulator.SRDumpable;
  35
  36 /**
  37  * Object which provides data backing for a disk device.  Currently this
  38  * includes IDE devices and floppy drives.
  39  * @author Chris Dennis
  40  */
  41 public interface BlockDevice extends SRDumpable
  42 {
  43     /**
  44      * Size of a sector unit in bytes.
  45      */
  46     public static final int SECTOR_SIZE = 512;
  47
  48     /**
  49      * Enumeration representing the possible types of a block device.
  50      * <p>
  51      * Possible values are <code>HARDDRIVE</code>, <code>CDROM</code> and
  52      * <code>FLOPPY</code>.
  53      */
  54     public static enum Type {HARDDRIVE, CDROM, FLOPPY};
  55
  56     /**
  57      * Closes the current device.  Once <code>close</code> has been called any further reads
  58      * from or writes to the device will most likely fail.
  59      */
  60     public void close();
  61
  62     /**
  63      * Reads <code>size</code> sectors starting at <code>sectorNumber</code>
  64      * into the given array.  Returns a negative value on failure.
  65      * @param sectorNumber offset of the first sector to read
  66      * @param buffer array to write data into
  67      * @param size number of sectors to read.
  68      * @return negative on failure
  69      */
  70     public int read(long sectorNumber, byte[] buffer, int size);
  71
  72     /**
  73      * Writes <code>size</code> sectors starting at <code>sectorNumber</code>
  74      * from the given array.  Returns a negative value on failure
  75      * @param sectorNumber offset of the first sector to write
  76      * @param buffer array to read data from
  77      * @param size number of sectors to write
  78      * @return negative on failure
  79      */
  80     public int write(long sectorNumber, byte[] buffer, int size);
  81
  82     /**
  83      * Returns <code>true</code> if something is 'inserted' in this device.
  84      * This only has meaning for CD-ROM and floppy drives which return
  85      * <code>true</code> if a disk in inserted.
  86      * @return <code>true</code> if the device media is inserted
  87      */
  88     public boolean isInserted();
  89
  90     /**
  91      * Returns <code>true</code> if this device is 'locked'.  For a CD-ROM
  92      * device, locked means that a call to <code>eject</code> will fail to eject
  93      * the device.
  94      * @return <code>true</code> if the device media is locked
  95      */
  96     public boolean isLocked();
  97
  98     /**
  99      * Returns <code>true</code> if this device is read-only.  Writes to
 100      * read-only devices may either fail silently, or throw exceptions.
 101      */
 102     public boolean isReadOnly();
 103
 104     /**
 105      * Attempts to lock or unlock this device.  Success or failure can only be tested by
 106      * a subsequent call to <code>isLocked</code>.
 107      * @param locked whether to lock (<code>true</code>) or unlock (<code>false</code>)
 108      */
 109     public void setLock(boolean locked);
 110
 111     /**
 112      * Returns the total size of this device in sectors.
 113      * @return total size in sectors
 114      */
 115     public long getTotalSectors();
 116
 117     /**
 118      * Returns the number of cylinders on the device.  May or may not have any
 119      * physical meaning relating to the geometry of the media.
 120      * @return number of cylinders
 121      */
 122     public int getCylinders();
 123
 124     /**
 125      * Returns the number of heads on the device.  May or may not have any
 126      * physical meaning relating to the geometry of the media.
 127      * @return number of heads
 128      */
 129     public int getHeads();
 130
 131     /**
 132      * Returns the number of sectors on the device.  May or may not have any
 133      * physical meaning relating to the geometry of the media.
 134      * @return number of sectors
 135      */
 136     public int getSectors();
 137
 138     /**
 139      * Returns this device type.  This is either: <code>TYPE_HD</code>,
 140      * <code>TYPE_CDROM</code> or <code>TYPE_FLOPPY</code>.
 141      * @return type constant
 142      */
 143     public Type getType();
 144
 145     /**
 146      * Configure the device with given string configuration information.
 147      * @param spec configuration information
 148      * @throws java.io.IOException if configuration failed for I/O reasons
 149      * @throws java.lang.IllegalArgumentException if the configuration information is invalid
 150      */
 151     public void configure(String spec) throws IOException, IllegalArgumentException;
 152     public DiskImage getImage();
 153     public void dumpStatus(StatusDumper output);
 154 }