home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 (Developer) / NS_dev_3.2.iso / NextDeveloper / Headers / driverkit / IODisk.h < prev    next >
Text File  |  1993-08-06  |  10KB  |  379 lines
  1. /*     Copyright (c) 1991 NeXT Computer, Inc.  All rights reserved. 
  2.  *
  3.  * IODisk.h - Interface for generic Disk class.
  4.  *
  5.  * HISTORY
  6.  * 31-Jan-91    Doug Mitchell at NeXT
  7.  *      Created. 
  8.  */
  9.  
  10. #import <driverkit/return.h>
  11. #import <driverkit/IODevice.h>
  12. #import <bsd/sys/disktab.h>
  13. #import <kernserv/clock_timer.h>
  14.  
  15. #ifdef    KERNEL
  16. /*
  17.  * The Unix-level code associated with a particular subclass of IODisk
  18.  * keeps an array of these to allow mapping from a dev_t to a IODisk
  19.  * id. One per Unix unit (a unit is a physical disk). The _devAndIdInfo
  20.  * instance variable for an instances of a given class of IODisk 
  21.  * points to the one element in a static array of IODevToIdMap's for 
  22.  * that class.
  23.  */
  24. typedef struct {
  25.     id liveId;            // IODisk/... for live partition
  26.     id partitionId[NPART-1];    // for block and raw devices
  27.     dev_t rawDev;            // used by volCheck logic
  28.     dev_t blockDev;            // ditto
  29. } IODevAndIdInfo;
  30.  
  31. #endif    KERNEL
  32.  
  33. /*
  34.  * Basic "usefulness" state of drive.
  35.  */
  36. typedef enum {
  37.     IO_Ready,         // Ready for r/w operations
  38.     IO_NotReady,        // not ready (spinning up or busy)
  39.     IO_NoDisk,         // no disk present
  40.     IO_Ejecting        // eject in progress
  41. } IODiskReadyState;
  42.  
  43. /*
  44.  * Current known disk types.
  45.  */
  46. typedef enum {
  47.     IO_SCSI,
  48.     IO_Floppy,
  49.     IO_Other
  50. } IODiskType;
  51.  
  52. @interface IODisk:IODevice
  53. {
  54. @private
  55.     id        _nextLogicalDisk;    // next LogicalDisk object
  56.                         // in chain.
  57.                         // May be nil. 
  58.     unsigned    _blockSize;        // in bytes 
  59.     unsigned    _diskSize;        // in blockSize's
  60.     BOOL        _removable;        // removable media device 
  61.     BOOL        _formatted;        // disk is formatted
  62.     BOOL        _isPhysical;        // this is NOT a logical disk
  63.     BOOL        _writeProtected;
  64. #ifdef    KERNEL
  65.     IODevAndIdInfo    *_devAndIdInfo;        // provides dev_t to id 
  66.                         // mapping for this instance.
  67. #endif    KERNEL
  68.     id        _LogicalDiskLock;    // NXLock. Serializes
  69.                         // operations whcih change 
  70.                         // LogicalDisks attached to 
  71.                         // this device.
  72.     char        _driveName[MAXDNMLEN];    // for Unix 'drive_info'
  73.                         // requests 
  74.                         
  75.     /*
  76.      * The lastReadyState variable is initialized by device-specific
  77.      * subclass, but is subsequently only changed by the volCheck module.
  78.      */
  79.     IODiskReadyState _lastReadyState;    
  80.     
  81.     /*
  82.      * Statistics. Accessed en masse via 
  83.      * getIntValues::DISK_STATS_ARRAY.
  84.      * All times in ms.
  85.      */
  86.     unsigned    _readOps;
  87.     unsigned    _bytesRead;
  88.     unsigned    _readTotalTime;
  89.     unsigned    _readLatentTime;
  90.     unsigned    _readRetries;
  91.     unsigned    _readErrors;
  92.     unsigned    _writeOps;
  93.     unsigned     _bytesWritten;
  94.     unsigned    _writeTotalTime;
  95.     unsigned    _writeLatentTime;
  96.     unsigned    _writeRetries;
  97.     unsigned    _writeErrors;
  98.     unsigned    _otherRetries;
  99.     unsigned    _otherErrors;
  100.     
  101.     int        _IODisk_reserved[4];
  102. }
  103.  
  104. /*
  105.  * Register instance with current name space.  
  106.  */
  107. - registerDevice;        // nil return means failure
  108.  
  109. /*
  110.  * Public methods to get and set disk parameters. These are implemented in
  111.  * the IODisk class. 
  112.  */
  113. - (unsigned)diskSize;
  114. - (unsigned)blockSize;
  115. - (IOReturn)setFormatted : (BOOL)formattedFlag;
  116. - (BOOL)isFormatted;
  117. - (BOOL)isRemovable;
  118. - (BOOL)isPhysical;
  119. - (BOOL)isWriteProtected;
  120. - (const char *)driveName;
  121.  
  122. /*
  123.  * Two forms of eject - one for use with logical disks attached
  124.  * (eject), so that attached NXDisks can be polled for open 
  125.  * state; this method is implemented in IODisk but is normally overridden
  126.  * by a subclass like IODiskPartition. The other is ejectPhysical, 
  127.  * in the IOPhysicalDiskMethods protocol (below). 
  128.  */
  129. - (IOReturn) eject;
  130.  
  131. /*
  132.  * Get/set parameters used only by subclasses.
  133.  */              
  134. - (void)setDiskSize            : (unsigned)size;
  135. - (void)setBlockSize            : (unsigned)size;
  136. - (void)setIsPhysical            : (BOOL)isPhysical;
  137. - nextLogicalDisk;
  138. - (void)setRemovable            : (BOOL)removableFlag;
  139. - (void)setDriveName            : (const char *)name;
  140. - (IODiskReadyState)lastReadyState;
  141. - (void)setLastReadyState        : (IODiskReadyState)readyState;
  142. - (void)setWriteProtected        : (BOOL)writeProtectFlag;
  143. - (void)setFormattedInternal         : (BOOL)formattedFlag;
  144.  
  145. /*
  146.  * Statistics support.
  147.  *
  148.  * These methods are invoked by subclass during I/O.
  149.  */
  150. - (void)addToBytesRead        : (unsigned)bytesRead
  151.                   totalTime  : (ns_time_t)totalTime
  152.                   latentTime : (ns_time_t)latentTime;
  153. - (void)addToBytesWritten    : (unsigned)bytesWritten
  154.                   totalTime  : (ns_time_t)totalTime
  155.                   latentTime : (ns_time_t)latentTime;
  156. - (void)incrementReadRetries;
  157. - (void)incrementReadErrors;
  158. - (void)incrementWriteRetries;
  159. - (void)incrementWriteErrors;
  160. - (void)incrementOtherRetries;
  161. - (void)incrementOtherErrors;
  162.  
  163. /*
  164.  * For gathering cumulative statistics.
  165.  */
  166. - (IOReturn)getIntValues        : (unsigned *)parameterArray
  167.                forParameter : (IOParameterName)parameterName
  168.                       count : (unsigned *)count;    // in/out
  169.  
  170. /*
  171.  * Obtain statistics in array defined by IODiskStatIndices.
  172.  */
  173. #define IO_DISK_STATS        "IODiskStats"
  174.  
  175. /*
  176.  * RPC equivalent of isKindOfClassNamed:IODisk. Used in 
  177.  * getParameterInt. Returns no data; just returns IO_R_SUCCESS.
  178.  */
  179. #define IO_IS_A_DISK        "IOIsADisk"
  180.  
  181. /*
  182.  * RPC equivalent of _isPhysDevice. Used in getParameterInt. Returns one 
  183.  * int, the value of _isPhysDevice.
  184.  */
  185. #define IO_IS_A_PHYSICAL_DISK    "IOIsAPhysicalDisk"
  186.  
  187. /*
  188.  * Indices into array obtained via getParameterInt : IO_DISK_STATS.
  189.  */
  190. typedef enum {
  191.     IO_Reads,
  192.     IO_BytesRead,
  193.     IO_TotalReadTime,
  194.     IO_LatentReadTime,
  195.     IO_ReadRetries,
  196.     IO_ReadErrors,
  197.     IO_Writes,
  198.     IO_BytesWritten,
  199.     IO_TotalWriteTime,
  200.     IO_LatentWriteTime,
  201.     IO_WriteRetries,
  202.     IO_WriteErrors,
  203.     IO_OtherRetries,
  204.     IO_OtherErrors,
  205. } IODiskStatIndices;
  206.     
  207. #define IO_DISK_STAT_ARRAY_SIZE        (IO_OtherErrors + 1)
  208.  
  209. /*
  210.  * Register a connection with LogicalDisk.
  211.  */
  212. - (void) setLogicalDisk    : diskId;
  213.  
  214. /*
  215.  * Lock/Unlock device for LogicalDisk-specific methods. Invoked only by
  216.  * LogicalDisks which are attached to this device.
  217.  */
  218. - (void)lockLogicalDisks;
  219. - (void)unlockLogicalDisks;
  220.  
  221. /*
  222.  * Convert an IOReturn to text. Overrides superclass's method of same name
  223.  * to allow for additional IOReturn's defined in this file.
  224.  */
  225. - (const char *)stringFromReturn    : (IOReturn)rtn;
  226.  
  227. /*
  228.  * Request a "please insert disk" panel.
  229.  */
  230. - (void)requestInsertionPanelForDiskType : (IODiskType)diskType;
  231.  
  232. /*
  233.  * Notify volCheck thread that specified device is in a "disk ejecting" state.
  234.  */
  235. - (void)diskIsEjecting : (IODiskType)diskType;
  236.  
  237. /*
  238.  * Notify volCheck that disk has gone not ready. Typically called on
  239.  * gross error detection.
  240.  */
  241. - (void)diskNotReady;
  242.  
  243. /*
  244.  * To be optionally overridden by subclass. IODisk version returns NO.
  245.  * If subclass's version returns NO, and the drive is a removable media 
  246.  * drive, the drive will not be polled once per second while ready state
  247.  * is IO_NotReady or IO_NoDisk; instead; polling will only occur when
  248.  * an DKIOCCHECKINSERT ioctl is executed on the vol driver.
  249.  */
  250. - (BOOL)needsManualPolling;
  251.  
  252. @end
  253.  
  254. /* End of IODisk interface. */
  255.  
  256. /*
  257.  * The IOPhysicalDiskMethods protocol must be implemented by each bottom-level 
  258.  * physical disk subclass of IODisk.
  259.  */
  260.  
  261. @protocol IOPhysicalDiskMethods
  262.  
  263. /*
  264.  * Get physical parameters (dev_size, block_size, etc.) from new disk. Called 
  265.  * upon disk insertion detection or other transition to RS_READY.
  266.  */
  267. - (IOReturn)updatePhysicalParameters;
  268.  
  269. /*
  270.  * Called by volCheck thread when WS has told us that a requested disk is
  271.  * not present. Pending I/Os which require a disk to be present must be 
  272.  * aborted.
  273.  */
  274. - (void)abortRequest;
  275.  
  276. /*
  277.  * Called by the volCheck thread when a transition to "ready" is detected.
  278.  * Pending I/Os which require a disk may proceed.
  279.  */
  280. - (void)diskBecameReady;
  281.  
  282. /*
  283.  * Inquire if disk is present; if not, and 'prompt' is TRUE, ask for it. 
  284.  * Returns IO_R_NODISK if:
  285.  *    prompt TRUE, disk not present, and user cancels request for disk.
  286.  *    prompt FALSE, disk not present.
  287.  * Else returns IO_R_SUCCESS.
  288.  */
  289. - (IOReturn)isDiskReady    : (BOOL)prompt;
  290.  
  291. /*
  292.  * Device-specific eject method, only called on physical device.
  293.  */
  294. - (IOReturn) ejectPhysical;
  295.  
  296. /*
  297.  * Determine basic state of device. This method should NOT implement any
  298.  * retries. It also should not return RS_EJECTING (That's only used in the
  299.  * lastReadyState instance variable).
  300.  */
  301. - (IODiskReadyState)updateReadyState;
  302.  
  303. @end
  304.  
  305. /* end of IOPhysicalDiskMethods protocol */
  306.  
  307. /*
  308.  * Standard IODisk read/write protocol. Offsets are in blocks.
  309.  * Lengths are in bytes.
  310.  * FIXME - readAsyncAt should NOT copy data back to caller on return in
  311.  * Distrubuted Objects implementation.
  312.  */
  313. @protocol IODiskReadingAndWriting
  314.  
  315. #ifndef    KERNEL
  316.  
  317. - (IOReturn) readAt        : (unsigned)offset 
  318.                   length : (unsigned)length 
  319.                   buffer : (unsigned char *)buffer
  320.                   actualLength : (unsigned *)actualLength;
  321.                   
  322. - (IOReturn) readAsyncAt    : (unsigned)offset 
  323.                   length : (unsigned)length 
  324.                   buffer : (unsigned char *)buffer
  325.                   pending : (void *)pending;    // untyped
  326.                   
  327. - (IOReturn) writeAt        : (unsigned)offset 
  328.                   length : (unsigned)length 
  329.                   buffer : (unsigned char *)buffer
  330.                   actualLength : (unsigned *)actualLength;
  331.                       
  332. - (IOReturn) writeAsyncAt    : (unsigned)offset 
  333.                   length : (unsigned)length 
  334.                   buffer : (unsigned char *)buffer
  335.                   pending : (void *)pending;
  336. #else    KERNEL
  337.  
  338. - (IOReturn) readAt        : (unsigned)offset 
  339.                   length : (unsigned)length 
  340.                   buffer : (unsigned char *)buffer
  341.                   actualLength : (unsigned *)actualLength 
  342.                   client : (vm_task_t)client;
  343.  
  344. - (IOReturn) readAsyncAt    : (unsigned)offset 
  345.                   length : (unsigned)length 
  346.                   buffer : (unsigned char *)buffer
  347.                   pending : (void *)pending
  348.                   client : (vm_task_t)client;
  349.         
  350. - (IOReturn) writeAt        : (unsigned)offset 
  351.                   length : (unsigned)length 
  352.                   buffer : (unsigned char *)buffer
  353.                   actualLength : (unsigned *)actualLength 
  354.                   client : (vm_task_t)client;
  355.           
  356. - (IOReturn) writeAsyncAt    : (unsigned)offset 
  357.                   length : (unsigned)length 
  358.                   buffer : (unsigned char *)buffer
  359.                   pending : (void *)pending
  360.                   client : (vm_task_t)client;
  361.                   
  362. #endif    KERNEL
  363.  
  364. @end
  365.  
  366. /* end of DiskDeviceRw protocol */
  367.  
  368.  
  369. /*
  370.  * IOReturn's specific to IODisk.
  371.  */
  372. #define IO_R_NO_LABEL        (-1100)        /* no label present */
  373. #define IO_R_UNFORMATTED    (-1101)        /* disk not formatted */
  374. #define IO_R_NO_DISK        (-1102)        /* disk not present */
  375. #define IO_R_NO_BLOCK_ZERO    (-1103)        /* can't read first sector */
  376. #define IO_R_NO_NEXT_PART    (-1104)        /* No NeXT partition on */
  377.                         /* DOS disk */
  378. extern IONamedValue readyStateValues[];
  379.